trodo-python 2.1.0__py3-none-any.whl → 2.2.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.2.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -85,6 +85,8 @@ __all__ = [
     "llm",
     "retrieval",
     "join_run",
+    "start_run",
+    "end_run",
     "track_llm_call",
     "feedback",
     "get_tracer",
@@ -264,6 +266,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,

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,
 )
@@ -284,6 +286,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,

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.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.1.0
+Version: 2.2.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.2.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-trodo/__init__.py,sha256=dQ7g0ETsOiDsrgrF9fBV7PCNplmc49Ffrha8RG3zBvo,11603
-trodo/client.py,sha256=0D_1AXpIQYThwZ_Y03CpfGyhblHTsRYiWIKY3JkAuZE,14092
+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
@@ -15,15 +15,15 @@ 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/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.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,,