torrix-sdk 1.1.0__tar.gz

torrix_sdk-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Torrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

torrix_sdk-1.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: torrix-sdk
+Version: 1.1.0
+Summary: Python SDK for Torrix, self-hosted observability for AI agents: record OpenAI and Anthropic calls with no dependencies.
+Author: Torrix
+License: MIT
+Project-URL: Homepage, https://github.com/TorrixAI/torrix
+Project-URL: Documentation, https://github.com/TorrixAI/torrix/blob/main/docs/integrations/python-sdk.md
+Project-URL: Issues, https://github.com/TorrixAI/torrix/issues
+Keywords: llm,observability,ai-agents,openai,anthropic,tracing,cost,self-hosted
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
+Dynamic: license-file
+
+# Torrix Python SDK
+
+Record every OpenAI and Anthropic call your Python app or agent makes in
+[Torrix](https://github.com/TorrixAI/torrix), the self-hosted observability platform for AI agents.
+You get the prompt, response, tokens, cost, latency and tool calls of each call, grouped into
+traces and sessions.
+
+- No dependencies of its own. Works with sync, async and streaming clients.
+- Sends data in a background thread, so your app is not slowed down.
+- Your data goes only to your own Torrix server.
+
+## Install
+
+```bash
+pip install torrix-sdk
+```
+
+You also need a running Torrix server. The quickest way:
+
+```bash
+docker run -d --name torrix -p 8088:8088 -v torrix_data:/data gettorrixai/torrix:latest
+```
+
+Open http://localhost:8088, create your account, and copy an API key from **Integrations**.
+
+## Use
+
+The package installs as `torrix-sdk` and imports as `torrix`.
+
+```python
+import torrix
+
+torrix.init(api_key="trxk_YOUR_KEY", base_url="http://localhost:8088")
+```
+
+That is all. Every call made through the installed `openai` and `anthropic` packages is recorded
+from now on.
+
+Group calls into one turn and name the agent that made them:
+
+```python
+with torrix.run_context(session_id="chat-7", agent_name="support-bot"):
+    answer = client.chat.completions.create(model="gpt-4o-mini", messages=[...])
+```
+
+Short scripts and serverless functions should call `torrix.flush()` before they exit.
+
+## Learn more
+
+- [Python SDK guide](https://github.com/TorrixAI/torrix/blob/main/docs/integrations/python-sdk.md)
+- [How Torrix organizes your data](https://github.com/TorrixAI/torrix/blob/main/docs/concepts.md)
+- [Torrix on GitHub](https://github.com/TorrixAI/torrix)
+
+MIT licensed.

torrix_sdk-1.1.0/README.md

@@ -0,0 +1,54 @@
+# Torrix Python SDK
+
+Record every OpenAI and Anthropic call your Python app or agent makes in
+[Torrix](https://github.com/TorrixAI/torrix), the self-hosted observability platform for AI agents.
+You get the prompt, response, tokens, cost, latency and tool calls of each call, grouped into
+traces and sessions.
+
+- No dependencies of its own. Works with sync, async and streaming clients.
+- Sends data in a background thread, so your app is not slowed down.
+- Your data goes only to your own Torrix server.
+
+## Install
+
+```bash
+pip install torrix-sdk
+```
+
+You also need a running Torrix server. The quickest way:
+
+```bash
+docker run -d --name torrix -p 8088:8088 -v torrix_data:/data gettorrixai/torrix:latest
+```
+
+Open http://localhost:8088, create your account, and copy an API key from **Integrations**.
+
+## Use
+
+The package installs as `torrix-sdk` and imports as `torrix`.
+
+```python
+import torrix
+
+torrix.init(api_key="trxk_YOUR_KEY", base_url="http://localhost:8088")
+```
+
+That is all. Every call made through the installed `openai` and `anthropic` packages is recorded
+from now on.
+
+Group calls into one turn and name the agent that made them:
+
+```python
+with torrix.run_context(session_id="chat-7", agent_name="support-bot"):
+    answer = client.chat.completions.create(model="gpt-4o-mini", messages=[...])
+```
+
+Short scripts and serverless functions should call `torrix.flush()` before they exit.
+
+## Learn more
+
+- [Python SDK guide](https://github.com/TorrixAI/torrix/blob/main/docs/integrations/python-sdk.md)
+- [How Torrix organizes your data](https://github.com/TorrixAI/torrix/blob/main/docs/concepts.md)
+- [Torrix on GitHub](https://github.com/TorrixAI/torrix)
+
+MIT licensed.

torrix_sdk-1.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "torrix-sdk"
+version = "1.1.0"
+description = "Python SDK for Torrix, self-hosted observability for AI agents: record OpenAI and Anthropic calls with no dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Torrix" }]
+keywords = ["llm", "observability", "ai-agents", "openai", "anthropic", "tracing", "cost", "self-hosted"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.30.0"]
+
+[project.urls]
+Homepage = "https://github.com/TorrixAI/torrix"
+Documentation = "https://github.com/TorrixAI/torrix/blob/main/docs/integrations/python-sdk.md"
+Issues = "https://github.com/TorrixAI/torrix/issues"
+
+[tool.setuptools.packages.find]
+include = ["torrix*"]
+
+[tool.setuptools.package-data]
+torrix = ["py.typed"]

torrix_sdk-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

torrix_sdk-1.1.0/tests/test_context.py

@@ -0,0 +1,79 @@
+"""Run context linkage, checked against a local capture server (stdlib only)."""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Dict, List
+
+from torrix import run_context
+from torrix._client import TorrixClient
+
+
+class _Capture(BaseHTTPRequestHandler):
+    records: List[Dict[str, Any]] = []
+
+    def do_POST(self) -> None:  # noqa: N802 (http.server naming)
+        length = int(self.headers.get("content-length", "0"))
+        body = json.loads(self.rfile.read(length) or b"{}")
+        batch = body.get("records", body if isinstance(body, list) else [])
+        _Capture.records.extend(batch)
+        payload = json.dumps({"accepted": len(batch), "ids": [r.get("id") for r in batch]}).encode()
+        self.send_response(200)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, *_: Any) -> None:
+        return
+
+
+class RunContextTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.server = HTTPServer(("127.0.0.1", 0), _Capture)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.client = TorrixClient(f"http://127.0.0.1:{cls.server.server_port}", "trxk_test", background=False)
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.server.shutdown()
+
+    def setUp(self) -> None:
+        _Capture.records.clear()
+
+    def test_sequential_calls_are_siblings(self) -> None:
+        with run_context(session_id="ses_1", agent_name="planner", name="plan"):
+            self.client.ingest({"id": "first"}, wait=True)
+            self.client.ingest({"id": "second"}, wait=True)
+        first, second = _Capture.records
+        self.assertEqual(first["session_id"], "ses_1")
+        self.assertEqual(first["agent_name"], "planner")
+        self.assertEqual(first["name"], "plan")
+        self.assertNotIn("parent_run_id", first)
+        self.assertNotIn("parent_run_id", second)
+        self.assertEqual(first["trace_id"], second["trace_id"])
+
+    def test_nested_context_hangs_under_the_call_that_started_it(self) -> None:
+        with run_context(agent_name="planner"):
+            self.client.ingest({"id": "plan"}, wait=True)
+            for agent in ("search", "write"):
+                with run_context(agent_name=agent):
+                    self.client.ingest({"id": f"{agent}-1"}, wait=True)
+                    self.client.ingest({"id": f"{agent}-2"}, wait=True)
+            self.client.ingest({}, wait=True)
+        by_id = {r["id"]: r for r in _Capture.records}
+        self.assertEqual(by_id["search-1"]["parent_run_id"], "plan")
+        self.assertEqual(by_id["search-2"]["parent_run_id"], "plan")
+        self.assertEqual(by_id["search-1"]["agent_name"], "search")
+        # Each subagent context opens under the planner's latest call, not under its sibling.
+        self.assertEqual(by_id["write-1"]["parent_run_id"], "plan")
+        last = _Capture.records[-1]
+        self.assertTrue(last["id"])
+        self.assertNotIn("parent_run_id", last)
+        self.assertEqual(len({r["trace_id"] for r in _Capture.records}), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

torrix_sdk-1.1.0/torrix/__init__.py

@@ -0,0 +1,157 @@
+"""torrix — self-hosted LLM observability SDK.
+
+Intercept and log every model call your application makes to a Torrix
+instance. Two usage styles are supported:
+
+``torrix.init(...)`` then ``torrix.wrap()``
+    Apply a global patch to the OpenAI or Anthropic SDK so
+    ``chat.completions.create`` / ``messages.create`` are captured
+    automatically (sync and async, streaming included).
+
+``torrix.ingest(record)``
+    Log arbitrary run records manually — useful for providers without a
+    ready-made wrapper or for custom tooling. Records are delivered by a
+    background thread and flushed on process exit.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from ._client import TorrixClient, TorrixError
+from ._context import current_context, run_context
+from ._wrap import patch_classes as _patch_classes
+from ._wrap import wrap as _wrap_sdk
+from ._wrap import unwrap as _unpatch
+
+__all__ = [
+    "init",
+    "wrap",
+    "unwrap",
+    "ingest",
+    "flush",
+    "current",
+    "get_client",
+    "run_context",
+    "current_run_context",
+    "TorrixClient",
+    "TorrixError",
+]
+__version__ = "1.1.0"
+
+_DEFAULT: Optional[TorrixClient] = None
+
+
+def init(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    *,
+    project: Optional[str] = None,
+    sample_rate: float = 1.0,
+    timeout: float = 10.0,
+    enabled: bool = True,
+    background: bool = True,
+    auto_instrument: bool = True,
+) -> TorrixClient:
+    """Configure the default Torrix client used by ``wrap`` and ``ingest``.
+
+    ``api_key`` is one of your Torrix API keys (``trxk_...``) and ``base_url``
+    points at the running Torrix server (default ``http://localhost:8088``).
+    The older ``init(base_url, api_key)`` order is detected and accepted.
+    ``project`` selects the project by id or name; when omitted the account's
+    default project is used. ``sample_rate`` in ``(0, 1]`` controls what
+    fraction of calls are recorded.
+
+    Unless ``auto_instrument=False``, init patches the OpenAI and Anthropic SDK
+    resource classes (whichever are installed) so calls are traced without an
+    explicit ``wrap()``; ``wrap()`` then becomes a no-op returning the existing
+    handle.
+    """
+    global _DEFAULT
+    api_key, base_url = _normalize_endpoint(api_key, base_url)
+    _DEFAULT = TorrixClient(
+        base_url,
+        api_key,
+        project=project,
+        sample_rate=sample_rate,
+        timeout=timeout,
+        enabled=enabled,
+        background=background,
+    )
+    if auto_instrument:
+        for provider in ("openai", "anthropic"):
+            try:
+                _patch_classes(provider)
+            except Exception:
+                # the SDK is optional; a missing library is not an error
+                pass
+    return _DEFAULT
+
+
+def _normalize_endpoint(
+    api_key: Optional[str],
+    base_url: Optional[str],
+) -> tuple[Optional[str], str]:
+    default = "http://localhost:8088"
+    looks_like_url = isinstance(api_key, str) and api_key.startswith(("http://", "https://"))
+    if looks_like_url and (base_url is None or not base_url.startswith(("http://", "https://"))):
+        # Legacy init(base_url, api_key) order.
+        return base_url or None, api_key.rstrip("/")
+    return api_key, (base_url or default).rstrip("/")
+
+
+def current() -> Optional[TorrixClient]:
+    """Return the default client configured by ``init`` (or ``None``)."""
+    return _DEFAULT
+
+
+def get_client() -> Optional[TorrixClient]:
+    """Alias for :func:`current`."""
+    return _DEFAULT
+
+
+def current_run_context() -> Optional[Dict[str, Any]]:
+    """Return the active run context fields, or ``None`` outside a context."""
+    return current_context()
+
+
+def wrap(target: Any = None, provider: Optional[str] = None) -> Any:
+    """Patch the OpenAI or Anthropic SDK to auto-log calls into Torrix.
+
+    ``wrap()`` / ``wrap("anthropic")`` patch the SDK resource classes globally
+    (sync, async and streaming). ``wrap(client)`` returns a tracing proxy for a
+    single client instance instead. The handle returned by the class-level form
+    can be passed to ``unwrap``; proxies are dropped by using the raw client
+    again.
+    """
+    return _wrap_sdk(target, provider)
+
+
+def unwrap(handle: Optional[int] = None) -> None:
+    """Restore the original SDK methods for a wrapped ``handle`` (or all)."""
+    _unpatch(handle)
+
+
+def ingest(records: Union[Dict[str, Any], List[Dict[str, Any]]], *, wait: bool = False) -> List[str]:
+    """Log one or several run records through the default client.
+
+    Background delivery is the default; pass ``wait=True`` to block until the
+    records are accepted and receive their ids. Raises :class:`TorrixError` if
+    no client has been configured with :func:`init`.
+    """
+    if _DEFAULT is None:
+        raise TorrixError("torrix not initialized: call torrix.init() first")
+    return _DEFAULT.ingest(records, wait=wait)
+
+
+def flush(timeout: float = 5.0) -> bool:
+    """Wait for queued records to be delivered (5 second default)."""
+    if _DEFAULT is None:
+        return True
+    return _DEFAULT.flush(timeout)
+
+
+def health() -> bool:
+    if _DEFAULT is None:
+        return False
+    return _DEFAULT.health()

torrix_sdk-1.1.0/torrix/_client.py

@@ -0,0 +1,197 @@
+"""Low-level ingest client for the Torrix server.
+
+Records are queued and delivered by a background daemon thread, so logging
+never blocks a request path. The queue is flushed on interpreter shutdown
+(``atexit``) and can be flushed manually with :meth:`TorrixClient.flush`.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import queue
+import random
+import uuid
+import threading
+import time
+from typing import Any, Dict, List, Optional, Union
+from urllib import request
+
+from ._context import current_context
+
+
+class TorrixError(RuntimeError):
+    """Raised when the Torrix server rejects a payload or cannot be reached."""
+
+
+_BATCH_SIZE = 500
+_FLUSH_TIMEOUT_SECONDS = 5.0
+
+
+class TorrixClient:
+    """Posts run records to a Torrix instance over HTTP."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        *,
+        project: Optional[str] = None,
+        sample_rate: float = 1.0,
+        timeout: float = 10.0,
+        enabled: bool = True,
+        background: bool = True,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.project = project
+        self.sample_rate = _clamp01(sample_rate)
+        self.timeout = timeout
+        self.enabled = enabled
+        self.background = background
+        self._accepted = 0
+        self._dropped = 0
+        self._last_error: Optional[str] = None
+        self._queue: "queue.Queue[List[Dict[str, Any]] | None]" = queue.Queue()
+        self._worker: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+        self._closed = False
+        if background:
+            self._worker = threading.Thread(target=self._worker_loop, name="torrix-ingest", daemon=True)
+            self._worker.start()
+            atexit.register(self.close)
+
+    def ingest(
+        self,
+        records: Union[Dict[str, Any], List[Dict[str, Any]]],
+        *,
+        wait: bool = False,
+    ) -> List[str]:
+        """Send one run record (or a batch) and return the accepted run ids.
+
+        With the default background mode the call returns immediately (an empty
+        list) after queueing; pass ``wait=True`` to deliver synchronously and
+        receive the ids. Each record accepts the fields documented for
+        ``POST /api/ingest``: ``request`` / ``response`` (each ``{"body": ...}``),
+        ``model``, ``provider``, ``status``, ``error``, ``latency_ms``,
+        ``start_time`` / ``end_time``, ``input_tokens``, ``output_tokens``,
+        ``cost_usd``, ``target_url``, ``trace_id``, ``session_id``, ``tags``.
+        """
+        if not self.enabled or self._closed:
+            return []
+        items = [records] if isinstance(records, dict) else list(records)
+        if not items:
+            return []
+        context = current_context()
+        if context:
+            for record in items:
+                if not isinstance(record, dict):
+                    continue
+                record.setdefault("trace_id", context.get("trace_id"))
+                if context.get("session_id"):
+                    record.setdefault("session_id", context["session_id"])
+                if context.get("agent_name"):
+                    record.setdefault("agent_name", context["agent_name"])
+                # Calls inside one context are siblings under the context's parent;
+                # only a nested context hangs under the latest call of its enclosing one.
+                if context.get("parent_run_id"):
+                    record.setdefault("parent_run_id", context["parent_run_id"])
+                if context.get("name") and not record.get("name"):
+                    record["name"] = context["name"]
+                record.setdefault("id", uuid.uuid4().hex)
+                context["last_run_id"] = record["id"]
+
+        accepted: List[str] = []
+        for start in range(0, len(items), _BATCH_SIZE):
+            batch = [r for r in items[start : start + _BATCH_SIZE] if random.random() < self.sample_rate]
+            if not batch:
+                continue
+            if self.background and not wait:
+                self._queue.put(batch)
+            else:
+                accepted.extend(self._send(batch, timeout=self.timeout))
+        self._accepted += len(accepted)
+        self._dropped += len(items) - len(accepted)
+        return accepted
+
+    def flush(self, timeout: float = _FLUSH_TIMEOUT_SECONDS) -> bool:
+        """Block until the queue drains or ``timeout`` elapses."""
+        if not self.background:
+            return True
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._queue.unfinished_tasks == 0:
+                return True
+            time.sleep(0.01)
+        return self._queue.unfinished_tasks == 0
+
+    def close(self) -> None:
+        """Flush pending records and stop the worker thread."""
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+        if self.background:
+            self.flush()
+            self._queue.put(None)
+            if self._worker is not None:
+                self._worker.join(timeout=1.0)
+
+    def stats(self) -> Dict[str, Any]:
+        return {
+            "accepted": self._accepted,
+            "dropped": self._dropped,
+            "queued": self._queue.qsize(),
+            "last_error": self._last_error,
+        }
+
+    def _worker_loop(self) -> None:
+        while True:
+            batch = self._queue.get()
+            try:
+                if batch is None:
+                    return
+                self._send(batch, timeout=min(self.timeout, _FLUSH_TIMEOUT_SECONDS))
+            except TorrixError as exc:
+                self._last_error = str(exc)
+            except Exception as exc:  # pragma: no cover - defensive
+                self._last_error = str(exc)
+            finally:
+                self._queue.task_done()
+
+    def _send(self, batch: List[Dict[str, Any]], *, timeout: float) -> List[str]:
+        url = f"{self.base_url}/api/ingest"
+        payload = json.dumps({"records": batch}).encode("utf-8")
+        headers = {"content-type": "application/json", "user-agent": "torrix-sdk/1.1.0"}
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        if self.project:
+            headers["x-torrix-project"] = self.project
+        req = request.Request(url, data=payload, headers=headers, method="POST")
+        try:
+            with request.urlopen(req, timeout=timeout) as resp:
+                body = resp.read().decode("utf-8")
+                if resp.status >= 400:
+                    raise TorrixError(f"ingest rejected with HTTP {resp.status}: {body}")
+                parsed = json.loads(body) if body else {}
+                return list(parsed.get("ids", []))
+        except TorrixError:
+            self._last_error = "torrix_rejected"
+            raise
+        except Exception as exc:  # network, DNS, timeout
+            self._last_error = str(exc)
+            raise TorrixError(f"torrix unreachable: {exc}") from exc
+
+    def health(self) -> bool:
+        try:
+            with request.urlopen(f"{self.base_url}/health", timeout=self.timeout) as resp:
+                return resp.status == 200
+        except Exception:
+            return False
+
+
+def _clamp01(value: float) -> float:
+    try:
+        return min(1.0, max(0.0, float(value)))
+    except (TypeError, ValueError):
+        return 1.0

torrix_sdk-1.1.0/torrix/_context.py

@@ -0,0 +1,53 @@
+"""Run context propagation for automatic trace and parent linkage.
+
+``torrix.run_context(...)`` groups every call made inside the block into one
+trace and chains parent-child relationships without manual ids, so nested
+``torrix.wrap()`` calls build an agent tree on their own.
+"""
+
+from __future__ import annotations
+
+import uuid
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Dict, Iterator, Optional
+
+_current: ContextVar[Optional[Dict[str, Any]]] = ContextVar("torrix_run_context", default=None)
+
+
+def current_context() -> Optional[Dict[str, Any]]:
+    """Return the active run context, if any (mostly useful in tests/debugging)."""
+    return _current.get()
+
+
+@contextmanager
+def run_context(
+    name: Optional[str] = None,
+    trace_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    parent_run_id: Optional[str] = None,
+) -> Iterator[Dict[str, Any]]:
+    """Group calls into one trace and auto-link parents.
+
+    Records created inside the block inherit the context's ``trace_id``,
+    ``session_id`` and ``agent_name`` when they do not set their own. Calls in
+    the same block are siblings: they all get the block's ``parent_run_id``
+    (the enclosing context's latest run when the block was opened). Nested
+    blocks therefore hang a subagent's calls under the call that started it,
+    without turning sequential calls into one long chain.
+    """
+    parent = _current.get() or {}
+    context: Dict[str, Any] = {
+        "trace_id": trace_id or parent.get("trace_id") or uuid.uuid4().hex,
+        "session_id": session_id or parent.get("session_id"),
+        "agent_name": agent_name or parent.get("agent_name"),
+        "parent_run_id": parent_run_id or parent.get("last_run_id"),
+        "name": name or parent.get("name"),
+        "last_run_id": None,
+    }
+    token = _current.set(context)
+    try:
+        yield context
+    finally:
+        _current.reset(token)