Metadata-Version: 2.4
Name: turndb
Version: 0.1.5
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
Requires-Dist: opentelemetry-sdk>=1.20,<2 ; extra == 'otel'
Provides-Extra: otel
Summary: Embedded, byte-exact storage for AI traces
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# turndb for Python

The Python SDK is a thin PyO3 shell over TurnDB's single-file engine. It uses the same capability
and structured-query contract as Rust and Node. One dedicated Rust actor owns each writer, so
Python threads never concurrently enter mutable engine state.

```python
from turndb import Store

db = Store.open("agent.turndb")
db.write([{"kind": "put", "id": "trace/1", "attrs": [], "contents": []}], durable=True)
db.seal("agent-snapshot.turndb")
db.close()
```

Attributes, writes, scan requests, and scan results use the canonical data shapes in
`conformance/v1/query.schema.json`. Content bytes in those serializable shapes are base64. The
direct `read_content()` convenience returns `bytes`.

OpenTelemetry is the Tier-2 entrance. With an SDK provider already configured, tracing to one local
file is two lines:

```python
exporter = TurnDbSpanExporter("agent.turndb")
provider.add_span_processor(BatchSpanProcessor(exporter))
```

The exporter durably acknowledges each export by default, publishes after 512 spans or five
seconds, and always syncs and flushes on `force_flush()` and `shutdown()`.

Provider SDKs remain optional. `trace_gen_ai_call()` and `trace_gen_ai_call_async()` wrap any
client closure in the canonical `gen_ai` CLIENT span, move input/output message arrays onto the
content-bearing attributes consumed by the exporter, and preserve the exact return value or
exception.

