On this page

Python and TypeScript SDKs

Create a read key for the indexed Next Product Lab guide in Use ContextBase from an application. Set CONTEXTBASE_BASE_URL, CONTEXTBASE_API_KEY and CONTEXTBASE_SPACE_ID. The clients read the URL and key from the environment or take them as constructor arguments.

Search with Python

Install the release candidate from PyPI with pip install --pre contextbase-sdk. Save and run this script.

import os

from contextbase import ContextBase

with ContextBase() as client:
    client.check_compatibility()
    space = client.spaces.get(os.environ["CONTEXTBASE_SPACE_ID"])
    question = "How early should I prepare draft release notes before the demo?"
    for source in space.search(question):
        print(source.id, source.text)

Look for the release notes passage in the output. Use AsyncContextBase in an asyncio service. The context manager closes the HTTP connection.

Search with TypeScript

Use Node.js 18 or newer. Install the release candidate from npm with npm install contextbase-sdk@next. Run this example as an ES module.

import { ContextBase } from "contextbase-sdk";

const client = new ContextBase();
await client.checkCompatibility();
const space = await client.spaces.get(process.env.CONTEXTBASE_SPACE_ID);
const question = "How early should I prepare draft release notes before the demo?";
for (const source of await space.search(question, { top_k: 5 })) {
  console.log(source.id, source.text);
}

Generate or stream an answer

Configure a model and enable a generator in the Space. In the Python example, use this call within the client context.

result = space.query(question, top_k=5)
if result.outcome == "accepted":
    print(result.answer)
    for source in result.sources:
        print(source.locator, source.text)
else:
    print(result.outcome)

In the TypeScript example, call queryStream() with the same Space and question.

for await (const event of space.queryStream(question, { top_k: 5 })) {
  if (event.type === "done") {
    const { answer, sources, outcome } = event.answer;
    console.log(outcome === "accepted" ? { answer, sources } : { outcome });
  } else if (event.type === "error") {
    console.error(event.reason, event.detail);
  }
}

Install from a checkout

For Python, run uv sync --directory sdk/python --frozen from the repository root. Use uv run --directory sdk/python python to run scripts in that environment.

For TypeScript, build with Node.js 22. Install the resulting package in your application with npm install /path/to/package.tgz.

cd sdk/typescript
npm ci
npm run build
npm pack

Method map

Task

Python

TypeScript

Check the server API version

client.check_compatibility()

client.checkCompatibility()

List accessible Spaces

client.spaces.list()

client.spaces.list()

Upload into a Space and wait for indexing

space.documents.upload(), space.documents.wait_indexed()

space.documents.upload(), space.documents.waitIndexed()

Retrieve, answer, or stream

space.search(), space.query(), space.query_stream()

space.search(), space.query(), space.queryStream()

Validate and apply a pipeline

space.config.validate(), space.config.apply()

space.config.validate(), space.config.apply()

Measure a pipeline

client.eval_datasets.create(), space.evaluations.run()

client.evalDatasets.create(), space.evaluations.run()

search() returns a list of sources. Python’s search_with_receipt() also exposes the server’s retrieval receipt, including whether the requested rrf_k was applied. query() returns an answer object with separate answer, sources and outcome. The Python stream yields event classes such as Check, Token, Done and ErrorEvent. The TypeScript stream exposes an event whose type identifies the payload. In both clients the final result is event.answer on the completion event.

See Python SDK method reference for exact Python method signatures, defaults and descriptions. For endpoints beyond the facades, consult REST API reference. Use contextbase.types and the generated Python operations with the raw client, or types and operations with client.raw in TypeScript. Use the Python SDK exports or TypeScript SDK exports for all types and errors. SDK versions and release instructions are maintained in the Python README and TypeScript README.

Run an existing integration

  • Notebook searches an indexed Space and requests an answer with a generator. Select the kernel from the SDK environment after setting the three variables.

  • Upload and ask creates a Space with an explicit language model, uploads a file and waits for its index. Use a credential whose owner can create Spaces.

  • FastAPI service wraps a configured Space in a POST /ask handler. From sdk/python, run uv run fastapi dev examples/fastapi_service.py. Apply the application’s own authentication before serving it to end users.

  • LangChain adapter and LlamaIndex adapter pass retrieved passages into a separately configured synthesis pipeline.

See the examples README for setup commands and offline SDK example tests for checks using controlled HTTP responses.

ContextBase0.1.0

Search the documentation