@kontourai/survey 0.4.24 → 0.5.0

package/dist/src/agent-utterance.js

@@ -0,0 +1,373 @@
+/**
+ * Agent-utterance producer profile — ADR 0003 step 6.
+ *
+ * This module implements Survey as a producer pointed at agent utterances
+ * instead of web sources. Each factual statement in agent prose is extracted
+ * as a candidate claim and run through the Inquiry pipeline.
+ *
+ * Integration point: surveyAgentUtterance is the clean entry point for
+ * consumers wanting to "spell-check" an agent's output for evidence. Flow-agent
+ * hook wiring (connecting this function to a live agent's output pipeline) is
+ * out of scope for this module and lives in the flow-agents repo.
+ *
+ * Hard constraint (ADR 0003 §4): nothing here silently decides. The
+ * UtteranceClaimExtractor is a pluggable interface; implementations may be
+ * deterministic or model-backed, but they are always extractors — their output
+ * has full provenance (excerpt, span, extractor name, confidence) and is
+ * run through the Inquiry pipeline rather than treated as authoritative.
+ */
+import { resolveInquiry } from "@kontourai/surface";
+import { lookupMapping, resolveQuestion } from "./inquiry-mapping.js";
+// ---------------------------------------------------------------------------
+// SurveyInput projection
+// ---------------------------------------------------------------------------
+/**
+ * Project an agent utterance and its extracted statements into the standard
+ * SurveyInput shape so they can flow into buildSurveyTrustBundle.
+ *
+ * Each extracted statement lands as:
+ *   RawSource (agent-utterance) → Extraction (with text-span locator) →
+ *   Candidate → CandidateSet (needs-review, no review outcome) → ClaimTarget
+ *
+ * Status discipline (ADR 0003 §4, to-surface.ts producer rules):
+ * - All claims project as "proposed" — unreviewed extractions are proposals,
+ *   never authoritative. assertProducerDiscipline forbids verified/assumed
+ *   without a review outcome.
+ * - agent-utterance is not a manual-entry source, so extraction.locator is
+ *   required. Span-located statements use text-span:start-end; span-less
+ *   statements use text-span derived from the excerpt offset in the utterance
+ *   (best-effort, 0-based).
+ *
+ * The returned SurveyInput can be passed directly to buildSurveyTrustBundle
+ * to produce a TrustBundle with full provenance in the Trust Bundle metadata.
+ *
+ * @param utterance - The raw agent utterance text.
+ * @param extracted - ExtractedStatements produced by a UtteranceClaimExtractor.
+ * @param context - agentId, extractor name, optional now timestamp.
+ */
+export function utteranceToSurveyInput(utterance, extracted, context) {
+    const { agentId, extractorName, now } = context;
+    const observedAt = (now ?? new Date()).toISOString();
+    const source = context.source ?? `agent-utterance:${agentId}`;
+    // One shared RawSource for the entire utterance
+    const sourceId = `agent-utterance:${agentId}:${observedAt}`;
+    const rawSource = {
+        id: sourceId,
+        kind: "agent-utterance",
+        sourceRef: `agent-utterance://${agentId}/${observedAt}`,
+        observedAt,
+        locatorScheme: "text-span",
+        inlineText: utterance,
+        metadata: { agentId },
+    };
+    const extractions = [];
+    const candidateSets = [];
+    const claims = [];
+    for (let idx = 0; idx < extracted.length; idx++) {
+        const statement = extracted[idx];
+        const statementId = `${sourceId}.statement.${idx}`;
+        const extractionId = `${statementId}.extraction`;
+        const candidateId = `${statementId}.candidate`;
+        const candidateSetId = `${statementId}.candidate-set`;
+        const claimId = `${statementId}.claim`;
+        // Compute locator — required for non-manual-entry sources
+        // (assertProducerDiscipline throws without it)
+        const locator = spanToLocator(statement.span) ?? excerptLocator(utterance, statement.excerpt);
+        const extraction = {
+            id: extractionId,
+            sourceId,
+            target: canonicalTargetKey(statement.target),
+            value: statement.value ?? null,
+            confidence: statement.confidence,
+            locator,
+            excerpt: statement.excerpt,
+            extractor: extractorName,
+            extractedAt: observedAt,
+            metadata: {
+                agentUtterance: {
+                    span: statement.span,
+                    excerpt: statement.excerpt,
+                    extractorName,
+                    confidence: statement.confidence,
+                },
+            },
+        };
+        const candidate = {
+            id: candidateId,
+            extractionId,
+            value: statement.value ?? null,
+            confidence: statement.confidence,
+            metadata: {
+                agentUtterance: {
+                    span: statement.span,
+                    excerpt: statement.excerpt,
+                    extractorName,
+                    confidence: statement.confidence,
+                },
+            },
+        };
+        // needs-review status → statusFor returns "proposed" (no review outcome)
+        const candidateSet = {
+            id: candidateSetId,
+            target: canonicalTargetKey(statement.target),
+            candidates: [candidate],
+            selectedCandidateId: candidateId,
+            status: "needs-review",
+            metadata: {
+                agentUtterance: {
+                    subjectType: statement.target.subjectType,
+                    subjectId: statement.target.subjectId,
+                    fieldOrBehavior: statement.target.fieldOrBehavior,
+                },
+            },
+        };
+        // Unreviewed: status is omitted so statusFor() computes "proposed"
+        // assertProducerDiscipline: no verified/assumed without review → compliant
+        const claimTarget = {
+            id: claimId,
+            candidateSetId,
+            candidateId,
+            subjectType: statement.target.subjectType,
+            subjectId: statement.target.subjectId,
+            surface: "agent-utterance.profile",
+            claimType: "agent-extraction",
+            fieldOrBehavior: statement.target.fieldOrBehavior,
+            value: statement.value,
+            // status intentionally omitted → computed as "proposed" by statusFor
+            impactLevel: "low",
+            collectedBy: extractorName,
+            metadata: {
+                survey: {
+                    agentUtterance: {
+                        agentId,
+                        extractorName,
+                        excerpt: statement.excerpt,
+                        span: statement.span,
+                        confidence: statement.confidence,
+                        locator,
+                    },
+                },
+            },
+        };
+        extractions.push(extraction);
+        candidateSets.push(candidateSet);
+        claims.push(claimTarget);
+    }
+    return {
+        source,
+        generatedAt: observedAt,
+        rawSources: [rawSource],
+        extractions,
+        candidateSets,
+        reviewOutcomes: [],
+        claims,
+    };
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Survey an agent utterance, returning a trust report for each extracted claim.
+ *
+ * Steps:
+ * 1. Build a RawSource for the utterance (kind: "agent-utterance").
+ * 2. Run the extractor → project each statement into Survey records with full
+ *    provenance (excerpt, span locator, extractor name, confidence).
+ * 3. Resolve each extracted claim against the bundle via resolveInquiry or
+ *    resolveQuestion (if mappings are provided).
+ * 4. Return an UtteranceTrustReport with per-statement badges.
+ *
+ * This function is the integration point for consumers. Flow-agent hook wiring
+ * lives in the flow-agents repo.
+ */
+export async function surveyAgentUtterance(utterance, extractor, context) {
+    const { bundle, mappings, rules, now, agentId } = context;
+    const observedAt = (now ?? new Date()).toISOString();
+    // Step 1: Build a RawSource for this utterance
+    const sourceId = `agent-utterance:${agentId}:${observedAt}`;
+    const source = {
+        id: sourceId,
+        kind: "agent-utterance",
+        sourceRef: `agent-utterance://${agentId}/${observedAt}`,
+        observedAt,
+        locatorScheme: "text-span",
+        inlineText: utterance,
+        metadata: { agentId },
+    };
+    // Step 2: Extract statements
+    const extracted = await Promise.resolve(extractor.extract(utterance));
+    // Step 3 & 4: Resolve each statement and build the report
+    const statements = [];
+    for (const statement of extracted) {
+        const statementId = `${sourceId}.statement.${statements.length}`;
+        // Build Survey records for provenance
+        const extractionId = `${statementId}.extraction`;
+        const extraction = {
+            id: extractionId,
+            sourceId,
+            target: canonicalTargetKey(statement.target),
+            value: statement.value ?? null,
+            confidence: statement.confidence,
+            locator: statement.span ? `text-span:${statement.span.start}-${statement.span.end}` : undefined,
+            excerpt: statement.excerpt,
+            extractor: extractor.name,
+            extractedAt: observedAt,
+            metadata: {
+                agentUtterance: {
+                    span: statement.span,
+                    excerpt: statement.excerpt,
+                    extractorName: extractor.name,
+                    confidence: statement.confidence,
+                },
+            },
+        };
+        // Resolve the claim
+        let inquiryRecord;
+        if (mappings && mappings.length > 0) {
+            // If we have question-level mappings, check them first by building
+            // a question from the target
+            const syntheticQuestion = targetToQuestion(statement.target);
+            const mapping = lookupMapping(mappings, syntheticQuestion);
+            if (mapping) {
+                inquiryRecord = resolveQuestion(bundle, syntheticQuestion, {
+                    mappings,
+                    rules,
+                    now,
+                    askedBy: agentId,
+                });
+            }
+            else {
+                // No mapping: resolve directly by canonical target
+                inquiryRecord = resolveByTarget(bundle, statement.target, agentId, observedAt, rules, now);
+            }
+        }
+        else {
+            // Resolve directly by canonical target
+            inquiryRecord = resolveByTarget(bundle, statement.target, agentId, observedAt, rules, now);
+        }
+        const badge = badgeFromRecord(inquiryRecord);
+        statements.push({
+            excerpt: statement.excerpt,
+            span: statement.span,
+            target: statement.target,
+            inquiryRecord,
+            badge,
+        });
+        // Suppress unused-variable warning for extraction
+        void extraction;
+    }
+    return { source, statements };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function resolveByTarget(bundle, target, askedBy, askedAt, rules, now) {
+    const id = `inquiry.direct.${canonicalTargetKey(target)}.${askedAt}`;
+    const inquiry = {
+        id,
+        question: targetToQuestion(target),
+        target,
+        askedBy,
+        askedAt,
+    };
+    return resolveInquiry(bundle, inquiry, { now, rules });
+}
+function canonicalTargetKey(target) {
+    return `${target.subjectType}/${target.subjectId}/${target.fieldOrBehavior}`;
+}
+function targetToQuestion(target) {
+    return `${target.subjectId} ${target.fieldOrBehavior}`;
+}
+function badgeFromRecord(record) {
+    if (record.outcome === "unsupported")
+        return "unsupported";
+    const status = record.answer?.status;
+    if (!status)
+        return "unsupported";
+    if (status === "verified")
+        return "verified";
+    if (status === "assumed")
+        return "assumed";
+    if (status === "stale")
+        return "stale";
+    if (status === "disputed")
+        return "disputed";
+    if (status === "rejected" || status === "superseded")
+        return "rejected";
+    return "unsupported";
+}
+/**
+ * Convert a text-span to a locator string.
+ */
+function spanToLocator(span) {
+    if (!span)
+        return undefined;
+    return `text-span:${span.start}-${span.end}`;
+}
+/**
+ * Best-effort locator from excerpt text — find the first occurrence of the
+ * excerpt in the utterance and use that as a text-span locator.
+ * Falls back to text-span:0-0 if the excerpt is not found.
+ */
+function excerptLocator(utterance, excerpt) {
+    const idx = utterance.indexOf(excerpt);
+    if (idx >= 0) {
+        return `text-span:${idx}-${idx + excerpt.length}`;
+    }
+    // Fallback: anchor to start (preserves discipline contract; locator is
+    // best-effort for span-less extractors)
+    return `text-span:0-${excerpt.length}`;
+}
+// ---------------------------------------------------------------------------
+// Reference extractor (deterministic, for tests — not for production use)
+// ---------------------------------------------------------------------------
+/**
+ * Reference UtteranceClaimExtractor for tests.
+ *
+ * REFERENCE IMPLEMENTATION ONLY — not suitable for production extraction.
+ *
+ * Parsing strategy: looks for statements matching the pattern:
+ *   "<subjectId> <fieldOrBehavior> is <value>"
+ * or
+ *   "<subjectId> <fieldOrBehavior>: <value>"
+ *
+ * where subjectId and fieldOrBehavior are single words. This intentionally
+ * simple and transparent pattern lets tests be deterministic.
+ *
+ * The subjectType is always "unknown" since it cannot be inferred from text
+ * alone in this reference implementation.
+ */
+export const referenceUtteranceExtractor = {
+    name: "reference-utterance-extractor",
+    extract(utterance) {
+        const results = [];
+        // Pattern: "<word> <word> is <value>" or "<word> <word>: <value>"
+        // Value is a single non-whitespace token; trailing punctuation is stripped.
+        const isPattern = /\b(\S+)\s+(\S+)\s+is\s+(\S+)/giu;
+        const colonPattern = /\b(\S+)\s+(\S+):\s*(\S+)/giu;
+        for (const pattern of [isPattern, colonPattern]) {
+            let match;
+            while ((match = pattern.exec(utterance)) !== null) {
+                const [full, subjectId, fieldOrBehavior, rawValue] = match;
+                if (!subjectId || !fieldOrBehavior || rawValue === undefined)
+                    continue;
+                const start = match.index;
+                const end = start + full.length;
+                // Strip trailing punctuation from the captured value
+                const value = rawValue.replace(/[.!?,;]+$/u, "");
+                results.push({
+                    target: {
+                        subjectType: "unknown",
+                        subjectId: subjectId.toLowerCase(),
+                        fieldOrBehavior: fieldOrBehavior.toLowerCase(),
+                    },
+                    value,
+                    excerpt: full.replace(/[.!?,;]+$/u, ""),
+                    span: { start, end },
+                    confidence: 0.6,
+                });
+            }
+        }
+        return results;
+    },
+};

package/dist/src/anthropic.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Anthropic production adapters for Survey's pluggable interfaces.
+ *
+ * ADR 0003 §4 compliance: these implementations are PROPOSERS only. Every
+ * output is a proposal (MappingProposal / ExtractedStatement) that goes
+ * through the existing review/auto-accept machinery before counting.
+ * Nothing here bypasses review.
+ *
+ * Subpath export: import from "@kontourai/survey/anthropic" — this module is
+ * NOT re-exported from the main index.ts so consumers without @anthropic-ai/sdk
+ * pay nothing.
+ *
+ * Injected client: both factories accept an optional pre-built client so tests
+ * can inject a fake without hitting the network. If no client is provided, one
+ * is constructed from opts.apiKey (falling back to process.env.ANTHROPIC_API_KEY).
+ */
+import type { MappingProposer } from "./inquiry-mapping.js";
+import type { UtteranceClaimExtractor } from "./agent-utterance.js";
+export interface AnthropicToolResultBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+}
+export interface AnthropicToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+}
+export type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+} | AnthropicToolUseBlock;
+export interface AnthropicMessage {
+    id: string;
+    type: "message";
+    role: "assistant";
+    content: AnthropicContentBlock[];
+    model: string;
+    stop_reason: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export interface AnthropicMessageCreateParams {
+    model: string;
+    max_tokens: number;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+    tools: AnthropicTool[];
+    tool_choice: {
+        type: "tool";
+        name: string;
+    };
+}
+/**
+ * Minimal interface matching @anthropic-ai/sdk Anthropic.messages.create.
+ * Accept the real SDK client or a test double.
+ */
+export interface AnthropicMessagesClient {
+    create(params: AnthropicMessageCreateParams): Promise<AnthropicMessage>;
+}
+export interface AnthropicAdapterOptions {
+    /** Injected client (real or mock). If absent, one is built from apiKey. */
+    client?: AnthropicMessagesClient;
+    /** API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Defaults to "claude-sonnet-4-6". */
+    model?: string;
+}
+/**
+ * Create a MappingProposer backed by Anthropic's API using forced tool-use.
+ *
+ * ADR 0003 §4: returns PROPOSALS only — they flow through the existing
+ * review/auto-accept machinery before counting as mappings.
+ *
+ * Tool output is validated strictly: malformed items (missing required fields,
+ * out-of-range confidence, no target and no rule) are filtered out rather than
+ * silently accepted.
+ */
+export declare function createAnthropicMappingProposer(opts?: AnthropicAdapterOptions): MappingProposer;
+/**
+ * Create a UtteranceClaimExtractor backed by Anthropic's API using forced tool-use.
+ *
+ * ADR 0003 §4: returns EXTRACTED STATEMENTS only — they carry full provenance
+ * (excerpt, span, extractor name, confidence) and flow through the Inquiry
+ * pipeline. They are never treated as authoritative.
+ *
+ * Malformed tool output is rejected/filtered — items missing required fields
+ * (subjectId, fieldOrBehavior, excerpt, confidence) are dropped.
+ */
+export declare function createAnthropicUtteranceExtractor(opts?: AnthropicAdapterOptions): UtteranceClaimExtractor;