CopilotKit aimock

The aimock suite provides specialized mocks for various parts of the AI application stack. You can run them all on a single port using a configuration file or compose them programmatically.

To run the full suite from a config file:

npx @copilotkit/aimock --config aimock.json

When designing multi-turn conversations (e.g., Human-in-the-loop or tool-calling flows), choose a matching strategy based on your deployment environment.

Recommendation: Prefer stateless approaches (turnIndex, hasToolResult, toolResultContains) for shared aimock instances (e.g., deployed via Docker) to avoid issues with concurrency. Use sequenceIndex only in isolated, single-client unit tests.

Avoid these common pitfalls when configuring aimock:

1. Order Matters: The first matching fixture wins. Use prependFixture() to ensure specific fixtures take priority over general ones.
2. JSON Arguments: arguments in tool calls can be objects (preferred, auto-stringified) or strings. The fixture loader handles typeof === "object" automatically.
3. Latency: latency: 100 defines the delay between SSE chunks, not the total response time.
4. Tool Result Loops: Matching on userMessage for tool results will cause an infinite loop because the client sends the same conversation history. Always use a predicate checking role === "tool" for tool results.
5. Sequence Counts: Use resetMatchCounts() to reset counts between tests without clearing the fixtures. Use reset() only if you want to clear the entire fixture pool.
6. Embeddings: If no fixture matches an embedding request, aimock automatically generates deterministic vectors based on the input text hash.

aimock is a fixture-driven, zero-dependency mock infrastructure for AI applications. It operates by running a real HTTP server on a real port, allowing it to work across processes (unlike MSW-style interceptors).

Key concepts include:

• Fixtures: A combination of match criteria and the corresponding response.
• First-match-wins: The order of fixtures in your configuration matters; the first fixture that matches the incoming request is the one used.
• Unified Provider Pool: All providers (OpenAI, Anthropic, etc.) share a single fixture pool because provider adapters normalize requests to a standard ChatCompletionRequest format.
• Live Fixtures: Mutations made to fixtures after calling start() take effect immediately.
• Sequential Responses: You can provide multiple responses for the same match criteria using sequenceIndex, which tracks the match count per fixture.

The model-family sync follows a three-step process to keep the model-registry.ts up to date:

1. Sync (scripts/drift-sync.ts): Fetches live /models listings from providers and compares them against src/__tests__/drift/model-registry.ts.
   • Mechanical Removal: If a classified family is absent from live listings and has zero remaining aimock references, it is automatically marked for removal.
   • Human Decision Required: If a family is still referenced but deprecated, or if a new/unclassified family is found, the system never auto-edits the registry. Instead, it writes a note file in drift-proposals/ and routes the task to a human.
2. Gate (scripts/drift-sync-check.ts): Re-verifies any mechanical edits. It uses a changed-file allowlist (limited to model-registry.ts data literals and drift-proposals/ notes) and checksum-pinning to ensure safety.
3. PR (Pull Request): The workflow opens a PR for human review. There are two types:
   • ok-applied: A successful mechanical registry edit. A human reviews the diff and merges.
   • needs-human: A routed decision. The workflow pushes a drift-needs-human/* branch containing the proposal note. To approve a new family, a human must set the note's Decision: include line and merge the PR. The next sync run will then see the approved note on main and create an ok-applied PR to update the registry.