Core

const AI: Protocol<
  AiDef.Context,
  [config: AiDef.Config],
  AiDef.Actions
>

// AI.actions run against the installed AI implementation (e.g. OpenAI):
AI.actions.chat(
  messages: AiDef.Message[],
  options?: AiDef.ChatOptions,
): Future<AiDef.ChatResult>
AI.actions.chatStream(
  messages: AiDef.Message[],
  options?: AiDef.ChatOptions,
): Future<Stream<AiDef.ChatStreamChunk, AiDef.StreamClose>>
AI.actions.embed(
  input: string | string[],
  options?: AiDef.EmbedOptions,
): Future<number[][]>
AI.actions.tts(text: string, options?: AiDef.TtsOptions): Future<Uint8Array>
AI.actions.ttsStream(
  text: string,
  options?: AiDef.TtsOptions,
): Future<Stream<Uint8Array, AiDef.StreamClose>>
AI.actions.stt(audio: Uint8Array | Blob, options?: AiDef.SttOptions): Future<string>
AI.actions.sttStream(
  audio: Uint8Array | Blob,
  options?: AiDef.SttOptions,
): Future<Stream<string, AiDef.StreamClose>>

type AiDef = Plugin<AiDef.Context, [config: AiDef.Config], AiDef.Actions>

interface Config {
  /** API key sent as `Authorization: Bearer <apiKey>`. */
  apiKey: string
  /** Base URL of the OpenAI-compatible API. Defaults to `https://api.openai.com/v1`. */
  baseURL?: string
  /** Default model used for chat completions when a call omits `model`. */
  model?: string
  /** Extra headers merged into every request. */
  headers?: Record<string, string>
}

interface Context {
  apiKey: string
  baseURL: string
  model: string | undefined
  headers: Record<string, string>
}

type Role = 'system' | 'user' | 'assistant' | 'tool'

interface Message {
  role: Role
  content: string
  /** Optional name (e.g. the tool name for `role: 'tool'`). */
  name?: string
  /** Tool calls the assistant requested (set on `role: 'assistant'` messages). */
  toolCalls?: ToolCall[]
  /** The `ToolCall.id` this message answers (set on `role: 'tool'` result messages). */
  toolCallId?: string
}

interface ChatOptions {
  model?: string
  temperature?: number
  topP?: number
  maxTokens?: number
  stop?: string | string[]
  frequencyPenalty?: number
  presencePenalty?: number
  seed?: number
  /** Tools (functions) the model may call. */
  tools?: Tool[]
  /** How the model should pick tools. */
  toolChoice?: ToolChoice
  /** Constrain the model's output (free text, a JSON object, or a named JSON Schema). */
  responseFormat?: ResponseFormat
  /** Arbitrary extra body fields merged last (escape hatch for provider-specific params). */
  extra?: Record<string, unknown>
}

interface ChatResult {
  /** The full assistant message returned by the provider. */
  message: Message
  /** Convenience alias for `message.content`. */
  text: string
  model: string
  finishReason: string | undefined
  usage: Usage | undefined
  /** Tool calls the model requested, or `undefined` when none. */
  toolCalls: ToolCall[] | undefined
}

interface Usage {
  promptTokens: number | undefined
  completionTokens: number | undefined
  totalTokens: number | undefined
}

interface Tool {
  type: 'function'
  function: {
    name: string
    description?: string
    parameters?: Record<string, unknown>
  }
}

interface ToolCall {
  id: string
  name: string
  arguments: string
}

type ToolChoice = 'auto' | 'none' | 'required' | { name: string }

type ResponseFormat =
  | { type: 'text' }
  | { type: 'json_object' }
  | {
      type: 'json_schema'
      jsonSchema: { name: string; schema: Record<string, unknown>; strict?: boolean }
    }

interface ChatStreamChunk {
  delta: string
  toolCalls?: ToolCallDelta[]
  finishReason?: string
  usage?: Usage
}

interface ToolCallDelta {
  index: number
  id?: string
  name?: string
  /** Partial JSON fragment of the tool call's arguments — concatenate across chunks by `index`. */
  arguments?: string
}

interface EmbedOptions {
  model?: string
  dimensions?: number
  extra?: Record<string, unknown>
}

interface TtsOptions {
  model?: string
  voice?: string
  /** Output format, e.g. `mp3`, `wav`, `opus`. */
  format?: string
  speed?: number
  extra?: Record<string, unknown>
}

interface SttOptions {
  model?: string
  /** ISO-639-1 language hint. */
  language?: string
  prompt?: string
  /** File name reported to the provider for the multipart upload. */
  filename?: string
  /** MIME type of the audio blob. */
  contentType?: string
  extra?: Record<string, string>
}

type StreamClose = true | Result.Failure<unknown>

type Error = (typeof AiErrors)[keyof typeof AiErrors] | FetchDef.Error

const AiErrors: {
  Request: 'ai.request'
  Auth: 'ai.auth'
  RateLimit: 'ai.rate-limit'
  BadResponse: 'ai.bad-response'
  Unsupported: 'ai.unsupported'
}

const AI_SUBTYPE: unique symbol // Symbol.for('ozaco:ai')

const DEFAULT_BASE_URL = 'https://api.openai.com/v1'

const DEFAULT_CHAT_MODEL = 'gpt-4o-mini'

const DEFAULT_EMBED_MODEL = 'text-embedding-3-small'

const DEFAULT_TTS_MODEL = 'tts-1'

const DEFAULT_TTS_VOICE = 'alloy'

const DEFAULT_STT_MODEL = 'whisper-1'

const SSE_DONE = '[DONE]'