@stacksjs/ai 0.70.53 → 0.70.55

package/src/types.ts

@@ -0,0 +1,229 @@
+/**
+ * AI Module Types
+ *
+ * Shared type definitions for AI drivers and agents.
+ */
+
+export interface AIMessage {
+  role: 'user' | 'assistant' | 'system'
+  content: string | AIMessageContent[]
+}
+
+export interface AIMessageContent {
+  type: 'text' | 'image_url' | 'image'
+  text?: string
+  image_url?: { url: string, detail?: 'auto' | 'low' | 'high' }
+  source?: { type: 'base64', media_type: string, data: string }
+}
+
+export interface AIDriver {
+  name: string
+  process: (command: string, context: string, history: AIMessage[]) => Promise<string>
+  stream?: (command: string, context: string, history: AIMessage[]) => AsyncGenerator<string>
+  embed?: (input: string | string[]) => Promise<number[] | number[][]>
+}
+
+export interface AIDriverConfig {
+  apiKey?: string
+  baseUrl?: string
+  model?: string
+  maxTokens?: number
+}
+
+export interface StreamingResult {
+  stream: ReadableStream<Uint8Array>
+  fullResponse: Promise<string>
+}
+
+export interface EmbeddingResult {
+  embedding: number[]
+  index: number
+  object: string
+}
+
+export interface EmbeddingsResponse {
+  data: EmbeddingResult[]
+  model: string
+  usage: {
+    prompt_tokens: number
+    total_tokens: number
+  }
+}
+
+/**
+ * Tool / function definition that the model can call back into.
+ * Cross-provider shape: OpenAI's `tools[]` and Anthropic's `tools[]`
+ * map to this same structure via the JSON Schema for parameters.
+ */
+export interface AITool {
+  name: string
+  description?: string
+  /** JSON Schema for the tool's input. */
+  parameters?: Record<string, unknown>
+  /** OpenAI-only `tool_choice` semantics: 'auto' (default), 'required', or { name }. */
+}
+
+/**
+ * Structured-output / JSON-mode response format. Modeled after
+ * OpenAI's `response_format` but the Anthropic driver maps it to
+ * the tools-as-json pattern internally (stacksjs/stacks#1878 A-1).
+ */
+export type AIResponseFormat =
+  | { type: 'text' }
+  | { type: 'json_object' }
+  | {
+      type: 'json_schema'
+      json_schema: {
+        name: string
+        schema: Record<string, unknown>
+        strict?: boolean
+      }
+    }
+
+export interface ChatCompletionOptions {
+  model?: string
+  maxTokens?: number
+  temperature?: number
+  topP?: number
+  stop?: string | string[]
+  stream?: boolean
+  /**
+   * Tools / functions the model can call (stacksjs/stacks#1878 A-1).
+   * OpenAI threads as `tools` directly; Anthropic threads as
+   * `tools` (Claude 3.5+) — the cross-driver shape is the same.
+   */
+  tools?: AITool[]
+  /**
+   * Force the model to call a specific tool, or any tool, or no
+   * tool. OpenAI semantics. Anthropic supports the same via
+   * `tool_choice` field in Messages API.
+   */
+  toolChoice?: 'auto' | 'required' | 'none' | { name: string }
+  /**
+   * Force structured output (stacksjs/stacks#1878 A-1).
+   * - `{ type: 'text' }` → freeform (the default)
+   * - `{ type: 'json_object' }` → guaranteed JSON, schema not enforced
+   * - `{ type: 'json_schema', json_schema: {...} }` → JSON matching schema
+   */
+  responseFormat?: AIResponseFormat
+}
+
+export interface AIResult {
+  content: string
+  model: string
+  usage?: {
+    promptTokens: number
+    completionTokens: number
+    totalTokens: number
+  }
+  finishReason?: string
+}
+
+export interface ClaudeAPIResponse {
+  content: Array<{ type: string, text: string }>
+}
+
+export interface OpenAIAPIResponse {
+  choices: Array<{ message: { content: string } }>
+}
+
+export interface OllamaAPIResponse {
+  message: { content: string }
+}
+
+export interface ClaudeStreamEvent {
+  type: string
+  subtype?: string
+  message?: {
+    content: Array<{
+      type: string
+      text?: string
+      name?: string
+      input?: Record<string, unknown>
+    }>
+  }
+  delta?: { text?: string }
+  result?: string
+  // Content block events for better streaming
+  index?: number
+  content_block?: {
+    type: string
+    text?: string
+  }
+}
+
+// Buddy Types
+export interface RepoState {
+  path: string
+  name: string
+  branch: string
+  hasChanges: boolean
+  lastCommit?: string
+}
+
+export interface GitHubCredentials {
+  token: string
+  username: string
+  name: string
+  email: string
+}
+
+export interface BuddyState {
+  repo: RepoState | null
+  conversationHistory: AIMessage[]
+  currentDriver: string
+  github: GitHubCredentials | null
+}
+
+export interface BuddyConfig {
+  workDir: string
+  commitMessage: string
+  ollamaHost: string
+  ollamaModel: string
+}
+
+export interface BuddyApiKeys {
+  anthropic?: string
+  openai?: string
+  claudeCliHost?: string
+}
+
+// Image types
+export interface ImageGenerationConfig {
+  provider: 'openai'
+  model?: string
+  apiKey?: string
+}
+
+// Search/RAG types
+export interface SearchConfig {
+  embeddingProvider: 'openai' | 'ollama'
+  embeddingModel?: string
+  generationProvider?: 'anthropic' | 'openai' | 'ollama'
+  generationModel?: string
+}
+
+// MCP types
+export interface MCPConfig {
+  servers: Array<{
+    name: string
+    command?: string
+    args?: string[]
+    url?: string
+    env?: Record<string, string>
+  }>
+}
+
+// AI module config (used by @stacksjs/config)
+export interface AIConfig {
+  default?: string
+  models?: string[]
+  drivers?: {
+    anthropic?: AIDriverConfig & { anthropicVersion?: string }
+    openai?: AIDriverConfig & { embeddingModel?: string }
+    ollama?: AIDriverConfig & { host?: string; embeddingModel?: string }
+  }
+  image?: ImageGenerationConfig
+  search?: SearchConfig
+  mcp?: MCPConfig
+}

package/src/utils/client-bedrock-runtime.ts

@@ -0,0 +1,51 @@
+import type {
+  InvokeModelCommandInput,
+  InvokeModelCommandOutput,
+  InvokeModelWithResponseStreamCommandInput,
+  InvokeModelWithResponseStreamCommandOutput,
+} from '@stacksjs/ts-cloud/aws'
+import process from 'node:process'
+
+// Lazy-load the runtime BedrockRuntimeClient — see client-bedrock.ts
+// for the rationale (ts-cloud's /aws subpath ships types but not always
+// the JS bundle, and an eager top-level import takes the whole API
+// server down at boot).
+let _client: any | null = null
+async function getClient(): Promise<any> {
+  if (_client)
+    return _client
+  const mod: any = await import('@stacksjs/ts-cloud/aws')
+  if (!mod?.BedrockRuntimeClient) {
+    throw new Error(
+      '@stacksjs/ts-cloud/aws does not export BedrockRuntimeClient — rebuild ts-cloud or remove the AI dependency.',
+    )
+  }
+  _client = new mod.BedrockRuntimeClient(process.env.REGION || 'us-east-1')
+  return _client
+}
+
+/*
+ * Invoke Model
+ * @param {InvokeModelCommandInput} params
+ * @returns {Promise<InvokeModelCommandOutput>}
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/BedrockRuntime.html#invokeModel-property
+ */
+export async function invokeModel(params: InvokeModelCommandInput): Promise<InvokeModelCommandOutput> {
+  const c = await getClient()
+  return c.invokeModel(params)
+}
+
+/*
+ * Invoke Model With Response Stream
+ * @param {InvokeModelWithResponseStreamCommandInput} params
+ * @returns {Promise<InvokeModelWithResponseStreamCommandOutput>}
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/BedrockRuntime.html#invokeModelWithResponseStream-property
+ */
+export async function invokeModelWithResponseStream(
+  params: InvokeModelWithResponseStreamCommandInput,
+): Promise<InvokeModelWithResponseStreamCommandOutput> {
+  const c = await getClient()
+  return c.invokeModelWithResponseStream(params)
+}
+
+export type { InvokeModelCommandInput, InvokeModelWithResponseStreamCommandInput }

package/src/utils/client-bedrock.ts

@@ -0,0 +1,75 @@
+import type {
+  CreateModelCustomizationJobCommandInput,
+  CreateModelCustomizationJobCommandOutput,
+  GetModelCustomizationJobCommandInput,
+  GetModelCustomizationJobCommandOutput,
+  ListFoundationModelsCommandInput,
+  ListFoundationModelsCommandOutput,
+} from '@stacksjs/ts-cloud/aws'
+import process from 'node:process'
+
+// Lazy-load the runtime BedrockClient. `@stacksjs/ts-cloud/aws` ships the
+// type declarations but the JS bundle for that subpath isn't always
+// present (we hit this on `bun install` from a registry where the package
+// hadn't published the /aws bundle). Importing eagerly with a top-level
+// `import { BedrockClient } from ...` crashes the entire API server at
+// boot. With this shim, modules that don't actually call the helpers
+// below load fine, and callers who do use Bedrock get a clear error.
+let _client: any | null = null
+async function getClient(): Promise<any> {
+  if (_client)
+    return _client
+  const mod: any = await import('@stacksjs/ts-cloud/aws')
+  if (!mod?.BedrockClient) {
+    throw new Error(
+      '@stacksjs/ts-cloud/aws does not export BedrockClient — rebuild ts-cloud or remove the AI dependency.',
+    )
+  }
+  _client = new mod.BedrockClient(process.env.REGION || 'us-east-1')
+  return _client
+}
+
+/*
+ * Create Model Customization Job
+ * @param {CreateModelCustomizationJobCommandInput} params
+ * @returns {Promise<CreateModelCustomizationJobCommandOutput>}
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Bedrock.html#CreateModelCustomizationJob-property
+ */
+export async function createModelCustomizationJob(
+  param: CreateModelCustomizationJobCommandInput,
+): Promise<CreateModelCustomizationJobCommandOutput> {
+  const client = await getClient()
+  return client.createModelCustomizationJob(param)
+}
+
+/*
+ * Get Model Customization Job
+ * @param {GetModelCustomizationJobCommandInput} params
+ * @returns {Promise<GetModelCustomizationJobCommandOutput>}
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Bedrock.html#getModelCustomizationJob-property
+ */
+export async function getModelCustomizationJob(
+  params: GetModelCustomizationJobCommandInput,
+): Promise<GetModelCustomizationJobCommandOutput> {
+  const client = await getClient()
+  return client.getModelCustomizationJob(params)
+}
+
+/*
+ * List Foundation Models
+ * @param {ListFoundationModelsCommandInput} params
+ * @returns {Promise<ListFoundationModelsCommandOutput>}
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Bedrock.html#listFoundationModels-property
+ */
+export async function listFoundationModels(
+  params: ListFoundationModelsCommandInput,
+): Promise<ListFoundationModelsCommandOutput> {
+  const client = await getClient()
+  return client.listFoundationModels(params)
+}
+
+export type {
+  CreateModelCustomizationJobCommandInput,
+  GetModelCustomizationJobCommandInput,
+  ListFoundationModelsCommandInput,
+}

package/src/utils/model-access.ts

@@ -0,0 +1,32 @@
+import { log } from '@stacksjs/cli'
+import { ai } from '@stacksjs/config'
+
+// Lazy-load ts-cloud/aws — see client-bedrock.ts for context.
+async function getBedrockClient(): Promise<any> {
+  const mod: any = await import('@stacksjs/ts-cloud/aws')
+  if (!mod?.BedrockClient) {
+    throw new Error(
+      '@stacksjs/ts-cloud/aws does not export BedrockClient — rebuild ts-cloud or remove the AI dependency.',
+    )
+  }
+  return new mod.BedrockClient('us-east-1')
+}
+
+export async function requestModelAccess(): Promise<void> {
+  const client = await getBedrockClient()
+
+  const models = ai.models
+  if (!models)
+    throw new Error('No AI models found. Please set ./config/ai.ts values.')
+
+  for (const model of models) {
+    try {
+      log.info(`Requesting access to model ${model}`)
+      const data = await client.requestModelAccess({ modelId: model })
+      log.info(`Response for model ${model}:`, data)
+    }
+    catch (error) {
+      log.error(`Error requesting access to model ${model}:`, error)
+    }
+  }
+}

package/src/utils/retry.ts

@@ -0,0 +1,124 @@
+/**
+ * Retry helper for AI driver HTTP calls (stacksjs/stacks#1878 A-5).
+ *
+ * Background: OpenAI / Anthropic / etc. routinely return 429 (rate
+ * limit) and 5xx (capacity / overloaded) responses with a
+ * `Retry-After` header indicating when the caller should try again.
+ * The pre-fix AI drivers threw immediately on any non-2xx, surfacing
+ * transient capacity issues as hard user-facing failures.
+ *
+ * This helper wraps `fetch()` with:
+ *   - Honor `Retry-After` (seconds or HTTP-date) for 429 + 503
+ *   - Exponential backoff + jitter for other 5xx
+ *   - Cap at `maxRetries` attempts (default 3)
+ *   - Surface the final non-recoverable response to the caller
+ *
+ * No retry on 4xx other than 429 — those are caller bugs (bad API
+ * key, malformed request) that won't clear with more retries.
+ */
+
+/**
+ * Configurable retry policy. Defaults are tuned for the typical
+ * "Anthropic returned 429, try again in 3s" case without being so
+ * aggressive that a permanent outage hangs the request loop for
+ * minutes.
+ */
+export interface RetryConfig {
+  /** Max retry attempts (NOT including the initial call). Default: 3. */
+  maxRetries?: number
+  /** Base delay in ms for exponential backoff. Default: 500. */
+  baseDelayMs?: number
+  /** Cap on any single delay in ms. Default: 30s. */
+  maxDelayMs?: number
+}
+
+const DEFAULT_RETRY: Required<RetryConfig> = {
+  maxRetries: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 30_000,
+}
+
+/**
+ * Fetch with automatic retry on 429 / 5xx. Returns the final
+ * `Response` — the caller checks `.ok` and parses the body as usual.
+ *
+ * Does NOT retry network-level errors (connection reset, DNS
+ * failure) — those throw synchronously and the caller's existing
+ * try/catch handles them.
+ */
+export async function fetchWithRetry(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  config: RetryConfig = {},
+): Promise<Response> {
+  const cfg = { ...DEFAULT_RETRY, ...config }
+  let lastResponse: Response | undefined
+
+  for (let attempt = 0; attempt <= cfg.maxRetries; attempt++) {
+    lastResponse = await fetch(input, init)
+
+    // 2xx — done.
+    if (lastResponse.ok) return lastResponse
+
+    // Don't retry client errors except 429 (rate limit).
+    if (lastResponse.status < 500 && lastResponse.status !== 429)
+      return lastResponse
+
+    // Out of retries — return whatever we got so the caller can
+    // surface a meaningful error.
+    if (attempt === cfg.maxRetries) return lastResponse
+
+    // Decide how long to wait before the next attempt.
+    const retryAfterMs = parseRetryAfter(lastResponse.headers.get('Retry-After'))
+    const backoff = retryAfterMs ?? exponentialBackoff(attempt, cfg)
+    const delay = Math.min(backoff, cfg.maxDelayMs)
+
+    // Drain the body so the connection can be reused (Bun
+    // sometimes warns about un-consumed bodies otherwise).
+    try {
+      await lastResponse.text().catch(() => {})
+    }
+    catch {
+      // ignore
+    }
+
+    await new Promise(resolve => setTimeout(resolve, delay))
+  }
+
+  // Loop always returns inside; this is unreachable.
+  return lastResponse!
+}
+
+/**
+ * Parse a `Retry-After` header. Accepts either a delta-seconds
+ * integer (`'3'`) or an HTTP-date (`'Wed, 21 Oct 2026 07:28:00 GMT'`).
+ * Returns null if the header is missing or unparseable.
+ */
+function parseRetryAfter(header: string | null): number | null {
+  if (!header) return null
+  // Delta-seconds form.
+  const seconds = Number.parseInt(header, 10)
+  if (Number.isFinite(seconds) && String(seconds) === header.trim()) {
+    return Math.max(0, seconds * 1000)
+  }
+  // HTTP-date form.
+  const dateMs = Date.parse(header)
+  if (Number.isFinite(dateMs)) {
+    return Math.max(0, dateMs - Date.now())
+  }
+  return null
+}
+
+/**
+ * Exponential backoff with full jitter. `attempt` is 0-indexed, so
+ * the first retry uses `base * 2^0 * rand` = up to base ms; the
+ * second uses up to 2*base ms; the third up to 4*base ms; etc.
+ *
+ * Full jitter (vs equal jitter) is what AWS recommends — spreads
+ * herding traffic better when many clients retry the same upstream
+ * after a brief outage.
+ */
+function exponentialBackoff(attempt: number, cfg: Required<RetryConfig>): number {
+  const cap = Math.min(cfg.baseDelayMs * 2 ** attempt, cfg.maxDelayMs)
+  return Math.random() * cap
+}

package/src/utils/tokens.ts

@@ -0,0 +1,159 @@
+/**
+ * Token-counting + prompt-sanitization utils (stacksjs/stacks#1878 A-7).
+ *
+ * These are heuristic helpers — not exact-tokenizer replacements.
+ * Real exact counts come from the provider's tokenizer (tiktoken
+ * for OpenAI, anthropic's tokenizer endpoint). Both are heavy
+ * dependencies / network calls; this module ships a quick estimate
+ * that's good enough for cost projection and prompt-budget checks
+ * without paying the install/runtime cost.
+ *
+ * Calibration: empirical "chars-per-token" ratios from each
+ * provider's documentation. English prose hits ~4 chars/token on
+ * average; code and JSON skew lower (~3.5). The estimator picks a
+ * conservative ratio per model family so estimates over-count
+ * slightly — better to budget too tight than blow your context.
+ */
+
+/**
+ * Rough chars-per-token for a model. Tightened down to the
+ * conservative end of each provider's published range so apps
+ * pre-checking against the model's context window don't get
+ * blindsided by a slightly higher actual count.
+ */
+function charsPerToken(model: string): number {
+  const m = model.toLowerCase()
+  // GPT-4 / GPT-4o / GPT-5: ~4 chars/token average; conservative 3.5.
+  if (m.startsWith('gpt-')) return 3.5
+  // Claude family: roughly 4 chars/token; conservative 3.5.
+  if (m.startsWith('claude')) return 3.5
+  // Ollama / local models vary widely; fall through to default.
+  // Default: 3.5 — undercounts long English prose slightly, which
+  // is the safer direction.
+  return 3.5
+}
+
+/**
+ * Estimate the number of tokens in `text` for the given model.
+ * Heuristic only — for exact counts, use the provider's tokenizer.
+ *
+ * @example
+ * ```ts
+ * if (estimateTokens(prompt, 'gpt-4o') > 100_000) {
+ *   throw new Error('prompt too long; consider chunking')
+ * }
+ * ```
+ */
+export function estimateTokens(text: string, model: string = 'gpt-4o'): number {
+  if (!text) return 0
+  const ratio = charsPerToken(model)
+  // Add 1 to the divisor so very short strings round up to a
+  // non-zero estimate (single-char inputs still cost a token).
+  return Math.max(1, Math.ceil(text.length / ratio))
+}
+
+/**
+ * Estimate total tokens for a chat-completion request: sum of
+ * every message's content plus a fixed per-message overhead
+ * (matches the rough "+4 per message + 2 for the conversation"
+ * heuristic OpenAI's docs publish).
+ */
+export function estimateMessageTokens(
+  messages: Array<{ role: string, content: string | unknown }>,
+  model: string = 'gpt-4o',
+): number {
+  const PER_MESSAGE_OVERHEAD = 4
+  const CONVERSATION_OVERHEAD = 2
+  let total = CONVERSATION_OVERHEAD
+  for (const msg of messages) {
+    total += PER_MESSAGE_OVERHEAD
+    if (typeof msg.content === 'string') {
+      total += estimateTokens(msg.content, model)
+    }
+    else if (Array.isArray(msg.content)) {
+      // Multi-modal content arrays — count text blocks. Image blocks
+      // are model-specific (Anthropic ~85+ tokens per image, OpenAI
+      // tile-based); the heuristic adds 100 tokens per image as a
+      // round-number proxy. Apps that need real counts pre-flight via
+      // the provider's tokenizer.
+      for (const block of msg.content as Array<{ type: string, text?: string }>) {
+        if (block.type === 'text' && block.text)
+          total += estimateTokens(block.text, model)
+        else if (block.type === 'image' || block.type === 'image_url')
+          total += 100
+      }
+    }
+  }
+  return total
+}
+
+/**
+ * Patterns that match common prompt-injection / jailbreak attempts.
+ * NOT exhaustive — adversarial input is an open research problem.
+ * This catches the most common patterns ("ignore previous instructions",
+ * etc.) so apps have a cheap first-line defense; layered defenses
+ * (system-prompt isolation, output-side guards) are still required.
+ */
+const INJECTION_PATTERNS: RegExp[] = [
+  /\bignore\s+(?:all\s+)?(?:previous|prior|above)\s+instructions?\b/i,
+  /\bdisregard\s+(?:all\s+)?(?:previous|prior|above)\b/i,
+  /\bforget\s+(?:everything|all)\s+(?:you|i)\b/i,
+  /\byou\s+are\s+now\s+a\s+\w+/i, // "you are now a pirate AI"
+  /\bnew\s+instructions?:\s*/i,
+  /\bsystem\s*[:>]\s*/i, // injection attempts framed as system prompts
+  /\b(?:reveal|show|print|output|display)\s+(?:your|the)\s+(?:system\s+)?prompt\b/i,
+  /<\s*\/?\s*system\s*>/i, // pseudo-system XML tags
+  /\[INST\]|\[\/INST\]/i, // llama-instruct framing
+  /^\s*###\s+(?:instruction|system)/im,
+]
+
+export interface SanitizeResult {
+  /** True when no injection patterns matched. */
+  ok: boolean
+  /** List of pattern descriptions that matched (empty when ok). */
+  matched: string[]
+  /** The input, with matched patterns replaced by `[redacted]`. */
+  cleaned: string
+}
+
+/**
+ * Inspect `text` for common prompt-injection patterns. Returns
+ * `{ ok, matched, cleaned }`. Apps decide what to do with the
+ * result — reject the request (`if (!result.ok) throw...`), pass
+ * the cleaned text on (`useText(result.cleaned)`), or just log
+ * for audit while letting the original through.
+ *
+ * **Limits:** this is heuristic. Adversarial inputs can paraphrase
+ * around any specific pattern. Use as a cheap first filter; for
+ * real defense, isolate the user input from the system prompt
+ * structurally (different roles, JSON-mode for the system layer)
+ * and guard the output side too.
+ *
+ * @example
+ * ```ts
+ * const check = sanitizePrompt(userInput)
+ * if (!check.ok) {
+ *   log.warn('possible injection attempt', { patterns: check.matched })
+ *   // option A: reject
+ *   throw new HttpError(400, 'invalid input')
+ *   // option B: pass cleaned
+ *   await chat([{ role: 'user', content: check.cleaned }])
+ * }
+ * ```
+ */
+export function sanitizePrompt(text: string): SanitizeResult {
+  if (!text) return { ok: true, matched: [], cleaned: text }
+  const matched: string[] = []
+  let cleaned = text
+  for (const pattern of INJECTION_PATTERNS) {
+    if (pattern.test(cleaned)) {
+      matched.push(pattern.toString())
+      cleaned = cleaned.replace(pattern, '[redacted]')
+    }
+  }
+  return {
+    ok: matched.length === 0,
+    matched,
+    cleaned,
+  }
+}