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

trodo/__init__.py

@@ -40,7 +40,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -88,6 +88,7 @@ __all__ = [
     "start_run",
     "end_run",
     "track_llm_call",
+    "track_mcp",
     "feedback",
     "get_tracer",
     # Cross-service propagation
@@ -425,6 +426,65 @@ def track_llm_call(
     )
 
 
+def track_mcp(
+    *,
+    tool: str,
+    distinct_id: str,
+    input: Any = None,
+    output: Any = None,
+    error: Optional[str] = None,
+    duration_ms: Optional[int] = None,
+    session_id: Optional[str] = None,
+    client_label: Optional[str] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    agent_name: str = "MCP",
+    started_at: Optional[str] = None,
+    ended_at: Optional[str] = None,
+) -> str:
+    """Record one MCP tool call as a runless span (no parent run).
+
+    Use this from inside an MCP server's ``tools/call`` handler. The MCP
+    server proxies tool calls but never sees the user's prompt or the
+    LLM's final answer, so a parent run carries no analytical value.
+    Each call to ``track_mcp`` writes one self-contained span row tagged
+    with ``agent_name='MCP'`` (overridable), ``distinct_id`` (the user),
+    and ``conversation_id`` (the MCP-Session-Id, auto-uuid'd if omitted).
+
+    Required:
+      tool: the tool name. Becomes ``name='tool.<tool>'``.
+      distinct_id: end-user attribution (email or stable user id).
+
+    Optional:
+      input, output: full args + result. Truncated at 64KB by the SDK.
+      error: if set, marks ``status='error'``.
+      duration_ms: tool wall time. Defaults to 0 if omitted.
+      session_id: the ``Mcp-Session-Id`` from the client; auto-uuid'd
+                  if omitted (each call becomes its own grouping bucket).
+      client_label: 'anthropic' / 'cursor' / 'chatgpt' / etc.; merged
+                    into attributes as ``mcp_client_label``.
+      attributes: free-form extras.
+      agent_name: defaults to 'MCP'; override only for custom tags.
+      started_at / ended_at: ISO 8601; defaults derived from now() and
+                             ``duration_ms`` so callers usually skip them.
+
+    Returns the span_id (str) for caller-side correlation/logging.
+    """
+    return _get_client().track_mcp(
+        tool=tool,
+        distinct_id=distinct_id,
+        input=input,
+        output=output,
+        error=error,
+        duration_ms=duration_ms,
+        session_id=session_id,
+        client_label=client_label,
+        attributes=attributes,
+        agent_name=agent_name,
+        started_at=started_at,
+        ended_at=ended_at,
+    )
+
+
 def feedback(
     run_id: str,
     *,

trodo/api/http_client.py

@@ -107,6 +107,11 @@ class HttpClient:
             {"spans": spans},
         )
 
+    def post_runless_spans(self, spans: list) -> ApiResult:
+        """Ingest spans with no parent run (e.g. MCP tool calls). Each span
+        MUST carry distinct_id and agent_name; the server gates on that."""
+        return self._request("/api/sdk/spans/append", {"spans": spans})
+
     def post_run_feedback(self, run_id: str, payload: Dict[str, Any]) -> ApiResult:
         from urllib.parse import quote
         return self._request(

trodo/client.py

@@ -26,6 +26,7 @@ from .otel.auto_instrument import enable_auto_instrument
 from .otel.helpers import (
     tool as tool_decorator,
     track_llm_call as track_llm_call_fn,
+    track_mcp as track_mcp_fn,
     fastapi_middleware as fastapi_middleware_fn,
     propagation_headers as propagation_headers_fn,
 )
@@ -395,6 +396,65 @@ class TrodoClient:
             metadata=metadata,
         )
 
+    def track_mcp(
+        self,
+        *,
+        tool: str,
+        distinct_id: str,
+        input: Any = None,
+        output: Any = None,
+        error: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        session_id: Optional[str] = None,
+        client_label: Optional[str] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+        agent_name: str = "MCP",
+        started_at: Optional[str] = None,
+        ended_at: Optional[str] = None,
+    ) -> str:
+        """Record a single MCP tool call as a runless span.
+
+        Use this from inside an MCP server's ``tools/call`` handler — one
+        call to ``track_mcp`` = one row in ``agent_spans`` with ``run_id``
+        NULL. The MCP server proxies tool calls but never sees the user's
+        prompt or the LLM's final answer, so a parent run carries no
+        analytical value; the span is the unit of analytics.
+
+        Required:
+          tool: the tool name (becomes ``name = "tool.<tool>"``).
+          distinct_id: end-user attribution (email or stable user id).
+
+        Optional but recommended:
+          input / output: the tool's args + full result. Truncated at 64KB.
+          error: if set, marks ``status="error"`` and stored as
+                 ``error_message``.
+          duration_ms: tool wall time. If omitted, falls back to 0.
+          session_id: the ``Mcp-Session-Id`` from the client; stored as
+                      ``conversation_id`` for grouping. Auto-uuid'd if
+                      omitted (each call becomes its own bucket).
+          client_label: which MCP client (anthropic / cursor / chatgpt /
+                        etc.); merged into attributes.
+          attributes: any extra free-form key/values.
+          agent_name: defaults to "MCP"; override only for custom tags.
+
+        Returns the span_id (str) so the caller can correlate.
+        """
+        return track_mcp_fn(
+            http=self._http,
+            tool=tool,
+            distinct_id=distinct_id,
+            input=input,
+            output=output,
+            error=error,
+            duration_ms=duration_ms,
+            session_id=session_id,
+            client_label=client_label,
+            attributes=attributes,
+            agent_name=agent_name,
+            started_at=started_at,
+            ended_at=ended_at,
+        )
+
     def fastapi_middleware(self) -> Callable:
         """Return a FastAPI/Starlette middleware that auto-joins runs."""
         return fastapi_middleware_fn(self)

trodo/otel/helpers.py

@@ -286,6 +286,96 @@ def llm(
     )
 
 
+def track_mcp(
+    *,
+    http: Any,
+    tool: str,
+    distinct_id: str,
+    input: Any = None,
+    output: Any = None,
+    error: Optional[str] = None,
+    duration_ms: Optional[int] = None,
+    session_id: Optional[str] = None,
+    client_label: Optional[str] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    agent_name: str = "MCP",
+    started_at: Optional[str] = None,
+    ended_at: Optional[str] = None,
+) -> str:
+    """Record one MCP tool call as a runless span. See ``Client.track_mcp``
+    for the customer-facing docstring; this is the implementation that
+    builds the span payload and posts it via the HttpClient.
+
+    Returns the span_id.
+    """
+    import json as _json
+    import uuid as _uuid
+    from datetime import datetime, timedelta, timezone
+
+    if not tool:
+        raise ValueError("track_mcp: 'tool' is required")
+    if not distinct_id:
+        raise ValueError("track_mcp: 'distinct_id' is required (runless spans must attribute)")
+
+    span_id = str(_uuid.uuid4())
+    conv_id = session_id or str(_uuid.uuid4())
+
+    now = datetime.now(timezone.utc)
+    if ended_at is None:
+        ended_at = now.isoformat()
+    if started_at is None:
+        offset_ms = duration_ms if isinstance(duration_ms, int) and duration_ms > 0 else 0
+        started_at = (now - timedelta(milliseconds=offset_ms)).isoformat()
+    if duration_ms is None:
+        duration_ms = 0
+
+    status = "error" if error else "ok"
+    if error:
+        error_payload: Any = {"error": error}
+        output_to_record = output if output is not None else error_payload
+    else:
+        output_to_record = output
+
+    def _stringify(value: Any) -> Any:
+        if value is None or isinstance(value, str):
+            return value
+        try:
+            return _json.dumps(value, default=str)
+        except Exception:
+            return str(value)
+
+    merged_attributes: Dict[str, Any] = dict(attributes or {})
+    if client_label:
+        merged_attributes.setdefault("mcp_client_label", client_label)
+
+    span_payload: Dict[str, Any] = {
+        "span_id": span_id,
+        "kind": "tool",
+        "name": f"tool.{tool}",
+        "status": status,
+        "input": _stringify({"tool": tool, "params": input}) if input is not None else None,
+        "output": _stringify(output_to_record),
+        "tool_name": tool,
+        "started_at": started_at,
+        "ended_at": ended_at,
+        "duration_ms": duration_ms,
+        "distinct_id": distinct_id,
+        "conversation_id": conv_id,
+        "agent_name": agent_name,
+        "error_message": error,
+        "attributes": merged_attributes,
+    }
+
+    try:
+        http.post_runless_spans([span_payload])
+    except Exception:
+        # Span loss must never break the caller's request flow. The
+        # underlying HttpClient already retries; failures here mean the
+        # backend rejected (rare) or the network is permanently down.
+        pass
+    return span_id
+
+
 def track_llm_call(
     *,
     model: Optional[str] = None,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.2.0
+Version: 2.3.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.2.0.dist-info → trodo_python-2.3.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-trodo/__init__.py,sha256=lo_QFNEk_4ylQ_4-v0RBfdA8ed30M5QjlA7ylJAiAjU,12870
-trodo/client.py,sha256=x_HjIyLMowUU-w73GYETEZWWHKjWBC-4LpG6lfLBRmU,15499
+trodo/__init__.py,sha256=FFfTNjEugSRfWUELrR4CoqAJ-zvcAYizPGQjhT7QBes,15121
+trodo/client.py,sha256=5sT3mKh-AqHnB9_duTVwvnQcPmJ90hc2GJIe0Z7j1BI,17865
 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=HKQ3d_Mxf0y4HwlHor0XkSAwUVj-4Xvv--rzE9njxjM,1027
-trodo/api/http_client.py,sha256=AELbKiABR066px2Uhq_dtkSsiVqMMP23p8QeoywzeHg,4391
+trodo/api/http_client.py,sha256=bu_tRAhlsqHnLYZhRChs3ltNWuOXzQLArNbWG0P3whg,4676
 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
@@ -14,7 +14,7 @@ trodo/managers/people_manager.py,sha256=mMVnx40Mlifx6NGgChvohC9ViK6dQu2mkXNHbV8p
 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/helpers.py,sha256=_ImekkJOWWT0pD8Vm1NuKBIps4wjCjx-72SUu7MpAyk,16172
 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
@@ -23,7 +23,7 @@ trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,87
 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-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,,
+trodo_python-2.3.0.dist-info/METADATA,sha256=7d3-wba0IywiPL8MKzEKxyjZ3el8Z_6M8MUCrnBJ55k,16353
+trodo_python-2.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trodo_python-2.3.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.3.0.dist-info/RECORD,,