torina 0.1.1__tar.gz

torina-0.1.1/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: torina
+Version: 0.1.1
+Summary: Trace ingestion client for Torina — captures LLM agent traces and forwards them over HTTP.
+Author: noahwg
+Author-email: noahwg <nwg7199@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: wrapt>=1.14
+Requires-Python: >=3.8
+Project-URL: Homepage, https://github.com/Tribemails/torina-python-lib
+Project-URL: Issues, https://github.com/Tribemails/torina-python-lib/issues
+Description-Content-Type: text/markdown
+
+# torina
+
+Captures LLM agent traces (currently: LangChain) and forwards them to a
+Torina HTTP ingestion endpoint via a single POST per trace, authenticated
+with an `x-api-key` header. Not built on OpenTelemetry — it patches
+LangChain's own callback system directly, so the only dependency is
+[wrapt](https://github.com/GrahamDumpleton/wrapt).
+
+## Install
+
+```bash
+uv add torina
+# or
+pip install torina
+```
+
+## Usage
+
+```python
+import os
+import torina
+
+torina.auto_instrument()
+torina.init_logger(
+    api_key=os.environ["TORINA_API_KEY"],
+    project="My Project (Python)",
+    endpoint="https://ingest.torina.example/v1/traces",  # or set TORINA_ENDPOINT
+)
+```
+
+`auto_instrument()` patches LangChain automatically if it's installed, so
+every `agent.invoke()`/`.stream()` call anywhere in your app gets captured
+with no per-call-site changes. A trace is uploaded whole — one HTTP request
+per completed trace (every `llm`/`tool` span it contains, plus any `chain`
+span that carries real data — empty structural wrapper chains, like
+LangGraph's internal per-step nodes, are pruned), not one request per span.
+
+Every trace carries `payload["source"]` (`"langchain"` today — the only
+integration so far) so traces from different sources stay distinguishable as
+more get added later.
+
+A few things get deduplicated rather than taken at face value. Tool schemas
+and the system prompt are both usually identical across every LLM call in a
+trace — they're a property of the agent's definition, not the individual
+call, but get resent on every call because that's how chat APIs work. Both
+get hoisted to `payload["tool_definitions"]` / `payload["system_prompt"]`
+when they match across every `llm` span — left per-span only if a trace
+genuinely varied them mid-conversation.
+
+Spans don't carry `parent_span_id` — there's no span tree. Relationships that
+matter are expressed directly instead: a `tool` span's `tool_call_id` matches
+the `id` in the requesting `llm` span's `output_message.tool_calls`, which is
+more precise than a parent/child edge would be anyway (LangChain's own run
+tree only reflects LangGraph's internal step wrappers, not which `llm` call
+actually caused which `tool` call).
+
+Conversation grouping, the agent's name, and arbitrary metadata all come from
+LangChain's own `config`/`create_agent(name=...)`, no Torina-specific code
+needed:
+
+```python
+agent = create_agent(..., name="weather-agent")  # -> payload["agent_name"]
+
+agent.invoke(
+    {"messages": [...]},
+    config={
+        "configurable": {"thread_id": thread_id},  # -> payload["conversation_id"]
+        "metadata": {"user_id": "u_123", "plan": "enterprise"},  # -> payload["metadata"]
+    },
+)
+```
+
+For manual control over a specific call site instead of the global patch,
+`TorinaCallbackHandler` is available directly (requires `langchain-core`):
+
+```python
+from torina.langchain import TorinaCallbackHandler
+
+agent.invoke({"messages": [...]}, config={"callbacks": [TorinaCallbackHandler()]})
+```
+
+### dry_run
+
+```python
+torina.init_logger(dry_run=True)  # no api_key or endpoint needed
+```
+
+Traces are logged instead of sent — useful for local testing before you have
+a real endpoint. Same code path either way; `dry_run` only swaps the network
+call for a log line.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## Releasing
+
+Publishing to PyPI happens via [`.github/workflows/publish.yml`](.github/workflows/publish.yml),
+triggered by a GitHub release. It uses [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC), so no PyPI API token is stored in the repo.
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml).
+2. Commit and push to `main`.
+3. Tag and create a release:
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   gh release create vX.Y.Z --title vX.Y.Z --generate-notes
+   ```
+4. Publishing the release triggers the workflow, which runs `uv build` and
+   `uv publish`. Check the Actions tab for the run, then confirm at
+   [pypi.org/project/torina](https://pypi.org/project/torina/).

torina-0.1.1/README.md

@@ -0,0 +1,118 @@
+# torina
+
+Captures LLM agent traces (currently: LangChain) and forwards them to a
+Torina HTTP ingestion endpoint via a single POST per trace, authenticated
+with an `x-api-key` header. Not built on OpenTelemetry — it patches
+LangChain's own callback system directly, so the only dependency is
+[wrapt](https://github.com/GrahamDumpleton/wrapt).
+
+## Install
+
+```bash
+uv add torina
+# or
+pip install torina
+```
+
+## Usage
+
+```python
+import os
+import torina
+
+torina.auto_instrument()
+torina.init_logger(
+    api_key=os.environ["TORINA_API_KEY"],
+    project="My Project (Python)",
+    endpoint="https://ingest.torina.example/v1/traces",  # or set TORINA_ENDPOINT
+)
+```
+
+`auto_instrument()` patches LangChain automatically if it's installed, so
+every `agent.invoke()`/`.stream()` call anywhere in your app gets captured
+with no per-call-site changes. A trace is uploaded whole — one HTTP request
+per completed trace (every `llm`/`tool` span it contains, plus any `chain`
+span that carries real data — empty structural wrapper chains, like
+LangGraph's internal per-step nodes, are pruned), not one request per span.
+
+Every trace carries `payload["source"]` (`"langchain"` today — the only
+integration so far) so traces from different sources stay distinguishable as
+more get added later.
+
+A few things get deduplicated rather than taken at face value. Tool schemas
+and the system prompt are both usually identical across every LLM call in a
+trace — they're a property of the agent's definition, not the individual
+call, but get resent on every call because that's how chat APIs work. Both
+get hoisted to `payload["tool_definitions"]` / `payload["system_prompt"]`
+when they match across every `llm` span — left per-span only if a trace
+genuinely varied them mid-conversation.
+
+Spans don't carry `parent_span_id` — there's no span tree. Relationships that
+matter are expressed directly instead: a `tool` span's `tool_call_id` matches
+the `id` in the requesting `llm` span's `output_message.tool_calls`, which is
+more precise than a parent/child edge would be anyway (LangChain's own run
+tree only reflects LangGraph's internal step wrappers, not which `llm` call
+actually caused which `tool` call).
+
+Conversation grouping, the agent's name, and arbitrary metadata all come from
+LangChain's own `config`/`create_agent(name=...)`, no Torina-specific code
+needed:
+
+```python
+agent = create_agent(..., name="weather-agent")  # -> payload["agent_name"]
+
+agent.invoke(
+    {"messages": [...]},
+    config={
+        "configurable": {"thread_id": thread_id},  # -> payload["conversation_id"]
+        "metadata": {"user_id": "u_123", "plan": "enterprise"},  # -> payload["metadata"]
+    },
+)
+```
+
+For manual control over a specific call site instead of the global patch,
+`TorinaCallbackHandler` is available directly (requires `langchain-core`):
+
+```python
+from torina.langchain import TorinaCallbackHandler
+
+agent.invoke({"messages": [...]}, config={"callbacks": [TorinaCallbackHandler()]})
+```
+
+### dry_run
+
+```python
+torina.init_logger(dry_run=True)  # no api_key or endpoint needed
+```
+
+Traces are logged instead of sent — useful for local testing before you have
+a real endpoint. Same code path either way; `dry_run` only swaps the network
+call for a log line.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## Releasing
+
+Publishing to PyPI happens via [`.github/workflows/publish.yml`](.github/workflows/publish.yml),
+triggered by a GitHub release. It uses [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC), so no PyPI API token is stored in the repo.
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml).
+2. Commit and push to `main`.
+3. Tag and create a release:
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   gh release create vX.Y.Z --title vX.Y.Z --generate-notes
+   ```
+4. Publishing the release triggers the workflow, which runs `uv build` and
+   `uv publish`. Check the Actions tab for the run, then confirm at
+   [pypi.org/project/torina](https://pypi.org/project/torina/).

torina-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "torina"
+version = "0.1.1"
+description = "Trace ingestion client for Torina — captures LLM agent traces and forwards them over HTTP."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "noahwg", email = "nwg7199@gmail.com" }
+]
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "wrapt>=1.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/Tribemails/torina-python-lib"
+Issues = "https://github.com/Tribemails/torina-python-lib/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.6",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["uv_build>=0.9.3,<0.10.0"]
+build-backend = "uv_build"

torina-0.1.1/src/torina/__init__.py

@@ -0,0 +1,6 @@
+from torina._instrumentation import auto_instrument
+from torina._logger import init_logger
+
+__version__ = "0.1.0"
+
+__all__ = ["auto_instrument", "init_logger", "__version__"]

torina-0.1.1/src/torina/_config.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class _Config:
+    api_key: Optional[str] = None
+    endpoint: Optional[str] = None
+    project: Optional[str] = None
+    timeout: float = 10.0
+    dry_run: bool = False
+
+
+config = _Config()

torina-0.1.1/src/torina/_forwarder.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from torina._config import config
+from torina._http import HttpError, post_json
+
+logger = logging.getLogger("torina")
+
+_SCAFFOLD_FIELDS = {"span_id", "type", "name", "start_time", "end_time"}
+
+
+def _prune_empty_chain_spans(spans: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Drop chain spans that carry no data beyond timing/name — e.g. LangGraph's
+    internal per-step wrapper nodes, or a root chain span once its metadata has been
+    extracted. Spans don't track parent/child relationships, so this is a plain
+    filter, nothing to re-parent."""
+    return [
+        s for s in spans if not (s.get("type") == "chain" and not (set(s.keys()) - _SCAFFOLD_FIELDS))
+    ]
+
+
+def _hoist_common_tool_definitions(spans: List[Dict[str, Any]]) -> Optional[Any]:
+    """If every llm span in the trace was bound to the identical tool set (the common
+    case — tools are usually per-agent-definition, not per-call), lift it out to the
+    trace level and strip it from each span. If they differ, leave each span's copy
+    alone rather than guess which one is "right"."""
+    llm_spans = [s for s in spans if s.get("type") == "llm" and "tool_definitions" in s]
+    if not llm_spans:
+        return None
+    first = llm_spans[0]["tool_definitions"]
+    if any(s["tool_definitions"] != first for s in llm_spans):
+        return None
+    for s in llm_spans:
+        del s["tool_definitions"]
+    return first
+
+
+def _hoist_common_system_prompt(spans: List[Dict[str, Any]]) -> Optional[str]:
+    """If every llm span's first input message is the identical system prompt (the
+    common case — it's part of the agent's definition, resent unchanged with every
+    call because that's how chat APIs work, not something that varies per call),
+    lift it out to the trace level and drop it from each span's input_messages. If
+    it ever differs between spans, leave each span's copy alone."""
+
+    def system_content(s: Dict[str, Any]) -> Optional[str]:
+        messages = s.get("input_messages")
+        if messages and messages[0].get("role") == "system":
+            return messages[0].get("content")
+        return None
+
+    llm_spans = [s for s in spans if s.get("type") == "llm" and system_content(s) is not None]
+    if not llm_spans:
+        return None
+    first = system_content(llm_spans[0])
+    if any(system_content(s) != first for s in llm_spans):
+        return None
+    for s in llm_spans:
+        s["input_messages"] = s["input_messages"][1:]
+    return first
+
+
+def forward_trace(
+    trace_id: str,
+    spans: List[Dict[str, Any]],
+    *,
+    source: str,
+    conversation_id: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Send one completed trace to Torina.
+
+    source identifies which integration captured this trace (e.g. "langchain"),
+    so traces from different sources can be told apart once more are added.
+    conversation_id/agent_name/metadata are already-resolved values — each
+    integration is responsible for pulling them out of its own framework's
+    conventions before calling this.
+    """
+    tool_definitions = _hoist_common_tool_definitions(spans)
+    system_prompt = _hoist_common_system_prompt(spans)
+    spans = _prune_empty_chain_spans(spans)
+
+    payload: Dict[str, Any] = {
+        "trace_id": trace_id,
+        "source": source,
+        "conversation_id": conversation_id,
+        "agent_name": agent_name,
+        "system_prompt": system_prompt,
+        "tool_definitions": tool_definitions or [],
+        "project": config.project,
+        "metadata": metadata or {},
+        "spans": spans,
+    }
+    headers = {"x-api-key": config.api_key} if config.api_key else {}
+
+    if config.dry_run:
+        redacted_headers = dict(headers)
+        if "x-api-key" in redacted_headers:
+            redacted_headers["x-api-key"] = "<redacted>"
+        logger.info(
+            "torina dry-run: would POST trace %s (%d span(s)) to %s\nheaders=%s\npayload=%s",
+            trace_id,
+            len(spans),
+            config.endpoint or "<no endpoint configured>",
+            redacted_headers,
+            json.dumps(payload, indent=2, default=str),
+        )
+        return
+
+    try:
+        post_json(config.endpoint, payload, headers, config.timeout)
+    except HttpError:
+        logger.exception("Failed to export trace %s to Torina", trace_id)

torina-0.1.1/src/torina/_http.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict
+
+
+class HttpError(Exception):
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+
+
+def post_json(url: str, payload: Any, headers: Dict[str, str], timeout: float) -> None:
+    body = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(url, data=body, method="POST")
+    request.add_header("Content-Type", "application/json")
+    for key, value in headers.items():
+        request.add_header(key, value)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            response.read()
+    except urllib.error.HTTPError as exc:
+        raise HttpError(exc.code, exc.reason) from exc
+    except urllib.error.URLError as exc:
+        raise HttpError(0, str(exc.reason)) from exc

torina-0.1.1/src/torina/_instrumentation.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import importlib.util
+
+
+def auto_instrument() -> None:
+    """Patch every supported framework that's installed to capture Torina traces."""
+    if importlib.util.find_spec("langchain_core") is not None:
+        from torina.langchain import _patch_langchain
+
+        _patch_langchain()

torina-0.1.1/src/torina/_logger.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from torina._config import config
+
+_API_KEY_ENV_VAR = "TORINA_API_KEY"
+_ENDPOINT_ENV_VAR = "TORINA_ENDPOINT"
+
+
+def init_logger(
+    *,
+    api_key: Optional[str] = None,
+    project: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    timeout: float = 10.0,
+    dry_run: bool = False,
+) -> None:
+    """Configure where Torina sends traces captured by auto_instrument().
+
+    With dry_run=True, traces are logged instead of sent, so no endpoint or
+    api_key is required. Traces are uploaded whole, one HTTP request per
+    completed trace, not per span.
+    """
+    api_key = api_key or os.environ.get(_API_KEY_ENV_VAR)
+    endpoint = endpoint or os.environ.get(_ENDPOINT_ENV_VAR)
+    if not dry_run and not endpoint:
+        raise ValueError(
+            f"Torina ingestion endpoint is required: pass endpoint= or set {_ENDPOINT_ENV_VAR}"
+        )
+    if not dry_run and not api_key:
+        raise ValueError(f"Torina API key is required: pass api_key= or set {_API_KEY_ENV_VAR}")
+
+    config.api_key = api_key
+    config.endpoint = endpoint
+    config.project = project
+    config.timeout = timeout
+    config.dry_run = dry_run

torina-0.1.1/src/torina/_trace_tracker.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, List, Optional
+
+
+class TraceTracker:
+    """Groups individual spans into complete traces using parent_span_id to find each
+    trace's boundary. parent_span_id is bookkeeping only — spans don't carry it in
+    their output, since it duplicates relationships already expressed elsewhere (e.g.
+    a tool span's tool_call_id already says which llm span requested it).
+
+    A trace is considered complete the moment its root span (the one with no
+    parent) ends — at which point every span belonging to that trace is
+    returned together and dropped from memory. A span that starts but never
+    ends (e.g. the process crashes mid-trace) leaks until process exit; there
+    is no timeout/orphan sweep in this implementation.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._spans: Dict[str, Dict[str, Any]] = {}
+        self._root_of: Dict[str, str] = {}
+
+    def start_span(self, span_id: Any, parent_span_id: Optional[Any], **fields: Any) -> None:
+        span_id = str(span_id)
+        parent_span_id = str(parent_span_id) if parent_span_id else None
+        with self._lock:
+            root = self._root_of[parent_span_id] if parent_span_id in self._root_of else span_id
+            self._root_of[span_id] = root
+            self._spans[span_id] = {"span_id": span_id, **fields}
+
+    def end_span(self, span_id: Any, **fields: Any) -> Optional[Dict[str, Any]]:
+        """Record the span's completion. Returns the full trace dict once its root span ends."""
+        span_id = str(span_id)
+        with self._lock:
+            span = self._spans.get(span_id)
+            if span is None:
+                return None
+            span.update(fields)
+
+            root = self._root_of.get(span_id)
+            if root != span_id:
+                return None  # trace still in progress
+
+            trace_span_ids = [sid for sid, r in self._root_of.items() if r == root]
+            spans: List[Dict[str, Any]] = [
+                self._spans.pop(sid) for sid in trace_span_ids if sid in self._spans
+            ]
+            for sid in trace_span_ids:
+                self._root_of.pop(sid, None)
+
+        spans.sort(key=lambda s: s.get("start_time") or "")
+        return {"trace_id": root, "spans": spans}

torina-0.1.1/src/torina/langchain.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from langchain_core.callbacks.base import BaseCallbackHandler
+from wrapt import wrap_function_wrapper
+
+from torina._forwarder import forward_trace
+from torina._trace_tracker import TraceTracker
+
+_tracker = TraceTracker()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _run_name(serialized: Optional[Dict[str, Any]], kwargs: Dict[str, Any], default: str) -> str:
+    name = kwargs.get("name")
+    if name:
+        return name
+    if serialized:
+        name = serialized.get("name")
+        if name:
+            return name
+        ids = serialized.get("id")
+        if ids:
+            return ids[-1]
+    return default
+
+
+def _message_content_text(content: Any) -> Any:
+    """Collapse provider-specific content blocks (e.g. Anthropic's text/tool_use
+    blocks) down to plain text. Tool calls are dropped here since message.tool_calls
+    already captures them in a cleaner, provider-agnostic shape."""
+    if not isinstance(content, list):
+        return content
+    text_parts = [
+        block.get("text", "") for block in content if isinstance(block, dict) and block.get("type") == "text"
+    ]
+    return "".join(text_parts) or None
+
+
+def _message_dict(message: Any) -> Dict[str, Any]:
+    result: Dict[str, Any] = {
+        "role": getattr(message, "type", "unknown"),
+        "content": _message_content_text(getattr(message, "content", None)),
+    }
+    tool_calls = getattr(message, "tool_calls", None)
+    if tool_calls:
+        result["tool_calls"] = [
+            {"id": tc.get("id"), "name": tc.get("name"), "args": tc.get("args")} for tc in tool_calls
+        ]
+    return result
+
+
+class TorinaCallbackHandler(BaseCallbackHandler):
+    """LangChain callback handler that captures traces and forwards them to Torina."""
+
+    def on_chain_start(
+        self, serialized, inputs, *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs
+    ):
+        fields: Dict[str, Any] = {
+            "type": "chain",
+            "name": _run_name(serialized, kwargs, "chain"),
+            "start_time": _now(),
+        }
+        if parent_run_id is None and metadata:
+            fields["metadata"] = dict(metadata)
+        _tracker.start_span(run_id, parent_run_id, **fields)
+
+    def on_chain_end(self, outputs, *, run_id, parent_run_id=None, **kwargs):
+        self._end(run_id)
+
+    def on_chain_error(self, error, *, run_id, parent_run_id=None, **kwargs):
+        self._end(run_id, error=str(error))
+
+    def on_chat_model_start(
+        self, serialized, messages, *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs
+    ):
+        invocation_params = kwargs.get("invocation_params") or {}
+        fields: Dict[str, Any] = {
+            "type": "llm",
+            "name": _run_name(serialized, kwargs, "chat_model"),
+            "start_time": _now(),
+            "model": invocation_params.get("model"),
+            "input_messages": [_message_dict(m) for batch in messages for m in batch],
+        }
+        tools = invocation_params.get("tools")
+        if tools:
+            fields["tool_definitions"] = tools
+        if parent_run_id is None and metadata:
+            fields["metadata"] = dict(metadata)
+        _tracker.start_span(run_id, parent_run_id, **fields)
+
+    def on_llm_start(
+        self, serialized, prompts, *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs
+    ):
+        invocation_params = kwargs.get("invocation_params") or {}
+        fields: Dict[str, Any] = {
+            "type": "llm",
+            "name": _run_name(serialized, kwargs, "llm"),
+            "start_time": _now(),
+            "model": invocation_params.get("model"),
+            "input_prompts": list(prompts),
+        }
+        tools = invocation_params.get("tools")
+        if tools:
+            fields["tool_definitions"] = tools
+        if parent_run_id is None and metadata:
+            fields["metadata"] = dict(metadata)
+        _tracker.start_span(run_id, parent_run_id, **fields)
+
+    def on_llm_end(self, response, *, run_id, parent_run_id=None, tags=None, **kwargs):
+        llm_output = response.llm_output or {}
+        usage = llm_output.get("usage") or llm_output.get("token_usage") or {}
+        generations = response.generations[0] if response.generations else []
+        generation = generations[0] if generations else None
+        message = getattr(generation, "message", None)
+        if message is not None:
+            output = _message_dict(message)
+        elif generation is not None:
+            output = {"content": getattr(generation, "text", None)}
+        else:
+            output = None
+
+        self._end(
+            run_id,
+            model=llm_output.get("model") or llm_output.get("model_name"),
+            usage={
+                "input_tokens": usage.get("input_tokens") or usage.get("prompt_tokens"),
+                "output_tokens": usage.get("output_tokens") or usage.get("completion_tokens"),
+            }
+            if usage
+            else None,
+            output_message=output,
+        )
+
+    def on_llm_error(self, error, *, run_id, parent_run_id=None, tags=None, **kwargs):
+        self._end(run_id, error=str(error))
+
+    def on_tool_start(
+        self,
+        serialized,
+        input_str,
+        *,
+        run_id,
+        parent_run_id=None,
+        tags=None,
+        metadata=None,
+        inputs=None,
+        **kwargs,
+    ):
+        fields: Dict[str, Any] = {
+            "type": "tool",
+            "name": _run_name(serialized, kwargs, "tool"),
+            "start_time": _now(),
+            "input": inputs if inputs is not None else input_str,
+        }
+        tool_call_id = kwargs.get("tool_call_id")
+        if tool_call_id:
+            # Links this span to the matching entry in the requesting llm span's
+            # output_message.tool_calls — how to correlate a tool call with its
+            # execution when multiple calls happen in parallel.
+            fields["tool_call_id"] = tool_call_id
+        if parent_run_id is None and metadata:
+            fields["metadata"] = dict(metadata)
+        _tracker.start_span(run_id, parent_run_id, **fields)
+
+    def on_tool_end(self, output, *, run_id, parent_run_id=None, **kwargs):
+        content = getattr(output, "content", output)
+        if not isinstance(content, (str, int, float, bool, type(None))):
+            content = str(content)
+        self._end(run_id, output=content)
+
+    def on_tool_error(self, error, *, run_id, parent_run_id=None, **kwargs):
+        self._end(run_id, error=str(error))
+
+    def _end(self, run_id: Any, **fields: Any) -> None:
+        fields.setdefault("end_time", _now())
+        trace = _tracker.end_span(run_id, **fields)
+        if trace is None:
+            return
+
+        spans = trace["spans"]
+        root = spans[0] if spans else {}
+        raw_metadata = dict(root.pop("metadata", None) or {})
+        conversation_id = raw_metadata.pop("thread_id", None)
+        agent_name = raw_metadata.pop("lc_agent_name", None)
+        raw_metadata.pop("ls_integration", None)  # internal LangChain bookkeeping, no signal
+
+        forward_trace(
+            trace["trace_id"],
+            spans,
+            source="langchain",
+            conversation_id=conversation_id,
+            agent_name=agent_name,
+            metadata=raw_metadata,
+        )
+
+
+_patch_lock = threading.Lock()
+_patched = False
+
+
+def _patch_langchain() -> None:
+    global _patched
+    with _patch_lock:
+        if _patched:
+            return
+        handler = TorinaCallbackHandler()
+        wrap_function_wrapper(
+            "langchain_core.callbacks",
+            "BaseCallbackManager.__init__",
+            _init_wrapper(handler),
+        )
+        _patched = True
+
+
+def _init_wrapper(handler: TorinaCallbackHandler):
+    def wrapper(wrapped, instance, args, kwargs):
+        wrapped(*args, **kwargs)
+        for existing in instance.inheritable_handlers:
+            if isinstance(existing, TorinaCallbackHandler):
+                return
+        instance.add_handler(handler, True)
+
+    return wrapper