trodo-python 1.2.0__tar.gz → 2.1.0__tar.gz

{trodo_python-1.2.0 → trodo_python-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 1.2.0
+Version: 2.1.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -136,9 +136,160 @@ trodo.set_group('user-123', 'company', 'acme')
 
 ---
 
-## Agent Analytics
+## AI Agent Tracing (recommended)
 
-Track every step of your LLM agents. Each call counts as one event toward your plan limit.
+One wrap around your agent captures every LLM call, tool call, and
+nested step as a tree of spans — token counts, costs, inputs, outputs,
+errors. Works with any stack: OpenAI, Anthropic, LangChain, LlamaIndex,
+Gemini, raw HTTP, custom tools. Cost is derived server-side from
+`(provider, model)` — the SDK only sends tokens.
+
+### 30-second quickstart
+
+```python
+import trodo
+trodo.init(site_id='your-site-id')   # auto-instrument on by default
+
+with trodo.wrap_agent('customer-support',
+                       distinct_id=user_id,
+                       conversation_id=session_id) as run:
+    run.set_input({'query': 'where did sales drop'})
+    answer = agent.run(query)        # OpenAI/Anthropic/LangChain auto-captured
+    run.set_output(answer)
+```
+
+Open the Agent Runs dashboard — the row shows tokens in/out, cost,
+span count, tool count, error count, plus the full trace tree.
+
+### Auto-instrumentation
+
+`trodo.init()` calls `enable_auto_instrument()` which registers every
+installed OpenTelemetry instrumentor. No extra code required.
+
+| Framework | Install |
+|-----------|---------|
+| OpenAI | `pip install opentelemetry-instrumentation-openai` |
+| Anthropic | `pip install opentelemetry-instrumentation-anthropic` |
+| LangChain | `pip install opentelemetry-instrumentation-langchain` |
+| LlamaIndex | `pip install opentelemetry-instrumentation-llama-index` |
+| Google Gemini | `pip install opentelemetry-instrumentation-google-generativeai` |
+| Vertex AI | `pip install opentelemetry-instrumentation-vertexai` |
+| Bedrock | `pip install opentelemetry-instrumentation-bedrock` |
+| Cohere | `pip install opentelemetry-instrumentation-cohere` |
+| Mistral | `pip install opentelemetry-instrumentation-mistralai` |
+| Haystack | `pip install opentelemetry-instrumentation-haystack` |
+| httpx / requests | bundled — generic HTTP spans for raw-HTTP callers |
+
+Opt out with `trodo.init(site_id=..., auto_instrument=False)`.
+
+### Span helpers
+
+Typed function wrappers for custom code — every call becomes a span
+with the args auto-captured as `input`, return value as `output`,
+exception as `error`. Dual-form: helper **and** decorator.
+
+```python
+# trace — generic span
+prepared = trodo.trace('prepare', prepare_fn)(payload)
+
+@trodo.trace('step')
+def step(): ...
+
+# tool — tool span (auto tool_name, kind='tool')
+run_funnel = trodo.tool('run_funnel_query', run_funnel_query)
+result = run_funnel(team_id=1, preset='day7')
+
+@trodo.tool(name='fetch_user')
+async def fetch_user(uid): ...
+
+# llm — LLM span, auto-extracts OpenAI / Anthropic / Gemini usage
+answer = trodo.llm(
+    'answer', call_openai, model='gpt-4o-mini', provider='openai',
+)(messages)
+# Records input_tokens / output_tokens from response['usage'].
+
+# retrieval — vector search / RAG retriever span
+search = trodo.retrieval('vector_search', vector_search)
+docs = search(query)
+```
+
+### Raw-HTTP escape hatches
+
+If your LLM client isn't OTel-instrumented and you can't wrap it as a
+function, record a span post-hoc:
+
+```python
+resp = httpx.post(url, json=body).json()
+trodo.track_llm_call(
+    model='gemini-2.5-flash', provider='google',
+    input_tokens=resp['usageMetadata']['promptTokenCount'],
+    output_tokens=resp['usageMetadata']['candidatesTokenCount'],
+    prompt=body, completion=resp,
+)
+```
+
+For advanced cases, get a raw OTel tracer — the Trodo processor is
+already subscribed:
+
+```python
+tracer = trodo.get_tracer('my.module')
+with tracer.start_as_current_span('custom') as sp:
+    sp.set_attribute('gen_ai.system', 'my-llm')
+```
+
+### Cross-service runs
+
+When one service calls another, the downstream service **joins** the
+caller's run instead of creating its own. All spans nest under a single
+timeline in the dashboard.
+
+```python
+# Caller (FastAPI / Flask / Django / …) — outbound:
+import httpx
+httpx.post(url, headers=trodo.propagation_headers(), json=body)
+
+# Downstream (FastAPI):
+from fastapi import FastAPI
+app = FastAPI()
+app.middleware('http')(trodo.fastapi_middleware())
+# Every LLM call / @tool / trace helper inside handlers now nests under
+# the caller's run — no extra wiring.
+
+# Or manually:
+with trodo.join_run(
+    run_id=headers['x-trodo-run-id'],
+    parent_span_id=headers['x-trodo-parent-span-id'],
+):
+    ...
+```
+
+### Conversation binding & feedback
+
+```python
+with trodo.wrap_agent(
+    'chat', distinct_id=user_id, conversation_id=session_id,
+) as run:
+    ...
+# Later:
+trodo.feedback(run.run_id, satisfaction='positive', rating=5)
+```
+
+### Cookbook
+
+Runnable scenarios that double as integration tests live in
+`sandbox/scenarios/` — `span_helpers.py`, `raw_http.py`,
+`custom_tools.py`, `cross_service.py`, `concurrent_100.py`,
+`long_run.py`, plus opt-in `openai_auto.py`, `anthropic_auto.py`,
+`langchain_chain.py`. Run them with
+`python -m sandbox.run_all` from the SDK root.
+
+---
+
+## Agent Analytics (legacy event-based API)
+
+The older per-event API below is still supported but superseded by
+`wrap_agent` + span helpers above. Use it only if you're already wired
+into it; new integrations should prefer the tracing API.
 
 **Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
 
@@ -161,6 +312,7 @@ trodo.track_agent_call(AgentCallProps(
     provider='anthropic',
     system_prompt_version='v2',   # optional — track prompt iterations
     distinct_id=user_id,          # optional — link to a Trodo user
+    metadata={'thread_source': 'slack', 'locale': 'en'},  # optional — agent_calls.metadata JSONB
 ))
 ```
 

{trodo_python-1.2.0 → trodo_python-2.1.0}/README.md

@@ -109,9 +109,160 @@ trodo.set_group('user-123', 'company', 'acme')
 
 ---
 
-## Agent Analytics
+## AI Agent Tracing (recommended)
 
-Track every step of your LLM agents. Each call counts as one event toward your plan limit.
+One wrap around your agent captures every LLM call, tool call, and
+nested step as a tree of spans — token counts, costs, inputs, outputs,
+errors. Works with any stack: OpenAI, Anthropic, LangChain, LlamaIndex,
+Gemini, raw HTTP, custom tools. Cost is derived server-side from
+`(provider, model)` — the SDK only sends tokens.
+
+### 30-second quickstart
+
+```python
+import trodo
+trodo.init(site_id='your-site-id')   # auto-instrument on by default
+
+with trodo.wrap_agent('customer-support',
+                       distinct_id=user_id,
+                       conversation_id=session_id) as run:
+    run.set_input({'query': 'where did sales drop'})
+    answer = agent.run(query)        # OpenAI/Anthropic/LangChain auto-captured
+    run.set_output(answer)
+```
+
+Open the Agent Runs dashboard — the row shows tokens in/out, cost,
+span count, tool count, error count, plus the full trace tree.
+
+### Auto-instrumentation
+
+`trodo.init()` calls `enable_auto_instrument()` which registers every
+installed OpenTelemetry instrumentor. No extra code required.
+
+| Framework | Install |
+|-----------|---------|
+| OpenAI | `pip install opentelemetry-instrumentation-openai` |
+| Anthropic | `pip install opentelemetry-instrumentation-anthropic` |
+| LangChain | `pip install opentelemetry-instrumentation-langchain` |
+| LlamaIndex | `pip install opentelemetry-instrumentation-llama-index` |
+| Google Gemini | `pip install opentelemetry-instrumentation-google-generativeai` |
+| Vertex AI | `pip install opentelemetry-instrumentation-vertexai` |
+| Bedrock | `pip install opentelemetry-instrumentation-bedrock` |
+| Cohere | `pip install opentelemetry-instrumentation-cohere` |
+| Mistral | `pip install opentelemetry-instrumentation-mistralai` |
+| Haystack | `pip install opentelemetry-instrumentation-haystack` |
+| httpx / requests | bundled — generic HTTP spans for raw-HTTP callers |
+
+Opt out with `trodo.init(site_id=..., auto_instrument=False)`.
+
+### Span helpers
+
+Typed function wrappers for custom code — every call becomes a span
+with the args auto-captured as `input`, return value as `output`,
+exception as `error`. Dual-form: helper **and** decorator.
+
+```python
+# trace — generic span
+prepared = trodo.trace('prepare', prepare_fn)(payload)
+
+@trodo.trace('step')
+def step(): ...
+
+# tool — tool span (auto tool_name, kind='tool')
+run_funnel = trodo.tool('run_funnel_query', run_funnel_query)
+result = run_funnel(team_id=1, preset='day7')
+
+@trodo.tool(name='fetch_user')
+async def fetch_user(uid): ...
+
+# llm — LLM span, auto-extracts OpenAI / Anthropic / Gemini usage
+answer = trodo.llm(
+    'answer', call_openai, model='gpt-4o-mini', provider='openai',
+)(messages)
+# Records input_tokens / output_tokens from response['usage'].
+
+# retrieval — vector search / RAG retriever span
+search = trodo.retrieval('vector_search', vector_search)
+docs = search(query)
+```
+
+### Raw-HTTP escape hatches
+
+If your LLM client isn't OTel-instrumented and you can't wrap it as a
+function, record a span post-hoc:
+
+```python
+resp = httpx.post(url, json=body).json()
+trodo.track_llm_call(
+    model='gemini-2.5-flash', provider='google',
+    input_tokens=resp['usageMetadata']['promptTokenCount'],
+    output_tokens=resp['usageMetadata']['candidatesTokenCount'],
+    prompt=body, completion=resp,
+)
+```
+
+For advanced cases, get a raw OTel tracer — the Trodo processor is
+already subscribed:
+
+```python
+tracer = trodo.get_tracer('my.module')
+with tracer.start_as_current_span('custom') as sp:
+    sp.set_attribute('gen_ai.system', 'my-llm')
+```
+
+### Cross-service runs
+
+When one service calls another, the downstream service **joins** the
+caller's run instead of creating its own. All spans nest under a single
+timeline in the dashboard.
+
+```python
+# Caller (FastAPI / Flask / Django / …) — outbound:
+import httpx
+httpx.post(url, headers=trodo.propagation_headers(), json=body)
+
+# Downstream (FastAPI):
+from fastapi import FastAPI
+app = FastAPI()
+app.middleware('http')(trodo.fastapi_middleware())
+# Every LLM call / @tool / trace helper inside handlers now nests under
+# the caller's run — no extra wiring.
+
+# Or manually:
+with trodo.join_run(
+    run_id=headers['x-trodo-run-id'],
+    parent_span_id=headers['x-trodo-parent-span-id'],
+):
+    ...
+```
+
+### Conversation binding & feedback
+
+```python
+with trodo.wrap_agent(
+    'chat', distinct_id=user_id, conversation_id=session_id,
+) as run:
+    ...
+# Later:
+trodo.feedback(run.run_id, satisfaction='positive', rating=5)
+```
+
+### Cookbook
+
+Runnable scenarios that double as integration tests live in
+`sandbox/scenarios/` — `span_helpers.py`, `raw_http.py`,
+`custom_tools.py`, `cross_service.py`, `concurrent_100.py`,
+`long_run.py`, plus opt-in `openai_auto.py`, `anthropic_auto.py`,
+`langchain_chain.py`. Run them with
+`python -m sandbox.run_all` from the SDK root.
+
+---
+
+## Agent Analytics (legacy event-based API)
+
+The older per-event API below is still supported but superseded by
+`wrap_agent` + span helpers above. Use it only if you're already wired
+into it; new integrations should prefer the tracing API.
 
 **Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
 
@@ -134,6 +285,7 @@ trodo.track_agent_call(AgentCallProps(
     provider='anthropic',
     system_prompt_version='v2',   # optional — track prompt iterations
     distinct_id=user_id,          # optional — link to a Trodo user
+    metadata={'thread_source': 'slack', 'locale': 'en'},  # optional — agent_calls.metadata JSONB
 ))
 ```
 

{trodo_python-1.2.0 → trodo_python-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "1.2.0"
+version = "2.1.0"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }