@mcpmesh/sdk 0.8.0-beta.1

package/dist/llm-agent.d.ts

@@ -0,0 +1,193 @@
+/**
+ * MeshLlmAgent - Agentic loop implementation for LLM-powered tools.
+ *
+ * This class handles:
+ * - System prompt rendering (with Handlebars templates)
+ * - Agentic loop with tool execution
+ * - LLM provider calls (direct LiteLLM or mesh delegation)
+ * - Response parsing with Zod validation
+ * - Metadata tracking (tokens, latency, tool calls)
+ *
+ * @example
+ * ```typescript
+ * const agent = new MeshLlmAgent({
+ *   provider: "claude",
+ *   model: "anthropic/claude-sonnet-4-20250514",
+ *   systemPrompt: "file://prompts/assistant.hbs",
+ *   maxIterations: 10,
+ *   returnSchema: ResponseSchema,
+ * });
+ *
+ * const result = await agent.run("Help me calculate 2+2", {
+ *   templateContext: { user: "John" },
+ *   tools: resolvedToolProxies,
+ * });
+ * ```
+ */
+import type { ZodType } from "zod";
+import type { LlmProviderSpec, LlmMeta, LlmMessage, LlmToolDefinition, LlmCompletionResponse, LlmToolProxy, LlmCallOptions, LlmMessageInput, LlmOutputMode } from "./types.js";
+/**
+ * Configuration for MeshLlmAgent.
+ */
+export interface MeshLlmAgentConfig {
+    /** Function ID (used for event matching) */
+    functionId: string;
+    /** LLM provider spec */
+    provider: LlmProviderSpec;
+    /** Model override */
+    model?: string;
+    /** System prompt template */
+    systemPrompt?: string;
+    /** Parameter name for template context */
+    contextParam?: string;
+    /** Max agentic loop iterations */
+    maxIterations: number;
+    /** Max tokens */
+    maxOutputTokens?: number;
+    /** Temperature */
+    temperature?: number;
+    /** Top-p */
+    topP?: number;
+    /** Stop sequences */
+    stop?: string[];
+    /** Return schema for validation */
+    returnSchema?: ZodType;
+    /** Output mode: strict, hint, or text */
+    outputMode?: LlmOutputMode;
+}
+/**
+ * Runtime context for agent execution.
+ */
+export interface AgentRunContext {
+    /** Template context (from contextParam or runtime override) */
+    templateContext?: Record<string, unknown>;
+    /** Resolved tool proxies from mesh */
+    tools: LlmToolProxy[];
+    /** Resolved mesh provider (if using mesh delegation) */
+    meshProvider?: {
+        endpoint: string;
+        functionName: string;
+        model?: string;
+    };
+    /** Runtime overrides */
+    options?: LlmCallOptions;
+}
+/**
+ * Provider interface for making LLM completion calls.
+ */
+export interface LlmProvider {
+    complete(model: string, messages: LlmMessage[], tools?: LlmToolDefinition[], options?: {
+        maxOutputTokens?: number;
+        temperature?: number;
+        topP?: number;
+        stop?: string[];
+    }): Promise<LlmCompletionResponse>;
+}
+/**
+ * Default LiteLLM provider using HTTP proxy.
+ * Assumes LiteLLM proxy is running at LITELLM_URL or localhost:4000.
+ */
+export declare class LiteLLMProvider implements LlmProvider {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    complete(model: string, messages: LlmMessage[], tools?: LlmToolDefinition[], options?: {
+        maxOutputTokens?: number;
+        temperature?: number;
+        topP?: number;
+        stop?: string[];
+    }): Promise<LlmCompletionResponse>;
+}
+/**
+ * Mesh provider that delegates to an LLM provider discovered via mesh.
+ */
+export declare class MeshDelegatedProvider implements LlmProvider {
+    private endpoint;
+    private functionName;
+    constructor(endpoint: string, functionName: string);
+    complete(model: string, messages: LlmMessage[], tools?: LlmToolDefinition[], options?: {
+        maxOutputTokens?: number;
+        temperature?: number;
+        topP?: number;
+        stop?: string[];
+    }): Promise<LlmCompletionResponse>;
+}
+/**
+ * MeshLlmAgent - The core agentic loop implementation.
+ */
+export declare class MeshLlmAgent<T = string> {
+    private config;
+    private responseParser;
+    private _meta;
+    private _systemPromptOverride;
+    constructor(config: MeshLlmAgentConfig);
+    /**
+     * Get metadata from the last run.
+     */
+    get meta(): LlmMeta | null;
+    /**
+     * Override the system prompt at runtime.
+     */
+    setSystemPrompt(prompt: string): void;
+    /**
+     * Get the effective system prompt (override or config).
+     */
+    private getSystemPrompt;
+    /**
+     * Run the agentic loop.
+     *
+     * @param messageInput - User message string or multi-turn message array
+     * @param context - Runtime context with tools and options
+     * @returns Parsed response (validated if schema provided)
+     */
+    run(messageInput: LlmMessageInput, context: AgentRunContext): Promise<T>;
+    /**
+     * Create a callable LlmAgent interface.
+     */
+    createCallable(context: AgentRunContext): {
+        (message: LlmMessageInput, options?: LlmCallOptions): Promise<T>;
+        readonly meta: LlmMeta | null;
+        readonly tools: LlmToolProxy[];
+        setSystemPrompt(prompt: string): void;
+    };
+    /**
+     * Resolve the LLM provider to use.
+     */
+    private resolveProvider;
+    /**
+     * Get provider name for metadata.
+     */
+    private getProviderName;
+    /**
+     * Get default model based on provider.
+     */
+    private getDefaultModel;
+    /**
+     * Build tool definitions from proxies.
+     */
+    private buildToolDefinitions;
+    /**
+     * Build tool schema section for system prompt injection.
+     * Helps the LLM understand available tools and their schemas.
+     */
+    private buildToolSchemaSection;
+    /**
+     * Build output schema section for system prompt injection.
+     * Guides the LLM to produce structured output matching the schema.
+     */
+    private buildOutputSchemaSection;
+    /**
+     * Execute a tool call and record metadata.
+     */
+    private executeToolCall;
+}
+/**
+ * Create a tool proxy from resolved tool info.
+ */
+export declare function createLlmToolProxy(toolInfo: {
+    functionName: string;
+    capability: string;
+    endpoint: string;
+    agentId: string;
+    inputSchema?: string;
+}, description?: string): LlmToolProxy;
+//# sourceMappingURL=llm-agent.d.ts.map

package/dist/llm-agent.d.ts.map

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