@stacksjs/ai 0.70.53 → 0.70.55

package/src/utils/usage.ts

@@ -0,0 +1,98 @@
+/**
+ * AI usage tracking (stacksjs/stacks#1878 A-6).
+ *
+ * Background: `AIResult.usage` returns token counts per-call but
+ * nothing aggregates them. Apps that want "this user has spent
+ * $X this month" build the aggregation themselves — wiring a
+ * listener on every model invocation, persisting the running
+ * total, etc.
+ *
+ * This module ships a singleton recorder that drivers emit to on
+ * each completion. Apps install one or more `UsageReporter`
+ * functions that get called with `{ provider, model, prompt_tokens,
+ * completion_tokens, timestamp, durationMs }` and decide what to
+ * do (store to DB, push to Datadog, etc.). Default behavior with
+ * no reporter is a no-op — the framework doesn't impose a sink.
+ */
+
+export interface UsageRecord {
+  /** Provider name (e.g. `'openai'`, `'anthropic'`). */
+  provider: string
+  /** Model id from the response (e.g. `'gpt-4o'`, `'claude-sonnet-4'`). */
+  model: string
+  /** Prompt-side token count. */
+  promptTokens: number
+  /** Completion-side token count. */
+  completionTokens: number
+  /** Total tokens (`promptTokens + completionTokens`). */
+  totalTokens: number
+  /** Wall-clock duration of the completion in ms. */
+  durationMs: number
+  /** Wall-clock timestamp the completion finished, in epoch ms. */
+  timestamp: number
+  /** Optional caller-supplied tag (user id, request id, etc.). */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * A reporter is called once per recorded completion. Multiple
+ * reporters can be installed simultaneously; they fire in
+ * registration order. Reporters MUST NOT throw — errors are
+ * caught and logged but otherwise ignored so a flaky metrics
+ * sink doesn't break the user's completion call.
+ */
+export type UsageReporter = (record: UsageRecord) => void | Promise<void>
+
+const reporters: UsageReporter[] = []
+
+/**
+ * Register a usage reporter. Returns an `unregister` callback for
+ * apps that want to swap reporters at runtime (test setup/teardown,
+ * tenant isolation, etc.).
+ */
+export function onUsage(reporter: UsageReporter): () => void {
+  reporters.push(reporter)
+  return () => {
+    const idx = reporters.indexOf(reporter)
+    if (idx >= 0) reporters.splice(idx, 1)
+  }
+}
+
+/**
+ * Drop every registered reporter. Useful for tests.
+ */
+export function clearUsageReporters(): void {
+  reporters.length = 0
+}
+
+/**
+ * Emit a usage record to every registered reporter. Called by
+ * driver completion paths after the response lands. Reporter
+ * errors are caught + logged so a misbehaving sink doesn't
+ * propagate up to the caller.
+ */
+export function recordUsage(record: UsageRecord): void {
+  for (const reporter of reporters) {
+    try {
+      const result = reporter(record)
+      if (result && typeof (result as Promise<void>).then === 'function') {
+        (result as Promise<void>).catch((err) => {
+          // eslint-disable-next-line no-console
+          console.error('[ai/usage] reporter rejected:', err)
+        })
+      }
+    }
+    catch (err) {
+      // eslint-disable-next-line no-console
+      console.error('[ai/usage] reporter threw:', err)
+    }
+  }
+}
+
+/**
+ * Snapshot the currently-registered reporters. Useful for tests
+ * to assert behavior without exposing the internal array.
+ */
+export function listUsageReporters(): readonly UsageReporter[] {
+  return reporters
+}

package/src/utils/vision.ts

@@ -0,0 +1,119 @@
+/**
+ * Vision message normalization (stacksjs/stacks#1878 A-3).
+ *
+ * Background: `AIMessage.content` already accepts a content-array
+ * with `{ type: 'image_url' }` or `{ type: 'image', source: {...} }`
+ * blocks. Both OpenAI and Anthropic accept image inputs but via
+ * different wire shapes:
+ *
+ *   - **OpenAI** — content array with `{ type: 'image_url', image_url: { url, detail } }`
+ *     where `url` is either an https URL or a base64 data URI.
+ *   - **Anthropic** — content array with `{ type: 'image', source: { type: 'base64', media_type, data } }`
+ *     for base64 OR `{ type: 'image', source: { type: 'url', url } }` for URL form (Claude 3.5+).
+ *
+ * Driver users shouldn't have to know which wire format each
+ * provider wants. These helpers translate between the two so an
+ * app that switches between OpenAI and Anthropic doesn't have to
+ * rewrite its message construction.
+ */
+
+import type { AIMessage, AIMessageContent } from '../types'
+
+/**
+ * Normalize a message-content block for the OpenAI wire format.
+ * Pass-through for `image_url` blocks; converts Anthropic-style
+ * `{ type: 'image', source: {...} }` to OpenAI's `image_url` shape.
+ */
+function toOpenAIContent(block: AIMessageContent): unknown {
+  if (block.type === 'text') return { type: 'text', text: block.text ?? '' }
+  if (block.type === 'image_url') return { type: 'image_url', image_url: block.image_url }
+  if (block.type === 'image' && block.source) {
+    if (block.source.type === 'base64') {
+      const dataUri = `data:${block.source.media_type};base64,${block.source.data}`
+      return { type: 'image_url', image_url: { url: dataUri } }
+    }
+  }
+  // Unknown block type — pass through and let the API surface the error.
+  return block
+}
+
+/**
+ * Normalize a message-content block for the Anthropic wire format.
+ * Pass-through for `image` blocks; converts OpenAI-style `image_url`
+ * (either https URL or data URI) into Anthropic's `image` source shape.
+ */
+function toAnthropicContent(block: AIMessageContent): unknown {
+  if (block.type === 'text') return { type: 'text', text: block.text ?? '' }
+  if (block.type === 'image' && block.source)
+    return { type: 'image', source: block.source }
+  if (block.type === 'image_url' && block.image_url) {
+    const url = block.image_url.url
+    // data: URIs unwrap to Anthropic's base64 source shape.
+    const dataMatch = url.match(/^data:([^;]+);base64,(.+)$/)
+    if (dataMatch) {
+      return {
+        type: 'image',
+        source: { type: 'base64', media_type: dataMatch[1]!, data: dataMatch[2]! },
+      }
+    }
+    // Non-data URL — pass through as the url source variant (Claude 3.5+).
+    return { type: 'image', source: { type: 'url', url } }
+  }
+  return block
+}
+
+/**
+ * Normalize an entire `messages` array for the requested provider.
+ * Messages whose `content` is a plain string pass through unchanged.
+ * Messages with a content array get each block translated.
+ */
+export function normalizeMessagesForProvider(
+  messages: AIMessage[],
+  provider: 'openai' | 'anthropic',
+): AIMessage[] {
+  return messages.map((msg) => {
+    if (typeof msg.content === 'string') return msg
+    const mapper = provider === 'openai' ? toOpenAIContent : toAnthropicContent
+    return {
+      role: msg.role,
+      content: msg.content.map(mapper) as AIMessageContent[],
+    }
+  })
+}
+
+/**
+ * Convenience: convert a single command + optional image inputs into
+ * an `AIMessage` content array suitable for `chat()` calls. Used by
+ * the higher-level `text()` / `chat()` helpers when a user passes
+ * `{ command, images }` together.
+ *
+ * @example
+ * ```ts
+ * const content = buildMessageWithImages('What is in this image?', [
+ *   { url: 'https://example.com/cat.jpg' },
+ * ])
+ * await chat([{ role: 'user', content }])
+ * ```
+ */
+export function buildMessageWithImages(
+  command: string,
+  images: Array<{ url?: string, dataBase64?: string, mediaType?: string, detail?: 'auto' | 'low' | 'high' }>,
+): AIMessageContent[] {
+  const blocks: AIMessageContent[] = []
+  for (const img of images) {
+    if (img.dataBase64 && img.mediaType) {
+      blocks.push({
+        type: 'image',
+        source: { type: 'base64', media_type: img.mediaType, data: img.dataBase64 },
+      })
+    }
+    else if (img.url) {
+      blocks.push({
+        type: 'image_url',
+        image_url: { url: img.url, detail: img.detail },
+      })
+    }
+  }
+  blocks.push({ type: 'text', text: command })
+  return blocks
+}