aura-labs.ai

ADR-001: Natural Language Processing Distribution

Status: Superseded by ADR-002 Date: 2026-02-12 Superseded: 2026-03-09 — See ADR-002 Decision Makers: Marc Massar Context: Architectural decision for AURA platform

Context

AURA is a three-party system: Scouts (buyers), Core (broker), and Beacons (sellers). Natural language flows through the system at multiple points:

  1. User → Scout: “I need 50 ergonomic keyboards under $5000”
  2. Scout → Core: Intent transmission for matching
  3. Core → Beacon: Query broadcast to relevant vendors
  4. Beacon → Core → Scout: Offer responses and negotiation

The question: Where should NLP/intent parsing happen?

Options Considered

Option A: Scout-Heavy Processing

Scout does all NLP locally, sends only structured constraints to Core.

Pros Cons
Works offline Inconsistent across implementations
Privacy (raw intent stays local) Harder to upgrade/improve
Lower latency Scout bloat (requires LLM)
Resilient to Core outages User experience varies by Scout quality

Option B: Core-Heavy Processing (Centralized)

Raw intent flows to Core, Core does all semantic analysis.

Pros Cons
Consistent parsing Single point of failure
Single upgrade point Latency on every request
Market-aware context Privacy concern (raw intent to Core)
Easier to debug/audit Core must scale with demand

Option C: Beacon-Heavy Processing

Beacons receive raw intent and interpret it themselves.

Pros Cons
Domain expertise Inconsistent interpretation
Distributed load Unfair offer comparison
Beacons know their products best Security risk (raw user data to vendors)

Option D: Tiered Processing (Selected)

Distribute NLP across all three layers with clear responsibilities.

Decision

We will implement Tiered Processing (Option D) with the following distribution:

Layer 1 — Scout (20% of processing)

Responsibility: Basic extraction, user confirmation

Rationale: Scouts should work without an LLM. Basic extraction is deterministic and fast. User confirmation catches errors early.

Layer 2 — Core (70% of processing)

Responsibility: Semantic understanding, categorization, matching

Rationale: Core is the brain of the system. Centralized NLP ensures consistent interpretation. Market-aware context improves matching. Single upgrade point for improvements.

Layer 3 — Beacon (10% of processing)

Responsibility: Domain-specific interpretation (optional)

Rationale: Beacons have domain expertise Scouts and Core lack. Providing raw intent allows sophisticated Beacons to add value. Structured response requirement ensures fair comparison.

Protocol Negotiation Model

For MVP: All communication through Core (Option A below)

Scout ←→ Core ←→ Beacon

For V2: Core brokers introduction, direct negotiation with audit trail

Scout ←→ Core ←→ Beacon    [matching phase]
Scout ←────────→ Beacon    [negotiation phase]
         ↓
       Core                [receives signed audit trail]

Rationale for MVP

Rationale for V2 Direct Negotiation

Data Flow Specification

Scout → Core Request

{
  "raw_intent": "I need 50 ergonomic keyboards under $5000, delivery by end of month",
  "extracted": {
    "quantity": 50,
    "max_budget": 5000,
    "currency": "USD",
    "delivery_by": "2026-02-28"
  },
  "user_confirmed": true,
  "scout_version": "1.0.0"
}

Core → Beacon Query

{
  "session_id": "abc123",
  "raw_intent": "I need 50 ergonomic keyboards...",
  "structured": {
    "category": "office_equipment.keyboards",
    "keywords": ["ergonomic", "keyboard"],
    "quantity": 50,
    "max_unit_price": 100,
    "currency": "USD",
    "delivery_by": "2026-02-28"
  },
  "confidence": 0.92
}

Beacon → Core Response

{
  "offer_id": "offer_xyz",
  "beacon_id": "beacon_456",
  "product": {
    "name": "ErgoKey Pro Wireless",
    "sku": "EKP-2026",
    "unit_price": 89.99,
    "quantity_available": 200
  },
  "total_price": 4499.50,
  "currency": "USD",
  "delivery_estimate": "2026-02-25",
  "confidence": 0.88,
  "interpretation_notes": "Matched 'ergonomic keyboards' to ErgoKey Pro line"
}

Failure Modes

Scenario Behavior
Scout can’t extract anything Send raw intent only, Core handles all parsing
Core NLP fails Return error, Scout can retry or ask user to rephrase
Beacon can’t interpret Respond with null offer or low-confidence match
Core unavailable Scout shows cached results or offline message

Implementation Notes

Granite Integration (Core)

Scout Extraction (No LLM)

// Example: Scout-side extraction (regex/patterns)
function extractBasicConstraints(intent) {
  return {
    quantity: extractNumber(intent, /(\d+)\s*(units?|items?|pieces?)?/i),
    max_budget: extractCurrency(intent, /under\s*\$?([\d,]+)/i),
    delivery_by: extractDate(intent, /(by|before|within)\s+(.+)/i),
  };
}

Beacon Domain Expertise (Optional)

Beacons MAY implement their own NLP for competitive advantage but MUST respond with structured offers.

Consequences

Positive

Negative

Mitigations

References