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 |
|
|
List accessible Spaces |
|
|
Upload into a Space and wait for indexing |
|
|
Retrieve, answer, or stream |
|
|
Validate and apply a pipeline |
|
|
Measure a pipeline |
|
|
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¶
Notebooksearches an indexed Space and requests an answer with a generator. Select the kernel from the SDK environment after setting the three variables.Upload and askcreates a Space with an explicit language model, uploads a file and waits for its index. Use a credential whose owner can create Spaces.FastAPI servicewraps a configured Space in aPOST /askhandler. Fromsdk/python, runuv run fastapi dev examples/fastapi_service.py. Apply the application’s own authentication before serving it to end users.LangChain adapterandLlamaIndex adapterpass 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.