@matthesketh/utopia-ai 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Hesketh
+
+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

@@ -0,0 +1,67 @@
+# @matthesketh/utopia-ai
+
+AI adapters and MCP support for UtopiaJS. Unified interface for chat completions, streaming, embeddings, and agentic tool loops. Built-in support for OpenAI, Anthropic, Google Gemini, and Ollama. Includes a full MCP (Model Context Protocol) server and client implementation.
+
+## Install
+
+```bash
+pnpm add @matthesketh/utopia-ai
+```
+
+Install a provider SDK as needed:
+
+```bash
+pnpm add openai              # for OpenAI
+pnpm add @anthropic-ai/sdk   # for Anthropic
+pnpm add @google/generative-ai  # for Google Gemini
+# Ollama requires no extra dependency
+```
+
+## Usage
+
+```ts
+import { createAI } from '@matthesketh/utopia-ai';
+import { openaiAdapter } from '@matthesketh/utopia-ai/openai';
+
+const ai = createAI(openaiAdapter({
+  apiKey: process.env.OPENAI_API_KEY!,
+}));
+
+// Chat
+const res = await ai.chat({
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+// Streaming
+for await (const chunk of ai.stream({ messages })) {
+  process.stdout.write(chunk.delta);
+}
+
+// Agentic tool loop
+const result = await ai.run({
+  messages: [{ role: 'user', content: 'What is the weather?' }],
+  tools: [{
+    definition: { name: 'get_weather', description: '...', parameters: { type: 'object', properties: {} } },
+    handler: async ({ city }) => ({ temp: 72 }),
+  }],
+});
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `createAI(adapter, options?)` | Create an AI instance with hooks and retry |
+| `streamSSE(res, stream)` | Stream chat chunks as Server-Sent Events |
+| `parseSSEStream(response)` | Parse SSE events from a fetch Response (browser) |
+| `collectStream(stream)` | Collect a stream into a single string |
+
+**Adapters:** `@matthesketh/utopia-ai/openai`, `@matthesketh/utopia-ai/anthropic`, `@matthesketh/utopia-ai/google`, `@matthesketh/utopia-ai/ollama`.
+
+**MCP (`@matthesketh/utopia-ai/mcp`):** `createMCPServer`, `createMCPClient`, `createMCPHandler`.
+
+See [docs/ai.md](../../docs/ai.md) for full documentation on adapters, streaming, tool calling, MCP, and type reference.
+
+## License
+
+MIT

package/dist/adapters/anthropic.cjs

@@ -0,0 +1,253 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/anthropic.ts
+var anthropic_exports = {};
+__export(anthropic_exports, {
+  anthropicAdapter: () => anthropicAdapter
+});
+module.exports = __toCommonJS(anthropic_exports);
+function anthropicAdapter(config) {
+  let client = null;
+  async function getClient() {
+    if (client) return client;
+    let Anthropic;
+    try {
+      const mod = await import("@anthropic-ai/sdk");
+      Anthropic = mod.Anthropic ?? mod.default;
+    } catch {
+      throw new Error(
+        '@matthesketh/utopia-ai: "@anthropic-ai/sdk" package is required for the Anthropic adapter. Install it with: npm install @anthropic-ai/sdk'
+      );
+    }
+    client = new Anthropic({
+      apiKey: config.apiKey,
+      ...config.baseURL ? { baseURL: config.baseURL } : {}
+    });
+    return client;
+  }
+  return {
+    async chat(request) {
+      const anthropic = await getClient();
+      const model = request.model ?? config.defaultModel ?? "claude-sonnet-4-5-20250929";
+      const { system, messages } = toAnthropicMessages(request.messages);
+      const body = {
+        model,
+        messages,
+        max_tokens: request.maxTokens ?? 4096,
+        ...request.extra
+      };
+      if (system) body.system = system;
+      if (request.temperature !== void 0) body.temperature = request.temperature;
+      if (request.topP !== void 0) body.top_p = request.topP;
+      if (request.stop) body.stop_sequences = request.stop;
+      if (request.tools?.length) {
+        body.tools = request.tools.map(toAnthropicTool);
+        if (request.toolChoice) {
+          body.tool_choice = toAnthropicToolChoice(request.toolChoice);
+        }
+      }
+      const response = await anthropic.messages.create(body);
+      const textContent = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+      const toolCalls = response.content.filter((b) => b.type === "tool_use").map((b) => ({
+        id: b.id,
+        name: b.name,
+        arguments: b.input ?? {}
+      }));
+      return {
+        content: textContent,
+        toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
+        finishReason: mapStopReason(response.stop_reason),
+        usage: response.usage ? {
+          promptTokens: response.usage.input_tokens,
+          completionTokens: response.usage.output_tokens,
+          totalTokens: response.usage.input_tokens + response.usage.output_tokens
+        } : void 0,
+        raw: response
+      };
+    },
+    async *stream(request) {
+      const anthropic = await getClient();
+      const model = request.model ?? config.defaultModel ?? "claude-sonnet-4-5-20250929";
+      const { system, messages } = toAnthropicMessages(request.messages);
+      const body = {
+        model,
+        messages,
+        max_tokens: request.maxTokens ?? 4096,
+        stream: true,
+        ...request.extra
+      };
+      if (system) body.system = system;
+      if (request.temperature !== void 0) body.temperature = request.temperature;
+      if (request.topP !== void 0) body.top_p = request.topP;
+      if (request.stop) body.stop_sequences = request.stop;
+      if (request.tools?.length) {
+        body.tools = request.tools.map(toAnthropicTool);
+        if (request.toolChoice) {
+          body.tool_choice = toAnthropicToolChoice(request.toolChoice);
+        }
+      }
+      const stream = anthropic.messages.stream(body);
+      let promptTokens = 0;
+      for await (const event of stream) {
+        if (event.type === "message_start" && event.message?.usage) {
+          promptTokens = event.message.usage.input_tokens ?? 0;
+        } else if (event.type === "content_block_delta") {
+          if (event.delta.type === "text_delta") {
+            yield { delta: event.delta.text };
+          } else if (event.delta.type === "input_json_delta") {
+            yield {
+              delta: "",
+              toolCallDelta: {
+                arguments: tryParseJSON(event.delta.partial_json)
+              }
+            };
+          }
+        } else if (event.type === "content_block_start") {
+          if (event.content_block.type === "tool_use") {
+            yield {
+              delta: "",
+              toolCallDelta: {
+                id: event.content_block.id,
+                name: event.content_block.name,
+                index: event.index
+              }
+            };
+          }
+        } else if (event.type === "message_delta") {
+          const outputTokens = event.usage?.output_tokens ?? 0;
+          yield {
+            delta: "",
+            finishReason: mapStopReason(event.delta.stop_reason),
+            usage: event.usage ? {
+              promptTokens,
+              completionTokens: outputTokens,
+              totalTokens: promptTokens + outputTokens
+            } : void 0
+          };
+        }
+      }
+    }
+  };
+}
+function toAnthropicMessages(messages) {
+  let system;
+  const out = [];
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      system = typeof msg.content === "string" ? msg.content : Array.isArray(msg.content) ? msg.content.map((c) => typeof c === "string" ? c : "text" in c ? c.text : "").join("") : "text" in msg.content ? msg.content.text : "";
+      continue;
+    }
+    if (typeof msg.content === "string") {
+      out.push({ role: msg.role === "tool" ? "user" : msg.role, content: msg.content });
+      continue;
+    }
+    if (Array.isArray(msg.content)) {
+      const blocks = [];
+      for (const part2 of msg.content) {
+        if (typeof part2 === "string") {
+          blocks.push({ type: "text", text: part2 });
+        } else if (part2.type === "text") {
+          blocks.push({ type: "text", text: part2.text });
+        } else if (part2.type === "image") {
+          blocks.push({
+            type: "image",
+            source: {
+              type: part2.source.startsWith("data:") || part2.source.startsWith("http") ? "url" : "base64",
+              ...part2.source.startsWith("data:") || part2.source.startsWith("http") ? { url: part2.source } : { media_type: part2.mediaType ?? "image/png", data: part2.source }
+            }
+          });
+        } else if (part2.type === "tool_call") {
+          blocks.push({
+            type: "tool_use",
+            id: part2.id,
+            name: part2.name,
+            input: part2.arguments
+          });
+        } else if (part2.type === "tool_result") {
+          blocks.push({
+            type: "tool_result",
+            tool_use_id: part2.id,
+            content: part2.content,
+            is_error: part2.isError
+          });
+        }
+      }
+      const role = msg.role === "tool" ? "user" : msg.role;
+      out.push({ role, content: blocks });
+      continue;
+    }
+    const part = msg.content;
+    if (part.type === "text") {
+      out.push({ role: msg.role, content: part.text });
+    }
+  }
+  return { system, messages: out };
+}
+function toAnthropicTool(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.parameters
+  };
+}
+function toAnthropicToolChoice(choice) {
+  if (choice === "auto") return { type: "auto" };
+  if (choice === "none") return { type: "none" };
+  if (choice === "required") return { type: "any" };
+  if (choice && typeof choice === "object" && "name" in choice) {
+    return { type: "tool", name: choice.name };
+  }
+  return { type: "auto" };
+}
+function mapStopReason(reason) {
+  switch (reason) {
+    case "end_turn":
+      return "stop";
+    case "stop_sequence":
+      return "stop";
+    case "tool_use":
+      return "tool_calls";
+    case "max_tokens":
+      return "length";
+    default:
+      return "stop";
+  }
+}
+function tryParseJSON(str) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return void 0;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  anthropicAdapter
+});

package/dist/adapters/anthropic.d.cts

@@ -0,0 +1,17 @@
+import { b as AnthropicConfig, A as AIAdapter } from '../types-FSnS43LM.cjs';
+
+/**
+ * Create an Anthropic adapter.
+ *
+ * Requires `@anthropic-ai/sdk` as a peer dependency.
+ *
+ * ```ts
+ * import { createAI } from '@matthesketh/utopia-ai';
+ * import { anthropicAdapter } from '@matthesketh/utopia-ai/anthropic';
+ *
+ * const ai = createAI(anthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }));
+ * ```
+ */
+declare function anthropicAdapter(config: AnthropicConfig): AIAdapter;
+
+export { anthropicAdapter };

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,17 @@
+import { b as AnthropicConfig, A as AIAdapter } from '../types-FSnS43LM.js';
+
+/**
+ * Create an Anthropic adapter.
+ *
+ * Requires `@anthropic-ai/sdk` as a peer dependency.
+ *
+ * ```ts
+ * import { createAI } from '@matthesketh/utopia-ai';
+ * import { anthropicAdapter } from '@matthesketh/utopia-ai/anthropic';
+ *
+ * const ai = createAI(anthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }));
+ * ```
+ */
+declare function anthropicAdapter(config: AnthropicConfig): AIAdapter;
+
+export { anthropicAdapter };

package/dist/adapters/anthropic.js

@@ -0,0 +1,218 @@
+// src/adapters/anthropic.ts
+function anthropicAdapter(config) {
+  let client = null;
+  async function getClient() {
+    if (client) return client;
+    let Anthropic;
+    try {
+      const mod = await import("@anthropic-ai/sdk");
+      Anthropic = mod.Anthropic ?? mod.default;
+    } catch {
+      throw new Error(
+        '@matthesketh/utopia-ai: "@anthropic-ai/sdk" package is required for the Anthropic adapter. Install it with: npm install @anthropic-ai/sdk'
+      );
+    }
+    client = new Anthropic({
+      apiKey: config.apiKey,
+      ...config.baseURL ? { baseURL: config.baseURL } : {}
+    });
+    return client;
+  }
+  return {
+    async chat(request) {
+      const anthropic = await getClient();
+      const model = request.model ?? config.defaultModel ?? "claude-sonnet-4-5-20250929";
+      const { system, messages } = toAnthropicMessages(request.messages);
+      const body = {
+        model,
+        messages,
+        max_tokens: request.maxTokens ?? 4096,
+        ...request.extra
+      };
+      if (system) body.system = system;
+      if (request.temperature !== void 0) body.temperature = request.temperature;
+      if (request.topP !== void 0) body.top_p = request.topP;
+      if (request.stop) body.stop_sequences = request.stop;
+      if (request.tools?.length) {
+        body.tools = request.tools.map(toAnthropicTool);
+        if (request.toolChoice) {
+          body.tool_choice = toAnthropicToolChoice(request.toolChoice);
+        }
+      }
+      const response = await anthropic.messages.create(body);
+      const textContent = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+      const toolCalls = response.content.filter((b) => b.type === "tool_use").map((b) => ({
+        id: b.id,
+        name: b.name,
+        arguments: b.input ?? {}
+      }));
+      return {
+        content: textContent,
+        toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
+        finishReason: mapStopReason(response.stop_reason),
+        usage: response.usage ? {
+          promptTokens: response.usage.input_tokens,
+          completionTokens: response.usage.output_tokens,
+          totalTokens: response.usage.input_tokens + response.usage.output_tokens
+        } : void 0,
+        raw: response
+      };
+    },
+    async *stream(request) {
+      const anthropic = await getClient();
+      const model = request.model ?? config.defaultModel ?? "claude-sonnet-4-5-20250929";
+      const { system, messages } = toAnthropicMessages(request.messages);
+      const body = {
+        model,
+        messages,
+        max_tokens: request.maxTokens ?? 4096,
+        stream: true,
+        ...request.extra
+      };
+      if (system) body.system = system;
+      if (request.temperature !== void 0) body.temperature = request.temperature;
+      if (request.topP !== void 0) body.top_p = request.topP;
+      if (request.stop) body.stop_sequences = request.stop;
+      if (request.tools?.length) {
+        body.tools = request.tools.map(toAnthropicTool);
+        if (request.toolChoice) {
+          body.tool_choice = toAnthropicToolChoice(request.toolChoice);
+        }
+      }
+      const stream = anthropic.messages.stream(body);
+      let promptTokens = 0;
+      for await (const event of stream) {
+        if (event.type === "message_start" && event.message?.usage) {
+          promptTokens = event.message.usage.input_tokens ?? 0;
+        } else if (event.type === "content_block_delta") {
+          if (event.delta.type === "text_delta") {
+            yield { delta: event.delta.text };
+          } else if (event.delta.type === "input_json_delta") {
+            yield {
+              delta: "",
+              toolCallDelta: {
+                arguments: tryParseJSON(event.delta.partial_json)
+              }
+            };
+          }
+        } else if (event.type === "content_block_start") {
+          if (event.content_block.type === "tool_use") {
+            yield {
+              delta: "",
+              toolCallDelta: {
+                id: event.content_block.id,
+                name: event.content_block.name,
+                index: event.index
+              }
+            };
+          }
+        } else if (event.type === "message_delta") {
+          const outputTokens = event.usage?.output_tokens ?? 0;
+          yield {
+            delta: "",
+            finishReason: mapStopReason(event.delta.stop_reason),
+            usage: event.usage ? {
+              promptTokens,
+              completionTokens: outputTokens,
+              totalTokens: promptTokens + outputTokens
+            } : void 0
+          };
+        }
+      }
+    }
+  };
+}
+function toAnthropicMessages(messages) {
+  let system;
+  const out = [];
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      system = typeof msg.content === "string" ? msg.content : Array.isArray(msg.content) ? msg.content.map((c) => typeof c === "string" ? c : "text" in c ? c.text : "").join("") : "text" in msg.content ? msg.content.text : "";
+      continue;
+    }
+    if (typeof msg.content === "string") {
+      out.push({ role: msg.role === "tool" ? "user" : msg.role, content: msg.content });
+      continue;
+    }
+    if (Array.isArray(msg.content)) {
+      const blocks = [];
+      for (const part2 of msg.content) {
+        if (typeof part2 === "string") {
+          blocks.push({ type: "text", text: part2 });
+        } else if (part2.type === "text") {
+          blocks.push({ type: "text", text: part2.text });
+        } else if (part2.type === "image") {
+          blocks.push({
+            type: "image",
+            source: {
+              type: part2.source.startsWith("data:") || part2.source.startsWith("http") ? "url" : "base64",
+              ...part2.source.startsWith("data:") || part2.source.startsWith("http") ? { url: part2.source } : { media_type: part2.mediaType ?? "image/png", data: part2.source }
+            }
+          });
+        } else if (part2.type === "tool_call") {
+          blocks.push({
+            type: "tool_use",
+            id: part2.id,
+            name: part2.name,
+            input: part2.arguments
+          });
+        } else if (part2.type === "tool_result") {
+          blocks.push({
+            type: "tool_result",
+            tool_use_id: part2.id,
+            content: part2.content,
+            is_error: part2.isError
+          });
+        }
+      }
+      const role = msg.role === "tool" ? "user" : msg.role;
+      out.push({ role, content: blocks });
+      continue;
+    }
+    const part = msg.content;
+    if (part.type === "text") {
+      out.push({ role: msg.role, content: part.text });
+    }
+  }
+  return { system, messages: out };
+}
+function toAnthropicTool(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.parameters
+  };
+}
+function toAnthropicToolChoice(choice) {
+  if (choice === "auto") return { type: "auto" };
+  if (choice === "none") return { type: "none" };
+  if (choice === "required") return { type: "any" };
+  if (choice && typeof choice === "object" && "name" in choice) {
+    return { type: "tool", name: choice.name };
+  }
+  return { type: "auto" };
+}
+function mapStopReason(reason) {
+  switch (reason) {
+    case "end_turn":
+      return "stop";
+    case "stop_sequence":
+      return "stop";
+    case "tool_use":
+      return "tool_calls";
+    case "max_tokens":
+      return "length";
+    default:
+      return "stop";
+  }
+}
+function tryParseJSON(str) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return void 0;
+  }
+}
+export {
+  anthropicAdapter
+};