@yourgpt/llm-sdk 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @yourgpt/llm-sdk
+
+Multi-provider LLM integration for Copilot SDK.
+
+## Installation
+
+```bash
+npm install @yourgpt/llm-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createRuntime, createOpenAI } from "@yourgpt/llm-sdk";
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const runtime = createRuntime({
+  provider: openai,
+  model: "gpt-4o",
+  systemPrompt: "You are a helpful assistant.",
+});
+
+// Next.js App Router
+export async function POST(request: Request) {
+  return runtime.handleRequest(request);
+}
+```
+
+## Supported Providers
+
+| Provider      | Factory             |
+| ------------- | ------------------- |
+| OpenAI        | `createOpenAI()`    |
+| Anthropic     | `createAnthropic()` |
+| Google Gemini | `createGoogle()`    |
+| Groq          | `createGroq()`      |
+| Ollama        | `createOllama()`    |
+| xAI (Grok)    | `createXAI()`       |
+| Azure OpenAI  | `createAzure()`     |
+
+## Framework Integrations
+
+```typescript
+// Next.js
+import { createNextHandler } from "@yourgpt/llm-sdk";
+
+// Express
+import { createExpressMiddleware } from "@yourgpt/llm-sdk";
+
+// Hono
+import { createHonoApp } from "@yourgpt/llm-sdk";
+
+// Node.js HTTP
+import { createNodeHandler } from "@yourgpt/llm-sdk";
+```
+
+## Features
+
+- Multi-provider support (7 LLM providers)
+- Streaming responses (SSE)
+- Agent loop for multi-step tool execution
+- Framework-agnostic with built-in integrations
+- TypeScript-first
+
+## Documentation
+
+Visit [copilot-sdk.yourgpt.ai](https://copilot-sdk.yourgpt.ai)
+
+## License
+
+MIT

package/dist/adapters/index.d.mts

@@ -0,0 +1,497 @@
+import { Message, ActionDefinition, LLMConfig, StreamEvent, MessageAttachment } from '@yourgpt/copilot-sdk/core';
+
+/**
+ * Chat completion request
+ */
+interface ChatCompletionRequest {
+    /** Conversation messages */
+    messages: Message[];
+    /**
+     * Raw provider-formatted messages (for agent loop with tool calls)
+     * When provided, these are used instead of converting from Message[]
+     * This allows passing messages with tool_calls and tool role
+     */
+    rawMessages?: Array<Record<string, unknown>>;
+    /** Available actions/tools */
+    actions?: ActionDefinition[];
+    /** System prompt */
+    systemPrompt?: string;
+    /** LLM configuration overrides */
+    config?: Partial<LLMConfig>;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Non-streaming completion result
+ */
+interface CompletionResult {
+    /** Text content */
+    content: string;
+    /** Tool calls */
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    /** Thinking content (if extended thinking enabled) */
+    thinking?: string;
+    /** Raw provider response for debugging */
+    rawResponse: Record<string, unknown>;
+}
+/**
+ * Base LLM adapter interface
+ */
+interface LLMAdapter {
+    /** Provider name */
+    readonly provider: string;
+    /** Model name */
+    readonly model: string;
+    /**
+     * Stream a chat completion
+     */
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming chat completion (for debugging/comparison)
+     */
+    complete?(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Adapter factory function type
+ */
+type AdapterFactory = (config: LLMConfig) => LLMAdapter;
+/**
+ * Convert messages to provider format (simple text only)
+ */
+declare function formatMessages(messages: Message[], systemPrompt?: string): Array<{
+    role: string;
+    content: string;
+}>;
+/**
+ * Convert actions to OpenAI tool format
+ */
+declare function formatTools(actions: ActionDefinition[]): Array<{
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+    };
+}>;
+/**
+ * Content block types for multimodal messages
+ */
+type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+} | {
+    type: "document";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+};
+type OpenAIContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "low" | "high" | "auto";
+    };
+};
+/**
+ * Check if a message has image attachments
+ * Supports both new format (metadata.attachments) and legacy (attachments)
+ */
+declare function hasImageAttachments(message: Message): boolean;
+/**
+ * Check if a message has media attachments (images or PDFs)
+ */
+declare function hasMediaAttachments(message: Message): boolean;
+/**
+ * Convert MessageAttachment to Anthropic image content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "image",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "image/png",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicImage(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert MessageAttachment to OpenAI image_url content block
+ *
+ * OpenAI format:
+ * {
+ *   type: "image_url",
+ *   image_url: {
+ *     url: "data:image/png;base64,..."
+ *   }
+ * }
+ */
+declare function attachmentToOpenAIImage(attachment: MessageAttachment): OpenAIContentBlock | null;
+/**
+ * Convert MessageAttachment (PDF) to Anthropic document content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "document",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "application/pdf",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicDocument(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert a Message to Anthropic multimodal content blocks
+ */
+declare function messageToAnthropicContent(message: Message): string | AnthropicContentBlock[];
+/**
+ * Convert a Message to OpenAI multimodal content blocks
+ */
+declare function messageToOpenAIContent(message: Message): string | OpenAIContentBlock[];
+/**
+ * Anthropic content block types (extended for tools)
+ */
+type AnthropicToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type AnthropicToolResultBlock = {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+};
+type AnthropicMessageContent = string | Array<AnthropicContentBlock | AnthropicToolUseBlock | AnthropicToolResultBlock>;
+/**
+ * Format messages for Anthropic with full tool support
+ * Handles: text, images, tool_use, and tool_result
+ *
+ * Key differences from OpenAI:
+ * - tool_calls become tool_use blocks in assistant content
+ * - tool results become tool_result blocks in user content
+ */
+declare function formatMessagesForAnthropic(messages: Message[], systemPrompt?: string): {
+    system: string;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: AnthropicMessageContent;
+    }>;
+};
+/**
+ * OpenAI message format with tool support
+ */
+type OpenAIMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | OpenAIContentBlock[];
+} | {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+} | {
+    role: "tool";
+    content: string;
+    tool_call_id: string;
+};
+/**
+ * Format messages for OpenAI with full tool support
+ * Handles: text, images, tool_calls, and tool results
+ */
+declare function formatMessagesForOpenAI(messages: Message[], systemPrompt?: string): OpenAIMessage[];
+
+/**
+ * OpenAI adapter configuration
+ */
+interface OpenAIAdapterConfig extends Partial<LLMConfig> {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * OpenAI LLM Adapter
+ *
+ * Supports: GPT-4, GPT-4o, GPT-3.5-turbo, etc.
+ */
+declare class OpenAIAdapter implements LLMAdapter {
+    readonly provider = "openai";
+    readonly model: string;
+    private client;
+    private config;
+    constructor(config: OpenAIAdapterConfig);
+    private getClient;
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+}
+/**
+ * Create OpenAI adapter
+ */
+declare function createOpenAIAdapter(config: OpenAIAdapterConfig): OpenAIAdapter;
+
+/**
+ * Extended thinking configuration
+ */
+interface ThinkingConfig {
+    type: "enabled";
+    /** Budget for thinking tokens (minimum 1024) */
+    budgetTokens?: number;
+}
+/**
+ * Anthropic adapter configuration
+ */
+interface AnthropicAdapterConfig extends Partial<LLMConfig> {
+    apiKey: string;
+    model?: string;
+    /** Enable extended thinking (for Claude 3.7 Sonnet, Claude 4) */
+    thinking?: ThinkingConfig;
+}
+/**
+ * Anthropic LLM Adapter
+ *
+ * Supports: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku, etc.
+ */
+declare class AnthropicAdapter implements LLMAdapter {
+    readonly provider = "anthropic";
+    readonly model: string;
+    private client;
+    private config;
+    constructor(config: AnthropicAdapterConfig);
+    private getClient;
+    /**
+     * Convert OpenAI-style messages to Anthropic format
+     *
+     * OpenAI format:
+     * - { role: "assistant", content: "...", tool_calls: [...] }
+     * - { role: "tool", tool_call_id: "...", content: "..." }
+     *
+     * Anthropic format:
+     * - { role: "assistant", content: [{ type: "text", text: "..." }, { type: "tool_use", id: "...", name: "...", input: {...} }] }
+     * - { role: "user", content: [{ type: "tool_result", tool_use_id: "...", content: "..." }] }
+     */
+    private convertToAnthropicMessages;
+    /**
+     * Build common request options for both streaming and non-streaming
+     */
+    private buildRequestOptions;
+    /**
+     * Non-streaming completion (for debugging/comparison with original studio-ai)
+     */
+    complete(request: ChatCompletionRequest): Promise<CompletionResult>;
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+}
+/**
+ * Create Anthropic adapter
+ */
+declare function createAnthropicAdapter(config: AnthropicAdapterConfig): AnthropicAdapter;
+
+/**
+ * Groq adapter configuration
+ */
+interface GroqAdapterConfig extends Partial<LLMConfig> {
+    apiKey: string;
+    model?: string;
+}
+/**
+ * Groq LLM Adapter (Fast inference)
+ *
+ * Supports: Llama 3.1, Mixtral, Gemma, etc.
+ */
+declare class GroqAdapter implements LLMAdapter {
+    readonly provider = "groq";
+    readonly model: string;
+    private config;
+    constructor(config: GroqAdapterConfig);
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+}
+/**
+ * Create Groq adapter
+ */
+declare function createGroqAdapter(config: GroqAdapterConfig): GroqAdapter;
+
+/**
+ * Ollama adapter configuration
+ */
+interface OllamaAdapterConfig extends Partial<LLMConfig> {
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * Ollama LLM Adapter (Local models)
+ *
+ * Supports: Llama 3, Mistral, Phi, Gemma, CodeLlama, etc.
+ */
+declare class OllamaAdapter implements LLMAdapter {
+    readonly provider = "ollama";
+    readonly model: string;
+    private baseUrl;
+    private config;
+    constructor(config?: OllamaAdapterConfig);
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+}
+/**
+ * Create Ollama adapter
+ */
+declare function createOllamaAdapter(config?: OllamaAdapterConfig): OllamaAdapter;
+
+/**
+ * Google Gemini LLM Adapter
+ *
+ * Supports: Gemini 2.0, 1.5 Pro, 1.5 Flash, etc.
+ * Features: Vision, Audio, Video, PDF, Tools/Function Calling
+ */
+
+/**
+ * Google adapter configuration
+ */
+interface GoogleAdapterConfig extends Partial<LLMConfig> {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    /** Safety settings */
+    safetySettings?: Array<{
+        category: string;
+        threshold: string;
+    }>;
+}
+/**
+ * Google Gemini LLM Adapter
+ */
+declare class GoogleAdapter implements LLMAdapter {
+    readonly provider = "google";
+    readonly model: string;
+    private client;
+    private config;
+    constructor(config: GoogleAdapterConfig);
+    private getClient;
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming completion (optional, for debugging)
+     */
+    complete(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Create Google Gemini adapter
+ */
+declare function createGoogleAdapter(config: GoogleAdapterConfig): GoogleAdapter;
+
+/**
+ * xAI Grok LLM Adapter
+ *
+ * xAI uses an OpenAI-compatible API, so this adapter extends OpenAIAdapter
+ * with a different base URL.
+ *
+ * Supports: Grok-2, Grok-2-mini, Grok-beta
+ * Features: Vision, Tools/Function Calling
+ */
+
+/**
+ * xAI adapter configuration
+ */
+interface XAIAdapterConfig extends Partial<LLMConfig> {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * xAI Grok LLM Adapter
+ *
+ * Uses OpenAI-compatible API with xAI's endpoint
+ */
+declare class XAIAdapter implements LLMAdapter {
+    readonly provider = "xai";
+    readonly model: string;
+    private client;
+    private config;
+    constructor(config: XAIAdapterConfig);
+    private getClient;
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming completion (optional, for debugging)
+     */
+    complete(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Create xAI Grok adapter
+ */
+declare function createXAIAdapter(config: XAIAdapterConfig): XAIAdapter;
+
+/**
+ * Azure OpenAI LLM Adapter
+ *
+ * Azure OpenAI uses Microsoft's cloud infrastructure with
+ * different authentication and URL patterns than standard OpenAI.
+ *
+ * Supports: Any OpenAI model deployed on Azure (GPT-4, GPT-4o, etc.)
+ * Features: Vision, Tools/Function Calling (depends on deployed model)
+ */
+
+/**
+ * Azure OpenAI adapter configuration
+ */
+interface AzureAdapterConfig extends Partial<LLMConfig> {
+    /** Azure OpenAI API key */
+    apiKey: string;
+    /** Azure resource name (e.g., 'my-resource') */
+    resourceName: string;
+    /** Azure deployment name (e.g., 'gpt-4o-deployment') */
+    deploymentName: string;
+    /** API version (default: 2024-08-01-preview) */
+    apiVersion?: string;
+    /** Custom endpoint URL (optional, overrides resourceName) */
+    baseUrl?: string;
+}
+/**
+ * Azure OpenAI LLM Adapter
+ *
+ * Uses Azure's OpenAI service with Azure-specific authentication
+ */
+declare class AzureAdapter implements LLMAdapter {
+    readonly provider = "azure";
+    readonly model: string;
+    private client;
+    private config;
+    constructor(config: AzureAdapterConfig);
+    private getClient;
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming completion (optional, for debugging)
+     */
+    complete(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Create Azure OpenAI adapter
+ */
+declare function createAzureAdapter(config: AzureAdapterConfig): AzureAdapter;
+
+export { type AdapterFactory, AnthropicAdapter, type AnthropicAdapterConfig, type AnthropicContentBlock, AzureAdapter, type AzureAdapterConfig, type ChatCompletionRequest, type CompletionResult, GoogleAdapter, type GoogleAdapterConfig, GroqAdapter, type GroqAdapterConfig, type LLMAdapter, OllamaAdapter, type OllamaAdapterConfig, OpenAIAdapter, type OpenAIAdapterConfig, type OpenAIContentBlock, XAIAdapter, type XAIAdapterConfig, attachmentToAnthropicDocument, attachmentToAnthropicImage, attachmentToOpenAIImage, createAnthropicAdapter, createAzureAdapter, createGoogleAdapter, createGroqAdapter, createOllamaAdapter, createOpenAIAdapter, createXAIAdapter, formatMessages, formatMessagesForAnthropic, formatMessagesForOpenAI, formatTools, hasImageAttachments, hasMediaAttachments, messageToAnthropicContent, messageToOpenAIContent };