@outputai/core 0.15.1-next.4a437bf.0 → 0.15.1-next.8ef04e2.0

package/src/llm/index.d.ts

@@ -0,0 +1,631 @@
+import type {
+  GenerateTextResult as AIGenerateTextResult,
+  GenerateImageResult as AIGenerateImageResult,
+  StreamTextResult as AIStreamTextResult,
+  ToolSet,
+  ToolChoice,
+  StopCondition,
+  ModelMessage,
+  StreamTextOnChunkCallback,
+  GenerateTextOnEndCallback,
+  StreamTextOnErrorCallback
+} from 'ai';
+import type { Output as AIOutputNamespace } from 'ai';
+import type { Attribute } from '#trace_attribute';
+
+type BaseAttribute = Attribute.BaseAttribute;
+
+/** Full AI SDK module (values and types). Use `aiSdk.Output`, `aiSdk.tool`, `aiSdk.isStepCount`, `aiSdk.ToolSet`, and other AI SDK APIs. */
+export * as aiSdk from 'ai';
+
+/** Liquid interpolation variables, including nested objects and arrays. */
+export type PromptVariables = Record<string, unknown>;
+
+/**
+ * Represents a single message in a prompt conversation.
+ *
+ * @example
+ * ```ts
+ * const msg: PromptMessage = {
+ *   role: 'user',
+ *   content: 'Hello, Claude!'
+ * };
+ * ```
+ */
+export type PromptMessage = {
+  /** The message role. Authored prompt blocks support 'system', 'user', and 'assistant'. */
+  role: 'system' | 'user' | 'assistant';
+  /** The content of the message */
+  content: string;
+  /**
+   * Per-message provider options resolved at load from the role tag's `options` attribute and
+   * matching `config.messageOptions` sets. Authored as `<system options="set_a set_b">`.
+   * `options` is the only supported role-tag attribute and must have a value. Omitted when the tag
+   * has no effective `options`.
+   */
+  providerOptions?: Record<string, Record<string, unknown>>;
+};
+
+/**
+ * Configuration for LLM prompt generation.
+ *
+ * @example
+ * ```ts
+ * const prompt: Prompt = {
+ *   name: 'summarizePrompt',
+ *   fileDir: '/app/prompts',
+ *   variables: {},
+ *   config: {
+ *     provider: 'anthropic',
+ *     model: 'claude-opus-4-1',
+ *     temperature: 0.7,
+ *     maxOutputTokens: 2048,
+ *     maxSteps: 10,
+ *     skills: []
+ *   },
+ *   messages: [{ role: 'user', content: 'Summarize this document.' }],
+ *   instructions: null
+ * };
+ * ```
+ */
+export type Prompt = {
+  /** Prompt name used in tracing and errors. */
+  name: string;
+
+  /** Base directory for resolving relative prompt resources such as skills. */
+  fileDir: string;
+
+  /** Interpolation values associated with the prompt. Defaults to `{}` when validated. */
+  variables: PromptVariables;
+
+  /** General configuration for the LLM */
+  config: {
+    /**
+     * LLM provider.
+     *
+     * Built-in: `'anthropic'`, `'openai'`, `'azure'`, `'amazon-bedrock'`, `'google-vertex'`,
+     * `'perplexity'`. Legacy aliases `'bedrock'` and `'vertex'` are deprecated but still accepted
+     * in prompts and normalized to their canonical names with a warning. Custom providers
+     * registered via {@link registerProvider} are also accepted.
+     */
+    provider: string;
+
+    /** Model name/identifier */
+    model: string;
+
+    /** Generation temperature. Supported range and behavior vary by provider. */
+    temperature?: number;
+
+    /** Maximum number of tokens in the response. */
+    maxOutputTokens?: number;
+
+    /**
+     * Maximum number of tokens in the response.
+     *
+     * @deprecated Use `maxOutputTokens`.
+     */
+    maxTokens?: number;
+
+    /** Nucleus sampling value. Usually set instead of `temperature`. */
+    topP?: number;
+
+    /** Limits sampling to the top K token choices. */
+    topK?: number;
+
+    /** Penalizes tokens that already appear in the prompt or generated output. */
+    presencePenalty?: number;
+
+    /** Penalizes tokens according to how often they appear. */
+    frequencyPenalty?: number;
+
+    /** Sequences that stop text generation when produced. */
+    stopSequences?: string[];
+
+    /** Tool-loop iterations when `stopWhen` is omitted. Always a positive integer after load (default 10). */
+    maxSteps: number;
+
+    /** Number of images to generate */
+    n?: number;
+
+    /** Maximum images to request per provider call */
+    maxImagesPerCall?: number;
+
+    /** Image size, for example `1024x1024` */
+    size?: `${number}x${number}`;
+
+    /** Image aspect ratio, for example `16:9` */
+    aspectRatio?: `${number}:${number}`;
+
+    /** Random seed for deterministic text or image generation when supported */
+    seed?: number;
+
+    /** Skill file or directory paths relative to the prompt file. Always a `string[]` after load (`[]` if unset). */
+    skills: string[];
+
+    /**
+     * Provider-specific tools with configuration.
+     *
+     * @example Vertex googleSearch with config
+     * ```yaml
+     * tools:
+     *   googleSearch:
+     *     mode: MODE_DYNAMIC
+     *     dynamicThreshold: 0.8
+     * ```
+     *
+     * @example OpenAI webSearch with filters
+     * ```yaml
+     * tools:
+     *   webSearch:
+     *     searchContextSize: high
+     *     filters:
+     *       allowedDomains: [wikipedia.org]
+     * ```
+     */
+    tools?: Record<string, Record<string, unknown>>;
+
+    /** Provider-specific options */
+    providerOptions?: Record<string, unknown>;
+
+    /**
+     * Named, reusable per-message `providerOptions` sets, referenced from message blocks via the
+     * `options="<name>"` attribute. Each value is a provider-namespaced options object, e.g.
+     * `{ anthropic: { cacheControl: { type: 'ephemeral' } } }`.
+     */
+    messageOptions?: Record<string, Record<string, Record<string, unknown>>>;
+  };
+
+  /** Array of messages in the conversation */
+  messages: PromptMessage[];
+
+  /**
+   * The whole trimmed prompt body when its first meaningful token is plain text. Always set after
+   * `loadPrompt`: a non-empty string with `messages: []` for instruction mode, or `null` when the
+   * body starts with markup and is parsed into messages.
+   */
+  instructions: string | null;
+};
+
+type AnyAiOutput = AIOutputNamespace.Output<unknown, unknown, unknown>;
+type DefaultRuntimeContext = Record<string, unknown>;
+type CompatibleToolSchemaKey = 'inputSchema' | 'outputSchema' | 'contextSchema';
+type WithoutToolSchemaBrands<T> = T extends unknown ? {
+  [K in keyof T]: K extends CompatibleToolSchemaKey ? unknown : T[K];
+} : never;
+
+/**
+ * Structurally-compatible AI SDK 7 tool shape.
+ *
+ * This derives from AI SDK's `ToolSet` and widens only schema fields so tools from packages
+ * resolved with a different Zod peer instance remain assignable.
+ */
+export type CompatibleTool = WithoutToolSchemaBrands<ToolSet[string]>;
+
+/** AI SDK tools accepted by Output APIs without requiring one exact Zod peer instance. */
+export type CompatibleToolSet = Record<string, CompatibleTool>;
+
+type PromptFileCallOptions = {
+  /** Prompt file name (e.g. 'summary@v1') */
+  prompt: string;
+  /** Variables to interpolate into the prompt file */
+  variables?: PromptVariables;
+  /** Override the stack-resolved prompt directory */
+  promptDir?: string;
+};
+
+type PromptObjectCallOptions = {
+  /** Loaded or custom prompt object. */
+  prompt: Prompt;
+  /** Prompt objects are already rendered and cannot receive interpolation variables. */
+  variables?: never;
+  /** Prompt objects are not resolved from a prompt directory. */
+  promptDir?: never;
+};
+
+type PromptCallOptions = PromptFileCallOptions | PromptObjectCallOptions;
+
+type StopWhen<Tools extends ToolSet = ToolSet> =
+  StopCondition<NoInfer<Tools>, DefaultRuntimeContext> |
+  Array<StopCondition<NoInfer<Tools>, DefaultRuntimeContext>>;
+
+type TextCallOptions<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = PromptCallOptions & {
+  /** AI SDK tools, accepted structurally to tolerate different Zod peer versions. */
+  tools?: CompatibleToolSet;
+  /** Structured output specification */
+  output?: OutputSpec;
+  /** Tool choice, applied only when tools exist */
+  toolChoice?: ToolChoice<Tools>;
+  /** Caller stop condition; otherwise prompt `maxSteps` when tools exist */
+  stopWhen?: StopWhen<Tools>;
+  /** Abort signal for the request */
+  abortSignal?: AbortSignal;
+};
+
+/** Parameters accepted by {@link generateText}. */
+export type GenerateTextParameters<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = TextCallOptions<Tools, OutputSpec>;
+
+/** Parameters accepted by {@link generateTextWithStreaming}. */
+export type GenerateTextWithStreamingParameters<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = TextCallOptions<Tools, OutputSpec> & {
+  /** Callback for every AI SDK 7 stream part, including lifecycle, boundary, terminal, text, reasoning, and tool parts. */
+  onChunk?: StreamTextOnChunkCallback<Tools>;
+};
+
+/** Parameters accepted by {@link streamText}. */
+export type StreamTextParameters<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = TextCallOptions<Tools, OutputSpec> & {
+  /** Callback for every AI SDK 7 stream part, including lifecycle, boundary, terminal, text, reasoning, and tool parts. */
+  onChunk?: StreamTextOnChunkCallback<Tools>;
+  /** Callback when a stream error occurs */
+  onError?: StreamTextOnErrorCallback;
+  /** Callback when the stream completes. Receives the wrapped AI SDK `onEnd` event with `result`, `cost`, and `sources`. */
+  onEnd?: WrappedStreamTextOnEndCallback<Tools>;
+};
+
+/** Runtime image bytes or an object with optional media type. */
+export type GenerateImageInput =
+  | Buffer |
+  Uint8Array |
+  ArrayBuffer |
+  string |
+  {
+    data: Buffer | Uint8Array | ArrayBuffer | string;
+    mediaType?: string;
+  };
+
+type GenerateImageInputs =
+  | {
+    /** Runtime image inputs for image-to-image generation */
+    images: GenerateImageInput[];
+    /** Optional mask for image editing */
+    mask?: GenerateImageInput;
+  } |
+  {
+    images?: undefined;
+    mask?: never;
+  };
+
+/** Parameters accepted by {@link generateImage}. */
+export type GenerateImageParameters = PromptCallOptions & GenerateImageInputs & {
+  /** Abort signal for the request */
+  abortSignal?: AbortSignal;
+};
+
+/** Agent constructor options. */
+export type OutputAgentConstructorParameters<
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = PromptCallOptions & {
+  /** Structured output specification */
+  output?: OutputSpec;
+  /** AI SDK tools available during the reasoning loop */
+  tools?: CompatibleToolSet;
+  /** Caller stop condition; otherwise prompt `maxSteps` when tools exist */
+  stopWhen?: StopWhen;
+  /** Pluggable message store. Opt-in; stateless by default. */
+  messageStore?: MessageStore;
+};
+
+/** Agent {@link Agent.generate} options. */
+export type OutputAgentGenerateParameters = {
+  messages?: ModelMessage[];
+  abortSignal?: AbortSignal;
+  toolChoice?: ToolChoice<ToolSet>;
+};
+
+/** Agent {@link Agent.generateWithStreaming} options. Completion is the returned promise; use `onChunk` for progress. */
+export type OutputAgentGenerateWithStreamingParameters = OutputAgentGenerateParameters & {
+  onChunk?: StreamTextOnChunkCallback<ToolSet>;
+};
+
+/** Agent {@link Agent.stream} options. `onEnd` receives {@link WrappedStreamTextOnEndEvent} (`result`, `cost`, `sources`). */
+export type OutputAgentStreamParameters = OutputAgentGenerateWithStreamingParameters & {
+  onEnd?: WrappedStreamTextOnEndCallback<ToolSet>;
+  onError?: StreamTextOnErrorCallback;
+};
+
+/**
+ * One entry of `generateText().sources` after merge (tool URLs plus provider sources).
+ * Same item type as AI SDK `GenerateTextResult['sources']` (`sourceType: 'url' | 'document'`).
+ * `ai` does not export a named `Source` type.
+ */
+export type ExtractedSource =
+  AIGenerateTextResult<ToolSet, DefaultRuntimeContext, AnyAiOutput>['sources'][number];
+
+export type LLMGenerationUsageStatus = 'complete' | 'incomplete';
+
+/** Token usage reported for one normalized LLM usage component. `tools` counts billable tool calls, not tokens. */
+export interface LLMGenerationUsageItem {
+  group: 'input' | 'output' | 'tools';
+  label: string | null;
+  amount: number;
+}
+
+/** Normalized LLM token usage trace attribute. */
+export interface LLMGenerationUsage extends BaseAttribute {
+  type: 'llm:generation:usage';
+  providerId: string;
+  modelId: string;
+  input: number | null;
+  output: number | null;
+  total: number | null;
+  status: LLMGenerationUsageStatus;
+  items: LLMGenerationUsageItem[];
+}
+
+/** One priced usage line in the legacy LLM cost event. */
+export interface LLMUsageEventItem {
+  type: string;
+  ppm: number;
+  amount: number;
+  total: number;
+}
+
+/**
+ * Legacy `cost:llm:request` event payload.
+ *
+ * @deprecated Use the normalized `LLMGenerationUsage` and `LLMGenerationCost` payloads from the LLM generation metering event.
+ */
+export interface LLMUsageEvent {
+  type: 'llm:usage';
+  modelId: string;
+  usage: LLMUsageEventItem[];
+  readonly total: number;
+  readonly tokensUsed: number;
+}
+
+export type LLMGenerationCostItemStatus = 'ok' | 'fallback' | 'missing';
+export type LLMGenerationCostStatus = 'precise' | 'imprecise' | 'incomplete';
+export type LLMGenerationCostPricingFreshness = 'live' | 'cached' | 'stale' | 'snapshot';
+
+/** Cost calculated for one normalized LLM usage item. */
+export interface LLMGenerationCostItem {
+  group: 'input' | 'output' | 'tools';
+  label: string | null;
+  amount: number;
+  ppm: number | null;
+  total: number | null;
+  status: LLMGenerationCostItemStatus;
+}
+
+/** Normalized LLM generation cost trace attribute. */
+export interface LLMGenerationCost extends BaseAttribute {
+  type: 'llm:generation:cost';
+  providerId: string;
+  modelId: string;
+  input: number | null;
+  output: number | null;
+  tools: number | null;
+  total: number | null;
+  status: LLMGenerationCostStatus;
+  /** How current the rate table was. Absent on costs recorded before this field existed. */
+  pricingFreshness?: LLMGenerationCostPricingFreshness | null;
+  items: LLMGenerationCostItem[];
+}
+
+/** Payload emitted by the `llm:generation:metering` event. */
+export interface LLMGenerationMeteringEvent {
+  usage: LLMGenerationUsage;
+  cost: LLMGenerationCost | null;
+}
+
+/**
+ * `streamText` and agent `stream` `onEnd` event after the stream response wrapper: same as the AI SDK
+ * `onEnd` payload plus `result`, `cost`, and merged `sources`.
+ */
+export type WrappedStreamTextOnEndEvent<Tools extends ToolSet = ToolSet> =
+  Parameters<GenerateTextOnEndCallback<Tools, DefaultRuntimeContext>>[0] & {
+    result: string;
+    cost: LLMGenerationCost | null;
+    sources: ExtractedSource[];
+  };
+
+export type WrappedStreamTextOnEndCallback<Tools extends ToolSet = ToolSet> = (
+  event: WrappedStreamTextOnEndEvent<Tools>
+) => void | PromiseLike<void>;
+
+/**
+ * Result from generateText including full AI SDK response metadata.
+ * Extends AI SDK's GenerateTextResult with a unified `result` field.
+ * @typeParam Tools - The tools available for the model to call (preserves typing on steps)
+ */
+export type GenerateTextResult<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = AIGenerateTextResult<Tools, DefaultRuntimeContext, OutputSpec> & {
+  /** Unified field name alias for 'text' */
+  result: string;
+  /** Calculated cost for the LLM call; `null` when pricing data is not available */
+  cost: LLMGenerationCost | null;
+  /** Merged tool + provider sources (url and document). Always an array. */
+  sources: ExtractedSource[];
+};
+
+/** Completed result from {@link generateTextWithStreaming}. */
+export type GenerateTextWithStreamingResult<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> = GenerateTextResult<Tools, OutputSpec>;
+
+/** Result from generateImage including a unified `result` field pointing at the first image. */
+export type GenerateImageResult = AIGenerateImageResult & {
+  /** Unified field name alias for `image` */
+  result: AIGenerateImageResult['image'];
+  /** Calculated cost for the image generation call; `null` when pricing data is not available. */
+  cost: LLMGenerationCost | null;
+};
+
+/**
+ * Loads a prompt file and interpolates variables into its content.
+ *
+ * @param name - Name of the prompt file (without `.prompt` extension).
+ * @param variables - Variables to interpolate.
+ * @returns The loaded prompt object.
+ */
+export function loadPrompt(
+  name: string,
+  variables?: PromptVariables,
+  promptDir?: string
+): Prompt;
+
+/**
+ * Register a custom LLM provider for use in prompt files.
+ *
+ * @param name - Provider name (used in prompt config `provider` field)
+ * @param providerFn - Factory function that creates a model from a model name string
+ *
+ * @example
+ * ```ts
+ * import { createDeepSeek } from '@ai-sdk/deepseek';
+ * import { registerProvider } from '@outputai/core/llm';
+ *
+ * registerProvider('deepseek', createDeepSeek({ apiKey: '...' }));
+ * ```
+ */
+export function registerProvider(
+  name: string,
+  providerFn: ( modelName: string ) => unknown
+): void;
+
+/**
+ * Get the list of available provider names: built-in providers whose package is installed, plus custom registered ones.
+ *
+ * @returns Array of provider name strings
+ */
+export function getProviderNames(): string[];
+
+/**
+ * Use an LLM model to generate text.
+ *
+ * This function is a wrapper over the AI SDK's `generateText`.
+ * The prompt sets `model`, `messages`, generation settings, `maxSteps`, `skills`, and
+ * `providerOptions`. Pass either a prompt filename with optional `promptDir` / `variables`, or a
+ * loaded or custom {@link Prompt} object. Other call arguments are `tools`, `output`, `toolChoice`,
+ * `stopWhen`, and `abortSignal`.
+ *
+ * @param args - Generation arguments. See {@link GenerateTextParameters}.
+ * @returns AI SDK response with text and metadata.
+ */
+export function generateText<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+>(
+  args: GenerateTextParameters<Tools, OutputSpec>
+): Promise<GenerateTextResult<Tools, OutputSpec>>;
+
+/**
+ * Generate text over streaming transport and return a completed response.
+ *
+ * The stream is consumed internally. `onChunk` runs as parts arrive. Provider or
+ * transport errors reject the returned promise with the mapped error. Use {@link streamText}
+ * when you need `onEnd` / `onError` stream observers.
+ *
+ * @param args - Streaming arguments. See {@link GenerateTextWithStreamingParameters}.
+ * @returns Completed response with parsed output and generateText-compatible metadata.
+ */
+export function generateTextWithStreaming<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+>(
+  args: GenerateTextWithStreamingParameters<Tools, OutputSpec>
+): Promise<GenerateTextWithStreamingResult<Tools, OutputSpec>>;
+
+/**
+ * Use an LLM model to stream text generation.
+ *
+ * This function is a wrapper over the AI SDK's `streamText`.
+ * The prompt sets `model`, `messages`, generation settings, `maxSteps`, `skills`, and
+ * `providerOptions`. Pass either a prompt filename with optional `promptDir` / `variables`, or a
+ * loaded or custom {@link Prompt} object. Other call arguments match {@link generateText}, plus
+ * `onChunk`, `onEnd`, and `onError`. `onEnd` is wrapped to add `result`, `cost`, and merged
+ * `sources`.
+ *
+ * @param args - Streaming arguments. See {@link StreamTextParameters}.
+ * @returns AI SDK stream result with textStream, stream, and metadata promises.
+ */
+export function streamText<
+  Tools extends ToolSet = ToolSet,
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+>(
+  args: StreamTextParameters<Tools, OutputSpec>
+): AIStreamTextResult<Tools, DefaultRuntimeContext, OutputSpec>;
+
+/**
+ * Use an image model to generate images from a prompt filename or object.
+ *
+ * The prompt supplies `model`, instructions, `n`, `size`, `aspectRatio`, `seed`,
+ * `maxImagesPerCall`, and `providerOptions`. Pass either a prompt filename with optional
+ * `promptDir` / `variables`, or a loaded or custom {@link Prompt} object. Other call arguments are
+ * `images`, `mask`, and `abortSignal`.
+ *
+ * @param args - Image generation arguments. See {@link GenerateImageParameters}.
+ * @returns AI SDK image response with `result` aliasing the first image.
+ */
+export function generateImage(
+  args: GenerateImageParameters
+): Promise<GenerateImageResult>;
+
+/** Pluggable message store for multi-turn Agent interactions. */
+export interface MessageStore {
+  getMessages(): ModelMessage[] | Promise<ModelMessage[]>;
+  addMessages( messages: ModelMessage[] ): void | Promise<void>;
+}
+
+/**
+ * Agent wraps an internal AI SDK ToolLoopAgent with Output.ai prompt loading and validation.
+ *
+ * @example Workflow step - variables per call, stateless
+ * ```ts
+ * const reviewer = new Agent({
+ *   prompt: 'reviewer@v1',
+ *   output: aiSdk.Output.object({ schema: z.object({ summary: z.string() }) })
+ * });
+ * const result = await reviewer.generate();
+ * ```
+ *
+ * @example Interactive - fixed setup, message history
+ * ```ts
+ * const chatbot = new Agent({
+ *   prompt: 'chatbot@v1',
+ *   messageStore: { getMessages() { return []; }, addMessages() {} }
+ * });
+ * const r1 = await chatbot.generate({ messages: [{ role: 'user', content: 'Hello' }] });
+ * ```
+ */
+export declare class Agent<
+  OutputSpec extends AnyAiOutput = AnyAiOutput
+> {
+  constructor( params: OutputAgentConstructorParameters<OutputSpec> );
+
+  /**
+   * Run the agent and return when complete.
+   * Same augmented shape as {@link generateText}: `result`, `cost`, merged `sources`.
+   */
+  generate( options?: OutputAgentGenerateParameters ): Promise<GenerateTextResult<ToolSet, OutputSpec>>;
+
+  /**
+   * Run the agent over streaming transport and return a completed response.
+   * `onChunk` runs as parts arrive. Provider and transport errors reject with the mapped error.
+   * Use {@link Agent.stream} when you need `onEnd` / `onError` stream observers.
+   */
+  generateWithStreaming(
+    options?: OutputAgentGenerateWithStreamingParameters
+  ): Promise<GenerateTextWithStreamingResult<ToolSet, OutputSpec>>;
+
+  /**
+   * Stream the agent's response.
+   * `onEnd` receives {@link WrappedStreamTextOnEndEvent} (`result`, `cost`, `sources`), matching {@link streamText}.
+   */
+  stream( options?: OutputAgentStreamParameters ): Promise<
+    AIStreamTextResult<ToolSet, DefaultRuntimeContext, OutputSpec>
+  >;
+}

package/src/llm/index.js

@@ -0,0 +1,5 @@
+export { generateText, generateTextWithStreaming, streamText, generateImage } from './generate.js';
+export { Agent } from './agent.js';
+export { loadPrompt } from './prompt/loader.js';
+export { registerProvider, getProviderNames } from './ai_provider.js';
+export * as aiSdk from 'ai';

package/src/llm/prompt/content.js

@@ -0,0 +1,70 @@
+import { Role } from '../consts.js';
+import { decode } from './interpolations.js';
+import { FatalError } from '#errors';
+import { parseMarkup } from './markup/nodes.js';
+
+/** Merge two objects 2-level deep. */
+const mergeOptions = ( base = {}, extra = {} ) => {
+  const merged = { ...base };
+  for ( const [ namespace, options ] of Object.entries( extra ) ) {
+    merged[namespace] = { ...merged[namespace], ...options };
+  }
+  return merged;
+};
+
+/** Gets the options attribute from the message attributes */
+const extractOptions = attributes => {
+  const { options, ...unsupportedAttributes } = attributes;
+  if ( Object.keys( unsupportedAttributes ).length > 0 ) {
+    throw new FatalError( 'Message has unsupported attributes. The only supported attribute is "options".' );
+  }
+  if ( options === true ) {
+    throw new FatalError( 'Message "options" attribute must have a value.' );
+  }
+  const rawOptions = options?.trim();
+  return rawOptions ? rawOptions.split( /\s+/ ) : null;
+};
+
+/** Merge down messageOptions selected from a list */
+const resolveProviderOptions = ( options, messageOptions ) =>
+  options.reduce( ( result, option ) => {
+    if ( !messageOptions[option] ) {
+      throw new FatalError( `Message "options" attribute references unknown option "${option}" in \`config.messageOptions\`.` );
+    }
+    return mergeOptions( result, messageOptions[option] );
+  }, {} );
+
+const promptRoleSet = new Set( [ Role.SYSTEM, Role.USER, Role.ASSISTANT ] );
+
+/**
+ * Extract messages or instructions from prompt content. A leading role tag yields
+ * messages and null instructions; otherwise instructions are the decoded body.
+ */
+export const parseContent = ( content, messageOptions ) => {
+  const nodes = parseMarkup( content );
+
+  if ( nodes.length === 0 ) {
+    return { messages: [], instructions: decode( content.trim() ) };
+  }
+
+  const invalidRole = nodes.find( node => !promptRoleSet.has( node.tagName ) );
+  if ( invalidRole ) {
+    throw new FatalError( `Message has invalid role "${invalidRole.tagName}".` );
+  }
+
+  return {
+    messages: nodes.map( node => {
+      const options = extractOptions( node.attributes );
+      if ( options && Object.keys( messageOptions ?? {} ).length === 0 ) {
+        throw new FatalError( 'Message has "options" attribute but `config.messageOptions` is empty.' );
+      }
+      const providerOptions = options ? resolveProviderOptions( options, messageOptions ) : null;
+      return {
+        role: node.tagName.toLowerCase(),
+        content: decode( node.content.trim() ),
+        ...( providerOptions && { providerOptions } )
+      };
+    } ),
+    instructions: null
+  };
+};