{"_id":"@aura-labs-ai/nlp","_rev":"2-b1331b6b543a72da0556d4b2ec7582e6","name":"@aura-labs-ai/nlp","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aura-labs-ai/nlp","version":"0.1.0","license":"Apache-2.0","_id":"@aura-labs-ai/nlp@0.1.0","maintainers":[{"name":"marcmassar","email":"marc@aura-labs.ai"}],"homepage":"https://github.com/aura-labs/aura-labs#readme","bugs":{"url":"https://github.com/aura-labs/aura-labs/issues"},"dist":{"shasum":"c5a47dc616446cd45e2bb8a1b0f9d31337a5e175","tarball":"https://registry.npmjs.org/@aura-labs-ai/nlp/-/nlp-0.1.0.tgz","fileCount":14,"integrity":"sha512-axUbZzUUavTq8qIRT0uSb4TY7/4Br4t7cXUti6rErP/76nXhhVP4g8xWCeVJ4infZ5vypKDibtCr4ARGtGUllw==","signatures":[{"sig":"MEUCICtiRcdxLCvR8YqyFgonbWG58IEsAUsPm/fBsbZBju4fAiEAgWz0PwyrsJAZu8fdXhOgEF1LE4YS7NaXHmwuoRwBJo0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106009},"main":"src/index.js","type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./src/index.js"},"scripts":{"test":"node --test src/tests/*.test.js","test:unit":"node --test src/tests/*.test.js"},"_npmUser":{"name":"marcmassar","email":"marc@aura-labs.ai"},"repository":{"url":"git+https://github.com/aura-labs/aura-labs.git","type":"git","directory":"sdks/nlp"},"_npmVersion":"11.11.0","description":"Shared NLP module for AURA Agent Universal Resource Architecture — intent completeness checking, conversational clarification, and LLM provider abstraction","directories":{},"_nodeVersion":"25.8.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/nlp_0.1.0_1773248119175_0.7595805364690937","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aura-labs-ai/nlp","version":"0.2.0","description":"Shared NLP module for AURA Agent Universal Resource Architecture — intent completeness checking, conversational clarification, and LLM provider abstraction","type":"module","main":"src/index.js","exports":{".":"./src/index.js"},"scripts":{"test":"node --test src/tests/*.test.js","test:unit":"node --test src/tests/*.test.js"},"engines":{"node":">=20.0.0"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/aura-labs/aura-labs.git","directory":"sdks/nlp"},"gitHead":"8078e0c07073af97bc51fd949427a00286b6e53c","_id":"@aura-labs-ai/nlp@0.2.0","bugs":{"url":"https://github.com/aura-labs/aura-labs/issues"},"homepage":"https://github.com/aura-labs/aura-labs#readme","_nodeVersion":"22.23.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-mg9gq5Xwr3vOev/oVNtcpIGT7dVQrrobj5z4n9W06whS/cHia+DUIeKUDX+U7rY1WLwYVKyNJitSsJ8CIAlAEA==","shasum":"e6d3578f3537afbda709a8d40bc7ca2f66e37f15","tarball":"https://registry.npmjs.org/@aura-labs-ai/nlp/-/nlp-0.2.0.tgz","fileCount":14,"unpackedSize":106009,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIElSx2i+23v+57MXiVtP1eUFCF76VXlZ77Kyfd4m0zysAiBDgnHmBkuyGbUMYJxfezwk28WJl3zXIS7tXk/AO+AJdw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e212208f-f01e-4a33-bff9-d0910eafdb4b"}},"directories":{},"maintainers":[{"name":"marcmassar","email":"marc@aura-labs.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nlp_0.2.0_1783274092443_0.7463922923503776"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T16:55:19.117Z","modified":"2026-07-05T17:54:52.700Z","0.1.0":"2026-03-11T16:55:19.316Z","0.2.0":"2026-07-05T17:54:52.571Z"},"bugs":{"url":"https://github.com/aura-labs/aura-labs/issues"},"license":"Apache-2.0","homepage":"https://github.com/aura-labs/aura-labs#readme","repository":{"type":"git","url":"git+https://github.com/aura-labs/aura-labs.git","directory":"sdks/nlp"},"description":"Shared NLP module for AURA Agent Universal Resource Architecture — intent completeness checking, conversational clarification, and LLM provider abstraction","maintainers":[{"name":"marcmassar","email":"marc@aura-labs.ai"}],"readme":"# @aura-labs-ai/nlp\n\nShared NLP module for the Agent Universal Resource Architecture (AURA) platform. Provides intent completeness checking, conversational clarification, and LLM provider abstraction.\n\nUsed by: Scout SDK, Beacon SDK, Core intent-svc.\n\n## Install\n\nZero external dependencies. Link via `file:` reference in `package.json`:\n\n```json\n{ \"dependencies\": { \"@aura-labs-ai/nlp\": \"file:../../sdks/nlp\" } }\n```\n\n## API\n\n### `checkCompleteness(text, options?) → Promise<CompletenessResult>`\n\nDetermines whether an intent string contains all required information across 8 categories.\n\n```js\nimport { checkCompleteness } from '@aura-labs-ai/nlp';\n\nconst result = await checkCompleteness('I need 50 ergonomic keyboards under $5000');\n// { complete: false, missing: ['what_kind'], confidence: 0.63, categories: { ... } }\n```\n\n**Options:**\n- `provider` — LLM provider for model-based detection (what, what_kind, why, values_impact)\n- `activityLogger` — `NlpActivityLogger` instance for event emission\n\nWithout a provider, only regex-detectable categories are checked (how_many, how_much_cost, when, where). Categories requiring semantic understanding (what, what_kind) need a provider.\n\n### `generateClarification(missing, options?) → { question, suggestions }`\n\nGenerates a natural-language clarification question for missing categories.\n\n```js\nimport { generateClarification } from '@aura-labs-ai/nlp';\n\nconst { question } = generateClarification(['how_many', 'how_much_cost']);\n// \"How many would you like? Also, what's your budget or price range?\"\n```\n\n**Options:**\n- `previousRounds` — Array of prior round data for context-aware follow-ups\n\n### `createProvider(config) → MockProvider | RemoteProvider`\n\nFactory for LLM providers.\n\n```js\nimport { createProvider } from '@aura-labs-ai/nlp';\n\n// Testing\nconst mock = createProvider({ type: 'mock' });\n\n// Production (Together AI)\nconst together = createProvider({\n  type: 'together',\n  apiKey: process.env.NLP_PROVIDER_API_KEY,\n});\n\n// Production (Fireworks)\nconst fireworks = createProvider({\n  type: 'fireworks',\n  apiKey: process.env.NLP_PROVIDER_API_KEY,\n});\n\nconst result = await provider.parse('I need keyboards');\n// { structured: { ... }, confidence: 0.8, ambiguities: [] }\n```\n\n### `INTENT_CATEGORIES`\n\nFrozen object defining the 8 intent categories with tier, detection method, and regex patterns.\n\n| Category | Tier | Detection | Description |\n|----------|------|-----------|-------------|\n| what | 1 | model | Product/service identification |\n| how_many | 1 | regex | Quantity detection |\n| what_kind | 1 | model | Characteristics/attributes |\n| how_much_cost | 1 | regex | Price/budget detection |\n| where | 2 | hybrid | Location/delivery |\n| when | 2 | regex | Timing/deadline |\n| why | 2 | model | Purpose/use case |\n| values_impact | 2 | model | Values alignment (sustainability, etc.) |\n\nTier 1 categories are always required. Tier 2 categories are required only when triggered by intent language.\n\n### `NlpActivityLogger` / `NlpActivityEvents`\n\nStructured event system for observability.\n\n```js\nimport { NlpActivityLogger, NlpActivityEvents } from '@aura-labs-ai/nlp';\n\nconst logger = new NlpActivityLogger({ logger: console });\nlogger.on(NlpActivityEvents.COMPLETENESS_CHECKED, (event) => {\n  console.log(event.metadata.confidence);\n});\n```\n\nEvents: `COMPLETENESS_CHECKED`, `PROVIDER_CALLED`, `PROVIDER_FAILED`, `PROVIDER_DEGRADED`, `CLARIFICATION_GENERATED`, `SESSION_COMPLETED`.\n\n## Architecture\n\nSee [ADR-002: NLP Three-Layer Shared Module](../../docs/decisions/ADR-002-NLP-THREE-LAYER-SHARED-MODULE.md).\n\n## Testing\n\n```bash\nnode --test src/tests/*.test.js\n```\n\n119 tests covering categories, completeness, conversation, providers, activity logging, and remote provider SSRF/timeout handling.\n\n## Ref\n\n- ADR-002, DEC-024, DEC-025\n- NEUTRAL_BROKER.md Property 1 (Core retains semantic authority)\n","readmeFilename":"README.md"}