@copilotkit/aimock 1.13.0 → 1.14.1

package/fixtures/examples/langchain/agent-loop.json

@@ -0,0 +1,27 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "plan a trip", "sequenceIndex": 0 },
+      "response": {
+        "content": "I'll help plan your trip. Let me look up some options."
+      }
+    },
+    {
+      "match": { "userMessage": "plan a trip", "sequenceIndex": 1 },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "search_flights",
+            "arguments": { "origin": "SFO", "dest": "NRT" }
+          }
+        ]
+      }
+    },
+    {
+      "match": { "userMessage": "plan a trip", "sequenceIndex": 2 },
+      "response": {
+        "content": "I found 3 flights from SFO to Tokyo Narita. The best option is..."
+      }
+    }
+  ]
+}

package/fixtures/examples/llamaindex/aimock-config.json

@@ -0,0 +1,62 @@
+{
+  "llm": {
+    "fixtures": "./rag-pipeline.json"
+  },
+  "vector": {
+    "collections": [
+      {
+        "name": "knowledge-base",
+        "dimension": 3,
+        "vectors": [
+          {
+            "id": "doc-gravity",
+            "values": [0.9, 0.1, 0.05],
+            "metadata": {
+              "source": "physics.pdf",
+              "page": 12,
+              "text": "Gravity is a fundamental force of nature that attracts objects with mass toward one another."
+            }
+          },
+          {
+            "id": "doc-orbits",
+            "values": [0.75, 0.3, 0.15],
+            "metadata": {
+              "source": "physics.pdf",
+              "page": 45,
+              "text": "Orbital mechanics describes the motion of planets and satellites under gravitational influence."
+            }
+          },
+          {
+            "id": "doc-tides",
+            "values": [0.6, 0.5, 0.2],
+            "metadata": {
+              "source": "physics.pdf",
+              "page": 78,
+              "text": "Tidal forces result from the differential gravitational pull of the Moon and Sun on Earth's oceans."
+            }
+          }
+        ],
+        "queryResults": [
+          {
+            "id": "doc-gravity",
+            "score": 0.97,
+            "metadata": {
+              "source": "physics.pdf",
+              "page": 12,
+              "text": "Gravity is a fundamental force of nature that attracts objects with mass toward one another."
+            }
+          },
+          {
+            "id": "doc-orbits",
+            "score": 0.82,
+            "metadata": {
+              "source": "physics.pdf",
+              "page": 45,
+              "text": "Orbital mechanics describes the motion of planets and satellites under gravitational influence."
+            }
+          }
+        ]
+      }
+    ]
+  }
+}

package/fixtures/examples/llamaindex/rag-pipeline.json

@@ -0,0 +1,34 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "What is gravity?" },
+      "response": {
+        "content": "Based on the retrieved documents, gravity is a fundamental force of nature that attracts objects with mass toward one another. It is described by Newton's law of universal gravitation and Einstein's general theory of relativity."
+      }
+    },
+    {
+      "match": { "userMessage": "Summarize the document" },
+      "response": {
+        "content": "The document covers three main topics: gravitational force, orbital mechanics, and tidal effects. It explains how gravity governs planetary motion and influences ocean tides on Earth."
+      }
+    },
+    {
+      "match": { "inputText": "What is gravity?", "endpoint": "embedding" },
+      "response": {
+        "embedding": [0.9, 0.1, 0.05]
+      }
+    },
+    {
+      "match": { "inputText": "Gravity is a fundamental force", "endpoint": "embedding" },
+      "response": {
+        "embedding": [0.88, 0.12, 0.07]
+      }
+    },
+    {
+      "match": { "inputText": "orbital mechanics and planetary motion", "endpoint": "embedding" },
+      "response": {
+        "embedding": [0.75, 0.3, 0.15]
+      }
+    }
+  ]
+}

package/fixtures/examples/mastra/agent-workflow.json

@@ -0,0 +1,32 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "plan a trip", "sequenceIndex": 0 },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "search_flights",
+            "arguments": { "origin": "SFO", "destination": "NRT", "date": "2025-03-15" }
+          }
+        ]
+      }
+    },
+    {
+      "match": { "userMessage": "plan a trip", "sequenceIndex": 1 },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "search_hotels",
+            "arguments": { "city": "Tokyo", "checkIn": "2025-03-15", "checkOut": "2025-03-22" }
+          }
+        ]
+      }
+    },
+    {
+      "match": { "userMessage": "plan a trip", "sequenceIndex": 2 },
+      "response": {
+        "content": "I found a great itinerary for your Tokyo trip!\n\n**Flight:** SFO → NRT on March 15, departing 11:30 AM (United UA837) — $890 round trip\n\n**Hotel:** Hotel Gracery Shinjuku, March 15–22 — $185/night\n\nWould you like me to book these, or would you prefer different options?"
+      }
+    }
+  ]
+}

package/fixtures/examples/pydanticai/structured-output.json

@@ -0,0 +1,15 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "Weather" },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "final_result",
+            "arguments": { "city": "SF", "temp": 72, "unit": "fahrenheit" }
+          }
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "description": "Mock infrastructure for AI application testing — LLM APIs, image generation, text-to-speech, transcription, video generation, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. One package, one port, zero dependencies.",
   "license": "MIT",
   "keywords": [
@@ -35,6 +35,7 @@
     "embeddings",
     "copilotkit"
   ],
+  "homepage": "https://aimock.copilotkit.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/CopilotKit/aimock"

package/skills/write-fixtures/SKILL.md

@@ -7,7 +7,7 @@ description: Use when writing test fixtures for @copilotkit/aimock — mock LLM
 
 ## What aimock Is
 
-aimock is a zero-dependency mock LLM server. Fixture-driven. Multi-provider (OpenAI, Anthropic, Gemini, AWS Bedrock, Azure OpenAI, Vertex AI, Ollama, Cohere). Runs a real HTTP server on a real port — works across processes, unlike MSW-style interceptors. WebSocket support for OpenAI Responses/Realtime and Gemini Live APIs. Chaos testing and Prometheus metrics.
+aimock is a zero-dependency mock infrastructure for AI apps. Fixture-driven. Multi-provider (OpenAI, Anthropic, Gemini, AWS Bedrock, Azure OpenAI, Vertex AI, Ollama, Cohere). Multimedia endpoints (image generation, text-to-speech, audio transcription, video generation). MCP, A2A, AG-UI, and vector DB mocking. Runs a real HTTP server on a real port — works across processes, unlike MSW-style interceptors. WebSocket support for OpenAI Responses/Realtime and Gemini Live APIs. Record-and-replay for all endpoints including multimedia. Chaos testing and Prometheus metrics.
 
 ## Core Mental Model
 
@@ -19,19 +19,20 @@ aimock is a zero-dependency mock LLM server. Fixture-driven. Multi-provider (Ope
 
 ## Match Field Reference
 
-| Field            | Type                                      | Matches Against                                                               |
-| ---------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
-| `userMessage`    | `string`                                  | Substring of last `role: "user"` message text                                 |
-| `userMessage`    | `RegExp`                                  | Pattern test on last `role: "user"` message text                              |
-| `inputText`      | `string`                                  | Substring of embedding input text (concatenated if multiple inputs)           |
-| `inputText`      | `RegExp`                                  | Pattern test on embedding input text                                          |
-| `toolName`       | `string`                                  | Exact match on any tool in request's `tools[]` array (by `function.name`)     |
-| `toolCallId`     | `string`                                  | Exact match on `tool_call_id` of last `role: "tool"` message                  |
-| `model`          | `string`                                  | Exact match on `req.model`                                                    |
-| `model`          | `RegExp`                                  | Pattern test on `req.model`                                                   |
-| `responseFormat` | `string`                                  | Exact match on `req.response_format.type` (`"json_object"`, `"json_schema"`)  |
-| `sequenceIndex`  | `number`                                  | Matches only when this fixture's match count equals the given index (0-based) |
-| `predicate`      | `(req: ChatCompletionRequest) => boolean` | Custom function — full access to request                                      |
+| Field            | Type                                      | Matches Against                                                                                         |
+| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `userMessage`    | `string`                                  | Substring of last `role: "user"` message text                                                           |
+| `userMessage`    | `RegExp`                                  | Pattern test on last `role: "user"` message text                                                        |
+| `inputText`      | `string`                                  | Substring of embedding input text (concatenated if multiple inputs)                                     |
+| `inputText`      | `RegExp`                                  | Pattern test on embedding input text                                                                    |
+| `toolName`       | `string`                                  | Exact match on any tool in request's `tools[]` array (by `function.name`)                               |
+| `toolCallId`     | `string`                                  | Exact match on `tool_call_id` of last `role: "tool"` message                                            |
+| `model`          | `string`                                  | Exact match on `req.model`                                                                              |
+| `model`          | `RegExp`                                  | Pattern test on `req.model`                                                                             |
+| `responseFormat` | `string`                                  | Exact match on `req.response_format.type` (`"json_object"`, `"json_schema"`)                            |
+| `sequenceIndex`  | `number`                                  | Matches only when this fixture's match count equals the given index (0-based)                           |
+| `endpoint`       | `string`                                  | Restrict to endpoint type: `"chat"`, `"image"`, `"speech"`, `"transcription"`, `"video"`, `"embedding"` |
+| `predicate`      | `(req: ChatCompletionRequest) => boolean` | Custom function — full access to request                                                                |
 
 **AND logic**: all specified fields must match. Empty match `{}` = catch-all.
 
@@ -50,12 +51,18 @@ Multi-part content (e.g., `[{type: "text", text: "hello"}]`) is automatically ex
 ### Tool Calls
 
 ```typescript
+// Preferred: object form (auto-stringified by the fixture loader)
+{
+  toolCalls: [{ name: "get_weather", arguments: { city: "SF" } }];
+}
+
+// Also accepted: JSON string form (backward compatible)
 {
   toolCalls: [{ name: "get_weather", arguments: '{"city":"SF"}' }];
 }
 ```
 
-**`arguments` MUST be a JSON string**, not an object. This is the #1 mistake.
+**Both object and string forms are accepted** for `arguments`. The fixture loader auto-stringifies objects via `JSON.stringify()`. Object form is preferred for readability.
 
 ### Embedding
 
@@ -67,6 +74,49 @@ Multi-part content (e.g., `[{type: "text", text: "hello"}]`) is automatically ex
 
 The embedding vector is returned for each input in the request. If no embedding fixture matches, deterministic embeddings are auto-generated from the input text hash — you only need fixtures when you want specific vectors.
 
+### Image
+
+<!-- prettier-ignore -->
+```typescript
+// Single image
+{
+  image: {
+    url: "https://example.com/generated.png"
+  }
+}
+// Multiple images
+{
+  images: [{ url: "https://example.com/1.png" }, { b64Json: "iVBOR..." }]
+}
+```
+
+Use `match: { endpoint: "image" }` to prevent cross-matching with chat fixtures.
+
+### Speech (TTS)
+
+```typescript
+{ audio: "base64-encoded-audio-data" }
+// With explicit format (default: mp3)
+{ audio: "base64-data", format: "opus" }
+```
+
+### Transcription
+
+```typescript
+// Simple
+{ transcription: { text: "Hello world" } }
+// Verbose with timestamps
+{ transcription: { text: "Hello world", language: "en", duration: 2.5, words: [...], segments: [...] } }
+```
+
+### Video
+
+```typescript
+{ video: { id: "vid-1", status: "completed", url: "https://example.com/video.mp4" } }
+```
+
+Video uses async polling — `POST /v1/videos` creates, `GET /v1/videos/{id}` checks status.
+
 ### Error
 
 ```typescript
@@ -104,7 +154,7 @@ The most common pattern. Fixture 1 triggers the tool call, fixture 2 handles the
 ```typescript
 // Step 1: User asks about weather → LLM calls tool
 mock.onMessage("weather", {
-  toolCalls: [{ name: "get_weather", arguments: '{"city":"SF"}' }],
+  toolCalls: [{ name: "get_weather", arguments: { city: "SF" } }],
 });
 
 // Step 2: Tool result comes back → LLM responds with text
@@ -154,7 +204,7 @@ mock.addFixture({
 // First call returns tool call, second returns text
 mock.on(
   { userMessage: "status", sequenceIndex: 0 },
-  { toolCalls: [{ name: "check_status", arguments: "{}" }] },
+  { toolCalls: [{ name: "check_status", arguments: {} }] },
 );
 mock.on({ userMessage: "status", sequenceIndex: 1 }, { content: "All systems operational." });
 ```
@@ -189,7 +239,7 @@ mock.addFixture({
       return typeof sys === "string" && sys.includes("Flights found: false");
     },
   },
-  response: { toolCalls: [{ name: "search_flights", arguments: "{}" }] },
+  response: { toolCalls: [{ name: "search_flights", arguments: {} }] },
 });
 ```
 
@@ -263,6 +313,17 @@ mock.nextRequestError(429, { message: "Rate limited", type: "rate_limit_error" }
       "match": { "userMessage": "hello" },
       "response": { "content": "Hi!" }
     },
+    {
+      "match": { "userMessage": "weather" },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "get_weather",
+            "arguments": { "city": "SF", "units": "fahrenheit" }
+          }
+        ]
+      }
+    },
     {
       "match": { "inputText": "search query" },
       "response": { "embedding": [0.1, 0.2, 0.3] }
@@ -275,6 +336,8 @@ mock.nextRequestError(429, { message: "Rate limited", type: "rate_limit_error" }
 }
 ```
 
+**JSON auto-stringify**: In JSON fixture files, `arguments` and `content` can be objects — the loader auto-stringifies them with `JSON.stringify()`. The escaped-string form (`"{\"city\":\"SF\"}"`) still works but objects are preferred for readability.
+
 JSON files cannot use `RegExp` or `predicate` — those are code-only features. `streamingProfile` is supported in JSON fixture files.
 
 Load with `mock.loadFixtureFile("./fixtures/greetings.json")` or `mock.loadFixtureDir("./fixtures/")`.
@@ -309,12 +372,71 @@ All providers share the same fixture pool — write fixtures once, they work for
 | `WS /v1/responses`                                                                       | OpenAI        | WebSocket |
 | `WS /v1/realtime`                                                                        | OpenAI        | WebSocket |
 | `WS /ws/google.ai...BidiGenerateContent`                                                 | Gemini Live   | WebSocket |
+| `POST /v1/images/generations`                                                            | OpenAI        | HTTP      |
+| `POST /v1beta/models/{model}:predict`                                                    | Gemini Imagen | HTTP      |
+| `POST /v1/audio/speech`                                                                  | OpenAI        | HTTP      |
+| `POST /v1/audio/transcriptions`                                                          | OpenAI        | HTTP      |
+| `POST /v1/videos`                                                                        | OpenAI        | HTTP      |
+| `GET /v1/videos/{id}`                                                                    | OpenAI        | HTTP      |
+
+## Response Template Overrides
+
+Fixture responses can include optional override fields to control auto-generated envelope values. These are merged into the provider-specific response format (OpenAI, Claude, Gemini, Responses API).
+
+| Field               | Type   | Default                   | Description                                                                                                                                                                                                                                                                |
+| ------------------- | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                | string | auto-generated            | Override response ID (e.g., `chatcmpl-custom`)                                                                                                                                                                                                                             |
+| `created`           | number | `Date.now()/1000`         | Override Unix timestamp                                                                                                                                                                                                                                                    |
+| `model`             | string | echoes request            | Override model name in response                                                                                                                                                                                                                                            |
+| `usage`             | object | zeroed                    | Override token counts: `{ prompt_tokens, completion_tokens, total_tokens }`. OpenAI Chat includes usage in response body; Responses API uses `response.usage`. When omitted, auto-computed from content length                                                             |
+| `finishReason`      | string | `"stop"` / `"tool_calls"` | Override finish reason. Mappings: `stop` -> `end_turn` (Claude), `STOP` (Gemini); `tool_calls` -> `tool_use` (Claude), `FUNCTION_CALL` (Gemini); `length` -> `max_tokens` (Claude), `MAX_TOKENS` (Gemini); `content_filter` -> `SAFETY` (Gemini), `failed` (Responses API) |
+| `role`              | string | `"assistant"`             | Override message role                                                                                                                                                                                                                                                      |
+| `systemFingerprint` | string | (omitted)                 | Add `system_fingerprint` to response                                                                                                                                                                                                                                       |
+
+### Example
+
+```typescript
+mock.onMessage("hello", {
+  content: "Hi!",
+  model: "gpt-4-turbo-2024-04-09",
+  usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+  systemFingerprint: "fp_abc123",
+});
+```
+
+### In JSON fixtures
+
+```json
+{
+  "match": { "userMessage": "hello" },
+  "response": {
+    "content": "Hi!",
+    "model": "gpt-4-turbo-2024-04-09",
+    "usage": { "prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15 },
+    "systemFingerprint": "fp_abc123"
+  }
+}
+```
+
+These fields map correctly across all provider formats — for example, `finishReason: "stop"` becomes `finish_reason: "stop"` in OpenAI, `stop_reason: "end_turn"` in Claude, and `finishReason: "STOP"` in Gemini.
+
+## Provider Support Matrix
+
+| Feature              | OpenAI Chat | OpenAI Responses | Claude | Gemini | Bedrock | Azure | Ollama | Cohere |
+| -------------------- | ----------- | ---------------- | ------ | ------ | ------- | ----- | ------ | ------ |
+| Text                 | Yes         | Yes              | Yes    | Yes    | Yes     | Yes   | Yes    | Yes    |
+| Tool Calls           | Yes         | Yes              | Yes    | Yes    | Yes     | Yes   | Yes    | Yes    |
+| Content + Tool Calls | Yes         | Yes              | Yes    | Yes    | Yes     | Yes   | Yes    | Yes    |
+| Streaming            | SSE         | SSE              | SSE    | SSE    | Binary  | SSE   | NDJSON | SSE    |
+| Reasoning            | Yes         | Yes              | Yes    | Yes    | Yes     | Yes   | --     | --     |
+| Web Searches         | --          | Yes              | --     | --     | --      | --    | --     | --     |
+| Response Overrides   | Yes         | Yes              | Yes    | Yes    | --      | Yes   | --     | --     |
 
 ## Critical Gotchas
 
 1. **Order matters** — first match wins. Specific fixtures before general ones. Use `prependFixture()` to force priority.
 
-2. **`arguments` must be a JSON string** — `"arguments": "{\"key\":\"value\"}"` not `"arguments": {"key":"value"}`. The type system enforces this but JSON fixtures can get it wrong silently.
+2. **`arguments` accepts both objects and strings** — `"arguments": {"key":"value"}` (preferred, auto-stringified) or `"arguments": "{\"key\":\"value\"}"` (legacy). The same applies to `content` fields that contain JSON. The fixture loader detects `typeof === "object"` and calls `JSON.stringify()` automatically.
 
 3. **Latency is per-chunk, not total** — `latency: 100` means 100ms between each SSE chunk, not 100ms total response time. Similarly, `truncateAfterChunks` and `disconnectAfterMs` are for simulating stream interruptions (added in v1.3.0).
 
@@ -559,6 +681,10 @@ const mock = await LLMock.create({ port: 0 }); // creates + starts in one call
 | `onSearch(pattern, results)`            | Match search requests by query              |
 | `onRerank(pattern, results)`            | Match rerank requests by query              |
 | `onModerate(pattern, result)`           | Match moderation requests by input          |
+| `onImage(pattern, response)`            | Match image generation by prompt            |
+| `onSpeech(pattern, response)`           | Match TTS by input text                     |
+| `onTranscription(response)`             | Match audio transcription                   |
+| `onVideo(pattern, response)`            | Match video generation by prompt            |
 | `mount(path, handler)`                  | Mount a Mountable (VectorMock, etc.)        |
 | `url` / `baseUrl`                       | Server URL (throws if not started)          |
 | `port`                                  | Server port number                          |
@@ -567,19 +693,19 @@ Sequential responses use `on()` with `sequenceIndex` in the match — there is n
 
 ## Record-and-Replay (VCR Mode)
 
-llmock supports a VCR-style record-and-replay workflow: unmatched requests are proxied to real provider APIs, and the responses are saved as standard llmock fixture files for deterministic replay.
+aimock supports a VCR-style record-and-replay workflow for ALL endpoints including multimedia (image, TTS, transcription, video): unmatched requests are proxied to real provider APIs, and the responses are saved as standard aimock fixture files for deterministic replay. Binary TTS responses are base64-encoded with format derived from Content-Type. Multimedia fixtures automatically include `endpoint` in their match criteria for correct routing on replay.
 
 ### CLI usage
 
 ```bash
 # Record mode: proxy unmatched requests to real OpenAI and Anthropic APIs
-llmock --record \
+aimock --record \
   --provider-openai https://api.openai.com \
   --provider-anthropic https://api.anthropic.com \
   -f ./fixtures
 
 # Strict mode: fail on unmatched requests (no proxying, no catch-all 404)
-llmock --strict -f ./fixtures
+aimock --strict -f ./fixtures
 ```
 
 - `--record` enables proxy-on-miss. Requires at least one `--provider-*` flag.