ai.matey.wrapper 0.2.0

package/dist/types/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Headless Chat Client Types
+ *
+ * Type definitions for the framework-agnostic chat client.
+ *
+ * @module
+ */
+import type { IRMessage, IRChatResponse, IRStreamChunk, IRUsage, IRParameters, IRTool } from 'ai.matey.types';
+/**
+ * Configuration options for creating a chat instance.
+ */
+export interface ChatConfig {
+    /**
+     * The Bridge or BackendAdapter to use for requests.
+     * Can be either a Bridge instance or a raw BackendAdapter.
+     */
+    readonly backend: ChatBackend;
+    /**
+     * System prompt to prepend to all conversations.
+     * Can be a string or a function that returns a string (for dynamic prompts).
+     */
+    readonly systemPrompt?: string | (() => string | Promise<string>);
+    /**
+     * Maximum number of messages to keep in history.
+     * Older messages are dropped when limit is exceeded.
+     * @default 100
+     */
+    readonly historyLimit?: number;
+    /**
+     * Default parameters for all requests.
+     * Can be overridden per-request.
+     */
+    readonly defaultParameters?: IRParameters;
+    /**
+     * Available tools for the conversation.
+     */
+    readonly tools?: readonly IRTool[];
+    /**
+     * Called when a tool needs to be executed.
+     * If not provided, tool calls will be included in responses but not executed.
+     */
+    readonly onToolCall?: ToolCallHandler;
+    /**
+     * Auto-execute tool calls and continue the conversation.
+     * Requires onToolCall to be set.
+     * @default false
+     */
+    readonly autoExecuteTools?: boolean;
+    /**
+     * Maximum number of consecutive tool call rounds.
+     * Prevents infinite loops when autoExecuteTools is enabled.
+     * @default 10
+     */
+    readonly maxToolRounds?: number;
+}
+/**
+ * Backend interface - either a Bridge or BackendAdapter.
+ * Both have execute() and executeStream() methods.
+ */
+export interface ChatBackend {
+    execute(request: import('ai.matey.types').IRChatRequest, signal?: AbortSignal): Promise<IRChatResponse>;
+    executeStream?(request: import('ai.matey.types').IRChatRequest, signal?: AbortSignal): AsyncGenerator<IRStreamChunk, void, undefined>;
+}
+/**
+ * Handler for tool calls.
+ */
+export type ToolCallHandler = (toolName: string, toolInput: Record<string, unknown>, toolId: string) => Promise<string | {
+    content: string;
+    isError?: boolean;
+}>;
+/**
+ * Options for a single chat request.
+ */
+export interface SendOptions {
+    /**
+     * Override default parameters for this request.
+     */
+    readonly parameters?: IRParameters;
+    /**
+     * AbortSignal to cancel the request.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Custom metadata to include in the request.
+     */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Options for streaming requests.
+ */
+export interface StreamOptions extends SendOptions {
+    /**
+     * Called for each content chunk.
+     */
+    readonly onChunk?: (chunk: StreamChunkEvent) => void;
+    /**
+     * Called when streaming starts.
+     */
+    readonly onStart?: (metadata: {
+        requestId: string;
+    }) => void;
+    /**
+     * Called when streaming completes.
+     */
+    readonly onDone?: (response: ChatResponse) => void;
+    /**
+     * Called on error.
+     */
+    readonly onError?: (error: Error) => void;
+    /**
+     * Called for tool use chunks.
+     */
+    readonly onToolUse?: (tool: {
+        id: string;
+        name: string;
+        input: string;
+    }) => void;
+}
+/**
+ * Simplified chat response.
+ */
+export interface ChatResponse {
+    /**
+     * The assistant's response content as a string.
+     */
+    readonly content: string;
+    /**
+     * The full message object.
+     */
+    readonly message: IRMessage;
+    /**
+     * Why generation stopped.
+     */
+    readonly finishReason: IRChatResponse['finishReason'];
+    /**
+     * Token usage for this response.
+     */
+    readonly usage?: IRUsage;
+    /**
+     * Tool calls in the response, if any.
+     */
+    readonly toolCalls?: readonly ToolCall[];
+    /**
+     * Request ID for correlation.
+     */
+    readonly requestId: string;
+}
+/**
+ * Tool call extracted from response.
+ */
+export interface ToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+}
+/**
+ * Stream chunk event for callbacks.
+ */
+export interface StreamChunkEvent {
+    /**
+     * The delta content (new text only).
+     */
+    readonly delta: string;
+    /**
+     * Accumulated content so far.
+     */
+    readonly accumulated: string;
+    /**
+     * Chunk sequence number.
+     */
+    readonly sequence: number;
+}
+/**
+ * Conversation state snapshot.
+ */
+export interface ConversationState {
+    /**
+     * All messages in the conversation.
+     */
+    readonly messages: readonly IRMessage[];
+    /**
+     * Whether a request is currently in progress.
+     */
+    readonly isLoading: boolean;
+    /**
+     * Current error, if any.
+     */
+    readonly error: Error | null;
+    /**
+     * Cumulative token usage across the conversation.
+     */
+    readonly totalUsage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly totalTokens: number;
+    };
+    /**
+     * Number of requests made.
+     */
+    readonly requestCount: number;
+}
+/**
+ * Event types emitted by the chat instance.
+ */
+export type ChatEventType = 'message' | 'stream-start' | 'stream-chunk' | 'stream-done' | 'error' | 'state-change';
+/**
+ * Event listener callback.
+ */
+export type ChatEventListener<T = unknown> = (event: T) => void;
+/**
+ * Event data for each event type.
+ */
+export interface ChatEvents {
+    message: {
+        message: IRMessage;
+        response: ChatResponse;
+    };
+    'stream-start': {
+        requestId: string;
+    };
+    'stream-chunk': StreamChunkEvent;
+    'stream-done': {
+        response: ChatResponse;
+    };
+    error: {
+        error: Error;
+    };
+    'state-change': {
+        state: ConversationState;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

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

package/package.json

@@ -0,0 +1,132 @@
+{
+  "name": "ai.matey.wrapper",
+  "version": "0.2.0",
+  "description": "SDK wrappers for AI Matey - Use familiar SDK patterns with any provider",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./openai": {
+      "import": {
+        "types": "./dist/types/openai-sdk.d.ts",
+        "default": "./dist/esm/openai-sdk.js"
+      },
+      "require": {
+        "types": "./dist/types/openai-sdk.d.ts",
+        "default": "./dist/cjs/openai-sdk.js"
+      }
+    },
+    "./anthropic": {
+      "import": {
+        "types": "./dist/types/anthropic-sdk.d.ts",
+        "default": "./dist/esm/anthropic-sdk.js"
+      },
+      "require": {
+        "types": "./dist/types/anthropic-sdk.d.ts",
+        "default": "./dist/cjs/anthropic-sdk.js"
+      }
+    },
+    "./ir": {
+      "import": {
+        "types": "./dist/types/ir-index.d.ts",
+        "default": "./dist/esm/ir-index.js"
+      },
+      "require": {
+        "types": "./dist/types/ir-index.d.ts",
+        "default": "./dist/cjs/ir-index.js"
+      }
+    },
+    "./chrome-ai": {
+      "import": {
+        "types": "./dist/types/chrome-ai.d.ts",
+        "default": "./dist/esm/chrome-ai.js"
+      },
+      "require": {
+        "types": "./dist/types/chrome-ai.d.ts",
+        "default": "./dist/cjs/chrome-ai.js"
+      }
+    },
+    "./chat": {
+      "import": {
+        "types": "./dist/types/chat.d.ts",
+        "default": "./dist/esm/chat.js"
+      },
+      "require": {
+        "types": "./dist/types/chat.d.ts",
+        "default": "./dist/cjs/chat.js"
+      }
+    },
+    "./anymethod": {
+      "import": {
+        "types": "./dist/types/anymethod.d.ts",
+        "default": "./dist/esm/anymethod.js"
+      },
+      "require": {
+        "types": "./dist/types/anymethod.d.ts",
+        "default": "./dist/cjs/anymethod.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "ai.matey.types": "*",
+    "ai.matey.utils": "*",
+    "ai.matey.frontend": "*"
+  },
+  "devDependencies": {
+    "ai.matey.testing": "*",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "wrapper",
+    "openai",
+    "anthropic",
+    "sdk",
+    "ai-matey"
+  ],
+  "author": "AI Matey",
+  "license": "MIT",
+  "homepage": "https://github.com/johnhenry/ai.matey#readme",
+  "bugs": {
+    "url": "https://github.com/johnhenry/ai.matey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/ai.matey.git",
+    "directory": "packages/wrapper"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,92 @@
+# ai.matey.wrapper
+
+SDK wrappers and utilities for AI Matey - Universal AI Adapter System.
+
+Part of the [ai.matey](https://github.com/johnhenry/ai.matey) monorepo.
+
+## Installation
+
+```bash
+npm install ai.matey.wrapper
+```
+
+## Overview
+
+This package provides SDK-compatible wrappers that let you use familiar SDK patterns (like OpenAI's or Anthropic's) with any AI Matey backend. It also includes IR-native chat utilities for direct usage.
+
+## Included Components
+
+### SDK Wrappers
+- **OpenAI SDK Wrapper** - Use OpenAI SDK patterns with any backend
+- **Anthropic SDK Wrapper** - Use Anthropic SDK patterns with any backend
+- **Chrome AI Wrapper** - Simplified Chrome AI interface
+- **AnyMethod Wrapper** - Flexible method-based wrapper
+
+### IR Utilities
+- **Chat** - High-level chat interface with conversation management
+- **Stream Utilities** - Stream processing helpers
+
+## Usage
+
+### OpenAI SDK Wrapper
+
+```typescript
+import { OpenAI } from 'ai.matey.wrapper';
+
+const client = new OpenAI({ backend: yourBackend });
+
+const response = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+```
+
+### Anthropic SDK Wrapper
+
+```typescript
+import { Anthropic } from 'ai.matey.wrapper';
+
+const client = new Anthropic({ backend: yourBackend });
+
+const response = await client.messages.create({
+  model: 'claude-3-opus',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  max_tokens: 1024,
+});
+```
+
+### IR Chat Interface
+
+```typescript
+import { Chat, createChat } from 'ai.matey.wrapper';
+
+const chat = createChat({ backend: yourBackend });
+
+// Send a message
+const response = await chat.send('Hello!');
+
+// Stream a response
+for await (const chunk of chat.stream('Tell me a story')) {
+  process.stdout.write(chunk.delta);
+}
+```
+
+### Stream Utilities
+
+```typescript
+import { collectStream, streamToText } from 'ai.matey.wrapper';
+
+// Collect all chunks from a stream
+const collected = await collectStream(stream);
+
+// Convert stream to text
+const text = await streamToText(stream);
+```
+
+## API Reference
+
+See the TypeScript definitions for detailed API documentation.
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.