TraceDB Docs

TraceDB Python SDK

TraceDB is an AI-native transactional candidate-stream database. One logical record. One commit epoch. Many native views. No external sync drift. Explain every candidate.

This directory contains the sync-first Python SDK surface for the current TraceDB Platform Contract v0 lane. This is the standalone Python SDK package, pinned by `tracedb-protocol.lock` to `platform-contract-v0`. It targets the current TraceDB HTTP product surface. TraceField runtime work, Agent Memory Flight Recorder, and tensor artifacts are future research/demo or governed-module directions, not current Python SDK claims.

Install

The package is live on PyPI:

pip install tracedb

> Install the `async` extra for `AsyncTraceDB` helpers backed by `aiohttp`: > ```bash > pip install tracedb[async] > ```

Current public DX:

from tracedb import TraceDB

db = TraceDB.from_env()
docs = db.table("docs").tenant("tenant-a")

docs.insert("intro", {
    "body": "TraceDB Python SDK",
    "embedding": [1, 0, 0],
    "status": "published",
})

docs.insert_rows([
    {"id": "sdk", "body": "TraceDB sync SDK", "embedding": [0.8, 0.2, 0], "status": "published"},
    {"id": "ops", "body": "TraceDB snapshot restore path", "embedding": [0, 1, 0], "status": "published"},
], idempotency_key="docs-batch-1")

rows = (
    db.table("docs")
    .where({"tenant_id": "tenant-a", "status": "published"})
    .match_text("body", "TraceDB")
    .near("embedding", [1, 0, 0])
    .with_options(explain=True, freshness="lazy")
    .limit(20)
    .all()
)

traceql_rows = db.traceql("""
FROM docs
TENANT tenant-a
WHERE status = "published"
MATCH body "TraceDB"
LIMIT 20
""")

graphql_schema = db.graphql_schema()

graphql_rows = db.graphql(
    'query { docs(tenant_id: "tenant-a", match: "TraceDB", limit: 20) { record_id } }'
)

The query builder preserves field selection: `match_text("body", ...)` becomes `HybridQuery.text_field = "body"` and `near("embedding", ...)` becomes `HybridQuery.vector_field = "embedding"` on the HTTP wire. It also canonicalizes `strict`, `lazy`, and `allow_dirty` freshness inputs to the `Strict`, `Lazy`, and `AllowDirty` wire modes.

Typed response dataclasses such as `ReadyResponse`, `HealthResponse`, `QueryResult`, `ScanResult`, `PutResult`, and `BatchPutResult` are exported from `tracedb` and preserve dict-like compatibility with `get(...)`, indexing, membership checks, and `to_dict()`. The package exposes `__version__ = "0.1.0"`, and sync/async HTTP requests send `User-Agent: tracedb-python/0.1.0`.

The package is fully typed and ships a `py.typed` marker (PEP 561). Type checkers such as mypy, pyright, and IDE language servers will discover and use the inline annotations automatically when the package is installed.

`TraceDB.from_env()` reads `TRACEDB_URL`, optional `TRACEDB_TOKEN`, `TRACEDB_DATABASE_ID`, `TRACEDB_BRANCH_ID`, `TRACEDB_TIMEOUT_MS`, and `TRACEDB_SAFE_RETRIES`, and `TRACEDB_IDEMPOTENCY_RETRIES`. Explicit keyword arguments override matching environment values. Direct construction with `TraceDB(url, token="dev-token")` remains supported. If `database_id` is configured and `branch_id` is omitted, copied JSON POST bodies default `branch_id` to `<database_id>:main`.

The sync client uses Python standard-library HTTP and imports without async dependencies installed. Install the `async` extra for `AsyncTraceDB` helpers backed by `aiohttp`. It preserves the raw HTTP escape hatch with `request_json(...)`, exposes `TraceDBHTTPError` with method, path, status, response body, parsed `error`, and optional `code`, and supports caller-provided `Idempotency-Key` values on mutation/admin calls. `table.insert_batch([{"id": ..., "fields": {...}}])` preserves the raw TraceDB record-input shape. `table.insert_rows([...])` is the notebook/data workflow helper: it accepts row dictionaries, reads the record id from `id` by default, supports `id_field="..."` for custom row keys, copies row fields into the canonical batch request, and still executes through `POST /v1/records/put-batch`. `TraceDB.traceql(query)` and `traceql_request({"query": query})` execute native TraceQL strings through `POST /v1/traceql`. `TraceDB.graphql_schema()` reads generated SDL from `GET /v1/graphql/schema`. `TraceDB.graphql(query)` and `graphql_request({"query": query})` execute native GraphQL operations through `POST /v1/graphql`; `bounded_graphql(...)` uses the bounded compatibility adapter at `POST /v1/graphql/bounded`. `safe_retries` retries transient HTTP 5xx responses only for read-only routes: health, ready, GraphQL schema export, get, scan, query, bounded GraphQL, explain, and polymorphic native TraceQL/GraphQL payloads classified as read-only. It does not retry mutating TraceQL/GraphQL commands/root fields or other writes/admin mutations without an idempotency key. `idempotency_retries` is default-off and retries transient HTTP 5xx responses for mutation/admin routes, including mutating native TraceQL/GraphQL payloads, only when that request carries a caller-provided `Idempotency-Key`; unkeyed writes and 4xx/conflict responses are not retried.

Run the local unit/package checks:

python3 -m unittest discover -s tests
python3 install_smoke.py

`install_smoke.py` prefers a temporary venv, installs this directory as the `tracedb` package with pip `--no-deps`, and runs a consumer script from outside the repo so source-path imports cannot hide package drift. On remote images where Python can run tests but `ensurepip` is unavailable, it falls back to an isolated temporary pip `--target` install. It emits `python sdk install smoke ok`.

Optional loopback HTTP smoke:

python3 http_smoke.py

The smoke starts a local `tracedb-server` from `TRACEDB_CORE_REPO`, falling back to sibling `../tracedb` from the standalone repo root. It drives schema apply, single put, row batch ingest, patch, get, scan, query, TraceQL string execution, explain, GraphQL schema export, bounded GraphQL result/explain, delete, idempotency replay and conflict, error envelope parsing, compact, snapshot, restore, and admin jobs. It emits `python sdk http smoke ok`.

This is sync Python SDK product-path evidence against a local server only. The package metadata and checkpoint commands above are local project/package-shape evidence only. The platform conformance lane installs a copied package into an isolated temporary pip `--target` and runs this HTTP smoke with source-path imports disabled, so SDK conformance cannot pass by accidentally importing the repo copy. It is not hosted-alpha readiness, managed-cloud proof, SQL compatibility, full GraphQL adapter parity, benchmark evidence, async support, or Go SDK support.