@crvouga/mockingbird-service-openai

Local emulators. Real API contracts. Part of Mockingbird.

A wip, portable, entirely local OpenAI emulator for Chat Completions, function tool loops, Chat SSE streams, embeddings, models, files and staged uploads. Verified with unmodified openai 7.27.0, @ai-sdk/openai 4.0.83 and ai 7.0.127 over Node HTTP. It makes no inference calls and requires no vendor account or billed API key.

Install

bun add @crvouga/mockingbird-service-openai

Usage

The examples use the official [email protected] SDK.

import OpenAI from "openai"
import { createRuntime, DEFAULT_TOKEN } from "@crvouga/mockingbird-service-openai"

// Test setup: the emulator, scripted with the reply the test expects.
const emulator = createRuntime({
  scripts: [{
    kind: "chat",
    message: { role: "assistant", content: "Fixture answer" },
    usage: { prompt_tokens: 12, completion_tokens: 3, cached_tokens: 8 },
  }],
})

// The app's own OpenAI client. Only its fetch changes: requests reach the
// emulator in this process instead of api.openai.com.
const openai = new OpenAI({
  apiKey: DEFAULT_TOKEN,
  fetch: (url: RequestInfo | URL, init?: RequestInit) => emulator.fetch(new Request(url, init)),
})
const completion = await openai.chat.completions.create({
  model: "fixture-chat",
  messages: [{ role: "user", content: "Fixture question" }],
})
console.log(completion.choices[0]?.message.content) // "Fixture answer"
console.log(completion.usage?.total_tokens) // 15

For the Vercel AI SDK, also install @ai-sdk/[email protected] and [email protected], and point the provider's baseURL at a listening server. Use the explicit .chat() provider: the provider's default model uses the Responses API.

import { createOpenAI } from "@ai-sdk/openai"
import { generateText } from "ai"
import { createServer } from "@crvouga/mockingbird-service-openai/server"
import { DEFAULT_TOKEN } from "@crvouga/mockingbird-service-openai"

const server = await createServer({
  scripts: [{ kind: "chat", message: { role: "assistant", content: "Fixture answer" } }],
})
try {
  const provider = createOpenAI({ baseURL: `${server.url}/v1`, apiKey: DEFAULT_TOKEN })
  console.log((await generateText({ model: provider.chat("fixture-chat"), prompt: "Fixture", maxRetries: 0 })).text)
} finally {
  await server.close()
}

openai also accepts baseURL: server.url + "/v1" and the fixture apiKey. The CLI is mockingbird-openai serve --port 8813. createServer() defaults to an ephemeral port.

Routes and persisted behavior

DEFAULT_TOKEN is fixture-openai-token; tokens: [{ token, models?: string[] }] configures synthetic bearer credentials and optional model access. Invalid/missing credentials return 401, model-scope denial 403, unknown model/resource 404, malformed requests 400, with { error: { message, type, param, code } } and x-request-id. Default models are fixture-chat and fixture-embedding (three dimensions). models accepts { id, kind: "chat" | "embedding", dimensions?, created?, owned_by? }. No model name implies real inference or vendor availability.

Script selection consumes the first unconsumed script matching its kind and optional match: { model?, lastRole?, contentIncludes?, toolCallId? }. Unmatched scripts stay queued. ChatScript has kind: "chat", message: { role: "assistant", content: string | null, tool_calls?, refusal? }, optional finish_reason, usage, chunk_size and stream_delay_ms. Function calls use { id?, type: "function", function: { name, arguments: string } }; arguments must be valid JSON strings. Missing IDs are generated once and persist. Assistant null content is preserved with tools/refusal; a role: "tool" reply must refer to an earlier assistant call ID. Finish reasons are stop, tool_calls, length, content_filter. EmbeddingScript has kind: "embedding", vectors: number[][], optional match and usage.

Exact usage is { prompt_tokens, completion_tokens?, cached_tokens? } (nonnegative integers, cached at most prompt). Chat replies include total tokens and prompt_tokens_details.cached_tokens. Without a script, the local default is Fixture response; embeddings use deterministic hash vectors. Default token estimates count UTF-8 bytes divided by four, rounded up, with a minimum of one. These defaults are synthetic policies; supply usage/vectors for precise consumer tests. They do not approximate semantic inference or claim tokenizer parity.

SSE emits chat.completion.chunk JSON with indexed content/tool argument deltas, a final finish reason, and [DONE]. stream_options.include_usage: true adds a final empty-choices usage chunk; earlier chunks carry null usage. chunk_size counts Unicode characters; stream_delay_ms delays frame delivery for cancellation tests. Aborting/canceling closes the stream and clears its pending timer; a begun completion remains a created resource.

Only store: true completions are available through vendor reads. Chat ordering defaults to ascending creation time. Its local page bounds are default 20, maximum 100. File ordering defaults locally to descending creation time, limit/max 10,000; callers can set order explicitly. Stable insertion order breaks creation-time ties. after is the last resource ID; all pages expose first_id, last_id, has_more. Repeating prompt_cache_key, headers or request IDs does not deduplicate creations: the documented Chat contract does not promise mutation idempotency. Upload completion only accepts pending uploads; completed/cancelled/expired uploads reject further mutation.

File multipart bodies use purpose and file. Supported purposes are assistants, batch, fine-tune, vision, user_data; staged Uploads use the first four. Batch files expire after 30 days. Optional expires_after[anchor]=created_at and expires_after[seconds] accept 3,600–2,592,000 seconds. Staged Upload completion creates the file atomically in caller part order, verifies byte count/checksum, and never publishes partial data. maxFileBytes defaults to 20 MiB and bounds files/uploads/parts locally; it is not a production quota.

All records use SQLite Collections and IdSequence; lifecycle timestamps/expiry use the shared clock. Each namespace receives constructor scripts, models, files fixtures; reset restores them. Files accept { id?, filename, purpose, bytes: string | number[], expires_at? }. Use x-mockingbird-namespace, /__admin/ns/{namespace}/v1/..., or shared credential registration for SDKs. Timeline branches/checkpoints reuse the shared runtime and keep their state isolated.

Controls, failures and privacy

DEFAULT_ADMIN_KEY is fixture-openai-admin. Admin data routes require x-mockingbird-admin-key; configure a nonempty adminKey to replace it. A custom adminPrefix relocates all controls and the namespace path carrier. Shared clock, fault, reset, journal, state, credential, metrics and Timeline routes remain available.

Normal scripts reject unknown fields and malformed response shapes atomically. Raw-fault controls are the sole escape hatch. fingerprint(body) computes the exact JSON-serialization SHA-256 hash for request assertions; property order matters. No incoming prompts/tool results are retained. Scripts, replies, file/part bytes and raw fault bodies are AES-GCM encrypted in SQLite with a private runtime key and logical namespace binding. Generic state snapshots show ciphertext and metadata, never plaintext bodies or keys. Vendor resource reads decrypt the requested output. The shared request journal/logs contain metadata only; API keys are never logged.

Presets fire once: rate_limited (429, Retry-After and retry-after-ms), server_error (500), service_unavailable (503), network_reset, invalid_json, malformed_stream, content_refusal, slow_response (50 ms before dispatch). Canned errors/drop do not consume scripts. The reported raw client retries only network errors, 429 and 5xx. Official OpenAI SDK additionally retries 408/409 by its own policy; configure maxRetries when asserting attempts. Transport latency uses wall time, while resource lifecycle uses the emulator clock.

API

Root exports OpenAIAPI, createRuntime, document, supportedOperationIds, DEFAULT_MODELS, DEFAULT_TOKEN, DEFAULT_ADMIN_KEY, OPENAI_NAMESPACE, OPENAI_PRESETS, fingerprint, validateScript, createVaultKey, vendorError, and exported fixture/script/options/runtime types. The API exposes fetch, reset, ensureSeeded, queue, queueRaw, seedFile, state, app, sqlite. Node ./server exports createServer, DEFAULT_PORT, serveTarget and server types. Optional vaultKey is caller-supplied private key material, never persisted in state.

Oracle and verification

The contract follows official Chat creation, function calling, stored Chat listing, embeddings, models, files, file listing, Uploads, completion, and errors.

bun test verifies unmodified SDKs over Node HTTP, the reported nonstream tool loop with exact retry counts, SSE/abort handling, exact bytes and staged atomicity, namespaces/reset/Timeline, privacy, pagination, every preset, every enabled JSON operation via independent-instance walks, and a deliberately divergent instance. Multipart/binary operations have served acceptance tests. bun run parity exits 2: repository policy prohibits billed inference. No live OpenAI result is claimed; official documentation and local SDK execution are the oracle evidence.

Deliberately not modelled

Responses API, realtime/audio/image/batch/fine-tuning APIs, built-in hosted tools, multimodal content interpretation, real inference/tokenization, account billing, production quotas, production opaque IDs/cursor encodings and undocumented request-ID deduplication. This package never calls OpenAI. Encrypted persistence is private runtime state, not a production key vault.