Metadata-Version: 2.4
Name: forum-ai-tracing
Version: 0.3.0
Summary: Record agent traces and turns in Forum AI.
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Forum AI Python SDK

Install with `pip install forum-ai-tracing`. Requires Python 3.10 or later.

```python
import os
from forum_ai import RecordingClient

forum = RecordingClient(base_url=os.environ['FORUM_BASE_URL'], api_key=os.environ['FORUM_API_KEY'], instance='support-agent', project='production')
trace = forum.start_trace('Resolve request', session_id='conversation-123', turn_id='turn-456')
trace.message('user', 'Where is my order?')
tool = trace.start_span('lookup_order', operation_type='tool', input={'order_id': '123'})
tool.end({'status': 'delivered'})
trace.message('assistant', 'Your order was delivered.')
receipt = trace.end()
```

A session groups related work. A turn is an interaction boundary; a trace records an execution segment. Spans represent operations. `flush()` sends an immutable in-progress snapshot; `end()` closes capture. Uploading does not start an evaluation.

Keep instrumentation and delivery failures isolated from the application, and preserve its original exception. Retain failed snapshots for retry. `upload(recording, expected_head=None)` retries identical content safely; changed content requires the current head explicitly. Do not silently refresh conflicting historical evidence. No evidence is silently truncated. API keys remain server-side.
