melchizedek-agents 0.9.0

package/dist/lib/models/claudeLlm.js

@@ -0,0 +1,332 @@
+/**
+ * lib/models/claudeLlm.ts — Anthropic Claude provider for the ADK LLMRegistry.
+ *
+ * WHY this file exists:
+ *   The ADK JS package (@google/adk v1.x) is Gemini-native. It does not ship a
+ *   Claude adapter the way the ADK Java SDK does. However, the ADK exposes a
+ *   clean extension point: subclass BaseLlm, implement generateContentAsync(),
+ *   and register the class via LLMRegistry.register(). The registry maps model
+ *   name patterns to provider classes, so once registered, any LlmAgent with
+ *   model: "claude-*" will automatically route through this class.
+ *
+ * HOW TO ENABLE:
+ *   1. Install the Anthropic SDK:
+ *        npm install @anthropic-ai/sdk
+ *   2. Add your API key to .env:
+ *        ANTHROPIC_API_KEY=sk-ant-...
+ *   3. registerAvailableProviders() (lib/models/registry.ts) registers this
+ *      adapter automatically when the key is set.
+ *   4. Set model: "claude-sonnet-4-6" (or any claude-* id) in your YAML.
+ *
+ * CAPABILITIES:
+ *   - Tools: FunctionTools AND MCP-discovered tools work. Tool schemas are
+ *     normalized from the ADK/Gemini UPPERCASE dialect to the lowercase
+ *     JSON-Schema types Anthropic requires (lib/models/schemaNormalize.ts).
+ *   - web_search: declaring the `web_search` tool in YAML enables Anthropic's
+ *     native web_search server tool — searches run on Anthropic's side.
+ *   - Extended thinking: generateContentConfig.thinkingConfig.thinkingBudget
+ *     maps to Anthropic's thinking parameter. Thinking blocks are surfaced
+ *     as { text, thought: true } parts (display-only; kept out of session
+ *     history). NOTE: thinking + tool use in the same agent is NOT supported
+ *     this pass — Anthropic requires signed thinking blocks to be replayed
+ *     on tool loops; the raw blocks are stashed in customMetadata
+ *     ['anthropic.thinking'] for a future upgrade.
+ *   - Token usage: response.usage is mapped to LlmResponse.usageMetadata, so
+ *     traceAgentRun / llm.request spans count Claude tokens like Gemini's.
+ *
+ * LIMITATIONS vs Gemini:
+ *   - generate_image tool uses the Gemini image model directly and is not
+ *     affected by the inference model choice.
+ *   - Live/bidirectional streaming (connect) is not supported.
+ *
+ * CONTENT FORMAT TRANSLATION:
+ *   The ADK uses Google GenAI Content/Part objects internally. This adapter
+ *   translates them to Anthropic MessageParam format and maps the response back
+ *   to LlmResponse. Tool calls (function_call / function_response parts) are
+ *   translated to Anthropic's tool_use / tool_result blocks.
+ */
+import { BaseLlm, LLMRegistry } from '@google/adk';
+import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
+import { wantsWebSearch, isWebSearchSentinel, } from "../tools/webSearchTool.js";
+import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+/** Anthropic's minimum extended-thinking budget. */
+const MIN_THINKING_BUDGET = 1024;
+// ── Request building (exported for offline tests) ────────────────────────────
+/** ADK toolsDict → Anthropic tool definitions (lowercase schemas; the
+ *  web_search sentinel becomes Anthropic's native server tool). */
+export function buildAnthropicTools(llmRequest) {
+    const anthropicTools = [];
+    for (const [, tool] of Object.entries(llmRequest.toolsDict ?? {})) {
+        if (isWebSearchSentinel(tool))
+            continue; // added as a server tool below
+        const t = tool;
+        if (t.name && t.description) {
+            anthropicTools.push({
+                name: t.name,
+                description: t.description,
+                input_schema: toLowercaseJsonSchema(t.parameters ?? { type: 'object', properties: {} }),
+            });
+        }
+    }
+    if (wantsWebSearch(llmRequest)) {
+        // Anthropic-native server tool: search runs on Anthropic's side, results
+        // are grounded into the reply — no client-side execution.
+        anthropicTools.push({
+            type: 'web_search_20250305',
+            name: 'web_search',
+            max_uses: 5,
+        });
+    }
+    return anthropicTools;
+}
+// ── ClaudeLlm ─────────────────────────────────────────────────────────────────
+export class ClaudeLlm extends BaseLlm {
+    /**
+     * Regex patterns that map model name strings to this provider.
+     * Any model: "claude-*" in a YAML config will route here after registration.
+     */
+    static supportedModels = [/^claude-.+/];
+    apiKey;
+    constructor({ model, apiKey }) {
+        super({ model });
+        this.apiKey = apiKey;
+    }
+    /**
+     * Main generation method called by the ADK Runner for every turn.
+     *
+     * We translate ADK's LlmRequest (Google Content format) → Anthropic
+     * MessageParam format, call the Anthropic Messages API, then translate
+     * the response back to LlmResponse. The whole call is wrapped in an
+     * llm.request OpenTelemetry span (provider/model/tokens/latency).
+     */
+    async *generateContentAsync(llmRequest, stream = false) {
+        yield* traceLlmGeneration({ provider: 'anthropic', model: this.model }, this.generateInner(llmRequest, stream));
+    }
+    async *generateInner(llmRequest, stream) {
+        const apiKey = this.apiKey || process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            yield {
+                errorCode: 'MISSING_API_KEY',
+                errorMessage: 'ANTHROPIC_API_KEY is not set in environment.',
+            };
+            return;
+        }
+        // Dynamic import — only loads @anthropic-ai/sdk when actually called,
+        // so the framework boots without the SDK installed for Gemini-only users.
+        let Anthropic;
+        try {
+            const mod = await import('@anthropic-ai/sdk');
+            Anthropic = mod.default ?? mod.Anthropic;
+        }
+        catch {
+            yield {
+                errorCode: 'SDK_NOT_INSTALLED',
+                errorMessage: 'The @anthropic-ai/sdk package is not installed. Run: npm install @anthropic-ai/sdk',
+            };
+            return;
+        }
+        const client = new Anthropic({ apiKey });
+        // ── Translate ADK Contents → Anthropic messages ──────────────────────────
+        const systemParts = [];
+        const messages = [];
+        for (const content of llmRequest.contents) {
+            // System instruction lives in config.systemInstruction, not contents.
+            // But ADK also injects it as a 'system' role content — extract it.
+            if (content.role === 'system') {
+                const text = content.parts
+                    ?.filter((p) => p.text)
+                    .map((p) => p.text)
+                    .join('\n');
+                if (text)
+                    systemParts.push(text);
+                continue;
+            }
+            const role = content.role === 'model' ? 'assistant' : 'user';
+            const blocks = [];
+            for (const part of content.parts ?? []) {
+                const p = part;
+                if (p.thought) {
+                    // Prior-turn scratchpad is display-only; never replay it as text.
+                    continue;
+                }
+                if (p.text) {
+                    blocks.push({ type: 'text', text: p.text });
+                }
+                else if (p.functionCall) {
+                    // ADK function_call → Anthropic tool_use
+                    blocks.push({
+                        type: 'tool_use',
+                        id: p.functionCall.id ?? `tool_${Date.now()}`,
+                        name: p.functionCall.name,
+                        input: p.functionCall.args ?? {},
+                    });
+                }
+                else if (p.functionResponse) {
+                    // ADK function_response → Anthropic tool_result
+                    blocks.push({
+                        type: 'tool_result',
+                        tool_use_id: p.functionResponse.id ?? '',
+                        content: JSON.stringify(p.functionResponse.response ?? {}),
+                    });
+                }
+            }
+            if (blocks.length > 0) {
+                messages.push({ role, content: blocks });
+            }
+        }
+        // Also pull system instruction from generateContentConfig if present
+        const configSystem = llmRequest.config?.systemInstruction;
+        if (configSystem) {
+            const text = typeof configSystem === 'string'
+                ? configSystem
+                : configSystem.parts?.map((p) => p.text).join('\n') ?? '';
+            if (text)
+                systemParts.unshift(text);
+        }
+        // ── Build Anthropic tool definitions from ADK toolsDict ──────────────────
+        const anthropicTools = buildAnthropicTools(llmRequest);
+        if (wantsWebSearch(llmRequest)) {
+            setLlmSpanAttribute('llm.web_search.native', true);
+        }
+        // ── Extended thinking (Gemini thinkingConfig → Anthropic thinking) ───────
+        const cfg = llmRequest.config ?? {};
+        let maxTokens = cfg.maxOutputTokens ?? 4096;
+        let thinking;
+        const requestedBudget = cfg.thinkingConfig?.thinkingBudget;
+        if (typeof requestedBudget === 'number' && requestedBudget > 0) {
+            const budget = Math.max(requestedBudget, MIN_THINKING_BUDGET);
+            thinking = { type: 'enabled', budget_tokens: budget };
+            // Anthropic requires max_tokens to exceed the thinking budget.
+            maxTokens = Math.max(maxTokens, budget + 2048);
+        }
+        const requestBase = {
+            model: this.model,
+            max_tokens: maxTokens,
+            system: systemParts.join('\n\n') || undefined,
+            messages,
+            tools: anthropicTools.length > 0 ? anthropicTools : undefined,
+            ...(thinking ? { thinking } : {}),
+        };
+        // ── Call Anthropic API ────────────────────────────────────────────────────
+        try {
+            if (stream) {
+                // Streaming path
+                const streamResponse = await client.messages.stream(requestBase);
+                for await (const chunk of streamResponse) {
+                    if (chunk.type === 'content_block_delta') {
+                        if (chunk.delta.type === 'text_delta') {
+                            yield {
+                                content: {
+                                    role: 'model',
+                                    parts: [{ text: chunk.delta.text }],
+                                },
+                                partial: true,
+                            };
+                        }
+                        else if (chunk.delta.type === 'thinking_delta') {
+                            yield {
+                                content: {
+                                    role: 'model',
+                                    parts: [{ text: chunk.delta.thinking, thought: true }],
+                                },
+                                partial: true,
+                            };
+                        }
+                    }
+                }
+                // Final message: tool_use blocks, thinking stash, and token usage.
+                const final = await streamResponse.finalMessage();
+                yield this.finalResponse(final, /*includeText=*/ false);
+            }
+            else {
+                // Non-streaming path
+                const response = await client.messages.create(requestBase);
+                // Thinking first, as a display-only partial.
+                const thinkingText = (response.content ?? [])
+                    .filter((b) => b.type === 'thinking')
+                    .map((b) => b.thinking)
+                    .join('\n\n');
+                if (thinkingText) {
+                    yield {
+                        content: {
+                            role: 'model',
+                            parts: [{ text: thinkingText, thought: true }],
+                        },
+                        partial: true,
+                    };
+                }
+                yield this.finalResponse(response, /*includeText=*/ true);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield { errorCode: 'ANTHROPIC_ERROR', errorMessage: msg };
+        }
+    }
+    /** Maps a complete Anthropic message → the final LlmResponse. */
+    finalResponse(response, includeText) {
+        const parts = [];
+        const thinkingBlocks = [];
+        for (const block of response.content ?? []) {
+            if (block.type === 'text' && includeText) {
+                parts.push({ text: block.text });
+            }
+            else if (block.type === 'tool_use') {
+                parts.push({
+                    functionCall: { name: block.name, args: block.input, id: block.id },
+                });
+            }
+            else if (block.type === 'thinking') {
+                // Raw signed blocks, preserved for a future thinking+tools upgrade
+                // (Anthropic requires them replayed verbatim on tool loops).
+                thinkingBlocks.push(block);
+            }
+        }
+        const usage = response.usage;
+        return {
+            ...(parts.length > 0 ? { content: { role: 'model', parts } } : {}),
+            turnComplete: true,
+            ...(usage
+                ? {
+                    usageMetadata: {
+                        ...(usage.input_tokens !== undefined
+                            ? { promptTokenCount: usage.input_tokens }
+                            : {}),
+                        ...(usage.output_tokens !== undefined
+                            ? { candidatesTokenCount: usage.output_tokens }
+                            : {}),
+                        ...(usage.input_tokens !== undefined &&
+                            usage.output_tokens !== undefined
+                            ? { totalTokenCount: usage.input_tokens + usage.output_tokens }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(thinkingBlocks.length > 0
+                ? { customMetadata: { 'anthropic.thinking': thinkingBlocks } }
+                : {}),
+        };
+    }
+    /**
+     * Live/bidirectional streaming connection — not supported by the Anthropic
+     * Messages API. Throws to surface this clearly rather than silently failing.
+     */
+    async connect(_llmRequest) {
+        throw new Error('ClaudeLlm does not support live bidirectional connections. ' +
+            'Use a Gemini model for live/streaming sessions.');
+    }
+}
+// ── Registration helper ───────────────────────────────────────────────────────
+/**
+ * Registers ClaudeLlm with the ADK LLMRegistry.
+ *
+ * WHY a separate function instead of auto-registering at import time:
+ *   Auto-registration at module load would cause every consumer of this file
+ *   to unconditionally register Claude, even if ANTHROPIC_API_KEY is absent.
+ *   By making registration explicit, registerAvailableProviders() can
+ *   conditionally call this only when the key is present, and log a clear
+ *   message about which provider is active.
+ */
+export function registerClaudeLlm() {
+    LLMRegistry.register(ClaudeLlm);
+}

package/dist/lib/models/gptLlm.d.ts

@@ -0,0 +1,110 @@
+/**
+ * lib/models/gptLlm.ts — OpenAI GPT provider for the ADK LLMRegistry.
+ *
+ * WHY this file exists:
+ *   Model optionality: any agent YAML with model: "gpt-*" (or an o-series
+ *   id like "o4-mini") routes here after registration. Unlike Grok/Ollama
+ *   this adapter does NOT reuse the chat-completions base class — it speaks
+ *   OpenAI's Responses API through the official `openai` SDK, because the
+ *   Responses API is where OpenAI exposes reasoning summaries (the model's
+ *   thinking, surfaced as { thought: true } parts here) and the first-class
+ *   `web_search` tool this framework's web_search abstraction maps to.
+ *
+ * HOW TO ENABLE:
+ *   1. Install the SDK (already in package.json):  npm install
+ *   2. Add your API key to .env:  OPENAI_API_KEY=sk-...
+ *   3. Set model: "gpt-5-mini" (or any gpt-* / o-series id) in your YAML.
+ *   registerAvailableProviders() registers this adapter when the key is set.
+ *
+ * CONTENT FORMAT TRANSLATION:
+ *   ADK Content/Part objects → Responses API `input` items:
+ *     user/model text        → { role, content } message items
+ *     functionCall part      → { type:'function_call', call_id, name, arguments }
+ *     functionResponse part  → { type:'function_call_output', call_id, output }
+ *   The call_id round-trip matters: this adapter emits functionCall.id so
+ *   ADK echoes it back on the tool response, and the Responses API requires
+ *   function_call_output.call_id to match the originating call.
+ *
+ *   Response `output` items map back:
+ *     'reasoning' summary    → { text, thought: true } partial (display-only)
+ *     'message' output_text  → text part
+ *     'function_call'        → functionCall part
+ *   usage.input_tokens / output_tokens / output_tokens_details.reasoning_tokens
+ *   → LlmResponse.usageMetadata, so token telemetry works like every provider.
+ *
+ * STREAMING (ADK stream=true, i.e. RunConfig streamingMode: SSE):
+ *   The request is sent with { stream: true }; SSE deltas
+ *   (response.output_text.delta / response.reasoning_summary_text.delta)
+ *   are yielded as { partial: true } responses — the ADK Runner displays
+ *   but does NOT persist partial events — and the terminal
+ *   response.completed payload is mapped through the same final-response
+ *   translator as the non-streaming path, carrying full content + usage
+ *   as the ONE event that lands in the session. Function calls are never
+ *   delta-streamed (both OpenAI and xAI deliver them whole).
+ */
+import { BaseLlm } from '@google/adk';
+import type { LlmRequest, LlmResponse } from '@google/adk';
+import type { BaseLlmConnection } from '@google/adk';
+/** ADK Contents → Responses API `input` items + `instructions` string. */
+export declare function buildResponsesInput(llmRequest: LlmRequest): {
+    instructions: string | undefined;
+    input: any[];
+};
+/** ADK toolsDict (+ web_search sentinel) → Responses API tool definitions. */
+export declare function buildResponsesTools(llmRequest: LlmRequest): any[];
+/** Maps one Responses-API SSE event to a displayable delta, or null for
+ *  event types that carry none. Function calls are NOT delta-streamed —
+ *  both OpenAI and xAI deliver them whole in the final response. */
+export declare function streamEventDelta(ev: any): {
+    thought: boolean;
+    text: string;
+} | null;
+export declare class GptLlm extends BaseLlm {
+    /** gpt-* and o-series ids route here after registration. */
+    static readonly supportedModels: Array<string | RegExp>;
+    protected apiKey?: string;
+    constructor({ model, apiKey }: {
+        model: string;
+        apiKey?: string;
+    });
+    /** Provider id for telemetry and error codes. */
+    protected providerId(): string;
+    /** SDK baseURL override; undefined = api.openai.com. */
+    protected baseURL(): string | undefined;
+    protected apiKeyFromEnv(): string | undefined;
+    protected missingKeyMessage(): string;
+    /** Responses API `reasoning` request param, or undefined to omit it.
+     *  Base: reasoning summaries for OpenAI's reasoning-capable ids.
+     *  Subclasses override per vendor (GrokLlm pins grok-4.5 to a reasoning
+     *  effort). A 400 from a model that rejects the param is retried once
+     *  without it — see createWithRetry. */
+    protected reasoningParam(): Record<string, unknown> | undefined;
+    /** Extra options for the OpenAI SDK client constructor. Subclasses
+     *  override per vendor (GrokLlm sets a long request timeout, per xAI's
+     *  streaming guidance for reasoning models). */
+    protected clientOptions(): Record<string, unknown>;
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
+    private generateInner;
+    /** responses.create with the guarded reasoning retry: if the model
+     *  rejects the reasoning param with a 400 (a non-reasoning model matched
+     *  the pattern), drop it and try once more. */
+    private createWithRetry;
+    /** Final (non-delta) Response → LlmResponse yields: reasoning summaries
+     *  as a display-only thought part, then text/functionCall parts with
+     *  usage. Shared by the non-streaming path and the stream finalizer
+     *  (which sets skipThoughts — its summaries already streamed as deltas). */
+    private mapFinalResponse;
+    /** SSE streaming: yield displayable DELTAS as { partial: true } responses
+     *  (the ADK Runner shows but never persists partials), then map the
+     *  terminal response.completed payload through mapFinalResponse — full
+     *  content + usage, the ONE event that lands in the session. Usage rides
+     *  only the final response so the tracer never double-counts tokens. */
+    private streamResponses;
+    /** Live/bidirectional streaming is not wired for this adapter. */
+    connect(_llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+}
+/**
+ * Registers GptLlm with the ADK LLMRegistry. Called by
+ * registerAvailableProviders() when OPENAI_API_KEY is present.
+ */
+export declare function registerGptLlm(): void;