@yourgpt/llm-sdk 1.5.42 → 1.5.44

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 YourGPT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,27 +4,24 @@ Multi-provider LLM SDK with streaming. One API, any provider.
 
 ## Installation
 
-```bash
-npm install @yourgpt/llm-sdk openai
-```
-
-For Anthropic, install `@anthropic-ai/sdk` instead:
-
 ```bash
 npm install @yourgpt/llm-sdk @anthropic-ai/sdk
 ```
 
+> For other providers (OpenAI, Google, xAI), see [Providers Documentation](https://copilot-sdk.yourgpt.ai/docs/providers).
+
 ## Quick Start
 
 ```ts
+// app/api/chat/route.ts
 import { streamText } from "@yourgpt/llm-sdk";
-import { openai } from "@yourgpt/llm-sdk/openai";
+import { anthropic } from "@yourgpt/llm-sdk/anthropic";
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = await streamText({
-    model: openai("gpt-4o"),
+    model: anthropic("claude-sonnet-4-20250514"),
     system: "You are a helpful assistant.",
     messages,
   });
@@ -33,104 +30,39 @@ export async function POST(req: Request) {
 }
 ```
 
-## Multi-Provider Support
-
-```ts
-import { openai } from "@yourgpt/llm-sdk/openai";
-import { anthropic } from "@yourgpt/llm-sdk/anthropic";
-import { google } from "@yourgpt/llm-sdk/google";
-import { xai } from "@yourgpt/llm-sdk/xai";
-
-// OpenAI
-await streamText({ model: openai("gpt-4o"), messages });
-
-// Anthropic
-await streamText({ model: anthropic("claude-sonnet-4-20250514"), messages });
-
-// Google Gemini (uses OpenAI-compatible API)
-await streamText({ model: google("gemini-2.0-flash"), messages });
-
-// xAI Grok (uses OpenAI-compatible API)
-await streamText({ model: xai("grok-3-fast"), messages });
-```
-
-## Server-Side Tools
-
-```ts
-import { streamText, tool } from "@yourgpt/llm-sdk";
-import { openai } from "@yourgpt/llm-sdk/openai";
-import { z } from "zod";
-
-const result = await streamText({
-  model: openai("gpt-4o"),
-  messages,
-  tools: {
-    getWeather: tool({
-      description: "Get current weather for a city",
-      parameters: z.object({
-        city: z.string().describe("City name"),
-      }),
-      execute: async ({ city }) => {
-        return { temperature: 72, condition: "sunny" };
-      },
-    }),
-  },
-  maxSteps: 5,
-});
-
-return result.toDataStreamResponse();
+```bash
+# .env.local
+ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-## Express Integration
+## With Copilot SDK
 
-Use the `createRuntime()` API with the new `stream()` method for Express:
+Use `createRuntime` for full Copilot SDK integration with tools support:
 
 ```ts
-import express from "express";
+// app/api/chat/route.ts
 import { createRuntime } from "@yourgpt/llm-sdk";
-import { createOpenAI } from "@yourgpt/llm-sdk/openai";
-
-const app = express();
-app.use(express.json());
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
 
 const runtime = createRuntime({
-  provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
-  model: "gpt-4o",
-});
-
-// One-liner streaming endpoint
-app.post("/api/chat", async (req, res) => {
-  await runtime.stream(req.body).pipeToResponse(res);
+  provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  model: "claude-sonnet-4-20250514",
+  systemPrompt: "You are a helpful assistant.",
 });
 
-app.listen(3001);
+export async function POST(req: Request) {
+  return runtime.stream(await req.json()).toResponse();
+}
 ```
 
-### Available Response Methods
-
-| Method                     | Framework     | Description                 |
-| -------------------------- | ------------- | --------------------------- |
-| `.toResponse()`            | Next.js, Deno | Returns Web Response        |
-| `.pipeToResponse(res)`     | Express, Node | Pipes SSE to ServerResponse |
-| `.pipeTextToResponse(res)` | Express, Node | Pipes text only             |
-| `.collect()`               | Any           | Collects full response      |
-
-## Supported Providers
-
-| Provider      | Import                       | SDK Required        |
-| ------------- | ---------------------------- | ------------------- |
-| OpenAI        | `@yourgpt/llm-sdk/openai`    | `openai`            |
-| Anthropic     | `@yourgpt/llm-sdk/anthropic` | `@anthropic-ai/sdk` |
-| Google Gemini | `@yourgpt/llm-sdk/google`    | `openai`            |
-| xAI (Grok)    | `@yourgpt/llm-sdk/xai`       | `openai`            |
-| Ollama        | `@yourgpt/llm-sdk/ollama`    | `openai`            |
-| Azure OpenAI  | `@yourgpt/llm-sdk/azure`     | `openai`            |
-
-> **Note:** OpenAI, Google, xAI, Ollama, and Azure all use the `openai` SDK because they have OpenAI-compatible APIs. Only Anthropic requires its native SDK for full feature support.
-
 ## Documentation
 
-Visit [copilot-sdk.yourgpt.ai](https://copilot-sdk.yourgpt.ai)
+Visit **[copilot-sdk.yourgpt.ai](https://copilot-sdk.yourgpt.ai)** for full documentation:
+
+- [All Providers](https://copilot-sdk.yourgpt.ai/docs/providers) - OpenAI, Anthropic, Google, xAI
+- [Server Setup](https://copilot-sdk.yourgpt.ai/docs/server) - Runtime, streaming, tools
+- [Tools](https://copilot-sdk.yourgpt.ai/docs/tools) - Server-side and client-side tools
+- [LLM SDK Reference](https://copilot-sdk.yourgpt.ai/docs/llm-sdk) - streamText, generateText
 
 ## License
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool, L as LLMAdapter, A as ActionDefinition, d as ToolDefinition, e as AgentLoopConfig, K as KnowledgeBaseConfig, D as DoneEventMessage, f as StreamEvent, g as ToolCallInfo, h as TokenUsageRaw, M as Message, i as ToolResponse } from './base-DdxolpKP.mjs';
+import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool, A as ActionDefinition, d as ToolDefinition, e as AgentLoopConfig, K as KnowledgeBaseConfig, L as LLMAdapter, D as DoneEventMessage, f as StreamEvent, g as ToolCallInfo, h as TokenUsageRaw, M as Message, i as ToolResponse } from './base-DdxolpKP.mjs';
 export { P as AdapterFactory, o as AssistantMessage, O as ChatCompletionRequest, C as CoreMessage, N as DEFAULT_CAPABILITIES, l as DoGenerateParams, m as DoGenerateResult, E as ErrorChunk, F as FilePart, B as FinishChunk, J as FinishReason, u as GenerateStep, I as ImagePart, Q as LLMConfig, j as LanguageModel, k as ModelCapabilities, R as ResponseOptions, w as StreamChunk, v as StreamPart, n as SystemMessage, x as TextDeltaChunk, r as TextPart, H as TokenUsage, s as ToolCall, y as ToolCallChunk, Y as ToolExecution, V as ToolLocation, p as ToolMessage, t as ToolResult, z as ToolResultChunk, W as UnifiedToolCall, X as UnifiedToolResult, q as UserContentPart, U as UserMessage } from './base-DdxolpKP.mjs';
 import { z } from 'zod';
 import { A as AIProvider } from './types-Ck25ZYma.mjs';
@@ -167,68 +167,11 @@ declare function formatToolsForGoogle(tools: Record<string, Tool>): Array<{
 }>;
 
 /**
- * LLM provider type for server-side configuration
- */
-type LLMProvider = "openai" | "anthropic" | "google" | "ollama" | "xai" | "azure";
-/**
- * Server-side LLM configuration (complete config for runtime)
- */
-interface ServerLLMConfig {
-    /** LLM provider */
-    provider: LLMProvider;
-    /** API key for the provider */
-    apiKey: string;
-    /** Model name */
-    model?: string;
-    /** Base URL for custom/self-hosted models */
-    baseUrl?: string;
-    /** Temperature (0-2) */
-    temperature?: number;
-    /** Maximum tokens in response */
-    maxTokens?: number;
-}
-/**
- * Runtime configuration with LLM config
- */
-interface RuntimeConfigWithLLM {
-    /** LLM configuration */
-    llm: ServerLLMConfig;
-    /** Custom LLM adapter (overrides llm config) */
-    adapter?: LLMAdapter;
-    /** System prompt */
-    systemPrompt?: string;
-    /** Available actions (legacy) */
-    actions?: ActionDefinition[];
-    /** Available tools (new - supports location: server/client) */
-    tools?: ToolDefinition[];
-    /** Agent loop configuration */
-    agentLoop?: AgentLoopConfig;
-    /** Knowledge base configuration (enables search_knowledge tool) */
-    knowledgeBase?: KnowledgeBaseConfig;
-    /** Enable debug logging */
-    debug?: boolean;
-    /**
-     * Custom context data passed to all tool handlers.
-     * Useful for passing auth tokens, user info, tenant data, etc.
-     *
-     * @example
-     * ```typescript
-     * const runtime = createRuntime({
-     *   llm: { ... },
-     *   toolContext: { userId: session.userId, tenantId: tenant.id },
-     * });
-     * ```
-     */
-    toolContext?: Record<string, unknown>;
-}
-/**
- * Runtime configuration with adapter
+ * Runtime configuration with adapter (advanced usage)
  */
 interface RuntimeConfigWithAdapter {
     /** Custom LLM adapter */
     adapter: LLMAdapter;
-    /** LLM configuration (optional when adapter provided) */
-    llm?: ServerLLMConfig;
     /** System prompt */
     systemPrompt?: string;
     /** Available actions (legacy) */
@@ -279,9 +222,23 @@ interface RuntimeConfigWithProvider {
     toolContext?: Record<string, unknown>;
 }
 /**
- * Runtime configuration - either provide llm config, adapter, or provider
+ * Runtime configuration - provide either a provider instance or a custom adapter
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Use provider instance
+ * const runtime = createRuntime({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   model: 'gpt-4o',
+ * });
+ *
+ * // Advanced: Use custom adapter
+ * const runtime = createRuntime({
+ *   adapter: myCustomAdapter,
+ * });
+ * ```
  */
-type RuntimeConfig = RuntimeConfigWithLLM | RuntimeConfigWithAdapter | RuntimeConfigWithProvider;
+type RuntimeConfig = RuntimeConfigWithProvider | RuntimeConfigWithAdapter;
 /**
  * Message attachment (images, files, etc.)
  */
@@ -823,10 +780,6 @@ declare class Runtime {
     private actions;
     private tools;
     constructor(config: RuntimeConfig);
-    /**
-     * Create LLM adapter based on config
-     */
-    private createAdapter;
     /**
      * Process a chat request and return streaming response
      */
@@ -887,10 +840,6 @@ declare class Runtime {
      * Get registered tools
      */
     getTools(): ToolDefinition[];
-    /**
-     * Get the AI provider name from config
-     */
-    private getProviderName;
     /**
      * Get the AI provider instance (if using provider config)
      */
@@ -1152,16 +1101,36 @@ declare function createHonoApp(runtime: Runtime): Hono;
 /**
  * Next.js App Router handler
  *
+ * For simple Next.js routes, prefer using `streamText()` directly:
+ * @example
+ * ```ts
+ * // app/api/chat/route.ts (RECOMMENDED)
+ * import { streamText } from '@yourgpt/llm-sdk';
+ * import { openai } from '@yourgpt/llm-sdk/openai';
+ *
+ * export async function POST(req: Request) {
+ *   const { messages } = await req.json();
+ *   const result = await streamText({
+ *     model: openai('gpt-4o'),
+ *     system: 'You are a helpful assistant.',
+ *     messages,
+ *   });
+ *   return result.toTextStreamResponse();
+ * }
+ * ```
+ *
+ * Use createNextHandler when you need runtime features like tools:
  * @example
  * ```ts
  * // app/api/chat/route.ts
  * import { createNextHandler } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
  *
- * const handler = createNextHandler({
- *   llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ * export const POST = createNextHandler({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   model: 'gpt-4o',
+ *   systemPrompt: 'You are a helpful assistant.',
  * });
- *
- * export const POST = handler;
  * ```
  */
 declare function createNextHandler(config: RuntimeConfig): (request: Request) => Promise<Response>;
@@ -1255,9 +1224,12 @@ declare function createExpressHandler(runtime: Runtime, options?: {
  * ```ts
  * import http from 'http';
  * import { createNodeHandler } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
  *
  * const handler = createNodeHandler({
- *   llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   model: 'gpt-4o',
+ *   systemPrompt: 'You are a helpful assistant.',
  * });
  *
  * const server = http.createServer(handler);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool, L as LLMAdapter, A as ActionDefinition, d as ToolDefinition, e as AgentLoopConfig, K as KnowledgeBaseConfig, D as DoneEventMessage, f as StreamEvent, g as ToolCallInfo, h as TokenUsageRaw, M as Message, i as ToolResponse } from './base-DdxolpKP.js';
+import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool, A as ActionDefinition, d as ToolDefinition, e as AgentLoopConfig, K as KnowledgeBaseConfig, L as LLMAdapter, D as DoneEventMessage, f as StreamEvent, g as ToolCallInfo, h as TokenUsageRaw, M as Message, i as ToolResponse } from './base-DdxolpKP.js';
 export { P as AdapterFactory, o as AssistantMessage, O as ChatCompletionRequest, C as CoreMessage, N as DEFAULT_CAPABILITIES, l as DoGenerateParams, m as DoGenerateResult, E as ErrorChunk, F as FilePart, B as FinishChunk, J as FinishReason, u as GenerateStep, I as ImagePart, Q as LLMConfig, j as LanguageModel, k as ModelCapabilities, R as ResponseOptions, w as StreamChunk, v as StreamPart, n as SystemMessage, x as TextDeltaChunk, r as TextPart, H as TokenUsage, s as ToolCall, y as ToolCallChunk, Y as ToolExecution, V as ToolLocation, p as ToolMessage, t as ToolResult, z as ToolResultChunk, W as UnifiedToolCall, X as UnifiedToolResult, q as UserContentPart, U as UserMessage } from './base-DdxolpKP.js';
 import { z } from 'zod';
 import { A as AIProvider } from './types-Dsz8SpdB.js';
@@ -167,68 +167,11 @@ declare function formatToolsForGoogle(tools: Record<string, Tool>): Array<{
 }>;
 
 /**
- * LLM provider type for server-side configuration
- */
-type LLMProvider = "openai" | "anthropic" | "google" | "ollama" | "xai" | "azure";
-/**
- * Server-side LLM configuration (complete config for runtime)
- */
-interface ServerLLMConfig {
-    /** LLM provider */
-    provider: LLMProvider;
-    /** API key for the provider */
-    apiKey: string;
-    /** Model name */
-    model?: string;
-    /** Base URL for custom/self-hosted models */
-    baseUrl?: string;
-    /** Temperature (0-2) */
-    temperature?: number;
-    /** Maximum tokens in response */
-    maxTokens?: number;
-}
-/**
- * Runtime configuration with LLM config
- */
-interface RuntimeConfigWithLLM {
-    /** LLM configuration */
-    llm: ServerLLMConfig;
-    /** Custom LLM adapter (overrides llm config) */
-    adapter?: LLMAdapter;
-    /** System prompt */
-    systemPrompt?: string;
-    /** Available actions (legacy) */
-    actions?: ActionDefinition[];
-    /** Available tools (new - supports location: server/client) */
-    tools?: ToolDefinition[];
-    /** Agent loop configuration */
-    agentLoop?: AgentLoopConfig;
-    /** Knowledge base configuration (enables search_knowledge tool) */
-    knowledgeBase?: KnowledgeBaseConfig;
-    /** Enable debug logging */
-    debug?: boolean;
-    /**
-     * Custom context data passed to all tool handlers.
-     * Useful for passing auth tokens, user info, tenant data, etc.
-     *
-     * @example
-     * ```typescript
-     * const runtime = createRuntime({
-     *   llm: { ... },
-     *   toolContext: { userId: session.userId, tenantId: tenant.id },
-     * });
-     * ```
-     */
-    toolContext?: Record<string, unknown>;
-}
-/**
- * Runtime configuration with adapter
+ * Runtime configuration with adapter (advanced usage)
  */
 interface RuntimeConfigWithAdapter {
     /** Custom LLM adapter */
     adapter: LLMAdapter;
-    /** LLM configuration (optional when adapter provided) */
-    llm?: ServerLLMConfig;
     /** System prompt */
     systemPrompt?: string;
     /** Available actions (legacy) */
@@ -279,9 +222,23 @@ interface RuntimeConfigWithProvider {
     toolContext?: Record<string, unknown>;
 }
 /**
- * Runtime configuration - either provide llm config, adapter, or provider
+ * Runtime configuration - provide either a provider instance or a custom adapter
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Use provider instance
+ * const runtime = createRuntime({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   model: 'gpt-4o',
+ * });
+ *
+ * // Advanced: Use custom adapter
+ * const runtime = createRuntime({
+ *   adapter: myCustomAdapter,
+ * });
+ * ```
  */
-type RuntimeConfig = RuntimeConfigWithLLM | RuntimeConfigWithAdapter | RuntimeConfigWithProvider;
+type RuntimeConfig = RuntimeConfigWithProvider | RuntimeConfigWithAdapter;
 /**
  * Message attachment (images, files, etc.)
  */
@@ -823,10 +780,6 @@ declare class Runtime {
     private actions;
     private tools;
     constructor(config: RuntimeConfig);
-    /**
-     * Create LLM adapter based on config
-     */
-    private createAdapter;
     /**
      * Process a chat request and return streaming response
      */
@@ -887,10 +840,6 @@ declare class Runtime {
      * Get registered tools
      */
     getTools(): ToolDefinition[];
-    /**
-     * Get the AI provider name from config
-     */
-    private getProviderName;
     /**
      * Get the AI provider instance (if using provider config)
      */
@@ -1152,16 +1101,36 @@ declare function createHonoApp(runtime: Runtime): Hono;
 /**
  * Next.js App Router handler
  *
+ * For simple Next.js routes, prefer using `streamText()` directly:
+ * @example
+ * ```ts
+ * // app/api/chat/route.ts (RECOMMENDED)
+ * import { streamText } from '@yourgpt/llm-sdk';
+ * import { openai } from '@yourgpt/llm-sdk/openai';
+ *
+ * export async function POST(req: Request) {
+ *   const { messages } = await req.json();
+ *   const result = await streamText({
+ *     model: openai('gpt-4o'),
+ *     system: 'You are a helpful assistant.',
+ *     messages,
+ *   });
+ *   return result.toTextStreamResponse();
+ * }
+ * ```
+ *
+ * Use createNextHandler when you need runtime features like tools:
  * @example
  * ```ts
  * // app/api/chat/route.ts
  * import { createNextHandler } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
  *
- * const handler = createNextHandler({
- *   llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ * export const POST = createNextHandler({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   model: 'gpt-4o',
+ *   systemPrompt: 'You are a helpful assistant.',
  * });
- *
- * export const POST = handler;
  * ```
  */
 declare function createNextHandler(config: RuntimeConfig): (request: Request) => Promise<Response>;
@@ -1255,9 +1224,12 @@ declare function createExpressHandler(runtime: Runtime, options?: {
  * ```ts
  * import http from 'http';
  * import { createNodeHandler } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
  *
  * const handler = createNodeHandler({
- *   llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   model: 'gpt-4o',
+ *   systemPrompt: 'You are a helpful assistant.',
  * });
  *
  * const server = http.createServer(handler);