@owlmeans/llm 0.1.14

package/src/helpers/json.ts

@@ -0,0 +1,117 @@
+/** Property names checked when a model wraps a scalar string in an object. */
+const SCALAR_KEYS = ['path', 'file', 'filename', 'name', 'value', 'source']
+
+const tryParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Recover a JSON value from message content. Some models ignore the tool they were
+ * pinned to and emit the schema-shaped JSON directly as plain message content, so the
+ * tool-call parse yields nothing while the content is still valid JSON. Tolerates
+ * markdown fences and leading/trailing prose by falling back to the outermost
+ * `{...}` / `[...]` span. Returns `null` when nothing parseable is found.
+ */
+export const parseJsonContent = (content: unknown): unknown => {
+  let text: string
+  if (typeof content === 'string') {
+    text = content
+  } else if (Array.isArray(content)) {
+    text = content.map(part => typeof part === 'object' && part !== null && 'text' in (part as Record<string, unknown>)
+      ? String((part as Record<string, unknown>).text) : '').join('')
+  } else {
+    return null
+  }
+
+  text = text.trim()
+  if (text === '') return null
+
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i)
+  if (fence != null) text = fence[1]!.trim()
+
+  const whole = tryParse(text)
+  if (whole !== undefined) return whole
+
+  const firstObj = text.indexOf('{')
+  const lastObj = text.lastIndexOf('}')
+  if (firstObj >= 0 && lastObj > firstObj) {
+    const parsed = tryParse(text.slice(firstObj, lastObj + 1))
+    if (parsed !== undefined) return parsed
+  }
+
+  const firstArr = text.indexOf('[')
+  const lastArr = text.lastIndexOf(']')
+  if (firstArr >= 0 && lastArr > firstArr) {
+    const parsed = tryParse(text.slice(firstArr, lastArr + 1))
+    if (parsed !== undefined) return parsed
+  }
+
+  return null
+}
+
+/**
+ * Reconcile a model's answer with the schema it was given, for the two mistakes models
+ * make most often with tool-call arguments:
+ *
+ * 1. **Stringified structures** — an `array` field filled with the string `"[]"`, an
+ *    `integer` field with `"7"`, a `boolean` with `"true"`. Parsed back to the declared
+ *    type; on a parse failure the original value is kept so validation reports the real error.
+ * 2. **Over-wrapped scalars** — a `string` field filled with `{ path: "…" }` instead of
+ *    `"…"`. Unwrapped via the likely key, or via the single string property if there is
+ *    exactly one.
+ *
+ * Walks objects and arrays, so nested occurrences are fixed too. Purely defensive: a
+ * value that already matches its schema is returned untouched.
+ */
+export const coerceToSchema = (value: unknown, schema: unknown): unknown => {
+  if (schema == null || typeof schema !== 'object') return value
+  const s = schema as { type?: string; properties?: Record<string, unknown>; items?: unknown }
+  const type = s.type
+
+  if (typeof value === 'string' && type != null && type !== 'string') {
+    if (type === 'array' || type === 'object') {
+      try {
+        return coerceToSchema(JSON.parse(value), schema)
+      } catch {
+        return value
+      }
+    }
+    if (type === 'integer' || type === 'number') {
+      const n = Number(value)
+      return Number.isNaN(n) ? value : n
+    }
+    if (type === 'boolean') {
+      if (value === 'true') return true
+      if (value === 'false') return false
+      return value
+    }
+  }
+
+  if (type === 'string' && value != null && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>
+    for (const key of SCALAR_KEYS) {
+      if (typeof obj[key] === 'string') return obj[key]
+    }
+    const strings = Object.values(obj).filter((v): v is string => typeof v === 'string')
+    if (strings.length === 1) return strings[0]
+  }
+
+  if (type === 'object' && s.properties != null && value != null
+    && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>
+    for (const [key, propSchema] of Object.entries(s.properties)) {
+      if (key in obj) obj[key] = coerceToSchema(obj[key], propSchema)
+    }
+    return obj
+  }
+
+  if (type === 'array' && Array.isArray(value) && s.items != null) {
+    return value.map(item => coerceToSchema(item, s.items))
+  }
+
+  return value
+}

package/src/helpers/messages.ts

@@ -0,0 +1,12 @@
+import type { MessageFieldWithRole } from '@langchain/core/messages'
+import type { ModelInput } from '../types.js'
+
+/**
+ * Normalize whatever a caller passed as input into an array of role-tagged messages:
+ * a bare string becomes a `user` message, a single message becomes a one-element array.
+ * The result is a fresh array the model is free to mutate (JSON directive, `/no_think`,
+ * cache markers) without touching the caller's data.
+ */
+export const normalizeInput = (input: ModelInput): MessageFieldWithRole[] =>
+  (Array.isArray(input) ? input : [input])
+    .map(message => typeof message === 'string' ? { role: 'user' as const, content: message } : message) as MessageFieldWithRole[]

package/src/helpers/retry.ts

@@ -0,0 +1,59 @@
+import { LlmRetryExceededError } from '../errors.js'
+import { plugins } from '../plugins/index.js'
+import type { FatalErrorResolver, RetryOptions } from '../types.js'
+
+const resolvers: FatalErrorResolver[] = []
+
+/**
+ * Register a globally-applicable rule that turns a thrown error into an immediate
+ * abort of every retry loop in this package. Use it for conditions no amount of
+ * retrying can fix — an exhausted budget, a revoked credential, a cancelled job.
+ *
+ * Provider plugins contribute their own through `LlmPlugin.isFatal`; both sets are
+ * consulted, plus the per-call {@link RetryOptions.fatal}.
+ */
+export const registerFatalError = (resolver: FatalErrorResolver): void => {
+  resolvers.push(resolver)
+}
+
+const resolveFatal = (e: unknown, fatal?: FatalErrorResolver): Error | null => {
+  const own = fatal?.(e)
+  if (own != null) return own
+  for (const resolver of resolvers) {
+    const found = resolver(e)
+    if (found != null) return found
+  }
+  for (const plugin of Object.values(plugins)) {
+    const found = plugin.isFatal?.(e)
+    if (found != null) return found
+  }
+  return null
+}
+
+/**
+ * Run `fn` up to `retries` times, passing the 0-based attempt number so the callee can
+ * escalate (a bigger output budget, a stronger model). Every non-fatal error is
+ * swallowed and retained as the `cause` of the {@link LlmRetryExceededError} thrown when
+ * the attempts run out; a fatal error (see {@link registerFatalError}) is rethrown at once.
+ */
+export const withRetry = async <T>(
+  { retries, outputErrors = false, fatal }: RetryOptions,
+  fn: (attempt: number) => Promise<T>
+): Promise<T> => {
+  const exceeded = new LlmRetryExceededError('max-retries')
+  for (let i = 0; i < retries; ++i) {
+    try {
+      return await fn(i)
+    } catch (e) {
+      const abort = resolveFatal(e, fatal)
+      if (abort != null) throw abort
+      exceeded.cause = e
+      exceeded.attempt = i
+      if (outputErrors) {
+        console.debug('Retry error on attempt', i)
+        console.error(e)
+      }
+    }
+  }
+  throw exceeded
+}

package/src/helpers/spectate.ts

@@ -0,0 +1,67 @@
+import { AIMessage, BaseMessage } from '@langchain/core/messages'
+import type { UsageMetadata } from '@langchain/core/messages'
+import { SpectatorContentType } from '@owlmeans/llm-common'
+import type { SpectatorEntryMessage } from '@owlmeans/llm-common'
+import type { LlmSpectator, ModelInputItem } from '../types.js'
+
+/** Normalize one prompt message into the spectator's storage shape. */
+const describeInput = (msg: ModelInputItem, callType: string): SpectatorEntryMessage => {
+  const entry: SpectatorEntryMessage = {
+    callType,
+    type: 'unknown',
+    content: '',
+    contentType: SpectatorContentType.Text,
+  }
+
+  if (msg instanceof BaseMessage) {
+    entry.type = msg.type
+    entry.content = msg.content as unknown as string
+    entry.name = msg.name
+    entry.contentType = typeof msg.content === 'string' ? SpectatorContentType.Text : SpectatorContentType.Json
+    entry.usage = 'usage_metadata' in msg ? msg.usage_metadata as UsageMetadata : undefined
+    entry.raw = JSON.stringify({ message: msg, content: msg.content, meta: msg.response_metadata })
+  } else if (typeof msg === 'object' && 'content' in msg) {
+    entry.type = msg.role as string ?? 'unknown'
+    entry.content = msg.content as string ?? msg as unknown as string
+    entry.raw = JSON.stringify(msg)
+  } else {
+    entry.content = msg as unknown as string
+    entry.raw = JSON.stringify(msg)
+  }
+
+  return entry
+}
+
+/**
+ * Log a completed model call: every prompt message plus the completion, as one entry.
+ * A tool-calling completion carries its arguments rather than its (empty) content.
+ */
+export const spectate = (spectator: LlmSpectator, callType: string) =>
+  async (
+    input: ModelInputItem[],
+    message: AIMessage,
+    action: string,
+    retries: number,
+    startedAt?: number,
+  ) => {
+    const messages = input.map(msg => describeInput(msg, callType))
+
+    const completion: SpectatorEntryMessage = {
+      type: message.type,
+      callType,
+      content: '',
+      name: message.name,
+      contentType: typeof message.content === 'string' ? SpectatorContentType.Text : SpectatorContentType.Json,
+      usage: message.usage_metadata,
+      raw: JSON.stringify({ message, content: message.content, meta: message.response_metadata }),
+    }
+
+    if (message.tool_calls != null && message.tool_calls.length > 0) {
+      completion.content = message.tool_calls as unknown as string
+      completion.contentType = SpectatorContentType.ToolCall
+    } else {
+      completion.content = message.content as unknown as string
+    }
+
+    return spectator.log({ action, retries, startedAt, messages: [...messages, completion] })
+  }

package/src/index.ts

@@ -0,0 +1,13 @@
+
+export * from './consts.js'
+export * from './errors.js'
+export type * from './types.js'
+export * from './model.js'
+export * from './service.js'
+export * from './helpers/index.js'
+export * from './execution/index.js'
+export type * from './plugins/types.js'
+export { plugins, registerLlmPlugin, pluginOf, pluginFor, resolvePlugin } from './plugins/index.js'
+export { anthropicPlugin, ANTHROPIC_FAMILY } from './plugins/anthropic.js'
+export { compatiblePlugin } from './plugins/compatible.js'
+export { openAiPlugin, openAiFamily, OPENAI_FAMILY } from './plugins/openai.js'

package/src/model.ts

@@ -0,0 +1,379 @@
+import { Ajv } from 'ajv'
+import type { JSONSchemaType } from 'ajv'
+import { AIMessage } from '@langchain/core/messages'
+import type { AIMessageChunk, MessageFieldWithRole } from '@langchain/core/messages'
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
+import { StructuredMode } from '@owlmeans/llm-common'
+import type { NullKind } from '@owlmeans/llm-common'
+import {
+  DEFAULT_MAX_OUTPUT_CAP, DEFAULT_MODEL_RETRIES, FALLBACK_AFTER_ATTEMPTS,
+} from './consts.js'
+import { LlmModelError } from './errors.js'
+import { pluginFor, pluginOf } from './plugins/index.js'
+import type { LlmPlugin } from './plugins/types.js'
+import { coerceToSchema, parseJsonContent } from './helpers/json.js'
+import { normalizeInput } from './helpers/messages.js'
+import { withRetry } from './helpers/retry.js'
+import { spectate } from './helpers/spectate.js'
+import { idleTimeout, readConfig } from './utils/config.js'
+import { reportNull } from './utils/null-report.js'
+import type { NullReportParams } from './utils/null-report.js'
+import { applyNoThink, ensureJsonMention } from './utils/prompt.js'
+import { resolveSchemaValidator, toToolName, unwrapNamed } from './utils/schema.js'
+import { streamWithDeadline } from './utils/stream.js'
+import type {
+  LlmAskOptions, LlmInvokeOptions, LlmModel, LlmModelOptions, LlmRequestOptions,
+  LlmSpectator, LlmTalkOptions, ModelInput, RefferedResult,
+} from './types.js'
+
+type StreamOptions = Parameters<BaseChatModel['stream']>[1]
+
+/**
+ * Build the four-method model API on top of a LangChain chat model.
+ *
+ * Everything provider-specific — how the client is refined between retries, how
+ * structured output is requested, whether prompt caching exists — is delegated to the
+ * `LlmPlugin` resolved for this model (see `plugins/`). The model itself only owns the
+ * provider-independent parts: streaming under an idle deadline, retry/fallback
+ * escalation, schema validation and coercion, spectator logging, and null diagnostics.
+ */
+export const makeLlmModel = ({
+  model,
+  outputErrors = false,
+  captureNull = false,
+  retries = DEFAULT_MODEL_RETRIES,
+  purpose,
+}: LlmModelOptions, spectator: LlmSpectator): LlmModel => {
+
+  const ajv = new Ajv({ strict: false })
+
+  // The original config and its plugin are static per model instance: a REFINED instance
+  // is rebuilt from `lc_kwargs` and does not reliably carry the metadata back.
+  const config = readConfig(model)
+  const plugin: LlmPlugin | undefined = pluginOf(config.provider) ?? pluginFor(model)
+  const timeout = idleTimeout(config)
+
+  /** Normalize, then apply every in-place prompt adaptation, in dependency order. */
+  const prepare = (input: ModelInput, useCache: boolean, cacheMax: number, json: boolean): MessageFieldWithRole[] => {
+    const msgs = normalizeInput(input)
+    if (json) ensureJsonMention(msgs)
+    applyNoThink(msgs, config.disableThinking)
+    // Cache markers replace string content with content blocks, so they must go last.
+    if (plugin?.patchCache?.(msgs, { model, useCache, cacheMax }) === true) {
+      console.log(`Prompt caching enabled for ${plugin.type} (up to ${cacheMax} breakpoints)`)
+    }
+    return msgs
+  }
+
+  const notifyRef = <T>(ref: RefferedResult<T> | undefined, value: T): void => {
+    if (ref != null) {
+      ref.value = value
+      void ref.callback?.(value).finally()
+    }
+  }
+
+  /**
+   * Record the diagnostics of a call that produced nothing usable and build the
+   * retryable error describing it. The caller throws it, so control flow stays visible.
+   */
+  const nullResult = async (
+    kind: NullKind,
+    p: Omit<NullReportParams, 'kind' | 'purpose' | 'config'>,
+    parsed: boolean = false,
+  ): Promise<LlmModelError> => {
+    await reportNull(spectator, captureNull, { ...p, kind, purpose, config })
+    const toolCalls = (p.raw as unknown as { tool_calls?: unknown[] } | null)?.tool_calls?.length ?? 0
+    const content = JSON.stringify(p.raw?.content ?? null).substring(0, 120)
+    return new LlmModelError(
+      `null-output:raw=${p.raw != null}, parsed=${parsed}, toolCalls=${toolCalls}, content=${content}`
+    )
+  }
+
+  /**
+   * Rebuild the model for attempt N.
+   *
+   * Two-layer fallback: once a cheap primary has failed {@link FALLBACK_AFTER_ATTEMPTS}
+   * times, escalate to the stronger model the service attached as `__fallbackModel`. The
+   * escalation only happens WITHIN one plugin family — rotating providers mid-call would
+   * flip the structured-output call shape (tool_choice spelling, native support), so it is
+   * better to keep retrying on the primary than to switch families.
+   */
+  const refineModel = (attempt: number, temperature?: number): BaseChatModel => {
+    const fallbackModel = (model as unknown as { __fallbackModel?: BaseChatModel }).__fallbackModel
+    const sameFamily = fallbackModel != null && plugin != null
+      && plugin.owns(model) && plugin.owns(fallbackModel)
+    const base = (sameFamily && attempt >= FALLBACK_AFTER_ATTEMPTS) ? fallbackModel : model
+
+    if (attempt === FALLBACK_AFTER_ATTEMPTS && fallbackModel != null) {
+      if (base !== model) {
+        console.warn(`${base.getName()}: switching to fallback model after ${attempt} failed attempts`)
+      } else {
+        console.warn(
+          `Skipping cross-family fallback (${fallbackModel.getName()}); staying on ${model.getName()}`
+        )
+      }
+    }
+
+    const baseConfig = readConfig(base)
+    const basePlugin = pluginOf(baseConfig.provider) ?? pluginFor(base)
+    if (basePlugin == null) return base
+
+    const maxOutputCap = typeof baseConfig.maxTokensCap === 'number' && baseConfig.maxTokensCap > 0
+      ? baseConfig.maxTokensCap
+      : DEFAULT_MAX_OUTPUT_CAP
+    const refined = basePlugin.refine({ base, attempt, temperature, maxOutputCap })
+
+    if (attempt > 0) {
+      const maxTokens = (refined as unknown as { maxTokens?: number }).maxTokens
+      console.warn(`${refined.getName()}: retry attempt ${attempt}, maxTokens now ${maxTokens}`)
+    }
+
+    return refined
+  }
+
+  /** How this model should be asked for schema-conforming output. */
+  const structuredMode = (): StructuredMode => plugin != null
+    ? plugin.structuredMode(config as Parameters<LlmPlugin['structuredMode']>[0])
+    : (config.structuredOutput === true ? StructuredMode.Native : StructuredMode.Tool)
+
+  /**
+   * Shared structured-output core for `invoke`/`request`. Streams under the idle deadline
+   * (whose break-on-`finish_reason` also dedups the duplicate final chunk some providers
+   * emit, which would otherwise corrupt accumulated tool-call arguments), accumulates the
+   * chunks and extracts the parsed object.
+   *
+   * `withStructuredOutput` is deliberately NOT used: it buffers the whole raw stream
+   * before yielding, which is too late to dedup.
+   */
+  const streamStructured = async <T>(
+    refined: BaseChatModel,
+    msgs: MessageFieldWithRole[],
+    innerSchema: JSONSchemaType<T>,
+    toolName: string,
+    action: string,
+  ): Promise<{ piece: AIMessageChunk | null; result: T | null; mode: StructuredMode }> => {
+    const responseFormat = structuredMode() === StructuredMode.Native
+      ? plugin?.responseFormat?.(toolName, innerSchema)
+      : undefined
+    // A plugin that declares Native but provides no response_format falls back to tools.
+    const mode = responseFormat != null ? StructuredMode.Native : StructuredMode.Tool
+
+    const start = (signal: AbortSignal): Promise<AsyncIterable<unknown>> => {
+      const base = { runName: action, metadata: { purpose }, signal }
+      if (mode === StructuredMode.Native) {
+        return refined.stream(msgs, { ...base, ...responseFormat && { response_format: responseFormat } } as unknown as StreamOptions)
+      }
+      // langchain converts the OpenAI-shaped tool DEFINITION for either provider, but the
+      // `tool_choice` shape is NOT converted — the plugin supplies the right spelling.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const bound = refined.bindTools!(
+        [{ type: 'function', function: { name: toolName, description: '', parameters: innerSchema } }],
+        { tool_choice: plugin?.toolChoice(toolName) ?? { type: 'function', function: { name: toolName } } }
+      )
+      return bound.stream(msgs, base)
+    }
+
+    let piece: AIMessageChunk | null = null
+    for await (const rawChunk of streamWithDeadline(start, timeout)) {
+      const chunk = rawChunk as AIMessageChunk
+      piece = piece == null ? chunk : (piece.concat(chunk) as AIMessageChunk)
+    }
+
+    let result: T | null = null
+    if (mode === StructuredMode.Tool) {
+      const rawArgs = piece?.tool_calls?.[0]?.args ?? null
+      result = rawArgs != null
+        ? (typeof rawArgs === 'string' ? parseJsonContent(rawArgs) as T | null : rawArgs as T)
+        : null
+    }
+    // Content fallback: some models ignore the pinned tool (or the JSON mode) and emit the
+    // schema-shaped JSON as plain content.
+    if (result == null && piece != null) {
+      const recovered = parseJsonContent(piece.content)
+      if (recovered != null) result = recovered as T
+    }
+
+    return { piece, result, mode }
+  }
+
+  const helper: LlmModel = {
+    ask: async (input, { ref, filter, action, useCache = false, cacheMax = 4 }: LlmAskOptions) => {
+      const msgs = prepare(input, useCache, cacheMax, false)
+      return withRetry({ retries, outputErrors }, async i => {
+        const refined = refineModel(i)
+        console.log('Use model to ask: ', refined.getName(), refined.lc_kwargs.model)
+        const startedAt = Date.now()
+        let result: AIMessageChunk | null = null
+        for await (const chunk of streamWithDeadline(
+          signal => refined.stream(msgs, { runName: action, metadata: { purpose }, signal }), timeout
+        )) {
+          result = result == null ? chunk : result.concat(chunk)
+        }
+        if (result == null) {
+          throw await nullResult('ask', { action, attempt: i, startedAt, refined, msgs, raw: result, useCache })
+        }
+
+        const message = new AIMessage(result)
+        let output: string | null = typeof result.content === 'string'
+          ? result.content
+          : Array.isArray(result.content)
+            ? result.content
+              .filter((c): c is { type: string; text: string } =>
+                typeof c === 'object' && c !== null && 'type' in c && c.type === 'text'
+              )
+              .map(c => c.text)
+              .join('') || null
+            : null
+
+        const entry = await spectate(spectator, 'ask')(msgs, message, action, i, startedAt)
+        if (ref != null) ref.spectatorEntry = entry
+
+        if (filter != null) {
+          output = await filter(output ?? '', message)
+          if (output == null) {
+            throw new LlmModelError(`filter-rejected:${JSON.stringify(message).substring(0, 50)}...`)
+          }
+        } else if (output == null || output.trim() === '') {
+          throw new LlmModelError(`empty-content:${JSON.stringify(message).substring(0, 50)}...`)
+        }
+
+        notifyRef(ref, message)
+        return output
+      })
+    },
+
+    talk: async (input, { ref, filter, action, useCache = false, cacheMax = 4 }: LlmTalkOptions) => {
+      const msgs = prepare(input, useCache, cacheMax, false)
+      return withRetry({ retries, outputErrors }, async i => {
+        const refined = refineModel(i)
+        console.log('Use model to talk: ', refined.getName(), refined.lc_kwargs.model)
+        const startedAt = Date.now()
+        let result: AIMessageChunk | null = null
+        for await (const chunk of streamWithDeadline(
+          signal => refined.stream(msgs, { runName: action, metadata: { purpose }, signal }), timeout
+        )) {
+          result = result == null ? chunk : result.concat(chunk)
+        }
+        if (result == null) {
+          throw await nullResult('talk', { action, attempt: i, startedAt, refined, msgs, raw: result, useCache })
+        }
+
+        let message: AIMessage | null = new AIMessage(result)
+        const entry = await spectate(spectator, 'talk')(msgs, message, action, i, startedAt)
+        if (ref != null) ref.spectatorEntry = entry
+
+        if (filter != null) {
+          message = await filter(message)
+          if (message == null) {
+            throw new LlmModelError('filter-rejected:talk')
+          }
+        }
+
+        notifyRef(ref, message)
+        return message
+      })
+    },
+
+    invoke: async <T>(
+      input: ModelInput,
+      schema: JSONSchemaType<T>,
+      { temperature, ref, filter, action, useCache = false, cacheMax = 4 }: LlmInvokeOptions<T>
+    ) => {
+      const msgs = prepare(input, useCache, cacheMax, true)
+      const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
+      const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
+
+      return withRetry({ retries, outputErrors }, async i => {
+        const refined = refineModel(i, temperature)
+        console.log('Use model invoke: ', refined.getName(), refined.lc_kwargs.model)
+        const startedAt = Date.now()
+        const { piece, result: collected } = await streamStructured(refined, msgs, innerSchema, toolName, action)
+        let result: T | null = collected
+        if (piece == null || result == null) {
+          throw await nullResult('invoke', {
+            action, attempt: i, startedAt, refined, msgs, raw: piece,
+            schema: { toolName, innerSchema }, useCache,
+          }, result != null)
+        }
+
+        const message = new AIMessage(piece)
+        const entry = await spectate(spectator, 'invoke')(msgs, message, action, i, startedAt)
+        if (ref != null) ref.spectatorEntry = entry
+
+        result = unwrapNamed(result, name)
+        result = coerceToSchema(result, innerSchema) as T
+
+        if (filter != null) {
+          const preFilter = result
+          result = await filter(result, message)
+          if (result == null) {
+            throw new LlmModelError(`filter-rejected:${JSON.stringify(preFilter).substring(0, 200)}`)
+          }
+        }
+
+        if (!validate(result)) {
+          const err = new LlmModelError(`validation-failed:${JSON.stringify(validate.errors)}`)
+          err.cause = validate.errors?.[0]
+          throw err
+        }
+
+        notifyRef(ref, message)
+        return result as T
+      })
+    },
+
+    request: async <T>(
+      input: ModelInput,
+      schema: JSONSchemaType<T>,
+      { ref, filter, action, useCache = false, cacheMax = 4 }: LlmRequestOptions
+    ) => {
+      const msgs = prepare(input, useCache, cacheMax, true)
+      const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
+      const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
+
+      return withRetry({ retries, outputErrors }, async i => {
+        const refined = refineModel(i)
+        console.log('Use model request: ', refined.getName(), refined.lc_kwargs.model)
+        const startedAt = Date.now()
+        const { piece, result: collected } = await streamStructured(refined, msgs, innerSchema, toolName, action)
+        let result: T | null = collected
+        if (piece == null || result == null) {
+          throw await nullResult('request', {
+            action, attempt: i, startedAt, refined, msgs, raw: piece,
+            schema: { toolName, innerSchema }, useCache,
+          }, result != null)
+        }
+
+        let message: AIMessage | null = new AIMessage(piece)
+        const entry = await spectate(spectator, 'request')(msgs, message, action, i, startedAt)
+        if (ref != null) ref.spectatorEntry = entry
+
+        // Structured output delivers the JSON as parsed tool arguments, not as message
+        // content. Surface it on `.content` so the AIMessage contract callers rely on holds.
+        result = unwrapNamed(result, name)
+        result = coerceToSchema(result, innerSchema) as T
+        message.content = JSON.stringify(result)
+
+        if (filter != null) {
+          message = await filter(message)
+          if (message == null) {
+            throw new LlmModelError('filter-rejected:request')
+          }
+        } else if (message.content == null || message.content.toString().trim() === '') {
+          throw new LlmModelError(`empty-content:${JSON.stringify(message).substring(0, 50)}...`)
+        }
+
+        if (!validate(JSON.parse(`${message.content}`))) {
+          const err = new LlmModelError(`validation-failed:${JSON.stringify(validate.errors)}`)
+          err.cause = validate.errors?.[0]
+          throw err
+        }
+
+        notifyRef(ref, message)
+        return message
+      })
+    },
+  }
+
+  return helper
+}