@stacksjs/ai 0.70.88 → 0.70.90

package/dist/image.js

@@ -0,0 +1,375 @@
+export async function generateImage(prompt, options = {}) {
+  const {
+    provider = "openai",
+    model = "dall-e-3",
+    size = "1024x1024",
+    quality = "standard",
+    n = 1,
+    responseFormat = "url",
+    style = "vivid"
+  } = options;
+  if (provider === "openai")
+    return generateImageOpenAI(prompt, { model, size, quality, n, responseFormat, style });
+  throw Error(`Image generation not supported for provider: ${provider}. Use 'openai'.`);
+}
+async function generateImageOpenAI(prompt, options) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    throw Error("OPENAI_API_KEY environment variable is required for image generation.");
+  const response = await fetch("https://api.openai.com/v1/images/generations", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model: options.model,
+      prompt,
+      size: options.size,
+      quality: options.quality,
+      n: options.n,
+      response_format: options.responseFormat,
+      style: options.style
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw Error(`OpenAI Image API error: ${error}`);
+  }
+  return {
+    images: (await response.json()).data.map((img) => ({
+      url: img.url,
+      b64_json: img.b64_json,
+      revisedPrompt: img.revised_prompt
+    })),
+    provider: "openai",
+    model: options.model
+  };
+}
+export async function editImage(image, prompt, options = {}) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    throw Error("OPENAI_API_KEY environment variable is required for image editing.");
+  const formData = new FormData;
+  formData.append("image", image);
+  formData.append("prompt", prompt);
+  formData.append("model", options.model || "dall-e-2");
+  if (options.mask)
+    formData.append("mask", options.mask);
+  if (options.n)
+    formData.append("n", String(options.n));
+  if (options.size)
+    formData.append("size", options.size);
+  if (options.responseFormat)
+    formData.append("response_format", options.responseFormat);
+  const response = await fetch("https://api.openai.com/v1/images/edits", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: formData
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw Error(`OpenAI Image Edit API error: ${error}`);
+  }
+  return {
+    images: (await response.json()).data.map((img) => ({
+      url: img.url,
+      b64_json: img.b64_json
+    })),
+    provider: "openai",
+    model: options.model || "dall-e-2"
+  };
+}
+export async function createImageVariation(image, options = {}) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    throw Error("OPENAI_API_KEY environment variable is required for image variations.");
+  const formData = new FormData;
+  formData.append("image", image);
+  formData.append("model", options.model || "dall-e-2");
+  if (options.n)
+    formData.append("n", String(options.n));
+  if (options.size)
+    formData.append("size", options.size);
+  if (options.responseFormat)
+    formData.append("response_format", options.responseFormat);
+  const response = await fetch("https://api.openai.com/v1/images/variations", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: formData
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw Error(`OpenAI Image Variations API error: ${error}`);
+  }
+  return {
+    images: (await response.json()).data.map((img) => ({
+      url: img.url,
+      b64_json: img.b64_json
+    })),
+    provider: "openai",
+    model: options.model || "dall-e-2"
+  };
+}
+export async function analyzeImage(imageInput, prompt, options = {}) {
+  const { provider = "anthropic" } = options;
+  switch (provider) {
+    case "anthropic":
+      return analyzeImageAnthropic(imageInput, prompt, options);
+    case "openai":
+      return analyzeImageOpenAI(imageInput, prompt, options);
+    case "ollama":
+      return analyzeImageOllama(imageInput, prompt, options);
+    default:
+      throw Error(`Vision not supported for provider: ${provider}`);
+  }
+}
+async function resolveImageToBase64(input) {
+  if (input.type === "base64")
+    return { data: input.data, mediaType: input.mediaType };
+  if (input.type === "url") {
+    const response = await fetch(input.url);
+    if (!response.ok)
+      throw Error(`Failed to fetch image from URL: ${input.url}`);
+    const buffer = await response.arrayBuffer(), base64 = Buffer.from(buffer).toString("base64"), contentType = response.headers.get("content-type") || "image/png";
+    return { data: base64, mediaType: contentType };
+  }
+  if (input.type === "file") {
+    const { readFile } = await import("node:fs/promises"), base64 = (await readFile(input.path)).toString("base64"), ext = input.path.split(".").pop()?.toLowerCase() || "png";
+    return { data: base64, mediaType: {
+      png: "image/png",
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      gif: "image/gif",
+      webp: "image/webp"
+    }[ext] || "image/png" };
+  }
+  throw Error("Invalid image input type");
+}
+async function analyzeImageAnthropic(imageInput, prompt, options) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey)
+    throw Error("ANTHROPIC_API_KEY environment variable is required for Claude vision.");
+  const { data, mediaType } = await resolveImageToBase64(imageInput), model = options.model || "claude-sonnet-4-20250514", maxTokens = options.maxTokens || 4096, messages = [{
+    role: "user",
+    content: [
+      {
+        type: "image",
+        source: { type: "base64", media_type: mediaType, data }
+      },
+      { type: "text", text: prompt }
+    ]
+  }], response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      temperature: options.temperature,
+      messages
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw Error(`Claude Vision API error: ${error}`);
+  }
+  const responseData = await response.json();
+  return {
+    content: responseData.content[0].text,
+    model: responseData.model,
+    provider: "anthropic",
+    usage: {
+      promptTokens: responseData.usage?.input_tokens || 0,
+      completionTokens: responseData.usage?.output_tokens || 0,
+      totalTokens: (responseData.usage?.input_tokens || 0) + (responseData.usage?.output_tokens || 0)
+    },
+    finishReason: responseData.stop_reason
+  };
+}
+async function analyzeImageOpenAI(imageInput, prompt, options) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    throw Error("OPENAI_API_KEY environment variable is required for GPT-4 vision.");
+  const model = options.model || "gpt-4o", maxTokens = options.maxTokens || 4096, detail = options.detail || "auto";
+  let imageContent;
+  if (imageInput.type === "url")
+    imageContent = { type: "image_url", image_url: { url: imageInput.url, detail } };
+  else {
+    const { data, mediaType } = await resolveImageToBase64(imageInput);
+    imageContent = {
+      type: "image_url",
+      image_url: { url: `data:${mediaType};base64,${data}`, detail }
+    };
+  }
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      temperature: options.temperature,
+      messages: [{
+        role: "user",
+        content: [
+          imageContent,
+          { type: "text", text: prompt }
+        ]
+      }]
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw Error(`OpenAI Vision API error: ${error}`);
+  }
+  const responseData = await response.json();
+  return {
+    content: responseData.choices[0].message.content,
+    model: responseData.model,
+    provider: "openai",
+    usage: {
+      promptTokens: responseData.usage?.prompt_tokens || 0,
+      completionTokens: responseData.usage?.completion_tokens || 0,
+      totalTokens: responseData.usage?.total_tokens || 0
+    },
+    finishReason: responseData.choices[0].finish_reason
+  };
+}
+async function analyzeImageOllama(imageInput, prompt, options) {
+  const host = process.env.OLLAMA_HOST || "http://localhost:11434", model = options.model || "llava", { data } = await resolveImageToBase64(imageInput), response = await fetch(`${host}/api/generate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      prompt,
+      images: [data],
+      stream: !1
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw Error(`Ollama Vision API error: ${error}`);
+  }
+  const responseData = await response.json();
+  return {
+    content: responseData.response,
+    model: responseData.model,
+    provider: "ollama",
+    usage: {
+      promptTokens: responseData.prompt_eval_count || 0,
+      completionTokens: responseData.eval_count || 0,
+      totalTokens: (responseData.prompt_eval_count || 0) + (responseData.eval_count || 0)
+    }
+  };
+}
+export async function analyzeImages(images, prompt, options = {}) {
+  const { provider = "anthropic" } = options;
+  if (provider === "anthropic") {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+      throw Error("ANTHROPIC_API_KEY required for multi-image analysis.");
+    const model = options.model || "claude-sonnet-4-20250514", contentBlocks = [];
+    for (const img of images) {
+      const { data, mediaType } = await resolveImageToBase64(img);
+      contentBlocks.push({
+        type: "image",
+        source: { type: "base64", media_type: mediaType, data }
+      });
+    }
+    contentBlocks.push({ type: "text", text: prompt });
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01"
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: options.maxTokens || 4096,
+        temperature: options.temperature,
+        messages: [{ role: "user", content: contentBlocks }]
+      })
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw Error(`Claude Vision API error: ${error}`);
+    }
+    const responseData = await response.json();
+    return {
+      content: responseData.content[0].text,
+      model: responseData.model,
+      provider: "anthropic",
+      usage: {
+        promptTokens: responseData.usage?.input_tokens || 0,
+        completionTokens: responseData.usage?.output_tokens || 0,
+        totalTokens: (responseData.usage?.input_tokens || 0) + (responseData.usage?.output_tokens || 0)
+      },
+      finishReason: responseData.stop_reason
+    };
+  }
+  if (provider === "openai") {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey)
+      throw Error("OPENAI_API_KEY required for multi-image analysis.");
+    const model = options.model || "gpt-4o", detail = options.detail || "auto", contentBlocks = [];
+    for (const img of images)
+      if (img.type === "url")
+        contentBlocks.push({ type: "image_url", image_url: { url: img.url, detail } });
+      else {
+        const { data, mediaType } = await resolveImageToBase64(img);
+        contentBlocks.push({
+          type: "image_url",
+          image_url: { url: `data:${mediaType};base64,${data}`, detail }
+        });
+      }
+    contentBlocks.push({ type: "text", text: prompt });
+    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: options.maxTokens || 4096,
+        temperature: options.temperature,
+        messages: [{ role: "user", content: contentBlocks }]
+      })
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw Error(`OpenAI Vision API error: ${error}`);
+    }
+    const responseData = await response.json();
+    return {
+      content: responseData.choices[0].message.content,
+      model: responseData.model,
+      provider: "openai",
+      usage: {
+        promptTokens: responseData.usage?.prompt_tokens || 0,
+        completionTokens: responseData.usage?.completion_tokens || 0,
+        totalTokens: responseData.usage?.total_tokens || 0
+      },
+      finishReason: responseData.choices[0].finish_reason
+    };
+  }
+  throw Error(`Multi-image analysis not supported for provider: ${provider}`);
+}
+export const image = {
+  generate: generateImage,
+  edit: editImage,
+  variation: createImageVariation,
+  analyze: analyzeImage,
+  analyzeMultiple: analyzeImages
+};

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export type { RetryConfig } from './utils/retry';
+export type { UsageRecord, UsageReporter } from './utils/usage';
+export type { SanitizeResult } from './utils/tokens';
+// Types
+export * from './types';
+// Drivers
+export * from './drivers/index';
+// Agents
+export * from './agents/index';
+// Buddy - Voice AI Code Assistant
+export * from './buddy';
+// Text utilities
+export * from './text';
+// Image generation & vision
+export * from './image';
+// Semantic search, embeddings & RAG
+export * from './search';
+// Personalization, sentiment & classification
+export * from './personalization';
+// Model Context Protocol (MCP) client
+export * from './mcp';
+// AWS Bedrock utilities
+export * from './utils/client-bedrock';
+export * from './utils/client-bedrock-runtime';
+// Cross-driver vision helpers (stacksjs/stacks#1878 A-3).
+// `buildMessageWithImages(command, images)` constructs portable
+// content arrays; `normalizeMessagesForProvider(messages, 'openai' | 'anthropic')`
+// translates between the OpenAI image_url and Anthropic image
+// source formats so apps can switch providers without rewriting.
+export { buildMessageWithImages, normalizeMessagesForProvider } from './utils/vision';
+// HTTP retry helper for 429/5xx (stacksjs/stacks#1878 A-5).
+export { fetchWithRetry } from './utils/retry';
+// Usage tracking (stacksjs/stacks#1878 A-6). Apps install reporters
+// via `onUsage(fn)`; drivers fire `recordUsage(...)` per completion.
+// Default with no reporters is a no-op.
+export { clearUsageReporters, listUsageReporters, onUsage, recordUsage } from './utils/usage';
+// Token estimation + prompt-injection heuristics (stacksjs/stacks#1878 A-7).
+export { estimateMessageTokens, estimateTokens, sanitizePrompt } from './utils/tokens';
+export * from './utils/model-access';

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from "./types";
+export * from "./drivers";
+export * from "./agents";
+export * from "./buddy";
+export * from "./text";
+export * from "./image";
+export * from "./search";
+export * from "./personalization";
+export * from "./mcp";
+export * from "./utils/client-bedrock";
+export * from "./utils/client-bedrock-runtime";
+export { buildMessageWithImages, normalizeMessagesForProvider } from "./utils/vision";
+export { fetchWithRetry } from "./utils/retry";
+export { clearUsageReporters, listUsageReporters, onUsage, recordUsage } from "./utils/usage";
+export { estimateMessageTokens, estimateTokens, sanitizePrompt } from "./utils/tokens";
+export * from "./utils/model-access";

package/dist/mcp.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Create and connect to an MCP server using stdio transport.
+ */
+export declare function connectStdio(name: string, command: string, args?: string[], env?: Record<string, string>): Promise<MCPClient>;
+/**
+ * Create and connect to an MCP server using HTTP transport.
+ */
+export declare function connectHTTP(name: string, url: string, headers?: Record<string, string>): Promise<MCPClient>;
+// ============================================================================
+// Exports
+// ============================================================================
+export declare const mcp: {
+  MCPClient: typeof MCPClient;
+  MCPManager: typeof MCPManager;
+  connectStdio: typeof connectStdio;
+  connectHTTP: typeof connectHTTP
+};
+/**
+ * MCP (Model Context Protocol) Module
+ *
+ * Implements an MCP client for connecting to MCP servers, discovering tools,
+ * and invoking them through AI providers. This enables AI models to interact
+ * with external services via a standardized protocol.
+ *
+ * @see https://modelcontextprotocol.io
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface MCPServerConfig {
+  name: string
+  transport: MCPTransport
+  capabilities?: MCPCapabilities
+}
+export declare interface MCPCapabilities {
+  tools?: boolean
+  resources?: boolean
+  prompts?: boolean
+}
+export declare interface MCPTool {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+export declare interface MCPResource {
+  uri: string
+  name: string
+  description?: string
+  mimeType?: string
+}
+export declare interface MCPPrompt {
+  name: string
+  description?: string
+  arguments?: Array<{
+    name: string
+    description?: string
+    required?: boolean
+  }>
+}
+export declare interface MCPToolCallResult {
+  content: Array<{
+    type: 'text' | 'image' | 'resource'
+    text?: string
+    data?: string
+    mimeType?: string
+  }>
+  isError?: boolean
+}
+export declare interface MCPResourceContent {
+  uri: string
+  mimeType?: string
+  text?: string
+  blob?: string
+}
+export type MCPTransport = | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
+  | { type: 'sse'; url: string; headers?: Record<string, string> }
+  | { type: 'streamable-http'; url: string; headers?: Record<string, string> }
+/**
+ * MCP Client for connecting to Model Context Protocol servers.
+ *
+ * Supports stdio and SSE/streamable-http transports.
+ * Provides tool discovery, invocation, resource reading, and prompt listing.
+ */
+export declare class MCPClient {
+  constructor(config: MCPServerConfig);
+  connect(): Promise<void>;
+  listTools(): MCPTool[];
+  listResources(): MCPResource[];
+  listPrompts(): MCPPrompt[];
+  callTool(name: string, args?: Record<string, unknown>): Promise<MCPToolCallResult>;
+  readResource(uri: string): Promise<MCPResourceContent>;
+  getPrompt(name: string, args?: Record<string, string>): Promise<{
+    description?: string
+    messages: Array<{ role: string; content: { type: string; text: string } }>
+  }>;
+  toAnthropicTools(): Array<{ name: string; description: string; input_schema: Record<string, unknown> }>;
+  toOpenAITools(): Array<{ type: 'function'; function: { name: string; description: string; parameters: Record<string, unknown> } }>;
+  disconnect(): Promise<void>;
+  get isConnected(): boolean;
+  get serverName(): string;
+}
+/**
+ * Manages connections to multiple MCP servers.
+ */
+export declare class MCPManager {
+  addServer(config: MCPServerConfig): Promise<MCPClient>;
+  removeServer(name: string): Promise<void>;
+  getServer(name: string): MCPClient | undefined;
+  listServers(): string[];
+  getAllTools(): Array<MCPTool & { serverName: string }>;
+  callTool(toolPath: string, args?: Record<string, unknown>): Promise<MCPToolCallResult>;
+  toAnthropicTools(): Array<{ name: string; description: string; input_schema: Record<string, unknown> }>;
+  toOpenAITools(): Array<{ type: 'function'; function: { name: string; description: string; parameters: Record<string, unknown> } }>;
+  disconnectAll(): Promise<void>;
+}