aura-labs.ai

Scout SDK Documentation

Build buying agents that represent user interests in the AURA ecosystem.

What is a Scout?

A Scout is a buying agent that:

Scouts integrate into buyer-facing applications: shopping apps, browser extensions, voice assistants, procurement portals.

Quick Start

Installation

npm install @aura-labs/scout

Basic Usage

import { Scout } from '@aura-labs/scout';

// Initialize Scout
const scout = new Scout({
  apiKey: process.env.AURA_API_KEY,
  userId: 'user-123' // Your internal user ID
});

// Connect to AURA Core
await scout.connect();

// Register intent
const intent = await scout.registerIntent({
  category: 'electronics',
  description: 'wireless headphones with ANC',
  constraints: {
    priceRange: { min: 100, max: 300 }
  }
});

// Listen for matches
scout.on('propositions', (propositions) => {
  console.log('Found matches:', propositions);
});

// Listen for offers during negotiation
scout.on('offer', (offer) => {
  // Present to user or auto-evaluate
  if (meetsUserCriteria(offer)) {
    scout.acceptOffer(offer.id);
  }
});

Core Concepts

Intent Registration

Express intent as natural language, optionally with structured constraints:

// Simple intent
const session = await scout.intent('I need wireless headphones under $300');

// Intent with constraints
const session = await scout.intent('wireless headphones with noise cancellation', {
  maxBudget: 300,
  deliveryBy: '2026-03-15',
  categories: ['electronics', 'headphones'],
});

Intent Completeness with IntentSession

For better matching, use createIntentSession() to validate intent completeness before sending to Core. The IntentSession uses @aura-labs/nlp to check for 8 intent categories (what, how_many, how_much_cost, when_needed, what_kind, where_deliver, quality_level, special_requirements) and generates clarification questions for missing categories.

const intentSession = scout.createIntentSession();

// First round — check completeness
let result = await intentSession.submit('I want headphones');
// { complete: false, missing: ['how_many', 'how_much_cost', 'when_needed'], question: 'How many do you need?' }

// Second round — add missing details
result = await intentSession.submit('2 pairs under $300 by next week');
// { complete: true, missing: [], confidence: 0.91 }

// Send complete intent with completeness attestation
const session = await scout.intent(intentSession.getText(), {
  completeness: intentSession.getAttestation(),
});

IntentSession state machine: idle → checking → incomplete → checking → … → complete

Completeness attestation is informational only — Core always parses intent independently (ref: NEUTRAL_BROKER.md Property 1). The attestation is stored in session context for observability.

Field Type Description
complete boolean Whether all required categories are present
missing string[] Names of missing categories
question string Clarification question for the user
confidence number Average detection confidence (0-1)

Ref: ADR-002 — Three-Layer NLP Architecture

Identity Abstraction

The Scout maintains user privacy:

// Behavioral data shared with Beacons (anonymized)
const behavioralData = {
  purchaseHistory: {
    totalPurchases: 15,
    averageOrderValue: 250,
    categoryAffinities: { electronics: 0.8, travel: 0.3 }
  },
  trustScore: 85  // Scout's network reputation
};

// Identity ONLY revealed at transaction
const identity = {
  name: 'Jane Doe',
  email: 'jane@example.com',
  shippingAddress: { /* ... */ }
};

Negotiation

Scouts can negotiate automatically or with user guidance:

// Set negotiation parameters
scout.setNegotiationStrategy({
  style: 'balanced',           // aggressive | balanced | conservative
  autoAcceptBelow: 250,        // Auto-accept offers under this price
  maxCounterOffers: 3,
  timeout: 300000              // 5 minutes
});

// Handle offers
scout.on('offer', async (offer) => {
  if (offer.price <= scout.autoAcceptBelow) {
    return scout.acceptOffer(offer.id);
  }

  // Present to user
  const userDecision = await presentToUser(offer);

  if (userDecision === 'accept') {
    scout.acceptOffer(offer.id);
  } else if (userDecision === 'counter') {
    scout.counterOffer(offer.id, { maxPrice: 275 });
  } else {
    scout.rejectOffer(offer.id);
  }
});

All transactions require explicit user consent:

// Configure consent requirements
scout.setConsentPolicy({
  requireApproval: 'always',   // always | above_threshold | never
  approvalThreshold: 100,
  notifyOnMatch: true,
  notifyOnOffer: true
});

// Handle consent flow
scout.on('transaction_ready', async (transaction) => {
  // Always present final terms to user
  const consent = await getUserConsent(transaction);

  if (consent.approved) {
    // NOW identity is revealed to seller
    await scout.completeTransaction(transaction.id, {
      identity: consent.identityToShare,
      paymentMethod: consent.paymentMethod
    });
  }
});

API Reference

Scout Class

Constructor

new Scout(config)
Parameter Type Description
apiKey string AURA API key
userId string Your internal user identifier
preferences object Default user preferences

Methods

Method Description
connect() Connect to AURA Core
disconnect() Disconnect from AURA Core
registerIntent(intent) Register purchase intent
cancelIntent(intentId) Cancel an intent
acceptOffer(offerId) Accept a negotiation offer
counterOffer(offerId, terms) Make counter-offer
rejectOffer(offerId) Reject an offer
completeTransaction(txId, details) Complete transaction

Events

Event Description
connected Connected to AURA Core
disconnected Disconnected
propositions Matching propositions found
offer Received negotiation offer
transaction_ready Ready to complete transaction
transaction_complete Transaction completed
error Error occurred

Best Practices

Privacy

User Experience

Error Handling

Examples

See the Examples directory for:

See Also