@aura-labs.ai/nlp

Shared NLP module for the Agent Universal Resource Architecture (AURA) platform. Provides intent completeness checking, conversational clarification, and LLM provider abstraction.

Used by: Scout SDK, Beacon SDK, Core intent-svc.

Install

Zero external dependencies. Link via file: reference in package.json:

{ "dependencies": { "@aura-labs.ai/nlp": "file:../../sdks/nlp" } }

API

checkCompleteness(text, options?) → Promise<CompletenessResult>

Determines whether an intent string contains all required information across 8 categories.

import { checkCompleteness } from '@aura-labs.ai/nlp';

const result = await checkCompleteness('I need 50 ergonomic keyboards under $5000');
// { complete: false, missing: ['what_kind'], confidence: 0.63, categories: { ... } }

Options:

• provider — LLM provider for model-based detection (what, what_kind, why, values_impact)
• activityLogger — NlpActivityLogger instance for event emission

Without 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.

generateClarification(missing, options?) → { question, suggestions }

Generates a natural-language clarification question for missing categories.

import { generateClarification } from '@aura-labs.ai/nlp';

const { question } = generateClarification(['how_many', 'how_much_cost']);
// "How many would you like? Also, what's your budget or price range?"

Options:

• previousRounds — Array of prior round data for context-aware follow-ups

createProvider(config) → MockProvider | RemoteProvider

Factory for LLM providers.

import { createProvider } from '@aura-labs.ai/nlp';

// Testing
const mock = createProvider({ type: 'mock' });

// Production (Together AI)
const together = createProvider({
  type: 'together',
  apiKey: process.env.NLP_PROVIDER_API_KEY,
});

// Production (Fireworks)
const fireworks = createProvider({
  type: 'fireworks',
  apiKey: process.env.NLP_PROVIDER_API_KEY,
});

const result = await provider.parse('I need keyboards');
// { structured: { ... }, confidence: 0.8, ambiguities: [] }

INTENT_CATEGORIES

Frozen object defining the 8 intent categories with tier, detection method, and regex patterns.

| Category | Tier | Detection | Description | |----------|------|-----------|-------------| | what | 1 | model | Product/service identification | | how_many | 1 | regex | Quantity detection | | what_kind | 1 | model | Characteristics/attributes | | how_much_cost | 1 | regex | Price/budget detection | | where | 2 | hybrid | Location/delivery | | when | 2 | regex | Timing/deadline | | why | 2 | model | Purpose/use case | | values_impact | 2 | model | Values alignment (sustainability, etc.) |

Tier 1 categories are always required. Tier 2 categories are required only when triggered by intent language.

NlpActivityLogger / NlpActivityEvents

Structured event system for observability.

import { NlpActivityLogger, NlpActivityEvents } from '@aura-labs.ai/nlp';

const logger = new NlpActivityLogger({ logger: console });
logger.on(NlpActivityEvents.COMPLETENESS_CHECKED, (event) => {
  console.log(event.metadata.confidence);
});

Events: COMPLETENESS_CHECKED, PROVIDER_CALLED, PROVIDER_FAILED, PROVIDER_DEGRADED, CLARIFICATION_GENERATED, SESSION_COMPLETED.

Architecture

See ADR-002: NLP Three-Layer Shared Module.

Testing

node --test src/tests/*.test.js

119 tests covering categories, completeness, conversation, providers, activity logging, and remote provider SSRF/timeout handling.

Ref

• ADR-002, DEC-024, DEC-025
• NEUTRAL_BROKER.md Property 1 (Core retains semantic authority)