Metadata-Version: 2.4
Name: tracedb
Version: 0.1.0
Summary: Sync-first TraceDB Python SDK with async helpers
Author-email: Trace-DB <hello@trace-db.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Trace-DB/tracedb-python
Project-URL: Repository, https://github.com/Trace-DB/tracedb-python
Keywords: tracedb,database,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: async
Requires-Dist: aiohttp>=3.8; extra == "async"
Dynamic: license-file

# 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.

Checkpoint status: this repository currently carries local unit/package
validation only. It does not claim PyPI publication, hosted-alpha readiness,
managed-cloud proof, benchmark evidence, or Go SDK support.

Current public DX:

```python
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:

```bash
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:

```bash
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 async support, PyPI publication, hosted-alpha readiness,
managed-cloud proof, SQL compatibility, full GraphQL adapter parity, benchmark
evidence, or Go SDK support.
