trodo-python 2.1.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.1.0"
+__version__ = "2.3.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -85,7 +85,10 @@ __all__ = [
     "llm",
     "retrieval",
     "join_run",
+    "start_run",
+    "end_run",
     "track_llm_call",
+    "track_mcp",
     "feedback",
     "get_tracer",
     # Cross-service propagation
@@ -264,6 +267,52 @@ def join_run(
     )
 
 
+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,
@@ -377,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

@@ -17,6 +17,8 @@ from .otel.wrap_agent import (
     wrap_agent as wrap_agent_ctx,
     span as span_ctx,
     join_run as join_run_ctx,
+    start_run as start_run_fn,
+    end_run as end_run_fn,
     current_run_id as _current_run_id,
     current_span_id as _current_span_id,
 )
@@ -24,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,
 )
@@ -284,6 +287,51 @@ class TrodoClient:
         """Create a nested span inside the current run."""
         return span_ctx(name=name, kind=kind, input=input, attributes=attributes)
 
+    def start_run(
+        self,
+        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 outside a context manager. Returns the run_id.
+
+        Use ``end_run`` to finalise, ``join_run`` from any process to add spans.
+        """
+        return start_run_fn(
+            processor=self._span_processor,
+            agent_name=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(
+        self,
+        run_id: str,
+        *,
+        output: Any = None,
+        status: str = "ok",
+        error_summary: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Finalise a Run previously opened by :meth:`start_run`."""
+        end_run_fn(
+            run_id,
+            processor=self._span_processor,
+            output=output,
+            status=status,
+            error_summary=error_summary,
+            metadata=metadata,
+        )
+
     def join_run(
         self,
         run_id: str,
@@ -348,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/otel/processor.py

@@ -136,6 +136,25 @@ class TrodoSpanProcessor:
         except Exception:
             pass
 
+    def start_run(self, run: TrodoRun) -> None:
+        """Open a Run row server-side without holding a context manager.
+
+        Pairs with ``end_run`` for sessions that span multiple processes or
+        HTTP requests. Spans emitted between start_run and end_run flush
+        incrementally via append_spans (callers are expected to mark_joined).
+        """
+        try:
+            self._http.post_run_start({"run": run.to_dict()})
+        except Exception:
+            pass
+
+    def end_run(self, run_id: str, payload: Dict[str, Any]) -> None:
+        """Finalise a Run opened by start_run."""
+        try:
+            self._http.post_run_end(run_id, payload)
+        except Exception:
+            pass
+
     def append_spans(self, run_id: str, spans: List[TrodoSpan]) -> None:
         """Stream spans for a long-running or joined run without finalising."""
         if not spans:

trodo/otel/wrap_agent.py

@@ -163,6 +163,76 @@ class SpanHandle:
         self.tool_name = tool_name
 
 
+def start_run(
+    *,
+    processor: TrodoSpanProcessor,
+    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 holding a context manager.
+
+    Pairs with :func:`end_run` for sessions that span multiple processes or
+    HTTP requests (e.g. an MCP server where ``initialize`` opens a run and
+    later ``tools/call`` requests append spans before a final close).
+
+    Returns the ``run_id`` (caller-supplied or freshly minted UUID). Between
+    ``start_run`` and ``end_run`` any process can use ``join_run(run_id, ...)``
+    to add spans — they flush incrementally via ``append_spans``.
+    """
+    rid = run_id or str(uuid.uuid4())
+    run = TrodoRun(
+        run_id=rid,
+        agent_name=agent_name,
+        distinct_id=distinct_id,
+        conversation_id=conversation_id,
+        parent_run_id=parent_run_id,
+        status="running",
+        input=_truncate(input),
+        started_at=_now_iso(),
+        metadata=metadata,
+    )
+    processor.mark_joined(rid)
+    processor.start_run(run)
+    return rid
+
+
+def end_run(
+    run_id: str,
+    *,
+    processor: TrodoSpanProcessor,
+    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`.
+
+    Aggregates any locally-buffered spans for ``run_id``, POSTs to the
+    ``/runs/{id}/end`` endpoint, and unmarks the run as joined. Idempotent
+    on the local-state side; the backend treats a second call as a row update.
+    """
+    pending = processor.get_pending(run_id)
+    agg = _aggregate(pending)
+    payload: Dict[str, Any] = {
+        "ended_at": _now_iso(),
+        "status": status,
+        **agg,
+    }
+    if output is not None:
+        payload["output"] = _truncate(output)
+    if error_summary is not None:
+        payload["error_summary"] = _truncate(error_summary, 4_000)
+    if metadata is not None:
+        payload["metadata"] = metadata
+    processor.end_run(run_id, payload)
+    processor.unmark_joined(run_id)
+
+
 class wrap_agent:
     """Context manager wrapping an agent run.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.1.0
+Version: 2.3.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -263,6 +263,34 @@ with trodo.join_run(
     ...
 ```
 
+### 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

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

@@ -1,11 +1,11 @@
-trodo/__init__.py,sha256=dQ7g0ETsOiDsrgrF9fBV7PCNplmc49Ffrha8RG3zBvo,11603
-trodo/client.py,sha256=0D_1AXpIQYThwZ_Y03CpfGyhblHTsRYiWIKY3JkAuZE,14092
+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,16 +14,16 @@ 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/processor.py,sha256=AHEfNGmSG0nrdUDgb__2_7PdBZM4sij26IugUN-E4Ko,5576
-trodo/otel/wrap_agent.py,sha256=xdJ2C6GrNaL38hy29m5QAprqcCJWJRlEAW9GHB765I0,15237
+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
 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-2.1.0.dist-info/METADATA,sha256=GMxU5fOOj4H2cXu9hV0QPER4XtnMXyyWvLmtMLFWpd8,15259
-trodo_python-2.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-trodo_python-2.1.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.1.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,,