@debriefer/ai 1.0.0

package/dist/ai-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-client.js","sourceRoot":"","sources":["../src/ai-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,SAAS,MAAM,mBAAmB,CAAA;AAoCzC;;;GAGG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAW;IACjB,KAAK,CAAQ;IAErB,YAAY,UAA+C,EAAE;QAC3D,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACvD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,2BAA2B,CAAA;IAC3D,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAA4B;QACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjD,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;YACrC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;SACpD,CAAC,CAAA;QAEF,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO;aAC1B,MAAM,CAAC,CAAC,KAAK,EAAgC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;aACtE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;aAC1B,IAAI,CAAC,EAAE,CAAC,CAAA;QAEX,OAAO;YACL,IAAI;YACJ,KAAK,EAAE;gBACL,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY;gBACxC,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa;aAC3C;SACF,CAAA;IACH,CAAC;CACF"}

package/dist/confidence.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AI-powered confidence scorer.
+ *
+ * Uses Claude Haiku to assess how relevant a piece of extracted text is
+ * to the research subject and goal, replacing keyword-based heuristics.
+ */
+import type { ResearchSubject } from "@debriefer/core";
+import type { AIClient } from "./ai-client.js";
+import type { TelemetryProvider } from "@debriefer/core";
+/**
+ * Creates a confidence scorer callback that uses AI to assess content relevance.
+ *
+ * When AI is unavailable or fails, falls back to a baseline score of 0.5
+ * (the same base score keyword matching gives when a required keyword is found).
+ */
+export declare function createAIConfidenceScorer(options: {
+    client: AIClient;
+    researchGoal?: string;
+    telemetry?: TelemetryProvider;
+    fallbackToHeuristics: boolean;
+}): (text: string, subject: ResearchSubject) => Promise<number>;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,QAAQ,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,oBAAoB,EAAE,OAAO,CAAA;CAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CA4C9D"}

package/dist/confidence.js

@@ -0,0 +1,53 @@
+/**
+ * AI-powered confidence scorer.
+ *
+ * Uses Claude Haiku to assess how relevant a piece of extracted text is
+ * to the research subject and goal, replacing keyword-based heuristics.
+ */
+import { stripMarkdownCodeFences } from "@debriefer/core";
+/**
+ * Creates a confidence scorer callback that uses AI to assess content relevance.
+ *
+ * When AI is unavailable or fails, falls back to a baseline score of 0.5
+ * (the same base score keyword matching gives when a required keyword is found).
+ */
+export function createAIConfidenceScorer(options) {
+    const { client, researchGoal, telemetry, fallbackToHeuristics } = options;
+    return async (text, subject) => {
+        if (!text || text.length === 0)
+            return 0;
+        // Truncate to keep prompt concise — first 2000 chars is enough for relevance
+        const truncatedText = text.length > 2000 ? text.slice(0, 2000) + "..." : text;
+        try {
+            const response = await client.complete({
+                system: "You are a research relevance scorer. Given a text and a research subject, " +
+                    "rate how relevant the text is to the subject on a scale of 0.0 to 1.0. " +
+                    "Respond ONLY with a single decimal number. No explanation.",
+                user: `Subject: ${subject.name}\n` +
+                    `Research goal: ${researchGoal ?? "Find information about this subject"}\n\n` +
+                    `Text:\n${truncatedText}\n\n` +
+                    "Relevance score (0.0-1.0):",
+                maxTokens: 32,
+            });
+            const cleaned = stripMarkdownCodeFences(response.text);
+            const score = parseFloat(cleaned);
+            if (!Number.isFinite(score) || score < 0 || score > 1) {
+                throw new Error(`Invalid score: ${cleaned}`);
+            }
+            return score;
+        }
+        catch (error) {
+            telemetry?.recordEvent("ai.call_failed", {
+                callback: "confidenceScorer",
+                error: error instanceof Error ? error.message : String(error),
+                fallback: fallbackToHeuristics,
+            });
+            if (fallbackToHeuristics) {
+                // Baseline score — equivalent to keyword match finding a required keyword
+                return 0.5;
+            }
+            return 0;
+        }
+    };
+}
+//# sourceMappingURL=confidence.js.map

package/dist/confidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.js","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAIzD;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAKxC;IACC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,OAAO,CAAA;IAEzE,OAAO,KAAK,EAAE,IAAY,EAAE,OAAwB,EAAmB,EAAE;QACvE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAA;QAExC,6EAA6E;QAC7E,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;QAE7E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;gBACrC,MAAM,EACJ,4EAA4E;oBAC5E,yEAAyE;oBACzE,4DAA4D;gBAC9D,IAAI,EACF,YAAY,OAAO,CAAC,IAAI,IAAI;oBAC5B,kBAAkB,YAAY,IAAI,qCAAqC,MAAM;oBAC7E,UAAU,aAAa,MAAM;oBAC7B,4BAA4B;gBAC9B,SAAS,EAAE,EAAE;aACd,CAAC,CAAA;YAEF,MAAM,OAAO,GAAG,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;YACtD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;YACjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAA;YAC9C,CAAC;YAED,OAAO,KAAK,CAAA;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE;gBACvC,QAAQ,EAAE,kBAAkB;gBAC5B,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,QAAQ,EAAE,oBAAoB;aAC/B,CAAC,CAAA;YAEF,IAAI,oBAAoB,EAAE,CAAC;gBACzB,0EAA0E;gBAC1E,OAAO,GAAG,CAAA;YACZ,CAAC;YACD,OAAO,CAAC,CAAA;QACV,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @debriefer/ai — AI-first defaults for the debriefer research engine.
+ *
+ * Provides `createAIDefaults()` which returns pre-built AI callbacks for
+ * section filtering, confidence scoring, link selection, and person validation.
+ * Also houses `ClaudeSynthesizer` (moved from @debriefer/core) making the
+ * core package fully zero-AI.
+ *
+ * @packageDocumentation
+ */
+import type { ResearchSubject, TelemetryProvider } from "@debriefer/core";
+import type { AsyncSectionFilter, WebSearchResult } from "@debriefer/sources";
+import type { AIClient } from "./ai-client.js";
+export { ClaudeSynthesizer } from "./synthesizer.js";
+export type { ClaudeSynthesizerOptions } from "./synthesizer.js";
+export type { AIClient, AICompletionRequest, AICompletionResponse } from "./ai-client.js";
+export { HaikuClient } from "./ai-client.js";
+/**
+ * Options for creating AI-powered defaults.
+ */
+export interface AIDefaultsOptions {
+    /** Anthropic API key. Defaults to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use for AI callbacks. Defaults to claude-haiku-4-5-20251001. */
+    model?: string;
+    /** Research goal injected into AI prompts for better relevance. */
+    researchGoal?: string;
+    /** Telemetry provider for logging AI call failures. */
+    telemetry?: TelemetryProvider;
+    /**
+     * Whether to fall back to heuristic behavior when AI calls fail.
+     * Default: true. When false, failures propagate as empty/zero results.
+     */
+    fallbackToHeuristics?: boolean;
+    /** Custom AI client for non-Anthropic providers. */
+    client?: AIClient;
+}
+/**
+ * Pre-built AI callbacks returned by `createAIDefaults()`.
+ */
+export interface AIDefaults {
+    /** AI section filter for Wikipedia sources. */
+    sectionFilter: AsyncSectionFilter;
+    /** AI confidence scorer for any source. */
+    confidenceScorer: (text: string, subject: ResearchSubject) => Promise<number>;
+    /** AI link ranker for web search sources. */
+    linkSelector: (results: WebSearchResult[], subject: ResearchSubject) => Promise<WebSearchResult[]>;
+    /** AI person validator for Wikipedia sources. */
+    personValidator: (articleText: string, subject: ResearchSubject) => Promise<boolean>;
+    /** Whether the AI client is available (API key is set). */
+    readonly isAvailable: boolean;
+}
+/**
+ * Create AI-powered defaults for debriefer source callbacks.
+ *
+ * Returns pre-built callbacks using Claude Haiku for section filtering,
+ * confidence scoring, link selection, and person validation. When
+ * `ANTHROPIC_API_KEY` is not set and no custom client is provided,
+ * records an `ai.unavailable` telemetry event and all callbacks fall
+ * through to heuristic behavior.
+ *
+ * @example
+ * ```typescript
+ * const ai = createAIDefaults({ researchGoal: "Find biographical information" })
+ *
+ * const sources = [
+ *   wikipedia({
+ *     asyncSectionFilter: ai.sectionFilter,
+ *     validatePerson: ai.personValidator,
+ *   }),
+ *   googleSearch({
+ *     linkSelector: ai.linkSelector,
+ *     confidenceScorer: ai.confidenceScorer,
+ *   }),
+ * ]
+ * ```
+ */
+export declare function createAIDefaults(options?: AIDefaultsOptions): AIDefaults;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAA;AAC/F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAQ9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAGhE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAM5C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,oDAAoD;IACpD,MAAM,CAAC,EAAE,QAAQ,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,aAAa,EAAE,kBAAkB,CAAA;IACjC,2CAA2C;IAC3C,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7E,6CAA6C;IAC7C,YAAY,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;IAClG,iDAAiD;IACjD,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACpF,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAsC5E"}

package/dist/index.js

@@ -0,0 +1,79 @@
+/**
+ * @debriefer/ai — AI-first defaults for the debriefer research engine.
+ *
+ * Provides `createAIDefaults()` which returns pre-built AI callbacks for
+ * section filtering, confidence scoring, link selection, and person validation.
+ * Also houses `ClaudeSynthesizer` (moved from @debriefer/core) making the
+ * core package fully zero-AI.
+ *
+ * @packageDocumentation
+ */
+import { HaikuClient } from "./ai-client.js";
+import { createAISectionFilter } from "./section-filter.js";
+import { createAIConfidenceScorer } from "./confidence.js";
+import { createAILinkSelector } from "./link-selector.js";
+import { createAIPersonValidator } from "./person-validator.js";
+// Re-export synthesizer (moved from core)
+export { ClaudeSynthesizer } from "./synthesizer.js";
+export { HaikuClient } from "./ai-client.js";
+/**
+ * Create AI-powered defaults for debriefer source callbacks.
+ *
+ * Returns pre-built callbacks using Claude Haiku for section filtering,
+ * confidence scoring, link selection, and person validation. When
+ * `ANTHROPIC_API_KEY` is not set and no custom client is provided,
+ * records an `ai.unavailable` telemetry event and all callbacks fall
+ * through to heuristic behavior.
+ *
+ * @example
+ * ```typescript
+ * const ai = createAIDefaults({ researchGoal: "Find biographical information" })
+ *
+ * const sources = [
+ *   wikipedia({
+ *     asyncSectionFilter: ai.sectionFilter,
+ *     validatePerson: ai.personValidator,
+ *   }),
+ *   googleSearch({
+ *     linkSelector: ai.linkSelector,
+ *     confidenceScorer: ai.confidenceScorer,
+ *   }),
+ * ]
+ * ```
+ */
+export function createAIDefaults(options = {}) {
+    const { apiKey, model, researchGoal, telemetry, fallbackToHeuristics = true } = options;
+    // Determine availability
+    const effectiveKey = apiKey || process.env.ANTHROPIC_API_KEY;
+    const hasApiKey = !!effectiveKey;
+    const hasCustomClient = !!options.client;
+    const available = hasApiKey || hasCustomClient;
+    // If unavailable, log via telemetry and return passthrough callbacks
+    if (!available) {
+        telemetry?.recordEvent("ai.unavailable", {
+            reason: "ANTHROPIC_API_KEY not set. AI features disabled — using heuristic fallbacks.",
+        });
+        return {
+            sectionFilter: async (sections) => sections,
+            confidenceScorer: async () => 0.5,
+            linkSelector: async (results) => results,
+            personValidator: async () => true,
+            get isAvailable() {
+                return false;
+            },
+        };
+    }
+    // Create AI client (or use custom)
+    const client = options.client ?? new HaikuClient({ apiKey: effectiveKey, model });
+    const commonOptions = { client, researchGoal, telemetry, fallbackToHeuristics };
+    return {
+        sectionFilter: createAISectionFilter(commonOptions),
+        confidenceScorer: createAIConfidenceScorer(commonOptions),
+        linkSelector: createAILinkSelector(commonOptions),
+        personValidator: createAIPersonValidator(commonOptions),
+        get isAvailable() {
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE/D,0CAA0C;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAKpD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AA2C5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA6B,EAAE;IAC9D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;IAEvF,yBAAyB;IACzB,MAAM,YAAY,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAA;IAC5D,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAA;IAChC,MAAM,eAAe,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAA;IACxC,MAAM,SAAS,GAAG,SAAS,IAAI,eAAe,CAAA;IAE9C,qEAAqE;IACrE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE;YACvC,MAAM,EAAE,8EAA8E;SACvF,CAAC,CAAA;QACF,OAAO;YACL,aAAa,EAAE,KAAK,EAAE,QAA4B,EAAE,EAAE,CAAC,QAAQ;YAC/D,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,GAAG;YACjC,YAAY,EAAE,KAAK,EAAE,OAA0B,EAAE,EAAE,CAAC,OAAO;YAC3D,eAAe,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;YACjC,IAAI,WAAW;gBACb,OAAO,KAAK,CAAA;YACd,CAAC;SACF,CAAA;IACH,CAAC;IAED,mCAAmC;IACnC,MAAM,MAAM,GAAa,OAAO,CAAC,MAAM,IAAI,IAAI,WAAW,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAA;IAC3F,MAAM,aAAa,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAA;IAE/E,OAAO;QACL,aAAa,EAAE,qBAAqB,CAAC,aAAa,CAAC;QACnD,gBAAgB,EAAE,wBAAwB,CAAC,aAAa,CAAC;QACzD,YAAY,EAAE,oBAAoB,CAAC,aAAa,CAAC;QACjD,eAAe,EAAE,uBAAuB,CAAC,aAAa,CAAC;QACvD,IAAI,WAAW;YACb,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/link-selector.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AI-powered link selector for web search sources.
+ *
+ * Uses Claude Haiku to rank and filter search result URLs by relevance
+ * to the research subject, replacing heuristic domain/keyword scoring.
+ */
+import type { ResearchSubject } from "@debriefer/core";
+import type { WebSearchResult } from "@debriefer/sources";
+import type { AIClient } from "./ai-client.js";
+import type { TelemetryProvider } from "@debriefer/core";
+/**
+ * Creates a link selector callback that uses AI to rank search results.
+ *
+ * When AI is unavailable or fails, falls back to returning results
+ * unchanged (preserving the search engine's original ordering).
+ */
+export declare function createAILinkSelector(options: {
+    client: AIClient;
+    researchGoal?: string;
+    telemetry?: TelemetryProvider;
+    fallbackToHeuristics: boolean;
+}): (results: WebSearchResult[], subject: ResearchSubject) => Promise<WebSearchResult[]>;
+//# sourceMappingURL=link-selector.d.ts.map

package/dist/link-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-selector.d.ts","sourceRoot":"","sources":["../src/link-selector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,MAAM,EAAE,QAAQ,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,oBAAoB,EAAE,OAAO,CAAA;CAC9B,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAkEvF"}

package/dist/link-selector.js

@@ -0,0 +1,67 @@
+/**
+ * AI-powered link selector for web search sources.
+ *
+ * Uses Claude Haiku to rank and filter search result URLs by relevance
+ * to the research subject, replacing heuristic domain/keyword scoring.
+ */
+import { stripMarkdownCodeFences } from "@debriefer/core";
+/**
+ * Creates a link selector callback that uses AI to rank search results.
+ *
+ * When AI is unavailable or fails, falls back to returning results
+ * unchanged (preserving the search engine's original ordering).
+ */
+export function createAILinkSelector(options) {
+    const { client, researchGoal, telemetry, fallbackToHeuristics } = options;
+    return async (results, subject) => {
+        if (results.length === 0)
+            return [];
+        const resultList = results
+            .map((r, i) => `${i}: ${r.title} — ${r.url}\n   ${r.snippet}`)
+            .join("\n");
+        try {
+            const response = await client.complete({
+                system: "You are a research assistant that ranks web search results by relevance. " +
+                    "Respond ONLY with a JSON array of result indices in order of relevance " +
+                    "(most relevant first). No explanation.",
+                user: `Subject: ${subject.name}\n` +
+                    `Research goal: ${researchGoal ?? "Find information about this subject"}\n\n` +
+                    `Search results:\n${resultList}\n\n` +
+                    "Rank these results by relevance. Return a JSON array of indices, e.g. [2, 0, 1].",
+                maxTokens: 256,
+            });
+            const indices = JSON.parse(stripMarkdownCodeFences(response.text));
+            if (!Array.isArray(indices)) {
+                throw new Error("Expected array of indices");
+            }
+            const validIndices = indices.filter((i) => typeof i === "number" && Number.isInteger(i) && i >= 0 && i < results.length);
+            // Build reordered list; append any results not mentioned by AI at the end
+            const reordered = [];
+            const used = new Set();
+            for (const idx of validIndices) {
+                if (!used.has(idx)) {
+                    reordered.push(results[idx]);
+                    used.add(idx);
+                }
+            }
+            for (let i = 0; i < results.length; i++) {
+                if (!used.has(i)) {
+                    reordered.push(results[i]);
+                }
+            }
+            return reordered;
+        }
+        catch (error) {
+            telemetry?.recordEvent("ai.call_failed", {
+                callback: "linkSelector",
+                error: error instanceof Error ? error.message : String(error),
+                fallback: fallbackToHeuristics,
+            });
+            if (fallbackToHeuristics) {
+                return results;
+            }
+            return [];
+        }
+    };
+}
+//# sourceMappingURL=link-selector.js.map

package/dist/link-selector.js.map

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

package/dist/person-validator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AI-powered person validator for Wikipedia source.
+ *
+ * Uses Claude Haiku to verify that a Wikipedia article is about the
+ * intended person, replacing regex/date-based heuristics.
+ */
+import type { ResearchSubject } from "@debriefer/core";
+import type { AIClient } from "./ai-client.js";
+import type { TelemetryProvider } from "@debriefer/core";
+/**
+ * Creates a person validator callback that uses AI to verify article matches.
+ *
+ * When AI is unavailable or fails, falls back to returning true
+ * (optimistically assuming the article matches, same as no validator).
+ */
+export declare function createAIPersonValidator(options: {
+    client: AIClient;
+    telemetry?: TelemetryProvider;
+    fallbackToHeuristics: boolean;
+}): (articleText: string, subject: ResearchSubject) => Promise<boolean>;
+//# sourceMappingURL=person-validator.d.ts.map

package/dist/person-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"person-validator.d.ts","sourceRoot":"","sources":["../src/person-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,MAAM,EAAE,QAAQ,CAAA;IAChB,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,oBAAoB,EAAE,OAAO,CAAA;CAC9B,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAyDtE"}

package/dist/person-validator.js

@@ -0,0 +1,63 @@
+/**
+ * AI-powered person validator for Wikipedia source.
+ *
+ * Uses Claude Haiku to verify that a Wikipedia article is about the
+ * intended person, replacing regex/date-based heuristics.
+ */
+/**
+ * Creates a person validator callback that uses AI to verify article matches.
+ *
+ * When AI is unavailable or fails, falls back to returning true
+ * (optimistically assuming the article matches, same as no validator).
+ */
+export function createAIPersonValidator(options) {
+    const { client, telemetry, fallbackToHeuristics } = options;
+    return async (articleText, subject) => {
+        if (!articleText || articleText.length === 0)
+            return false;
+        // Truncate to intro section — that's usually enough for identification
+        const truncatedText = articleText.length > 2000 ? articleText.slice(0, 2000) + "..." : articleText;
+        // Build context hints from subject metadata
+        const hints = [];
+        if (subject.context) {
+            if (subject.context.birthYear || subject.context.birthday) {
+                hints.push(`Born: ${subject.context.birthYear ?? subject.context.birthday}`);
+            }
+            if (subject.context.deathYear || subject.context.deathday) {
+                hints.push(`Died: ${subject.context.deathYear ?? subject.context.deathday}`);
+            }
+            if (subject.context.occupation) {
+                hints.push(`Occupation: ${subject.context.occupation}`);
+            }
+        }
+        const contextStr = hints.length > 0 ? `\nKnown details: ${hints.join(", ")}` : "";
+        try {
+            const response = await client.complete({
+                system: "You are verifying whether a Wikipedia article is about a specific person. " +
+                    "Respond ONLY with 'true' or 'false'. No explanation.",
+                user: `Person: ${subject.name}${contextStr}\n\n` +
+                    `Article text:\n${truncatedText}\n\n` +
+                    "Is this article about the person described above? Answer true or false.",
+                maxTokens: 8,
+            });
+            const answer = response.text
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z]/g, "");
+            return answer === "true" || answer === "yes";
+        }
+        catch (error) {
+            telemetry?.recordEvent("ai.call_failed", {
+                callback: "personValidator",
+                error: error instanceof Error ? error.message : String(error),
+                fallback: fallbackToHeuristics,
+            });
+            if (fallbackToHeuristics) {
+                // Optimistic fallback — assume it's the right person
+                return true;
+            }
+            return false;
+        }
+    };
+}
+//# sourceMappingURL=person-validator.js.map

package/dist/person-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"person-validator.js","sourceRoot":"","sources":["../src/person-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAIvC;IACC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,OAAO,CAAA;IAE3D,OAAO,KAAK,EAAE,WAAmB,EAAE,OAAwB,EAAoB,EAAE;QAC/E,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;QAE1D,uEAAuE;QACvE,MAAM,aAAa,GACjB,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,CAAA;QAE9E,4CAA4C;QAC5C,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBAC1D,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;YAC9E,CAAC;YACD,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBAC1D,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;YAC9E,CAAC;YACD,IAAI,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBAC/B,KAAK,CAAC,IAAI,CAAC,eAAe,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;YACzD,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAEjF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;gBACrC,MAAM,EACJ,4EAA4E;oBAC5E,sDAAsD;gBACxD,IAAI,EACF,WAAW,OAAO,CAAC,IAAI,GAAG,UAAU,MAAM;oBAC1C,kBAAkB,aAAa,MAAM;oBACrC,yEAAyE;gBAC3E,SAAS,EAAE,CAAC;aACb,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI;iBACzB,IAAI,EAAE;iBACN,WAAW,EAAE;iBACb,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;YACzB,OAAO,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,CAAA;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE;gBACvC,QAAQ,EAAE,iBAAiB;gBAC3B,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,QAAQ,EAAE,oBAAoB;aAC/B,CAAC,CAAA;YAEF,IAAI,oBAAoB,EAAE,CAAC;gBACzB,qDAAqD;gBACrD,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/section-filter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AI-powered Wikipedia section filter.
+ *
+ * Uses Claude Haiku to select the most relevant sections from a Wikipedia
+ * article based on the research goal, replacing regex-based section matching.
+ */
+import type { WikipediaSection } from "@debriefer/sources";
+import type { AIClient } from "./ai-client.js";
+import type { TelemetryProvider } from "@debriefer/core";
+/**
+ * Creates an AsyncSectionFilter that uses AI to select relevant Wikipedia sections.
+ *
+ * When AI is unavailable or fails, falls back to returning all sections
+ * (matching the default behavior).
+ */
+export declare function createAISectionFilter(options: {
+    client: AIClient;
+    researchGoal?: string;
+    telemetry?: TelemetryProvider;
+    fallbackToHeuristics: boolean;
+}): (sections: WikipediaSection[], articleText: string) => Promise<WikipediaSection[]>;
+//# sourceMappingURL=section-filter.d.ts.map

package/dist/section-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-filter.d.ts","sourceRoot":"","sources":["../src/section-filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,MAAM,EAAE,QAAQ,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,oBAAoB,EAAE,OAAO,CAAA;CAC9B,GAAG,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAkDrF"}

package/dist/section-filter.js

@@ -0,0 +1,54 @@
+/**
+ * AI-powered Wikipedia section filter.
+ *
+ * Uses Claude Haiku to select the most relevant sections from a Wikipedia
+ * article based on the research goal, replacing regex-based section matching.
+ */
+import { stripMarkdownCodeFences } from "@debriefer/core";
+/**
+ * Creates an AsyncSectionFilter that uses AI to select relevant Wikipedia sections.
+ *
+ * When AI is unavailable or fails, falls back to returning all sections
+ * (matching the default behavior).
+ */
+export function createAISectionFilter(options) {
+    const { client, researchGoal, telemetry, fallbackToHeuristics } = options;
+    return async (sections, articleText) => {
+        if (sections.length === 0)
+            return [];
+        const sectionList = sections.map((s) => `${s.index}: ${s.title} (depth ${s.depth})`).join("\n");
+        // Truncate article text to keep prompt concise
+        const truncatedText = articleText.length > 3000 ? articleText.slice(0, 3000) + "..." : articleText;
+        try {
+            const response = await client.complete({
+                system: "You are a research assistant that selects relevant Wikipedia sections. " +
+                    "Respond ONLY with a JSON array of section indices (numbers). No explanation.",
+                user: `Research goal: ${researchGoal ?? "Find biographical information"}\n\n` +
+                    `Article sections:\n${sectionList}\n\n` +
+                    `Article preview:\n${truncatedText}\n\n` +
+                    "Which section indices are most relevant to the research goal? " +
+                    "Return a JSON array of numbers, e.g. [0, 3, 5].",
+                maxTokens: 256,
+            });
+            const indices = JSON.parse(stripMarkdownCodeFences(response.text));
+            if (!Array.isArray(indices)) {
+                throw new Error("Expected array of indices");
+            }
+            const validIndices = new Set(indices.filter((i) => typeof i === "number" && Number.isInteger(i)));
+            const selected = sections.filter((s) => validIndices.has(s.index));
+            return selected.length > 0 ? selected : sections;
+        }
+        catch (error) {
+            telemetry?.recordEvent("ai.call_failed", {
+                callback: "sectionFilter",
+                error: error instanceof Error ? error.message : String(error),
+                fallback: fallbackToHeuristics,
+            });
+            if (fallbackToHeuristics) {
+                return sections;
+            }
+            return [];
+        }
+    };
+}
+//# sourceMappingURL=section-filter.js.map

package/dist/section-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-filter.js","sourceRoot":"","sources":["../src/section-filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAIzD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAKrC;IACC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,OAAO,CAAA;IAEzE,OAAO,KAAK,EAAE,QAA4B,EAAE,WAAmB,EAA+B,EAAE;QAC9F,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QAEpC,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAE/F,+CAA+C;QAC/C,MAAM,aAAa,GACjB,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,CAAA;QAE9E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;gBACrC,MAAM,EACJ,yEAAyE;oBACzE,8EAA8E;gBAChF,IAAI,EACF,kBAAkB,YAAY,IAAI,+BAA+B,MAAM;oBACvE,sBAAsB,WAAW,MAAM;oBACvC,qBAAqB,aAAa,MAAM;oBACxC,gEAAgE;oBAChE,iDAAiD;gBACnD,SAAS,EAAE,GAAG;aACf,CAAC,CAAA;YAEF,MAAM,OAAO,GAAY,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;YAC3E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAA;YAC9C,CAAC;YAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CACjF,CAAA;YAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;YAClE,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE;gBACvC,QAAQ,EAAE,eAAe;gBACzB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,QAAQ,EAAE,oBAAoB;aAC/B,CAAC,CAAA;YAEF,IAAI,oBAAoB,EAAE,CAAC;gBACzB,OAAO,QAAQ,CAAA;YACjB,CAAC;YACD,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/synthesizer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 type { ResearchSubject, ScoredFinding, SynthesisOptions, SynthesisResult, Synthesizer } from "@debriefer/core";
+/**
+ * Options for constructing a ClaudeSynthesizer.
+ *
+ * @typeParam TSubject - The research subject type (extends ResearchSubject)
+ * @typeParam TOutput - The structured output type produced by synthesis
+ */
+export interface ClaudeSynthesizerOptions<TSubject extends ResearchSubject, TOutput> {
+    /**
+     * Build the system prompt and user message from the subject and findings.
+     * This is where all domain knowledge lives -- the synthesizer itself is
+     * domain-agnostic.
+     */
+    promptBuilder: (subject: TSubject, findings: ScoredFinding[]) => {
+        system: string;
+        user: string;
+    };
+    /**
+     * Parse and validate the raw JSON response into the output type.
+     * Required to ensure type safety at runtime — the AI response is untrusted.
+     *
+     * @example
+     * ```typescript
+     * responseParser: (raw) => myZodSchema.parse(raw)
+     * ```
+     */
+    responseParser: (raw: unknown) => TOutput;
+    /** Anthropic API key. Defaults to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Default model. Can be overridden per-call via SynthesisOptions. */
+    defaultModel?: string;
+    /** Default max tokens. Can be overridden per-call. */
+    defaultMaxTokens?: number;
+}
+/**
+ * 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 declare class ClaudeSynthesizer<TSubject extends ResearchSubject, TOutput> implements Synthesizer<TSubject, TOutput> {
+    private client;
+    private options;
+    constructor(options: ClaudeSynthesizerOptions<TSubject, TOutput>);
+    /**
+     * 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
+     */
+    synthesize(subject: TSubject, findings: ScoredFinding[], options?: SynthesisOptions): Promise<SynthesisResult<TOutput>>;
+}
+//# sourceMappingURL=synthesizer.d.ts.map

package/dist/synthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizer.d.ts","sourceRoot":"","sources":["../src/synthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAGxB;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,eAAe,EAAE,OAAO;IACjF;;;;OAIG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAEjG;;;;;;;;OAQG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAA;IAEzC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,iBAAiB,CAAC,QAAQ,SAAS,eAAe,EAAE,OAAO,CAAE,YAAW,WAAW,CAC9F,QAAQ,EACR,OAAO,CACR;IACC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,OAAO,CAA6C;gBAEhD,OAAO,EAAE,wBAAwB,CAAC,QAAQ,EAAE,OAAO,CAAC;IAKhE;;;;;;;;;;;;OAYG;IACG,UAAU,CACd,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;CAmDrC"}