Python SDK
On this page you’ll install the Cortrix Python SDK, connect to a local Cortrix service, and run a query.
The SDK provides a synchronous client, Cortrix, and an asynchronous client, AsyncCortrix, both fully typed. Its runtime dependency is httpx, plus typing-extensions on Python versions before 3.12.
Prerequisites
- A running Cortrix service. See the Quickstart.
- Python 3.9 or later.
Install
Install the package from PyPI into a virtual environment:
Confirm the installed version:
Cortrix is in pre-release, so pip installs the latest pre-release, 1.0.0rc2.
Your first query
Save this as check.py. It connects to the service the quickstart started and queries the demo namespace:
Run it:
The quickstart service has no authentication, so there’s no api_key here. To connect to a service that requires one, use Cortrix(base_url=..., api_key="your-cortrix-api-key").
If every call raises CortrixError with status code 502 while curl to the same address works, a system proxy is usually intercepting requests to your own machine. Bypass the proxy for local addresses and try again:
Client options
| Option | Purpose |
|---|---|
base_url | The service address. Defaults to http://localhost:8420 |
api_key | An API key. Optional |
tenant_id | A tenant identifier. Optional |
timeout | The request timeout |
max_retries | The maximum number of automatic retries |
http_client | Pass in your own httpx.Client |
client_id | Sent as the X-Client-Id header to tell callers apart |
trace_id_provider | A function that returns a W3C traceparent, for distributed tracing |
Query
client.search() maps to POST /query. The first argument can be a single namespace, a list of namespaces, or ["*"] for all of them:
| Parameter | Default | Purpose |
|---|---|---|
top_k | 10 | How many results to return |
rerank | True | Whether to rerank |
include_sources | False | Whether to return source information |
filters | None | Filter conditions |
coverage_ratio, namespaces_succeeded, and namespaces_failed in results.meta tell you whether a cross-namespace query fully succeeded.
Upload documents
Uploads are processed asynchronously and return a task. Track it with client.documents.status() or client.documents.task_progress().
Async client
The async client mirrors the sync client exactly. Every resource method has an async counterpart:
Resources
| Resource | Methods |
|---|---|
client.documents | upload, list, get, status, task_progress, cancel_task, delete |
client.namespaces | create, list, get, update, delete, set_permission |
client.search(...) | Semantic query |
client.memory | search, log, list, create, update, delete |
client.watchers | add, list, remove, events |
client.system | health, version, namespace_stats, agent_llm_config |
client.ops.gc | status, run, restore, purge |
client.import_database(...) In development | Start a database import manually |
client.tenants In development | list, get, invite, update_role, quota, create |
Resources marked In development have no documentation yet.
Handle errors
Every exception derives from CortrixError and carries structured fields, so you can decide whether to retry or report:
The SDK retries automatically using the server’s hints. To decide whether to retry, it looks at the retryable field first and then at the HTTP status code. For the wait time it uses retry_after_ms, then the Retry-After header, then exponential backoff. Adjust the number of attempts with max_retries.
Operations
Runtime and maintenance operations live under client.ops:
client.ops.gc.run() and client.ops.gc.purge() are destructive. purge() deletes data permanently and can’t be undone.