@crvouga/mockingbird-service-llamacloud

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the LlamaCloud platform API (LlamaIndex's managed indexes) for test suites: project and pipeline lookup, pipeline documents (list, get, insert, upsert, delete), and retrieval. Retrieval is deterministic: a scripted answer when a test sets one, otherwise a term-overlap ranking over the documents in the pipeline. The chat knowledge tools (search_health_knowledge, search_faq) and the EMR chatbot-admin knowledge CRUD run against it with no vendor account, no embeddings and no nondeterminism.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from the official Python client's wire models (llama-cloud 0.1.45) and our backend adapter.

Install

npm install -D @crvouga/mockingbird-service-llamacloud

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-llamacloud serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

npx mockingbird-llamacloud serve --port 8805 --index acme-member-kb-v1 --project Default

Point the app at it:

import LlamaCloud from "@llamaindex/llama-cloud"
import { createRuntime } from "@crvouga/mockingbird-service-llamacloud"

// Test setup: a pipeline, and what retrieval answers for queries mentioning "apob".
// Anything else is ranked by term overlap over the documents the app upserted.
const emulator = createRuntime({ pipelines: [{ name: "acme-member-kb-v1", projectName: "Default" }] })
await emulator.fetch(
  new Request("http://llamacloud.test/__admin/retrieval", {
    method: "PUT",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      match: { contains: "apob" },
      nodes: [{ text: "ApoB counts atherogenic particles.", score: 0.92, metadata: { file_name: "apob.md" } }],
    }),
  }),
)

// The LlamaCloud SDK your application already uses. Only its fetch changes: requests reach
// the emulator in this process instead of api.cloud.llamaindex.ai.
const llama = new LlamaCloud({
  apiKey: "llx-mockingbird",
  fetch: (url: RequestInfo | URL, init?: RequestInit) => emulator.fetch(new Request(url, init)),
})
const [pipeline] = await llama.pipelines.list({ project_name: "Default", pipeline_name: "acme-member-kb-v1" })
const { retrieval_nodes } = await llama.pipelines.retrieve(pipeline?.id ?? "", { query: "What does ApoB measure?" })
console.log(retrieval_nodes[0]?.node.text, retrieval_nodes[0]?.score) // ApoB counts atherogenic particles. 0.92

Routes

All under Authorization: Bearer <key> (any non-empty key unless apiKeys is set). Errors are FastAPI-shaped: {"detail": "…"}, and 422 {"detail": [{loc, msg, type}]}.

Retrieval

1. Scripted. PUT /__admin/retrieval {match: {contains?, pipeline?}, nodes: [{text, score?, metadata?}]} adds a rule. The most recently added rule whose contains appears in the query (case-insensitive) and whose pipeline (id or name) matches answers its nodes verbatim, truncated to top-k. A node without a score gets 1, 0.9, 0.8, … Node ids are scripted_<n>.
2. Default: term overlap. Terms are lower-cased alphanumeric words of 2+ characters minus common stopwords. A document's score is the share of the query's distinct terms found in its text or metadata.title, rounded to 4 places. Non-matching documents are dropped and ties keep insertion order. Each document is one node (id_: "<docId>_0"), and its metadata gains document_id and pipeline_id, the fields the backend reads.

Node metadata is sent under both metadata (read by our backend) and extra_info (the official client model's field name). Without live credentials, which of the two the real API sends is unverified.

Python chat SDK: verified call sequence

The catalog listed this as unverified. It has now been checked against the installed SDK: llama-cloud-services 0.6.88, llama-cloud 0.1.45 and llama-index-core 0.14.10, the versions the consumer app's Python chat service pins. The wheels were read, and llamacloud.sdk.test.ts runs that service's real LlamaCloudClient file on the real SDK against the served emulator. LlamaCloudIndex(name, project_name=…, api_key=…) followed by .as_retriever(similarity_top_k=5).aretrieve(q) makes these calls:

1. GET /api/v1/projects?project_name=<name>: resolve_project. No match raises No project found with name …, and more than one match raises too.
2. GET /api/v1/pipelines?project_id=<id>&pipeline_name=<index>&pipeline_type=MANAGED: resolve_pipeline. No match raises Unknown index name ….
3. GET /api/v1/pipelines/{id}, then GET /api/v1/projects/{project_id}: as_retriever() builds a LlamaCloudRetriever(project_id=…, pipeline_id=…), which resolves both again by id.
4. POST /api/v1/pipelines/{id}/retrieve {query, dense_similarity_top_k: 5}.

The base URL comes from base_url or LLAMA_CLOUD_BASE_URL, falling back to https://api.cloud.llamaindex.ai (llama_index.core.ingestion.api_utils.get_client). The client passes no base_url, so setting the environment variable is enough. The SDK's pydantic models are strict: Pipeline.status must be CREATED or DELETING, and embedding_config is required. The emulator satisfies both, and the SDK test fails if a shape drifts.

Discrepancy: the Python client's llamacloud_project_name defaults to "default" (lowercase). The backend's default is "Default". Project lookup is exact, so it needs LLAMACLOUD_PROJECT_NAME=Default, or a seeded default project. Otherwise the client degrades to empty results, which the acceptance tests cover.

To run the SDK test:

uv venv /tmp/llama && VIRTUAL_ENV=/tmp/llama uv pip install \
  llama-cloud-services==0.6.88 llama-cloud==0.1.45 llama-index-core==0.14.10
MOCKINGBIRD_LLAMACLOUD_PYTHON=/tmp/llama/bin/python \
  MOCKINGBIRD_LLAMACLOUD_PY_CLIENT=/path/to/llamacloud_client.py bun test llamacloud.sdk

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets):

Namespaces

Neither consumer can add headers, so a namespace can be chosen three ways:

• the x-mockingbird-namespace header;
• a /__admin/ns/<name> prefix on the base URL;
• the API key: PUT /__admin/credentials {"credentials": {"<LLAMACLOUD_API_KEY>": "<namespace>"}}.

Each namespace starts with the seeded pipelines, by default acme-member-kb-v1 in project Default. The request journal records operation ids, statuses and pipeline and document ids. It never records queries, document text or titles.

Deliberately not modelled

• Real retrieval quality: no embeddings, chunking, hybrid search, reranking, metadata filters, image or page-figure nodes, or retrieval_mode routing. A document is always one node.
• Pipeline ingestion status and sync jobs. Upserted documents can be retrieved immediately.
• File uploads (/api/v1/files, pipeline_files), data sources, parsing (LlamaParse) and extraction.
• Creating projects or pipelines through the API. Use the seed or PUT /__admin/pipelines.
• Organizations beyond one per namespace.

API

Part of mockingbird.