@compresr/sdk 1.5.4 → 1.6.0

package/dist/esm/agents/research/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../src/agents/research/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAY,cAAc,EAAuB,MAAM,YAAY,CAAC;AAEhF,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,IAAI,EAAE;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,GAAG,OAAO,CAAC;QACV,IAAI,CAAC,EAAE;YAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC;YAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACpE,CAAC,CAAC;CACJ;AAED,UAAU,aAAa;IACrB,SAAS,CACP,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAC7B,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAC/B;QAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;CACtD;AAED,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzD,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,EAAE;QAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;QAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAwBD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,EAAE,oBAAoB;IAWnC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAE,kBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC;IAyFzF;;;OAGG;IACH,OAAO,CAAC,iBAAiB;YAmCX,YAAY;YAcZ,QAAQ;IAiBtB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,gBAAgB;CAazB"}

package/dist/esm/agents/research/agent.js

@@ -0,0 +1,292 @@
+/**
+ * `ResearchAgent` — strict-output ReAct loop with per-snippet compression.
+ *
+ * Mirrors the Python implementation in `compresr/agents/research/agent.py`.
+ * Bypasses `_Engine.run` so we can set `tool_choice` per step and compress
+ * each tool result before it enters the conversation.
+ */
+import { parseResearchOutput } from './parser.js';
+import { DEFAULT_RESEARCH_SYSTEM_PROMPT } from './prompts.js';
+const DEFAULT_MAX_CONTEXT_TOKENS = 120_000;
+const DEFAULT_MAX_STEPS = 10;
+const DEFAULT_MIN_COMPRESS_TOKENS = 100;
+const CACHE_READ_ALIASES = [
+    'cached_tokens',
+    'cache_read',
+    'priority_cache_read',
+    'flex_cache_read',
+    'cached_content_token_count',
+];
+function estimateTokens(text) {
+    return Math.max(1, Math.floor(text.length / 4));
+}
+function stringifyContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const block of content) {
+            if (block && typeof block === 'object' && 'text' in block) {
+                const t = block.text;
+                if (typeof t === 'string')
+                    parts.push(t);
+            }
+            else if (typeof block === 'string') {
+                parts.push(block);
+            }
+        }
+        return parts.join('');
+    }
+    if (content == null)
+        return '';
+    if (typeof content === 'number' || typeof content === 'boolean')
+        return String(content);
+    return JSON.stringify(content);
+}
+function readCacheTokens(details) {
+    if (!details)
+        return { read: 0, create: 0 };
+    let read = 0;
+    for (const alias of CACHE_READ_ALIASES) {
+        const v = details[alias];
+        if (typeof v === 'number')
+            read += v;
+    }
+    // langchain-anthropic zeros ``cache_creation`` when ttl-specific keys are set.
+    const ttl5 = typeof details['ephemeral_5m_input_tokens'] === 'number'
+        ? (details['ephemeral_5m_input_tokens']) : 0;
+    const ttl1 = typeof details['ephemeral_1h_input_tokens'] === 'number'
+        ? (details['ephemeral_1h_input_tokens']) : 0;
+    const gen = typeof details['cache_creation'] === 'number'
+        ? (details['cache_creation']) : 0;
+    const create = ttl5 + ttl1 > 0 ? ttl5 + ttl1 : gen;
+    return { read, create };
+}
+export class ResearchAgent {
+    engine;
+    searchTool;
+    maxSteps;
+    systemPrompt;
+    compressSnippets;
+    compressionModel;
+    minCompressTokens;
+    maxContextTokens;
+    constructor(options) {
+        this.engine = options.engine;
+        this.searchTool = options.searchTool;
+        this.maxSteps = Math.max(1, options.maxSteps ?? DEFAULT_MAX_STEPS);
+        this.systemPrompt = options.systemPrompt ?? DEFAULT_RESEARCH_SYSTEM_PROMPT;
+        this.compressSnippets = options.compressSnippets ?? true;
+        this.compressionModel = options.compressionModel ?? 'latte_v1';
+        this.minCompressTokens = options.minCompressTokens ?? DEFAULT_MIN_COMPRESS_TOKENS;
+        this.maxContextTokens = options.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+    }
+    async run(question, runOptions = {}) {
+        const { SystemMessage, HumanMessage, ToolMessage } = await import('@langchain/core/messages');
+        const modelName = this.engine._resolveModel(runOptions.model);
+        const chat = await this.engine._getChatModel(modelName);
+        const messages = [
+            new SystemMessage(this.systemPrompt),
+            new HumanMessage(question),
+        ];
+        const aiHistory = [];
+        const trajectory = [];
+        let lastAi = null;
+        for (let stepIdx = 0; stepIdx < this.maxSteps; stepIdx++) {
+            this.maybeTruncate(messages);
+            const toolChoice = stepIdx === this.maxSteps - 1 ? 'none' : 'auto';
+            const bound = chat.bindTools([this.searchTool], { tool_choice: toolChoice });
+            const invokeMessages = this.applyCacheControl(messages);
+            const t0 = Date.now();
+            let response;
+            try {
+                response = (await bound.invoke(invokeMessages));
+            }
+            catch (exc) {
+                trajectory.push({
+                    type: 'error',
+                    text: exc instanceof Error ? exc.message : String(exc),
+                    latencyS: (Date.now() - t0) / 1000,
+                });
+                break;
+            }
+            const stepLatencyS = (Date.now() - t0) / 1000;
+            aiHistory.push(response);
+            lastAi = response;
+            messages.push(response);
+            const toolCalls = response.tool_calls ?? [];
+            if (toolCalls.length === 0) {
+                trajectory.push({
+                    type: 'answer',
+                    text: stringifyContent(response.content),
+                    latencyS: stepLatencyS,
+                });
+                break;
+            }
+            for (const tc of toolCalls) {
+                const args = tc.args ?? {};
+                const query = typeof args['query'] === 'string' ? (args['query']) : undefined;
+                trajectory.push({ type: 'search', query, latencyS: stepLatencyS });
+                const rawResult = await this.invokeSearch(args);
+                const finalResult = this.compressSnippets
+                    ? await this.compress(rawResult, query ?? question)
+                    : rawResult;
+                trajectory.push({ type: 'tool_result', chars: finalResult.length, text: finalResult });
+                messages.push(new ToolMessage({
+                    content: finalResult,
+                    tool_call_id: tc.id ?? '',
+                    name: this.searchTool.name ?? 'search_web',
+                }));
+            }
+        }
+        const usage = this.aggregateUsage(aiHistory);
+        const finalText = lastAi ? stringifyContent(lastAi.content) : '';
+        const parsed = parseResearchOutput(finalText);
+        const citations = this.collectCitations(parsed.citationUrls, trajectory);
+        return {
+            answer: parsed.answer,
+            explanation: parsed.explanation,
+            confidence: parsed.confidence,
+            text: finalText,
+            citations,
+            trajectory,
+            usage,
+            raw: lastAi,
+        };
+    }
+    /**
+     * Mirrors AnthropicPromptCachingMiddleware for the bypass path — research
+     * doesn't go through createAgent so we stamp cache_control manually.
+     */
+    applyCacheControl(messages) {
+        if (this.engine.provider !== 'anthropic')
+            return messages;
+        const cfg = this.engine._promptCacheConfig;
+        if (!cfg?.enabled)
+            return messages;
+        if (messages.length < cfg.minMessages)
+            return messages;
+        const marker = { type: 'ephemeral', ttl: cfg.ttl };
+        const last = messages[messages.length - 1];
+        const content = last?.content;
+        let newContent;
+        if (typeof content === 'string') {
+            newContent = [{ type: 'text', text: content, cache_control: marker }];
+        }
+        else if (Array.isArray(content) && content.length > 0) {
+            newContent = [...content];
+            const tail = newContent[newContent.length - 1];
+            if (tail !== null && typeof tail === 'object') {
+                newContent[newContent.length - 1] = {
+                    ...tail,
+                    cache_control: marker,
+                };
+            }
+            else {
+                const tailText = typeof tail === 'string' ? tail : '';
+                newContent.push({ type: 'text', text: tailText, cache_control: marker });
+            }
+        }
+        else {
+            return messages;
+        }
+        const Ctor = last.constructor;
+        const patched = new Ctor({ content: newContent });
+        return [...messages.slice(0, -1), patched];
+    }
+    async invokeSearch(args) {
+        try {
+            const out = await this.searchTool.invoke(args);
+            if (typeof out === 'string')
+                return out;
+            if (out == null)
+                return '';
+            return JSON.stringify(out);
+        }
+        catch (exc) {
+            const msg = exc instanceof Error ? exc.message : String(exc);
+            // eslint-disable-next-line no-console
+            console.warn(`[compresr.research] search tool raised: ${msg}; continuing.`);
+            return `Search error: ${msg}`;
+        }
+    }
+    async compress(text, query) {
+        if (!text || estimateTokens(text) < this.minCompressTokens)
+            return text;
+        const client = this.engine._compresrClient;
+        if (!client?.compress)
+            return text;
+        try {
+            const resp = await client.compress({
+                context: text,
+                query,
+                compressionModelName: this.compressionModel,
+            });
+            const cc = resp?.data?.compressedContext ?? resp?.data?.compressed_context;
+            return typeof cc === 'string' && cc.length > 0 ? cc : text;
+        }
+        catch {
+            return text;
+        }
+    }
+    maybeTruncate(messages) {
+        if (!this.maxContextTokens)
+            return;
+        const total = () => messages.reduce((acc, m) => acc + estimateTokens(stringifyContent(m?.content)), 0);
+        let cur = total();
+        if (cur <= this.maxContextTokens)
+            return;
+        let guard = 0;
+        while (cur > this.maxContextTokens && messages.length >= 4 && guard < 4) {
+            messages.splice(2, 2);
+            cur = total();
+            guard++;
+        }
+    }
+    aggregateUsage(aiMessages) {
+        const totals = {
+            input_tokens: 0,
+            output_tokens: 0,
+            cache_read_tokens: 0,
+            cache_creation_tokens: 0,
+        };
+        for (const m of aiMessages) {
+            const um = m?.usage_metadata ?? {};
+            const inTok = typeof um['input_tokens'] === 'number' ? (um['input_tokens']) : 0;
+            totals['output_tokens'] += typeof um['output_tokens'] === 'number'
+                ? (um['output_tokens']) : 0;
+            const details = um['input_token_details'];
+            const { read, create } = readCacheTokens(details);
+            totals['cache_read_tokens'] += read;
+            totals['cache_creation_tokens'] += create;
+            // langchain-anthropic 1.x inflates input_tokens to fresh+read+create.
+            const overcount = read + create;
+            totals['input_tokens'] += Math.max(0, inTok - overcount);
+        }
+        return {
+            input_tokens: totals['input_tokens'],
+            output_tokens: totals['output_tokens'],
+            cache_read_tokens: totals['cache_read_tokens'],
+            cache_creation_tokens: totals['cache_creation_tokens'],
+            calls: aiMessages.length,
+        };
+    }
+    collectCitations(parsedUrls, trajectory) {
+        const urls = [];
+        for (const u of parsedUrls)
+            if (!urls.includes(u))
+                urls.push(u);
+        const urlRe = /https?:\/\/[^\s,;<>"')]+/g;
+        for (const step of trajectory) {
+            if (step.type !== 'tool_result' || !step.text)
+                continue;
+            let m;
+            while ((m = urlRe.exec(step.text)) !== null) {
+                if (!urls.includes(m[0]))
+                    urls.push(m[0]);
+            }
+        }
+        return urls.map((url) => ({ url }));
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/esm/agents/research/agent.js.map

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

package/dist/esm/agents/research/facade.d.ts

@@ -0,0 +1,22 @@
+/** `client.research` facade — thin wrapper over `ResearchAgent`. */
+import type { ResearchAgentOptions } from './agent.js';
+import type { ResearchResult } from './types.js';
+export interface ResearchRunOptions {
+    search?: string | ResearchAgentOptions['searchTool'];
+    maxSteps?: number;
+    model?: string;
+    compressSnippets?: boolean;
+    compressionModel?: string;
+    minCompressTokens?: number;
+    maxContextTokens?: number;
+    systemPrompt?: string;
+}
+export declare class ResearchFacade {
+    private readonly engine;
+    constructor(engine: ResearchAgentOptions['engine']);
+    run(question: string, options?: ResearchRunOptions): Promise<ResearchResult>;
+    /** Single-shot: one search + forced answer (`maxSteps=2`). */
+    search(question: string, options?: Omit<ResearchRunOptions, 'maxSteps'>): Promise<ResearchResult>;
+    private resolveSearchTool;
+}
+//# sourceMappingURL=facade.d.ts.map

package/dist/esm/agents/research/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../../../src/agents/research/facade.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAGpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOjD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAE5C,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC;IAI5C,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC;IAetF,8DAA8D;IACxD,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YAI7F,iBAAiB;CA0BhC"}

package/dist/esm/agents/research/facade.js

@@ -0,0 +1,53 @@
+/** `client.research` facade — thin wrapper over `ResearchAgent`. */
+import { ResearchAgent } from './agent.js';
+const SEARCH_PROVIDER_ENV = {
+    tavily: ['TAVILY_API_KEY'],
+    brave: ['BRAVE_SEARCH_API_KEY', 'BRAVE_API_KEY'],
+};
+export class ResearchFacade {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async run(question, options = {}) {
+        const tool = await this.resolveSearchTool(options.search ?? 'tavily');
+        const agent = new ResearchAgent({
+            engine: this.engine,
+            searchTool: tool,
+            maxSteps: options.maxSteps ?? 10,
+            ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),
+            compressSnippets: options.compressSnippets ?? true,
+            compressionModel: options.compressionModel ?? 'latte_v1',
+            minCompressTokens: options.minCompressTokens ?? 100,
+            maxContextTokens: options.maxContextTokens ?? 120_000,
+        });
+        return agent.run(question, options.model !== undefined ? { model: options.model } : {});
+    }
+    /** Single-shot: one search + forced answer (`maxSteps=2`). */
+    async search(question, options = {}) {
+        return this.run(question, { ...options, maxSteps: 2 });
+    }
+    async resolveSearchTool(search) {
+        if (typeof search !== 'string')
+            return search;
+        const provider = search.toLowerCase();
+        if (!(provider in SEARCH_PROVIDER_ENV)) {
+            throw new Error(`unsupported search provider '${search}'; expected one of ${Object.keys(SEARCH_PROVIDER_ENV).join(', ')} or a LangChain tool`);
+        }
+        const { WebSearchTool } = await import('../tools/web-search.js');
+        let apiKey;
+        for (const env of SEARCH_PROVIDER_ENV[provider]) {
+            const v = process.env[env];
+            if (v) {
+                apiKey = v;
+                break;
+            }
+        }
+        const opts = apiKey !== undefined ? { apiKey } : {};
+        const tool = provider === 'tavily'
+            ? await WebSearchTool.tavily(opts)
+            : await WebSearchTool.brave(opts);
+        return tool;
+    }
+}
+//# sourceMappingURL=facade.js.map

package/dist/esm/agents/research/facade.js.map

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

package/dist/esm/agents/research/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Compresr research agent — multi-step web search with per-snippet compression.
+ *
+ * Public entry: `client.research.run(question)`.
+ * Loop structure adapted from Perplexity `search_evals` (MIT,
+ * https://github.com/perplexityai/search_evals).
+ */
+export { ResearchAgent } from './agent.js';
+export type { ResearchAgentOptions, ResearchRunOptions as ResearchAgentRunOptions } from './agent.js';
+export { ResearchFacade } from './facade.js';
+export type { ResearchRunOptions } from './facade.js';
+export { parseResearchOutput } from './parser.js';
+export type { ParsedResearch } from './parser.js';
+export { DEFAULT_RESEARCH_SYSTEM_PROMPT } from './prompts.js';
+export type { Citation, ResearchResult, ResearchUsage, Step, StepKind, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/agents/research/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/agents/research/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,IAAI,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACtG,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAC9D,YAAY,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,IAAI,EACJ,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/dist/esm/agents/research/index.js

@@ -0,0 +1,12 @@
+/**
+ * Compresr research agent — multi-step web search with per-snippet compression.
+ *
+ * Public entry: `client.research.run(question)`.
+ * Loop structure adapted from Perplexity `search_evals` (MIT,
+ * https://github.com/perplexityai/search_evals).
+ */
+export { ResearchAgent } from './agent.js';
+export { ResearchFacade } from './facade.js';
+export { parseResearchOutput } from './parser.js';
+export { DEFAULT_RESEARCH_SYSTEM_PROMPT } from './prompts.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/agents/research/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/agents/research/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/agents/research/parser.d.ts

@@ -0,0 +1,9 @@
+/** Parse the strict-format final response into structured fields. */
+export interface ParsedResearch {
+    readonly answer: string;
+    readonly explanation: string;
+    readonly confidence: number | null;
+    readonly citationUrls: ReadonlyArray<string>;
+}
+export declare function parseResearchOutput(text: string): ParsedResearch;
+//# sourceMappingURL=parser.d.ts.map

package/dist/esm/agents/research/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../src/agents/research/parser.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9C;AAcD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CA6BhE"}

package/dist/esm/agents/research/parser.js

@@ -0,0 +1,39 @@
+/** Parse the strict-format final response into structured fields. */
+const FIELD_PATTERNS = {
+    explanation: /^\s*explanation\s*:\s*([\s\S]+?)(?=^\s*(?:exact\s+answer|confidence|citations)\s*:|\s*$)/im,
+    answer: /^\s*exact\s+answer\s*:\s*([\s\S]+?)(?=^\s*(?:explanation|confidence|citations)\s*:|\s*$)/im,
+    confidence: /^\s*confidence\s*:\s*([\s\S]+?)(?=^\s*(?:explanation|exact\s+answer|citations)\s*:|\s*$)/im,
+    citations: /^\s*citations\s*:\s*([\s\S]+?)\s*$/im,
+};
+function grab(text, name) {
+    const m = FIELD_PATTERNS[name].exec(text);
+    return m ? m[1].trim() : '';
+}
+export function parseResearchOutput(text) {
+    if (!text) {
+        return { answer: '', explanation: '', confidence: null, citationUrls: [] };
+    }
+    const answer = grab(text, 'answer');
+    const explanation = grab(text, 'explanation');
+    const confidenceRaw = grab(text, 'confidence');
+    const citationsRaw = grab(text, 'citations');
+    let confidence = null;
+    if (confidenceRaw) {
+        const m = /(\d+(?:\.\d+)?)/.exec(confidenceRaw);
+        if (m) {
+            const v = parseFloat(m[1]);
+            confidence = v > 1 ? v / 100 : v;
+        }
+    }
+    const citationUrls = [];
+    if (citationsRaw) {
+        const urlRe = /https?:\/\/[^\s,;<>"')]+/g;
+        let m;
+        while ((m = urlRe.exec(citationsRaw)) !== null) {
+            if (!citationUrls.includes(m[0]))
+                citationUrls.push(m[0]);
+        }
+    }
+    return { answer, explanation, confidence, citationUrls };
+}
+//# sourceMappingURL=parser.js.map

package/dist/esm/agents/research/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../../src/agents/research/parser.ts"],"names":[],"mappings":"AAAA,qEAAqE;AASrE,MAAM,cAAc,GAA2B;IAC7C,WAAW,EAAE,4FAA4F;IACzG,MAAM,EAAE,4FAA4F;IACpG,UAAU,EAAE,4FAA4F;IACxG,SAAS,EAAE,sCAAsC;CAClD,CAAC;AAEF,SAAS,IAAI,CAAC,IAAY,EAAE,IAAY;IACtC,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IAC7E,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAE7C,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChD,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,2BAA2B,CAAC;QAC1C,IAAI,CAAyB,CAAC;QAC9B,OAAO,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC/C,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AAC3D,CAAC"}

package/dist/esm/agents/research/prompts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Default system prompt — adapted from Perplexity `search_evals` (MIT,
+ * https://github.com/perplexityai/search_evals/blob/main/search_evals/agents/deep_research.py).
+ */
+export declare const DEFAULT_RESEARCH_SYSTEM_PROMPT = "You are a research agent. The user will ask you a specific question whose answer cannot be reliably produced from your internal weights (hallucination risk is high), and that takes several steps of web research to resolve.\n\n## Tool\nsearch_web(query: str) \u2014 Search the web with a single query. Returns titles, URLs, and snippets.\n\n## Query format\nWrite queries for a modern keyword/semantic search engine, not for an LLM:\n- Keep them focused \u2014 search is a limited budget.\n- Do not rely on quotes, brackets, or special syntax.\n- Natural language is fine; keyword strings are fine too.\n\n## Solution strategy\nYou have a hard search budget. At each step, decrement the counter and plan ahead how you will spend what is left. Ask yourself: did this SERP bring me closer to the answer? If not, and rephrasing didn't help, explicitly say you're switching hypothesis and pursue a different direction.\n\n## General web-search recommendations\n- One query at a time.\n- Cross-verify across sources before committing.\n- If sources conflict, search more to resolve the conflict.\n- Never assert a claim you don't have a source for.\n\n## Response format (mandatory)\nWhen you are done researching, end your response with exactly these fields in this order:\n\nExplanation: <your research process and the key findings from each source>\nExact Answer: <the precise final answer, or \"I don't know\" if you couldn't find it>\nConfidence: <0-100%>\nCitations: <comma-separated list of URLs you actually relied on>\n";
+//# sourceMappingURL=prompts.d.ts.map

package/dist/esm/agents/research/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../../src/agents/research/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,8BAA8B,u/CA2B1C,CAAC"}

package/dist/esm/agents/research/prompts.js

@@ -0,0 +1,33 @@
+/**
+ * Default system prompt — adapted from Perplexity `search_evals` (MIT,
+ * https://github.com/perplexityai/search_evals/blob/main/search_evals/agents/deep_research.py).
+ */
+export const DEFAULT_RESEARCH_SYSTEM_PROMPT = `You are a research agent. The user will ask you a specific question whose answer cannot be reliably produced from your internal weights (hallucination risk is high), and that takes several steps of web research to resolve.
+
+## Tool
+search_web(query: str) — Search the web with a single query. Returns titles, URLs, and snippets.
+
+## Query format
+Write queries for a modern keyword/semantic search engine, not for an LLM:
+- Keep them focused — search is a limited budget.
+- Do not rely on quotes, brackets, or special syntax.
+- Natural language is fine; keyword strings are fine too.
+
+## Solution strategy
+You have a hard search budget. At each step, decrement the counter and plan ahead how you will spend what is left. Ask yourself: did this SERP bring me closer to the answer? If not, and rephrasing didn't help, explicitly say you're switching hypothesis and pursue a different direction.
+
+## General web-search recommendations
+- One query at a time.
+- Cross-verify across sources before committing.
+- If sources conflict, search more to resolve the conflict.
+- Never assert a claim you don't have a source for.
+
+## Response format (mandatory)
+When you are done researching, end your response with exactly these fields in this order:
+
+Explanation: <your research process and the key findings from each source>
+Exact Answer: <the precise final answer, or "I don't know" if you couldn't find it>
+Confidence: <0-100%>
+Citations: <comma-separated list of URLs you actually relied on>
+`;
+//# sourceMappingURL=prompts.js.map

package/dist/esm/agents/research/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../../src/agents/research/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B7C,CAAC"}

package/dist/esm/agents/research/types.d.ts

@@ -0,0 +1,32 @@
+/** Public types returned by `ResearchAgent.run(...)`. */
+export interface Citation {
+    readonly url: string;
+    readonly title?: string;
+    readonly snippet?: string;
+}
+export type StepKind = 'search' | 'tool_result' | 'answer' | 'error';
+export interface Step {
+    readonly type: StepKind;
+    readonly query?: string;
+    readonly text?: string;
+    readonly chars?: number;
+    readonly latencyS?: number;
+}
+export interface ResearchUsage {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly cache_read_tokens: number;
+    readonly cache_creation_tokens: number;
+    readonly calls: number;
+}
+export interface ResearchResult {
+    readonly answer: string;
+    readonly explanation: string;
+    readonly confidence: number | null;
+    readonly text: string;
+    readonly citations: ReadonlyArray<Citation>;
+    readonly trajectory: ReadonlyArray<Step>;
+    readonly usage: ResearchUsage;
+    readonly raw: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/agents/research/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/agents/research/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErE,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB"}

package/dist/esm/agents/research/types.js

@@ -0,0 +1,3 @@
+/** Public types returned by `ResearchAgent.run(...)`. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/agents/research/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/agents/research/types.ts"],"names":[],"mappings":"AAAA,yDAAyD"}