# 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