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

trodo/__init__.py

@@ -1,35 +1,71 @@
 """
 trodo-python — Trodo Analytics SDK for Python
 
-Usage (module-level singleton):
+Quick start (any stack):
     import trodo
-    trodo.init(site_id='your-site-id')
-    user = trodo.for_user('user-123')
-    user.track('purchase_completed', {'amount': 99.99})
-
-Usage (class):
-    from trodo import TrodoClient
-    client = TrodoClient(site_id='your-site-id')
-    user = client.for_user('user-123')
-    user.track('purchase_completed', {'amount': 99.99})
+    trodo.init(site_id='your-site-id')  # auto-instrument on by default
+
+    # Anthropic / OpenAI / LangChain / LlamaIndex — nothing else to do.
+    with trodo.wrap_agent('customer-support',
+                          distinct_id=uid, conversation_id=conv) as run:
+        result = agent.run(query)
+        run.set_output(result)
+
+    trodo.feedback(run.run_id, satisfaction='positive', rating=5)
+
+Raw-HTTP LLM caller (no OTel integration for your client):
+    resp = httpx.post(..., 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,
+    )
+
+Custom tool:
+    @trodo.tool()
+    def run_funnel_query(team_id, preset): ...
+
+Downstream microservice (join the caller's run instead of making a new one):
+    # In FastAPI:
+    app.middleware('http')(trodo.fastapi_middleware())
+
+    # Or manually:
+    with trodo.join_run(
+        run_id=headers['X-Trodo-Run-Id'],
+        parent_span_id=headers['X-Trodo-Parent-Span-Id'],
+    ):
+        ...
 """
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional, Union
+__version__ = "2.2.0"
+
+from typing import Any, Callable, Dict, List, Optional, Union
 
 from .client import TrodoClient
 from .user_context import UserContext
 from .managers.group_manager import GroupProfile
+from .otel.wrap_agent import (
+    wrap_agent as _wrap_agent_ctx,
+    span as _span_ctx,
+    join_run as _join_run_ctx,
+    RunHandle,
+    SpanHandle,
+)
 from .types import (
     ApiResult, ResetResult, WalletAddressResult,
-    AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps, FeedbackProps,
+    FeedbackProps,
 )
 
 __all__ = [
     "TrodoClient",
     "UserContext",
     "GroupProfile",
+    "RunHandle",
+    "SpanHandle",
+    "FeedbackProps",
     "init",
     "for_user",
     "track",
@@ -40,17 +76,25 @@ __all__ = [
     "disable_auto_events",
     "flush",
     "shutdown",
-    # Agent analytics
-    "AgentCallProps",
-    "ToolUseProps",
-    "AgentResponseProps",
-    "AgentErrorProps",
-    "FeedbackProps",
-    "track_agent_call",
-    "track_tool_use",
-    "track_agent_response",
-    "track_agent_error",
-    "track_feedback",
+    # Agent runs
+    "wrap_agent",
+    "agent",
+    "span",
+    "tool",
+    "trace",
+    "llm",
+    "retrieval",
+    "join_run",
+    "start_run",
+    "end_run",
+    "track_llm_call",
+    "feedback",
+    "get_tracer",
+    # Cross-service propagation
+    "fastapi_middleware",
+    "propagation_headers",
+    "current_run_id",
+    "current_span_id",
 ]
 
 # ============================================================================
@@ -68,6 +112,10 @@ def _get_client() -> TrodoClient:
     return _client
 
 
+def _maybe_client() -> Optional[TrodoClient]:
+    return _client
+
+
 def init(
     site_id: str,
     api_base: str = "https://sdkapi.trodo.ai",
@@ -79,8 +127,15 @@ def init(
     auto_events: bool = False,
     on_error: Optional[Any] = None,
     debug: bool = False,
+    auto_instrument: bool = True,
 ) -> TrodoClient:
-    """Initialise the singleton SDK instance."""
+    """Initialise the singleton SDK instance.
+
+    ``auto_instrument=True`` (default) registers OTel adapters for
+    Anthropic, OpenAI, LangChain, LlamaIndex, Google Generative AI and
+    any other installed opentelemetry-instrumentation-* package, so
+    LLM calls emit token/cost spans with no further code.
+    """
     global _client
     _client = TrodoClient(
         site_id=site_id,
@@ -93,6 +148,7 @@ def init(
         auto_events=auto_events,
         on_error=on_error,
         debug=debug,
+        auto_instrument=auto_instrument,
     )
     return _client
 
@@ -101,7 +157,6 @@ def for_user(
     distinct_id: str,
     session_id: Optional[str] = None,
 ) -> UserContext:
-    """Return a UserContext bound to the given distinctId."""
     return _get_client().for_user(distinct_id, session_id)
 
 
@@ -111,22 +166,18 @@ def track(
     properties: Optional[Dict[str, Any]] = None,
     category: str = "custom",
 ) -> None:
-    """Track an event for a user (direct-call pattern)."""
     _get_client().track(distinct_id, event_name, properties, category)
 
 
 def identify(identify_id: str, session_id: Optional[str] = None) -> UserContext:
-    """Create or retrieve a UserContext for an identified user. Fires identify API on first call."""
     return _get_client().identify(identify_id, session_id)
 
 
 def wallet_address(distinct_id: str, wallet_addr: str) -> WalletAddressResult:
-    """Associate a wallet address with a user."""
     return _get_client().wallet_address(distinct_id, wallet_addr)
 
 
 def reset(distinct_id: str) -> ResetResult:
-    """Reset a user's session."""
     return _get_client().reset(distinct_id)
 
 
@@ -139,39 +190,289 @@ def disable_auto_events() -> None:
 
 
 def flush() -> None:
-    """Flush any queued batch events."""
     _get_client().flush()
 
 
 def shutdown() -> None:
-    """Flush, stop timers, and disable auto events."""
     _get_client().shutdown()
 
 
 # ----------------------------------------------------------------------------
-# Agent Analytics — singleton wrappers
+# Agent Runs
 # ----------------------------------------------------------------------------
 
-def track_agent_call(props: AgentCallProps) -> None:
-    """Track an LLM invocation / inbound message."""
-    _get_client().track_agent_call(props)
+def wrap_agent(
+    agent_name: str,
+    *,
+    distinct_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    parent_run_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> _wrap_agent_ctx:
+    """Wrap a block as an agent run — returns a context manager yielding RunHandle."""
+    return _get_client().wrap_agent(
+        agent_name,
+        distinct_id=distinct_id,
+        conversation_id=conversation_id,
+        parent_run_id=parent_run_id,
+        metadata=metadata,
+    )
+
+
+def agent(
+    agent_name: str,
+    *,
+    distinct_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator form of wrap_agent."""
+    return _get_client().agent(
+        agent_name,
+        distinct_id=distinct_id,
+        conversation_id=conversation_id,
+        metadata=metadata,
+    )
+
+
+def span(
+    name: str,
+    *,
+    kind: str = "generic",
+    input: Any = None,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> _span_ctx:
+    """Nested span inside the current run."""
+    return _get_client().span(name, kind=kind, input=input, attributes=attributes)
+
+
+def join_run(
+    run_id: str,
+    parent_span_id: Optional[str] = None,
+    *,
+    name: str = "remote.handler",
+    kind: str = "agent",
+    input: Any = None,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> _join_run_ctx:
+    """Open a span on an existing run owned by a remote service."""
+    return _get_client().join_run(
+        run_id,
+        parent_span_id,
+        name=name,
+        kind=kind,
+        input=input,
+        attributes=attributes,
+    )
+
+
+def start_run(
+    agent_name: str,
+    *,
+    run_id: Optional[str] = None,
+    distinct_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    parent_run_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    input: Any = None,
+) -> str:
+    """Open a Run record without a context manager.
+
+    Pairs with :func:`end_run` for sessions that span multiple processes or
+    HTTP requests. Returns the run_id (caller-supplied or freshly minted).
+    Between start_run and end_run any process can use ``join_run(run_id, ...)``
+    to add spans.
+    """
+    return _get_client().start_run(
+        agent_name,
+        run_id=run_id,
+        distinct_id=distinct_id,
+        conversation_id=conversation_id,
+        parent_run_id=parent_run_id,
+        metadata=metadata,
+        input=input,
+    )
+
+
+def end_run(
+    run_id: str,
+    *,
+    output: Any = None,
+    status: str = "ok",
+    error_summary: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Finalise a Run opened by :func:`start_run`."""
+    _get_client().end_run(
+        run_id,
+        output=output,
+        status=status,
+        error_summary=error_summary,
+        metadata=metadata,
+    )
+
+
+def tool(
+    name: Any = None,
+    fn: Optional[Callable[..., Any]] = None,
+    *,
+    kind: str = "tool",
+) -> Any:
+    """Wrap a function as a tool span — dual-form helper and decorator.
+
+    Helper form::
+
+        run_funnel_query = trodo.tool('run_funnel_query', run_funnel_query)
+
+    Decorator form (backward-compatible)::
+
+        @trodo.tool()
+        def run_funnel_query(team_id, preset): ...
+
+        @trodo.tool(name='custom-name')
+        async def fetch(...): ...
+    """
+    # Deferred import: allow @trodo.tool() at import-time before init().
+    from .otel.helpers import tool as _tool_helper
+    return _tool_helper(name, fn, kind=kind)
+
+
+def trace(
+    name: Any = None,
+    fn: Optional[Callable[..., Any]] = None,
+) -> Any:
+    """Wrap a function as a generic span — dual-form helper and decorator."""
+    from .otel.helpers import trace as _trace_helper
+    return _trace_helper(name, fn)
+
+
+def llm(
+    name: Any = None,
+    fn: Optional[Callable[..., Any]] = None,
+    *,
+    model: Optional[str] = None,
+    provider: Optional[str] = None,
+    temperature: Optional[float] = None,
+    extract_usage: Optional[Callable[[Any], Any]] = None,
+) -> Any:
+    """Wrap an LLM call — auto-captures tokens from OpenAI/Anthropic/Gemini
+    response shapes. Dual-form helper and decorator."""
+    from .otel.helpers import llm as _llm_helper
+    return _llm_helper(
+        name,
+        fn,
+        model=model,
+        provider=provider,
+        temperature=temperature,
+        extract_usage=extract_usage,
+    )
+
+
+def retrieval(
+    name: Any = None,
+    fn: Optional[Callable[..., Any]] = None,
+) -> Any:
+    """Wrap a retriever / vector search as a kind='retrieval' span."""
+    from .otel.helpers import retrieval as _retrieval_helper
+    return _retrieval_helper(name, fn)
+
+
+def get_tracer(name: str = "trodo") -> Any:
+    """Return a raw OTel tracer — the Trodo processor is already subscribed.
+
+    Use for advanced cases where you want to emit spans with the raw OTel
+    API; they'll be captured and forwarded to Trodo like any other span.
+
+        tracer = trodo.get_tracer('my.module')
+        with tracer.start_as_current_span('custom') as sp:
+            sp.set_attribute('foo', 'bar')
+    """
+    try:
+        from opentelemetry import trace as _otel_trace  # type: ignore
+    except Exception as e:  # pragma: no cover
+        raise RuntimeError(
+            "trodo.get_tracer requires the opentelemetry-api package"
+        ) from e
+    return _otel_trace.get_tracer(name)
+
+
+def track_llm_call(
+    *,
+    model: Optional[str] = None,
+    provider: Optional[str] = None,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+    prompt: Any = None,
+    completion: Any = None,
+    temperature: Optional[float] = None,
+    cost: Optional[float] = None,
+    name: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Record a one-shot LLM span for a raw-HTTP caller."""
+    from .otel.helpers import track_llm_call as _fn
+    _fn(
+        model=model,
+        provider=provider,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        prompt=prompt,
+        completion=completion,
+        temperature=temperature,
+        cost=cost,
+        name=name,
+        metadata=metadata,
+    )
+
+
+def feedback(
+    run_id: str,
+    *,
+    satisfaction: Optional[str] = None,
+    rating: Optional[float] = None,
+    comment: Optional[str] = None,
+    feedback: Optional[str] = None,
+    distinct_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> ApiResult:
+    """Attach feedback to a completed run."""
+    return _get_client().feedback(
+        run_id,
+        satisfaction=satisfaction,
+        rating=rating,
+        comment=comment,
+        feedback=feedback,
+        distinct_id=distinct_id,
+        metadata=metadata,
+    )
+
+
+# ----------------------------------------------------------------------------
+# Cross-service propagation
+# ----------------------------------------------------------------------------
 
+def fastapi_middleware() -> Callable:
+    """Return a FastAPI/Starlette middleware that auto-joins inbound runs.
 
-def track_tool_use(props: ToolUseProps) -> None:
-    """Track a tool invocation within an agent turn."""
-    _get_client().track_tool_use(props)
+    Usage:
+        app = FastAPI()
+        trodo.init(site_id='...')
+        app.middleware('http')(trodo.fastapi_middleware())
+    """
+    return _get_client().fastapi_middleware()
 
 
-def track_agent_response(props: AgentResponseProps) -> None:
-    """Track an LLM response / completion."""
-    _get_client().track_agent_response(props)
+def propagation_headers() -> Dict[str, str]:
+    """Return outbound HTTP headers carrying the current run/span id."""
+    from .otel.helpers import propagation_headers as _fn
+    return _fn()
 
 
-def track_agent_error(props: AgentErrorProps) -> None:
-    """Track an error during an agent turn."""
-    _get_client().track_agent_error(props)
+def current_run_id() -> Optional[str]:
+    from .otel.wrap_agent import current_run_id as _fn
+    return _fn()
 
 
-def track_feedback(props: FeedbackProps) -> None:
-    """Track a user feedback reaction on an agent response."""
-    _get_client().track_feedback(props)
+def current_span_id() -> Optional[str]:
+    from .otel.wrap_agent import current_span_id as _fn
+    return _fn()

trodo/api/endpoints.py

@@ -1,5 +1,4 @@
 TRACK = "/api/sdk/track"
-TRACK_AGENT = "/api/sdk/track-agent"
 EVENTS = "/api/events"
 EVENTS_BULK = "/api/events/bulk"
 IDENTIFY = "/api/sdk/identify"
@@ -19,3 +18,8 @@ GROUPS_SET = "/api/sdk/groups/set_group"
 GROUPS_ADD = "/api/sdk/groups/add_group"
 GROUPS_REMOVE = "/api/sdk/groups/remove_group"
 GROUPS_PROFILE = "/api/sdk/groups/profile"
+# Agent run tracking (Lemma-style, run-centric)
+RUNS_INGEST = "/api/sdk/runs/ingest"
+RUNS_START = "/api/sdk/runs/start"
+RUNS_BASE = "/api/sdk/runs"  # /runs/{run_id}/end, /spans, /feedback
+OTLP_TRACES = "/api/sdk/otel/v1/traces"

trodo/api/http_client.py

@@ -86,5 +86,33 @@ class HttpClient:
     def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
         return self._request(path, payload)
 
-    def post_agent_event(self, payload: Dict[str, Any]) -> ApiResult:
-        return self._request("/api/sdk/track-agent", payload)
+    # ------------------------------------------------------------------
+    # Agent Runs (Lemma-style)
+    # ------------------------------------------------------------------
+
+    def post_run_ingest(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/runs/ingest", payload)
+
+    def post_run_start(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/runs/start", payload)
+
+    def post_run_end(self, run_id: str, payload: Dict[str, Any]) -> ApiResult:
+        from urllib.parse import quote
+        return self._request(f"/api/sdk/runs/{quote(run_id, safe='')}/end", payload)
+
+    def post_spans_append(self, run_id: str, spans: list) -> ApiResult:
+        from urllib.parse import quote
+        return self._request(
+            f"/api/sdk/runs/{quote(run_id, safe='')}/spans",
+            {"spans": spans},
+        )
+
+    def post_run_feedback(self, run_id: str, payload: Dict[str, Any]) -> ApiResult:
+        from urllib.parse import quote
+        return self._request(
+            f"/api/sdk/runs/{quote(run_id, safe='')}/feedback",
+            payload,
+        )
+
+    def post_otlp_traces(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/otel/v1/traces", payload)