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:

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.