trodo-python 1.2.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

{trodo_python-1.2.0.dist-info → trodo_python-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 1.2.0
+Version: 2.2.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -136,9 +136,188 @@ 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'],
+):
+    ...
+```
+
+### Long-lived sessions across processes — `start_run` / `end_run`
+
+`wrap_agent` is a context manager — it opens *and* closes the run in one
+call stack. For sessions that live across many HTTP requests (an MCP
+server, a websocket-pinned chat, scheduled jobs that resume on different
+workers), use `start_run` to open the run from one process and `end_run`
+to finalise it later. Between the two, any process can use `join_run` to
+add child spans. Same `run_id` threads through everything.
+
+```python
+# Process A — open the run for an MCP session.
+run_id = trodo.start_run(
+    'external_mcp_session',
+    distinct_id=str(user_id),
+    conversation_id=mcp_session_id,
+)
+redis.set(f"mcp:run:{mcp_session_id}", run_id, ex=3600)
+
+# Process B (later, possibly a different worker) — append a tool span.
+run_id = redis.get(f"mcp:run:{mcp_session_id}").decode()
+with trodo.join_run(run_id, name='tool.run_funnel_query', kind='tool') as span:
+    span.set_input(args)
+    span.set_output(result)
+
+# When the session ends (timeout sweeper, explicit close):
+trodo.end_run(run_id, status='ok')
+```
+
+### 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 +340,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.dist-info → trodo_python-2.2.0.dist-info}/RECORD

@@ -1,23 +1,29 @@
-trodo/__init__.py,sha256=xbXCxPZtQfCgJeB1Yg_Rv067DOXCDztLXpo-f8XkL68,4837
-trodo/client.py,sha256=FkcUYymCMVJA9U509I5Lba9EZAYkjHb5-Fpoi3fI3oc,12122
-trodo/types.py,sha256=aX8aQrENDwSpouxqshHxDbjjzkvAveeClSSL0TDEygQ,4610
+trodo/__init__.py,sha256=lo_QFNEk_4ylQ_4-v0RBfdA8ed30M5QjlA7ylJAiAjU,12870
+trodo/client.py,sha256=x_HjIyLMowUU-w73GYETEZWWHKjWBC-4LpG6lfLBRmU,15499
+trodo/types.py,sha256=eySgUvCXROG2TxtxgiU0MNr5iH0DEcduK8bmYtTKG44,3138
 trodo/user_context.py,sha256=9la6azzwEanVmdP4ps_xMoufbeWVeIGU-M8ychmgajg,7859
 trodo/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/api/async_client.py,sha256=rZN4aJ2QiKyrHBK260bApCUB9JaMWU6BQtzoSJZh7xk,3408
-trodo/api/endpoints.py,sha256=JaJ5hjjKPi4aO6R25oasQTasEptg1FFFkDUIqO7uOXs,835
-trodo/api/http_client.py,sha256=h1p37Z-kmVxwCnodb5j8MXiP-cRwOKiF2lznoIW1bFI,3252
+trodo/api/endpoints.py,sha256=HKQ3d_Mxf0y4HwlHor0XkSAwUVj-4Xvv--rzE9njxjM,1027
+trodo/api/http_client.py,sha256=AELbKiABR066px2Uhq_dtkSsiVqMMP23p8QeoywzeHg,4391
 trodo/auto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/auto/auto_event_manager.py,sha256=cztuRsRkNoJE5R4NfSfTrTJTGl4jx2Yb-Ncy0aVAPo8,4247
 trodo/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/managers/group_manager.py,sha256=ki3Se3qEoSZfREX63oeDeBmEfZF-ISHLE8azEtLg0tM,3542
 trodo/managers/people_manager.py,sha256=mMVnx40Mlifx6NGgChvohC9ViK6dQu2mkXNHbV8pK1E,2882
+trodo/otel/__init__.py,sha256=yiRFXWUU45bAM2CV37XeO7zf1hmnmjufdP4XO50yEyE,624
+trodo/otel/auto_instrument.py,sha256=J_neFxvO-3YACUvtetY4RdM8xYA_79SZUgPry6hXrm8,9434
+trodo/otel/context.py,sha256=iJ1rE42-SbO8VZHAxhIl2ZJXgNwLIVps5xLg8GKgfFc,1165
+trodo/otel/helpers.py,sha256=cvgFrdT8yP92P9mttloiHPr_eTCe8cC4NVrxrJo_I-A,13234
+trodo/otel/processor.py,sha256=jVZkslZlw50G5uRAa7-GMRgn_yvae58EmlWTZL8tMkQ,6285
+trodo/otel/wrap_agent.py,sha256=mwHYwxtg9A9VUBdlbCKLswrNP0v5oY8ELpvt1JVYE8Q,17495
 trodo/queue/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/queue/batch_flusher.py,sha256=4Lg6T3Urwi9U0Q4FpFGPmjDYKg4ZliCTR-ND8BJvWaY,1298
 trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,872
 trodo/session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/session/server_session.py,sha256=uBAq1QSYPUUaHFSeoOyM5Yr65dLb8T82OOx3D1BrdrE,1970
 trodo/session/session_manager.py,sha256=JrgH1VeicmtlxPR4dXEuJbxhi23OelkgwW3-9Slv80o,2525
-trodo_python-1.2.0.dist-info/METADATA,sha256=GNdzVrFziphK3z0HtY02YyMNNBgGrFuYpsf8EgML54Y,10179
-trodo_python-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-trodo_python-1.2.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-1.2.0.dist-info/RECORD,,
+trodo_python-2.2.0.dist-info/METADATA,sha256=2WsoZx5P03S5LG7JDUsCfBwTLVGSCVYa3R8ZS8KKLqw,16353
+trodo_python-2.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trodo_python-2.2.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.2.0.dist-info/RECORD,,