VectorMock

Mock vector database server for testing RAG pipelines and embedding-based retrieval. Supports Pinecone, Qdrant, and ChromaDB API formats with collection management, upsert, query, and delete operations.

Quick Start

Standalone mode typescript 
import { VectorMock } from "@copilotkit/aimock";

const vector = new VectorMock();

vector.addCollection("docs", { dimension: 1536 });
vector.onQuery("docs", [
  { id: "doc-1", score: 0.95, metadata: { title: "Getting Started" } },
  { id: "doc-2", score: 0.87, metadata: { title: "API Reference" } },
]);

const url = await vector.start();
// Point your vector DB client at `url`

Mounted Mode

Mount VectorMock onto an LLMock server to share a single port with LLM mocking and other services:

Mount on LLMock typescript 
import { LLMock, VectorMock } from "@copilotkit/aimock";

const llm = new LLMock({ port: 5555 });
const vector = new VectorMock();

vector.addCollection("embeddings", { dimension: 768 });
vector.onQuery("embeddings", [{ id: "v1", score: 0.9 }]);

llm.mount("/vector", vector);
await llm.start();
// Vector API at http://127.0.0.1:5555/vector

Collection Management

Collections API typescript 
// Create a collection with a dimension
vector.addCollection("products", { dimension: 384 });

// Upsert vectors into a collection
vector.upsert("products", [
  { id: "p1", values: [0.1, 0.2, ...], metadata: { name: "Widget" } },
  { id: "p2", values: [0.3, 0.4, ...], metadata: { name: "Gadget" } },
]);

// Delete a collection
vector.deleteCollection("products");

Query Handlers

Register static results or dynamic handlers for query responses:

onQuery API typescript
// Static results — always returns these
vector.onQuery("docs", [
  { id: "d1", score: 0.95, metadata: { topic: "setup" } },
]);

// Dynamic handler — receives the query, returns results
vector.onQuery("docs", (query) => {
  const topK = query.topK ?? 10;
  return Array.from({ length: topK }, (_, i) => ({
    id: `result-${i}`,
    score: 1 - i * 0.1,
  }));
});

Pinecone-Compatible Endpoints

Method Path Description
POST /query Query vectors by namespace
POST /vectors/upsert Upsert vectors into a namespace
POST /vectors/delete Delete vectors by ID
GET /describe-index-stats Get index statistics

Qdrant-Compatible Endpoints

Method Path Description
POST /collections/{name}/points/search Search points in a collection
PUT /collections/{name}/points Upsert points into a collection
POST /collections/{name}/points/delete Delete points by ID

ChromaDB-Compatible Endpoints

Method Path Description
POST /api/v1/collections/{id}/query Query a collection
POST /api/v1/collections/{id}/add Add embeddings to a collection
GET /api/v1/collections List all collections
DELETE /api/v1/collections/{id} Delete a collection

Config File

VectorMock can be configured via the aimock JSON config file:

aimock.json json
{
  "vector": {
    "path": "/vector",
    "collections": [
      {
        "name": "docs",
        "dimension": 1536,
        "vectors": [
          { "id": "v1", "values": [0.1, 0.2], "metadata": { "title": "Intro" } }
        ],
        "queryResults": [
          { "id": "v1", "score": 0.95, "metadata": { "title": "Intro" } }
        ]
      }
    ]
  }
}

Inspection

Inspection API typescript 
vector.health();       // { status: "ok", collections: 2 }
vector.getRequests();  // Journal entries (when mounted with shared journal)
vector.reset();        // Clears all collections and query handlers