@debriefer/ai 1.0.0

package/dist/synthesizer.js

@@ -0,0 +1,127 @@
+/**
+ * AI synthesis module for distilling scored findings into structured output.
+ *
+ * Provides ClaudeSynthesizer (Anthropic Claude API). NoopSynthesizer
+ * (pass-through) remains in @debriefer/core.
+ *
+ * The consumer controls domain-specific behavior via promptBuilder and
+ * responseParser callbacks. The synthesizer handles API calls, cost
+ * calculation, JSON parsing, and code fence stripping.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { stripMarkdownCodeFences } from "@debriefer/core";
+/**
+ * Approximate cost per million tokens by model family (USD).
+ * Used for cost estimation in SynthesisResult.
+ *
+ * These are approximate and may not reflect current Anthropic pricing.
+ * Consumers should verify costs against https://docs.anthropic.com/en/docs/about-claude/models
+ * Falls back to Sonnet pricing for unrecognized model families.
+ */
+const MODEL_COSTS = {
+    "claude-sonnet": { input: 3, output: 15 },
+    "claude-opus": { input: 15, output: 75 },
+    "claude-haiku": { input: 0.25, output: 1.25 },
+};
+/**
+ * Look up per-million-token costs for a model string.
+ * Falls back to Sonnet pricing if the model family is unrecognized.
+ */
+function getModelCosts(model) {
+    for (const [family, costs] of Object.entries(MODEL_COSTS)) {
+        if (model.includes(family))
+            return costs;
+    }
+    // Default to Sonnet pricing if unknown
+    return { input: 3, output: 15 };
+}
+/**
+ * Claude-powered synthesizer that distills scored findings into structured output.
+ *
+ * The consumer provides:
+ * - `promptBuilder`: converts subject + findings into system/user prompts
+ * - `responseParser`: validates/transforms the raw JSON response
+ *
+ * The synthesizer handles:
+ * - Anthropic API calls with configurable model and max tokens
+ * - JSON parsing with code fence stripping
+ * - Cost calculation from token usage
+ * - Sorting findings by reliability before passing to the prompt builder
+ *
+ * @typeParam TSubject - The research subject type
+ * @typeParam TOutput - The structured output type
+ *
+ * @example
+ * ```typescript
+ * const synthesizer = new ClaudeSynthesizer<ActorSubject, DeathInfo>({
+ *   promptBuilder: (actor, findings) => ({
+ *     system: "You are extracting death information...",
+ *     user: `Actor: ${actor.name}\nFindings:\n${findings.map(f => f.text).join("\n")}`,
+ *   }),
+ *   responseParser: (raw) => DeathInfoSchema.parse(raw),
+ * })
+ * ```
+ */
+export class ClaudeSynthesizer {
+    client;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.client = new Anthropic({ apiKey: options.apiKey });
+    }
+    /**
+     * Synthesize scored findings into structured output via Claude API.
+     *
+     * Findings are sorted by reliability score (highest first) before being
+     * passed to the prompt builder, so higher-quality sources appear first
+     * in the prompt.
+     *
+     * @param subject - The research subject
+     * @param findings - Scored findings from source lookups
+     * @param options - Per-call overrides for model, max tokens, etc.
+     * @returns Synthesis result with structured output and cost metadata
+     * @throws Error if Claude returns no text content or unparseable JSON
+     */
+    async synthesize(subject, findings, options = {}) {
+        const model = options.model ?? this.options.defaultModel ?? "claude-sonnet-4-20250514";
+        const maxTokens = options.maxTokens ?? this.options.defaultMaxTokens ?? 4096;
+        // Sort findings by reliability score (highest first) so the prompt
+        // builder receives the most trustworthy sources at the top
+        const sortedFindings = [...findings].sort((a, b) => b.reliabilityScore - a.reliabilityScore);
+        // Build prompt via consumer-provided builder
+        const { system, user } = this.options.promptBuilder(subject, sortedFindings);
+        // Call Claude API
+        const response = await this.client.messages.create({
+            model,
+            max_tokens: maxTokens,
+            system,
+            messages: [{ role: "user", content: user }],
+        });
+        // Extract text content from response blocks
+        const responseText = response.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("");
+        if (!responseText) {
+            throw new Error("No text response from Claude");
+        }
+        // Parse JSON, stripping any code fences Claude may have added
+        const cleanJson = stripMarkdownCodeFences(responseText);
+        const rawParsed = JSON.parse(cleanJson);
+        // Validate through consumer's parser (required for type safety)
+        const data = this.options.responseParser(rawParsed);
+        // Calculate cost from token usage
+        const inputTokens = response.usage.input_tokens;
+        const outputTokens = response.usage.output_tokens;
+        const costs = getModelCosts(model);
+        const costUsd = (inputTokens * costs.input) / 1_000_000 + (outputTokens * costs.output) / 1_000_000;
+        return {
+            data,
+            costUsd,
+            inputTokens,
+            outputTokens,
+            model,
+        };
+    }
+}
+//# sourceMappingURL=synthesizer.js.map

package/dist/synthesizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizer.js","sourceRoot":"","sources":["../src/synthesizer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@debriefer/ai",
+  "version": "1.0.0",
+  "description": "AI-first defaults for debriefer: Claude-powered synthesis, section filtering, confidence scoring, link selection, and person validation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "debriefer",
+    "ai",
+    "claude",
+    "anthropic",
+    "research",
+    "synthesis"
+  ],
+  "author": "Chris Henderson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenders/debriefer.git",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://github.com/chenders/debriefer#readme",
+  "bugs": {
+    "url": "https://github.com/chenders/debriefer/issues"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": ">=0.39.0 <1"
+  },
+  "peerDependencies": {
+    "@debriefer/core": ">=2.0.0",
+    "@debriefer/sources": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@debriefer/sources": {
+      "optional": true
+    }
+  }
+}