@mcpmesh/sdk 0.8.0-beta.1

package/dist/llm.js

@@ -0,0 +1,304 @@
+/**
+ * mesh.llm() - LLM-powered tool wrapper for MCP Mesh.
+ *
+ * Creates a tool that uses an LLM with agentic capabilities,
+ * including access to other mesh tools and structured output.
+ *
+ * @example
+ * ```typescript
+ * import { FastMCP } from "fastmcp";
+ * import { mesh } from "@mcpmesh/sdk";
+ * import { z } from "zod";
+ *
+ * const server = new FastMCP({ name: "Smart Assistant", version: "1.0.0" });
+ *
+ * const AssistResponse = z.object({
+ *   answer: z.string(),
+ *   confidence: z.number(),
+ * });
+ *
+ * server.addTool(mesh.llm({
+ *   name: "assist",
+ *   capability: "smart_assistant",
+ *   provider: "claude",
+ *   systemPrompt: "file://prompts/assistant.hbs",
+ *   filter: [{ capability: "calculator" }],
+ *   returns: AssistResponse,
+ *   parameters: z.object({ message: z.string() }),
+ *   execute: async ({ message }, { llm }) => llm(message),
+ * }));
+ *
+ * const agent = mesh(server, { name: "smart-assistant", port: 9003 });
+ * ```
+ */
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { MeshLlmAgent, createLlmToolProxy } from "./llm-agent.js";
+import { debug } from "./debug.js";
+/**
+ * Registry for LLM tools - stores configuration and resolved dependencies.
+ */
+export class LlmToolRegistry {
+    static instance = null;
+    /** LLM tool configurations by function ID */
+    configs = new Map();
+    /** Resolved tools for each LLM function (from llm_tools_updated events) */
+    resolvedTools = new Map();
+    /** Resolved providers for each LLM function (from llm_provider_available events) */
+    resolvedProviders = new Map();
+    constructor() { }
+    static getInstance() {
+        if (!LlmToolRegistry.instance) {
+            LlmToolRegistry.instance = new LlmToolRegistry();
+        }
+        return LlmToolRegistry.instance;
+    }
+    /**
+     * Reset the registry (for testing).
+     */
+    static reset() {
+        LlmToolRegistry.instance = null;
+    }
+    /**
+     * Register an LLM tool configuration.
+     */
+    register(functionId, config) {
+        this.configs.set(functionId, config);
+    }
+    /**
+     * Get an LLM tool configuration.
+     */
+    getConfig(functionId) {
+        return this.configs.get(functionId);
+    }
+    /**
+     * Get all registered LLM tool configurations.
+     */
+    getAllConfigs() {
+        return new Map(this.configs);
+    }
+    /**
+     * Update resolved tools for an LLM function.
+     */
+    setResolvedTools(functionId, tools) {
+        this.resolvedTools.set(functionId, tools);
+        debug.llm(`Tools updated for ${functionId}: ${tools.length} tools available`);
+    }
+    /**
+     * Get resolved tools for an LLM function.
+     */
+    getResolvedTools(functionId) {
+        return this.resolvedTools.get(functionId) ?? [];
+    }
+    /**
+     * Update resolved provider for an LLM function.
+     */
+    setResolvedProvider(functionId, provider) {
+        this.resolvedProviders.set(functionId, provider);
+        debug.llm(`Provider available for ${functionId}: ${provider.endpoint}`);
+    }
+    /**
+     * Remove resolved provider for an LLM function.
+     */
+    removeResolvedProvider(functionId) {
+        this.resolvedProviders.delete(functionId);
+        debug.llm(`Provider unavailable for ${functionId}`);
+    }
+    /**
+     * Get resolved provider for an LLM function.
+     */
+    getResolvedProvider(functionId) {
+        return this.resolvedProviders.get(functionId);
+    }
+    /**
+     * Clear all resolved dependencies.
+     */
+    clearAllResolved() {
+        this.resolvedTools.clear();
+        this.resolvedProviders.clear();
+    }
+}
+/**
+ * Create an LLM-powered tool definition.
+ *
+ * This function returns a fastmcp-compatible tool definition that can be
+ * passed to server.addTool(). The tool will use an LLM with agentic capabilities.
+ *
+ * @param config - LLM tool configuration
+ * @returns fastmcp tool definition
+ */
+export function llm(config) {
+    const registry = LlmToolRegistry.getInstance();
+    // Generate function ID
+    const functionId = config.name;
+    // Normalize configuration
+    const llmConfig = {
+        functionId,
+        name: config.name,
+        capability: config.capability ?? config.name,
+        description: config.description ?? "",
+        version: config.version ?? "1.0.0",
+        tags: config.tags ?? [],
+        provider: config.provider,
+        model: config.model,
+        maxIterations: config.maxIterations ?? 10,
+        systemPrompt: config.systemPrompt,
+        contextParam: config.contextParam,
+        filter: config.filter,
+        filterMode: config.filterMode ?? "all",
+        maxOutputTokens: config.maxOutputTokens,
+        temperature: config.temperature,
+        topP: config.topP,
+        stop: config.stop,
+        inputSchema: JSON.stringify(zodToJsonSchema(config.parameters, { $refStrategy: "none" })),
+        returnSchema: config.returns,
+        outputMode: config.outputMode ?? "hint",
+        execute: config.execute,
+    };
+    // Register with LLM tool registry
+    registry.register(functionId, llmConfig);
+    // Create MeshLlmAgent once (cached for reuse)
+    const agent = new MeshLlmAgent({
+        functionId,
+        provider: llmConfig.provider,
+        model: llmConfig.model,
+        systemPrompt: llmConfig.systemPrompt,
+        contextParam: llmConfig.contextParam,
+        maxIterations: llmConfig.maxIterations,
+        maxOutputTokens: llmConfig.maxOutputTokens,
+        temperature: llmConfig.temperature,
+        topP: llmConfig.topP,
+        stop: llmConfig.stop,
+        returnSchema: llmConfig.returnSchema,
+        outputMode: llmConfig.outputMode,
+    });
+    // Create the execute wrapper
+    const wrappedExecute = async (args) => {
+        try {
+            debug.llm(`Executing ${functionId} with args:`, JSON.stringify(args));
+            // Get resolved tools and provider
+            const tools = registry.getResolvedTools(functionId);
+            const meshProvider = registry.getResolvedProvider(functionId);
+            debug.llm(`Tools: ${tools.length}, Provider:`, meshProvider ? meshProvider.endpoint : "none");
+            // Extract template context from args if contextParam is specified
+            let templateContext = {};
+            if (llmConfig.contextParam && args && typeof args === "object") {
+                const argsObj = args;
+                if (argsObj[llmConfig.contextParam]) {
+                    templateContext = argsObj[llmConfig.contextParam];
+                }
+            }
+            // Create callable LLM agent
+            const llmCallable = agent.createCallable({
+                tools,
+                meshProvider: meshProvider
+                    ? {
+                        endpoint: meshProvider.endpoint,
+                        functionName: meshProvider.functionName,
+                        model: meshProvider.model,
+                    }
+                    : undefined,
+                templateContext,
+            });
+            // Call user's execute handler
+            debug.llm(`Calling user execute handler`);
+            const result = await llmConfig.execute(args, { llm: llmCallable });
+            debug.llm(`Execute completed successfully`);
+            // Convert result to string for MCP
+            if (typeof result === "string") {
+                return result;
+            }
+            return JSON.stringify(result);
+        }
+        catch (error) {
+            debug.llm(`Error in ${functionId}:`, error);
+            throw error;
+        }
+    };
+    // Return fastmcp-compatible tool definition with mesh metadata
+    return {
+        name: config.name,
+        description: config.description,
+        parameters: config.parameters,
+        execute: wrappedExecute,
+        _meshLlmConfig: llmConfig,
+    };
+}
+/**
+ * Build JsLlmAgentSpec for Rust core from LLM tool configs.
+ */
+export function buildLlmAgentSpecs() {
+    const registry = LlmToolRegistry.getInstance();
+    const specs = [];
+    for (const [, config] of registry.getAllConfigs()) {
+        // Serialize provider to JSON
+        const providerJson = typeof config.provider === "string"
+            ? JSON.stringify({ direct: config.provider })
+            : JSON.stringify(config.provider);
+        // Serialize filter to JSON if present
+        const filterJson = config.filter ? JSON.stringify(config.filter) : undefined;
+        specs.push({
+            functionId: config.functionId,
+            provider: providerJson,
+            filter: filterJson,
+            filterMode: config.filterMode,
+            maxIterations: config.maxIterations,
+        });
+    }
+    return specs;
+}
+/**
+ * Handle llm_tools_updated event from Rust core.
+ */
+export function handleLlmToolsUpdated(functionId, tools) {
+    const registry = LlmToolRegistry.getInstance();
+    // Create tool proxies
+    const proxies = tools.map((tool) => createLlmToolProxy(tool));
+    // Update registry
+    registry.setResolvedTools(functionId, proxies);
+}
+/**
+ * Handle llm_provider_available event from Rust core.
+ */
+export function handleLlmProviderAvailable(functionId, providerInfo) {
+    debug.llm(`Provider available for ${functionId}: ${providerInfo.endpoint}/${providerInfo.functionName}`);
+    const registry = LlmToolRegistry.getInstance();
+    registry.setResolvedProvider(functionId, {
+        endpoint: providerInfo.endpoint,
+        functionName: providerInfo.functionName,
+        model: providerInfo.model,
+        agentId: providerInfo.agentId,
+    });
+    debug.llm(`Provider stored for ${functionId}`);
+}
+/**
+ * Handle llm_provider_unavailable event from Rust core.
+ */
+export function handleLlmProviderUnavailable(functionId) {
+    const registry = LlmToolRegistry.getInstance();
+    registry.removeResolvedProvider(functionId);
+}
+/**
+ * Get LLM tool metadata for JsToolSpec.
+ */
+export function getLlmToolMetadata(toolName) {
+    const registry = LlmToolRegistry.getInstance();
+    const config = registry.getConfig(toolName);
+    if (!config) {
+        return null;
+    }
+    return {
+        llmFilter: config.filter ? JSON.stringify(config.filter) : undefined,
+        llmProvider: typeof config.provider === "string"
+            ? config.provider
+            : JSON.stringify(config.provider),
+    };
+}
+/**
+ * Check if a tool is an LLM tool.
+ */
+export function isLlmTool(toolDef) {
+    return (typeof toolDef === "object" &&
+        toolDef !== null &&
+        "_meshLlmConfig" in toolDef);
+}
+//# sourceMappingURL=llm.js.map

package/dist/llm.js.map

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

package/dist/provider-handlers/claude-handler.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Claude/Anthropic provider handler.
+ *
+ * Optimized for Claude API (Claude 3.x, Sonnet, Opus, Haiku)
+ * using Anthropic's best practices for tool calling and JSON responses.
+ *
+ * Supports three output modes for performance/reliability tradeoffs:
+ * - strict: Use response_format for guaranteed schema compliance (slowest, 100% reliable)
+ * - hint: Use prompt-based JSON instructions (medium speed, ~95% reliable)
+ * - text: Plain text output for str return types (fastest)
+ *
+ * Features:
+ * - Anti-XML tool calling instructions
+ * - Output mode optimization based on return type
+ *
+ * Note: Prompt caching is not yet implemented for AI SDK v6.
+ * TODO: Re-enable via experimental_providerOptions when AI SDK v6 supports it.
+ *
+ * Based on Python's ClaudeHandler:
+ * src/runtime/python/_mcp_mesh/engine/provider_handlers/claude_handler.py
+ */
+import type { LlmMessage } from "../types.js";
+import { type ProviderHandler, type VendorCapabilities, type ToolSchema, type OutputSchema, type PreparedRequest, type OutputMode } from "./provider-handler.js";
+/**
+ * Provider handler for Claude/Anthropic models.
+ *
+ * Claude Characteristics:
+ * - Excellent at following detailed instructions
+ * - Native structured output via response_format (requires strict schema)
+ * - Native tool calling (via Anthropic messages API)
+ * - Performs best with anti-XML tool calling instructions
+ *
+ * Output Modes:
+ * - strict: response_format with JSON schema (slowest, guaranteed valid JSON)
+ * - hint: JSON schema in prompt (medium speed, usually valid JSON)
+ * - text: Plain text output for str return types (fastest)
+ *
+ * Best Practices (from Anthropic docs):
+ * - Use response_format for guaranteed JSON schema compliance
+ * - Schema must have additionalProperties: false on all objects
+ * - Add anti-XML instructions to prevent <invoke> style tool calls
+ * - Use one tool call at a time for better reliability
+ */
+export declare class ClaudeHandler implements ProviderHandler {
+    readonly vendor = "anthropic";
+    /**
+     * Prepare request parameters for Claude API with output mode support.
+     *
+     * Output Mode Strategy:
+     * - strict: Use response_format for guaranteed JSON schema compliance (slowest)
+     * - hint: No response_format, rely on prompt instructions (medium speed)
+     * - text: No response_format, plain text output (fastest)
+     *
+     * Message Format (Anthropic-specific):
+     * - Assistant messages with tool_calls → content blocks with type "tool-call"
+     * - Tool result messages → content blocks with type "tool-result"
+     * This is required for Vercel AI SDK to properly convert to Anthropic's native format.
+     */
+    prepareRequest(messages: LlmMessage[], tools: ToolSchema[] | null, outputSchema: OutputSchema | null, options?: {
+        outputMode?: OutputMode;
+        temperature?: number;
+        maxOutputTokens?: number;
+        topP?: number;
+        [key: string]: unknown;
+    }): PreparedRequest;
+    /**
+     * Format system prompt for Claude with output mode support.
+     *
+     * Output Mode Strategy:
+     * - strict: Minimal JSON instructions (response_format handles schema)
+     * - hint: Add detailed JSON schema instructions in prompt
+     * - text: No JSON instructions (plain text output)
+     */
+    formatSystemPrompt(basePrompt: string, toolSchemas: ToolSchema[] | null, outputSchema: OutputSchema | null, outputMode?: OutputMode): string;
+    /**
+     * Return Claude-specific capabilities.
+     */
+    getCapabilities(): VendorCapabilities;
+    /**
+     * Determine the output mode based on schema complexity.
+     *
+     * Logic:
+     * - If overrideMode specified, use it
+     * - If no schema (string return type), use "text" mode
+     * - If schema is simple (<5 fields, basic types), use "hint" mode
+     * - Otherwise, use "strict" mode
+     */
+    determineOutputMode(outputSchema: OutputSchema | null, overrideMode?: OutputMode): OutputMode;
+    /**
+     * Check if a schema is simple enough for hint mode.
+     *
+     * Simple schema criteria:
+     * - Less than 5 fields
+     * - No nested objects (hasNestedObjects flag or $defs present)
+     */
+    private isSimpleSchema;
+}
+//# sourceMappingURL=claude-handler.d.ts.map

package/dist/provider-handlers/claude-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-handler.d.ts","sourceRoot":"","sources":["../../src/provider-handlers/claude-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAgB/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,QAAQ,CAAC,MAAM,eAAe;IAE9B;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,EAC1B,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,GACA,eAAe;IAgDlB;;;;;;;OAOG;IACH,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,EAChC,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,UAAU,CAAC,EAAE,UAAU,GACtB,MAAM;IAqET;;OAEG;IACH,eAAe,IAAI,kBAAkB;IAWrC;;;;;;;;OAQG;IACH,mBAAmB,CACjB,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,YAAY,CAAC,EAAE,UAAU,GACxB,UAAU;IAwBb;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAkDvB"}

package/dist/provider-handlers/claude-handler.js

@@ -0,0 +1,268 @@
+/**
+ * Claude/Anthropic provider handler.
+ *
+ * Optimized for Claude API (Claude 3.x, Sonnet, Opus, Haiku)
+ * using Anthropic's best practices for tool calling and JSON responses.
+ *
+ * Supports three output modes for performance/reliability tradeoffs:
+ * - strict: Use response_format for guaranteed schema compliance (slowest, 100% reliable)
+ * - hint: Use prompt-based JSON instructions (medium speed, ~95% reliable)
+ * - text: Plain text output for str return types (fastest)
+ *
+ * Features:
+ * - Anti-XML tool calling instructions
+ * - Output mode optimization based on return type
+ *
+ * Note: Prompt caching is not yet implemented for AI SDK v6.
+ * TODO: Re-enable via experimental_providerOptions when AI SDK v6 supports it.
+ *
+ * Based on Python's ClaudeHandler:
+ * src/runtime/python/_mcp_mesh/engine/provider_handlers/claude_handler.py
+ */
+import { createDebug } from "../debug.js";
+import { convertMessagesToVercelFormat, makeSchemaStrict, BASE_TOOL_INSTRUCTIONS, CLAUDE_ANTI_XML_INSTRUCTION, } from "./provider-handler.js";
+import { ProviderHandlerRegistry } from "./provider-handler-registry.js";
+const debug = createDebug("claude-handler");
+// ============================================================================
+// Constants
+// ============================================================================
+/** Simple schema threshold - schemas with fewer fields use hint mode */
+const SIMPLE_SCHEMA_FIELD_THRESHOLD = 5;
+// ============================================================================
+// Claude Handler Implementation
+// ============================================================================
+/**
+ * Provider handler for Claude/Anthropic models.
+ *
+ * Claude Characteristics:
+ * - Excellent at following detailed instructions
+ * - Native structured output via response_format (requires strict schema)
+ * - Native tool calling (via Anthropic messages API)
+ * - Performs best with anti-XML tool calling instructions
+ *
+ * Output Modes:
+ * - strict: response_format with JSON schema (slowest, guaranteed valid JSON)
+ * - hint: JSON schema in prompt (medium speed, usually valid JSON)
+ * - text: Plain text output for str return types (fastest)
+ *
+ * Best Practices (from Anthropic docs):
+ * - Use response_format for guaranteed JSON schema compliance
+ * - Schema must have additionalProperties: false on all objects
+ * - Add anti-XML instructions to prevent <invoke> style tool calls
+ * - Use one tool call at a time for better reliability
+ */
+export class ClaudeHandler {
+    vendor = "anthropic";
+    /**
+     * Prepare request parameters for Claude API with output mode support.
+     *
+     * Output Mode Strategy:
+     * - strict: Use response_format for guaranteed JSON schema compliance (slowest)
+     * - hint: No response_format, rely on prompt instructions (medium speed)
+     * - text: No response_format, plain text output (fastest)
+     *
+     * Message Format (Anthropic-specific):
+     * - Assistant messages with tool_calls → content blocks with type "tool-call"
+     * - Tool result messages → content blocks with type "tool-result"
+     * This is required for Vercel AI SDK to properly convert to Anthropic's native format.
+     */
+    prepareRequest(messages, tools, outputSchema, options) {
+        const { outputMode, temperature, maxOutputTokens: maxTokens, topP, ...rest } = options ?? {};
+        const determinedMode = this.determineOutputMode(outputSchema, outputMode);
+        // Convert messages to Vercel AI SDK format (shared utility)
+        const convertedMessages = convertMessagesToVercelFormat(messages);
+        const request = {
+            messages: convertedMessages,
+            ...rest,
+        };
+        // Add tools if provided
+        // Vercel AI SDK will convert OpenAI tool format to Anthropic's format
+        if (tools && tools.length > 0) {
+            request.tools = tools;
+        }
+        // Add standard parameters if provided
+        if (temperature !== undefined) {
+            request.temperature = temperature;
+        }
+        if (maxTokens !== undefined) {
+            request.maxOutputTokens = maxTokens;
+        }
+        if (topP !== undefined) {
+            request.topP = topP;
+        }
+        // Only add response_format in "strict" mode
+        if (determinedMode === "strict" && outputSchema) {
+            // Claude requires additionalProperties: false on all object types
+            // Unlike OpenAI/Gemini, Claude doesn't require all properties in 'required'
+            const strictSchema = makeSchemaStrict(outputSchema.schema, { addAllRequired: false });
+            request.responseFormat = {
+                type: "json_schema",
+                jsonSchema: {
+                    name: outputSchema.name,
+                    schema: strictSchema,
+                    strict: false, // Allow optional fields with defaults
+                },
+            };
+            debug(`Using strict mode with response_format for schema: ${outputSchema.name}`);
+        }
+        return request;
+    }
+    /**
+     * Format system prompt for Claude with output mode support.
+     *
+     * Output Mode Strategy:
+     * - strict: Minimal JSON instructions (response_format handles schema)
+     * - hint: Add detailed JSON schema instructions in prompt
+     * - text: No JSON instructions (plain text output)
+     */
+    formatSystemPrompt(basePrompt, toolSchemas, outputSchema, outputMode) {
+        let systemContent = basePrompt;
+        const determinedMode = this.determineOutputMode(outputSchema, outputMode);
+        // Add tool calling instructions if tools available
+        // These prevent Claude from using XML-style <invoke> syntax
+        if (toolSchemas && toolSchemas.length > 0) {
+            // Use base instructions but insert anti-XML rule for Claude
+            const instructions = BASE_TOOL_INSTRUCTIONS.replace("- Make ONE tool call at a time", `- Make ONE tool call at a time\n${CLAUDE_ANTI_XML_INSTRUCTION}`);
+            systemContent += instructions;
+        }
+        // Add output format instructions based on mode
+        if (determinedMode === "text") {
+            // Text mode: No JSON instructions
+            return systemContent;
+        }
+        if (determinedMode === "strict") {
+            // Strict mode: Minimal instructions (response_format handles schema)
+            if (outputSchema) {
+                systemContent += `
+
+Your final response will be structured as JSON matching the ${outputSchema.name} format.`;
+            }
+            return systemContent;
+        }
+        // Hint mode: Add detailed JSON schema instructions
+        if (determinedMode === "hint" && outputSchema) {
+            const properties = (outputSchema.schema.properties ?? {});
+            const required = (outputSchema.schema.required ?? []);
+            // Build human-readable schema description
+            const fieldDescriptions = [];
+            for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+                const fieldType = fieldSchema.type ?? "any";
+                const isRequired = required.includes(fieldName);
+                const reqMarker = isRequired ? " (required)" : " (optional)";
+                const desc = fieldSchema.description ?? "";
+                const descText = desc ? ` - ${desc}` : "";
+                fieldDescriptions.push(`  - ${fieldName}: ${fieldType}${reqMarker}${descText}`);
+            }
+            const fieldsText = fieldDescriptions.join("\n");
+            const exampleFormat = Object.fromEntries(Object.entries(properties).map(([k, v]) => [k, `<${v.type ?? "value"}>`]));
+            systemContent += `
+
+RESPONSE FORMAT:
+You MUST respond with valid JSON matching this schema:
+{
+${fieldsText}
+}
+
+Example format:
+${JSON.stringify(exampleFormat, null, 2)}
+
+IMPORTANT: Respond ONLY with valid JSON. No markdown code fences, no preamble text.`;
+        }
+        return systemContent;
+    }
+    /**
+     * Return Claude-specific capabilities.
+     */
+    getCapabilities() {
+        return {
+            nativeToolCalling: true, // Claude has native function calling
+            structuredOutput: true, // Native response_format support via Vercel AI SDK
+            streaming: true, // Supports streaming
+            vision: true, // Claude 3+ supports vision
+            jsonMode: true, // Native JSON mode via response_format
+            promptCaching: false, // TODO: Re-enable via experimental_providerOptions
+        };
+    }
+    /**
+     * Determine the output mode based on schema complexity.
+     *
+     * Logic:
+     * - If overrideMode specified, use it
+     * - If no schema (string return type), use "text" mode
+     * - If schema is simple (<5 fields, basic types), use "hint" mode
+     * - Otherwise, use "strict" mode
+     */
+    determineOutputMode(outputSchema, overrideMode) {
+        // Allow explicit override
+        if (overrideMode) {
+            return overrideMode;
+        }
+        // No schema means text mode (string return type)
+        if (!outputSchema) {
+            return "text";
+        }
+        // Check if schema is simple
+        if (this.isSimpleSchema(outputSchema)) {
+            return "hint";
+        }
+        // Complex schema - use strict mode
+        return "strict";
+    }
+    // ==========================================================================
+    // Private Helper Methods
+    // ==========================================================================
+    /**
+     * Check if a schema is simple enough for hint mode.
+     *
+     * Simple schema criteria:
+     * - Less than 5 fields
+     * - No nested objects (hasNestedObjects flag or $defs present)
+     */
+    isSimpleSchema(outputSchema) {
+        // Use pre-computed values if available
+        if (outputSchema.fieldCount !== undefined) {
+            if (outputSchema.fieldCount >= SIMPLE_SCHEMA_FIELD_THRESHOLD) {
+                return false;
+            }
+        }
+        if (outputSchema.hasNestedObjects !== undefined) {
+            return !outputSchema.hasNestedObjects;
+        }
+        // Analyze schema directly
+        const schema = outputSchema.schema;
+        const properties = schema.properties;
+        // Check field count
+        if (properties && Object.keys(properties).length >= SIMPLE_SCHEMA_FIELD_THRESHOLD) {
+            return false;
+        }
+        // Check for $defs (indicates nested models)
+        if (schema.$defs) {
+            return false;
+        }
+        // Check for nested objects in properties
+        if (properties) {
+            for (const fieldSchema of Object.values(properties)) {
+                const fs = fieldSchema;
+                // Check for nested objects
+                if (fs.type === "object" && fs.properties) {
+                    return false;
+                }
+                // Check for $ref (nested model reference)
+                if (fs.$ref) {
+                    return false;
+                }
+                // Check array items for complex types
+                if (fs.type === "array") {
+                    const items = fs.items;
+                    if (items?.type === "object" || items?.$ref) {
+                        return false;
+                    }
+                }
+            }
+        }
+        return true;
+    }
+}
+// Register with the registry
+ProviderHandlerRegistry.register("anthropic", ClaudeHandler);
+//# sourceMappingURL=claude-handler.js.map