turingpulse-sdk-langchain 1.0.0__tar.gz

turingpulse_sdk_langchain-1.0.0/.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Database files
+*.db
+*.sqlite3
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Logs
+*.log
+logs/
+
+# OS files
+.DS_Store
+Thumbs.db

turingpulse_sdk_langchain-1.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: turingpulse-sdk-langchain
+Version: 1.0.0
+Summary: TuringPulse SDK integration for LangChain
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: turingpulse-sdk>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

turingpulse_sdk_langchain-1.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "turingpulse-sdk-langchain"
+version = "1.0.0"
+description = "TuringPulse SDK integration for LangChain"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+dependencies = [
+    "turingpulse-sdk>=1.0.0",
+    "langchain-core>=0.3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]

turingpulse_sdk_langchain-1.0.0/turingpulse_sdk_langchain/__init__.py

@@ -0,0 +1,6 @@
+"""TuringPulse SDK integration for LangChain."""
+
+from ._wrapper import instrument_langchain
+
+__version__ = "1.0.0"
+__all__ = ["instrument_langchain"]

turingpulse_sdk_langchain-1.0.0/turingpulse_sdk_langchain/_wrapper.py

@@ -0,0 +1,693 @@
+"""LangChain instrumentation for TuringPulse SDK.
+
+Wraps LangChain ``Runnable`` objects (chains, agents, RunnableSequence,
+AgentExecutor, etc.) for full observability via ``langchain-core``
+callbacks.
+
+Captures:
+- Per-step chain spans with state diffs
+- LLM calls with prompt, tokens, model, system prompt
+- Tool executions with input/output/errors
+- Retriever lookups with query and document counts
+- Nested sub-agent invocations via parent_run_id tracking
+
+Usage::
+
+    from turingpulse_sdk_langchain import instrument_langchain
+
+    chain = prompt | llm | output_parser
+    run = instrument_langchain(chain, name="my-chain")
+    result = run.invoke({"input": "Hello"})
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, AsyncIterator, Callable, Dict, Iterator, List, Optional, Sequence
+from uuid import uuid4
+
+from turingpulse_sdk.config import MAX_FIELD_SIZE
+from turingpulse_sdk.context import current_context
+from turingpulse_sdk import instrument, GovernanceDirective
+from turingpulse_sdk.integrations.base import emit_child_spans, emit_child_spans_async
+
+logger = logging.getLogger("turingpulse.sdk.integrations.langchain")
+
+FRAMEWORK_NAME = "langchain"
+
+_INPUT_KEYS = (
+    "input", "query", "question", "prompt", "request",
+    "user_input", "message", "text",
+)
+_OUTPUT_KEYS = (
+    "output", "result", "answer", "response", "text",
+)
+
+_HAS_CALLBACKS = False
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.messages import BaseMessage
+    _HAS_CALLBACKS = True
+except ImportError:
+    pass
+
+
+def _safe_str(value: Any) -> str:
+    try:
+        return str(value)[:MAX_FIELD_SIZE]
+    except Exception:
+        return ""
+
+
+def _extract_system_prompt(messages: List[Any]) -> str:
+    for msg in (messages or []):
+        if hasattr(msg, "type") and msg.type == "system":
+            return _safe_str(msg.content)
+        if isinstance(msg, dict) and msg.get("role") == "system":
+            return _safe_str(msg.get("content", ""))
+    return ""
+
+
+def _extract_user_query(messages: List[Any]) -> str:
+    for msg in reversed(messages or []):
+        if hasattr(msg, "type") and msg.type == "human":
+            return _safe_str(msg.content)
+        if isinstance(msg, dict) and msg.get("role") == "user":
+            return _safe_str(msg.get("content", ""))
+    return ""
+
+
+def _messages_to_str(messages: List[Any]) -> str:
+    parts = []
+    for msg in (messages or []):
+        role = getattr(msg, "type", "unknown")
+        content = getattr(msg, "content", str(msg))
+        parts.append(f"[{role}]: {content}")
+    return "\n".join(parts)[:MAX_FIELD_SIZE]
+
+
+def _condense_state(state: Any) -> Dict[str, Any]:
+    if not isinstance(state, dict):
+        return {"value": _safe_str(state)}
+    condensed = {}
+    for k, v in state.items():
+        s = _safe_str(v)
+        condensed[k] = s if len(s) <= 500 else s[:500] + "…"
+    return condensed
+
+
+def _state_diff(inputs: Any, outputs: Any) -> Dict[str, Any]:
+    if not isinstance(inputs, dict) or not isinstance(outputs, dict):
+        return outputs if isinstance(outputs, dict) else {"result": _safe_str(outputs)}
+    diff: Dict[str, Any] = {}
+    for key, value in outputs.items():
+        old = inputs.get(key)
+        try:
+            same = old == value
+        except Exception:
+            same = False
+        if key not in inputs or not same:
+            diff[key] = _safe_str(value)
+    return diff if diff else _condense_state(outputs)
+
+
+def _extract_io(data: Any, keys: tuple) -> str:
+    if isinstance(data, str):
+        return data[:MAX_FIELD_SIZE]
+    if isinstance(data, dict):
+        for k in keys:
+            v = data.get(k)
+            if v:
+                return _safe_str(v)
+        return _safe_str(data)
+    return _safe_str(data)
+
+
+if _HAS_CALLBACKS:
+    class _SpanCollector(BaseCallbackHandler):
+        """LangChain callback handler that collects per-step span data.
+
+        Handles chains, LLM calls, tool executions, and retriever lookups.
+        LLM calls inside named chains are merged into the parent chain span.
+        """
+
+        _SKIP_NAMES = frozenset({
+            "RunnableSequence", "RunnableLambda", "RunnableParallel",
+            "RunnablePassthrough", "RunnableBranch", "RunnableWithFallbacks",
+            "ChannelWrite", "ChannelRead",
+        })
+
+        def __init__(self, workflow_name: str, default_model: str, default_provider: str):
+            super().__init__()
+            self.workflow_name = workflow_name
+            self.default_model = default_model
+            self.default_provider = default_provider
+            self.collected_spans: List[Dict[str, Any]] = []
+            self._active_chains: Dict[str, Dict[str, Any]] = {}
+            self._active_llms: Dict[str, Dict[str, Any]] = {}
+            self._active_tools: Dict[str, Dict[str, Any]] = {}
+            self._active_retrievers: Dict[str, Dict[str, Any]] = {}
+            self._parent_map: Dict[str, str] = {}
+            self.total_prompt_tokens = 0
+            self.total_completion_tokens = 0
+
+        def _find_named_ancestor(self, parent_run_id: Optional[str]) -> Optional[str]:
+            visited: set = set()
+            rid = parent_run_id
+            while rid and rid not in visited:
+                visited.add(rid)
+                if rid in self._active_chains:
+                    return rid
+                rid = self._parent_map.get(rid)
+            return None
+
+        @staticmethod
+        def _resolve_chain_name(
+            serialized: Optional[Dict[str, Any]],
+            kwargs: Dict[str, Any],
+        ) -> str:
+            kw_name = kwargs.get("name", "")
+            if kw_name:
+                return str(kw_name)
+            if serialized:
+                return serialized.get("name", "") or (serialized.get("id", [""]) or [""])[-1]
+            return ""
+
+        def on_chain_start(
+            self, serialized: Optional[Dict[str, Any]], inputs: Dict[str, Any],
+            *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs,
+        ):
+            rid = str(run_id)
+            pid = str(parent_run_id) if parent_run_id else None
+            name = self._resolve_chain_name(serialized, kwargs)
+
+            if pid:
+                self._parent_map[rid] = pid
+
+            if name and name not in self._SKIP_NAMES:
+                self._active_chains[rid] = {
+                    "name": name,
+                    "started_at": time.time(),
+                    "inputs": dict(inputs) if isinstance(inputs, dict) else inputs,
+                    "parent_run_id": pid,
+                    "llm_data": None,
+                    "node_type": "processor",
+                }
+
+        def on_chain_end(self, outputs: Dict[str, Any], *, run_id, **kwargs):
+            key = str(run_id)
+            data = self._active_chains.pop(key, None)
+            if not data:
+                return
+            dur = int((time.time() - data["started_at"]) * 1000)
+
+            llm = data.get("llm_data")
+
+            if llm:
+                node_input = data["inputs"]
+                node_output = outputs if isinstance(outputs, dict) else {"result": _safe_str(outputs)}
+            else:
+                node_input = _condense_state(data["inputs"])
+                raw_out = outputs if isinstance(outputs, dict) else {}
+                node_output = _state_diff(data["inputs"], raw_out)
+
+            span: Dict[str, Any] = {
+                "node": data["name"],
+                "node_type": "llm" if llm else data.get("node_type", "processor"),
+                "duration_ms": dur,
+                "status": "success",
+                "input": node_input,
+                "output": node_output,
+            }
+
+            if llm:
+                span["model"] = llm.get("model", self.default_model)
+                span["provider"] = self.default_provider
+                span["tokens"] = llm.get("tokens")
+                if llm.get("system_prompt"):
+                    span["system_prompt"] = llm["system_prompt"]
+                if llm.get("prompt"):
+                    span["prompt"] = llm["prompt"]
+                if llm.get("user_query"):
+                    span["input"] = {"user_query": llm["user_query"]}
+                if llm.get("tool_calls"):
+                    span["tool_calls"] = llm["tool_calls"]
+                if llm.get("llm_output"):
+                    span["output"] = llm["llm_output"]
+
+            self.collected_spans.append(span)
+
+        def on_chain_error(self, error: BaseException, *, run_id, **kwargs):
+            key = str(run_id)
+            data = self._active_chains.pop(key, None)
+            if not data:
+                return
+            dur = int((time.time() - data["started_at"]) * 1000)
+            self.collected_spans.append({
+                "node": data["name"],
+                "node_type": data.get("node_type", "processor"),
+                "duration_ms": dur,
+                "status": "error",
+                "input": _condense_state(data["inputs"]),
+                "output": {"error": str(error)[:MAX_FIELD_SIZE]},
+            })
+
+        def on_llm_start(self, serialized: Dict[str, Any], prompts: List[str], *, run_id, parent_run_id=None, **kwargs):
+            rid = str(run_id)
+            if parent_run_id:
+                self._parent_map[rid] = str(parent_run_id)
+            self._active_llms[rid] = {
+                "started_at": time.time(),
+                "prompts": prompts,
+                "model": (serialized or {}).get("kwargs", {}).get("model_name", self.default_model),
+                "parent_run_id": str(parent_run_id) if parent_run_id else None,
+            }
+
+        def on_chat_model_start(self, serialized: Dict[str, Any], messages: List[List[Any]], *, run_id, parent_run_id=None, **kwargs):
+            rid = str(run_id)
+            if parent_run_id:
+                self._parent_map[rid] = str(parent_run_id)
+            flat = messages[0] if messages else []
+            self._active_llms[rid] = {
+                "started_at": time.time(),
+                "messages": flat,
+                "system_prompt": _extract_system_prompt(flat),
+                "user_query": _extract_user_query(flat),
+                "prompt": _messages_to_str(flat),
+                "model": (
+                    kwargs.get("invocation_params", {}).get("model_name")
+                    or kwargs.get("invocation_params", {}).get("model")
+                    or (serialized or {}).get("kwargs", {}).get("model_name")
+                    or self.default_model
+                ),
+                "parent_run_id": str(parent_run_id) if parent_run_id else None,
+            }
+
+        def on_llm_end(self, response, *, run_id, parent_run_id=None, **kwargs):
+            key = str(run_id)
+            data = self._active_llms.pop(key, None)
+            if not data:
+                return
+
+            dur = int((time.time() - data["started_at"]) * 1000)
+            content = ""
+            usage: Dict[str, int] = {}
+
+            if hasattr(response, "generations") and response.generations:
+                gen = response.generations[0]
+                if gen:
+                    msg = gen[0].message if hasattr(gen[0], "message") else gen[0]
+                    content = getattr(msg, "content", "") or str(gen[0])
+
+            if hasattr(response, "llm_output") and response.llm_output:
+                token_usage = response.llm_output.get("token_usage", {})
+                usage = {
+                    "prompt": int(token_usage.get("prompt_tokens", 0)),
+                    "completion": int(token_usage.get("completion_tokens", 0)),
+                }
+
+            if not usage.get("prompt") and hasattr(response, "generations") and response.generations:
+                gen = response.generations[0]
+                if gen:
+                    msg = gen[0].message if hasattr(gen[0], "message") else gen[0]
+                    um = getattr(msg, "usage_metadata", None) or {}
+                    if isinstance(um, dict):
+                        usage = {
+                            "prompt": int(um.get("input_tokens", 0)),
+                            "completion": int(um.get("output_tokens", 0)),
+                        }
+
+            self.total_prompt_tokens += usage.get("prompt", 0)
+            self.total_completion_tokens += usage.get("completion", 0)
+
+            tool_calls_raw = []
+            if hasattr(response, "generations") and response.generations:
+                gen = response.generations[0]
+                if gen:
+                    msg = gen[0].message if hasattr(gen[0], "message") else gen[0]
+                    if hasattr(msg, "tool_calls") and msg.tool_calls:
+                        for tc in msg.tool_calls:
+                            tool_calls_raw.append({
+                                "tool_name": tc.get("name", "unknown") if isinstance(tc, dict) else getattr(tc, "name", "unknown"),
+                                "tool_args": tc.get("args", {}) if isinstance(tc, dict) else getattr(tc, "args", {}),
+                                "tool_id": tc.get("id", str(uuid4())) if isinstance(tc, dict) else getattr(tc, "id", str(uuid4())),
+                                "tool_result": "",
+                                "success": True,
+                            })
+
+            llm_result = {
+                "model": data.get("model", self.default_model),
+                "tokens": usage if usage else None,
+                "system_prompt": data.get("system_prompt"),
+                "prompt": data.get("prompt"),
+                "user_query": data.get("user_query"),
+                "tool_calls": tool_calls_raw or None,
+                "llm_output": {"response": _safe_str(content)},
+                "duration_ms": dur,
+            }
+
+            ancestor_id = self._find_named_ancestor(
+                data.get("parent_run_id") or (str(parent_run_id) if parent_run_id else None)
+            )
+            if ancestor_id and ancestor_id in self._active_chains:
+                self._active_chains[ancestor_id]["llm_data"] = llm_result
+            else:
+                span: Dict[str, Any] = {
+                    "node": f"llm_{len(self.collected_spans)}",
+                    "node_type": "llm",
+                    "duration_ms": dur,
+                    "status": "success",
+                    "model": data.get("model", self.default_model),
+                    "provider": self.default_provider,
+                    "tokens": usage if usage else None,
+                    "output": {"response": _safe_str(content)},
+                }
+                if data.get("system_prompt"):
+                    span["system_prompt"] = data["system_prompt"]
+                if data.get("prompt"):
+                    span["prompt"] = data["prompt"]
+                if data.get("user_query"):
+                    span["input"] = {"user_query": data["user_query"]}
+                if tool_calls_raw:
+                    span["tool_calls"] = tool_calls_raw
+                self.collected_spans.append(span)
+
+        def on_tool_start(self, serialized: Dict[str, Any], input_str: str, *, run_id, parent_run_id=None, **kwargs):
+            rid = str(run_id)
+            if parent_run_id:
+                self._parent_map[rid] = str(parent_run_id)
+            tool_name = (serialized or {}).get("name", "unknown_tool")
+            self._active_tools[rid] = {
+                "name": tool_name,
+                "started_at": time.time(),
+                "input": input_str,
+            }
+
+        def on_tool_end(self, output: str, *, run_id, **kwargs):
+            key = str(run_id)
+            data = self._active_tools.pop(key, None)
+            if not data:
+                return
+            dur = int((time.time() - data["started_at"]) * 1000)
+            self.collected_spans.append({
+                "node": data["name"],
+                "node_type": "tool",
+                "duration_ms": dur,
+                "status": "success",
+                "input": {"tool_input": _safe_str(data["input"])},
+                "output": {"tool_output": _safe_str(output)},
+                "tool_calls": [{
+                    "tool_name": data["name"],
+                    "tool_args": _safe_str(data["input"]),
+                    "tool_result": _safe_str(output),
+                    "tool_id": str(uuid4()),
+                    "success": True,
+                }],
+            })
+
+        def on_tool_error(self, error: BaseException, *, run_id, **kwargs):
+            key = str(run_id)
+            data = self._active_tools.pop(key, None)
+            if not data:
+                return
+            dur = int((time.time() - data["started_at"]) * 1000)
+            self.collected_spans.append({
+                "node": data["name"],
+                "node_type": "tool",
+                "duration_ms": dur,
+                "status": "error",
+                "input": {"tool_input": _safe_str(data["input"])},
+                "output": {"error": str(error)[:MAX_FIELD_SIZE]},
+                "tool_calls": [{
+                    "tool_name": data["name"],
+                    "tool_args": _safe_str(data["input"]),
+                    "tool_result": "",
+                    "tool_id": str(uuid4()),
+                    "success": False,
+                    "error_message": str(error)[:MAX_FIELD_SIZE],
+                }],
+            })
+
+        def on_retriever_start(self, serialized: Dict[str, Any], query: str, *, run_id, parent_run_id=None, **kwargs):
+            rid = str(run_id)
+            if parent_run_id:
+                self._parent_map[rid] = str(parent_run_id)
+            retriever_name = (serialized or {}).get("name", "retriever")
+            self._active_retrievers[rid] = {
+                "name": retriever_name,
+                "started_at": time.time(),
+                "query": query,
+            }
+
+        def on_retriever_end(self, documents: List[Any], *, run_id, **kwargs):
+            key = str(run_id)
+            data = self._active_retrievers.pop(key, None)
+            if not data:
+                return
+            dur = int((time.time() - data["started_at"]) * 1000)
+            doc_count = len(documents) if documents else 0
+            self.collected_spans.append({
+                "node": data["name"],
+                "node_type": "retriever",
+                "duration_ms": dur,
+                "status": "success",
+                "input": {"query": _safe_str(data["query"])},
+                "output": {"document_count": doc_count},
+                "metadata": {"document_count": str(doc_count)},
+            })
+
+
+class _InstrumentedRunnable:
+    """Wrapper returned by ``instrument_langchain`` with .invoke/.ainvoke/.stream/.astream."""
+
+    def __init__(
+        self,
+        runnable: Any,
+        *,
+        name: str,
+        governance: Optional[GovernanceDirective] = None,
+        model: str = "gpt-4.1-mini",
+        provider: str = "openai",
+        kpis: Optional[Sequence] = None,
+        metadata: Optional[Dict[str, str]] = None,
+    ):
+        self._runnable = runnable
+        self._name = name
+        self._governance = governance
+        self._model = model
+        self._provider = provider
+        self._kpis = kpis
+        self._metadata = metadata or {}
+
+    def _make_collector(self) -> Any:
+        if not _HAS_CALLBACKS:
+            return None
+        return _SpanCollector(self._name, self._model, self._provider)
+
+    def _merge_config(self, config: Optional[Dict[str, Any]], collector: Any) -> Dict[str, Any]:
+        cfg = dict(config) if config else {}
+        if collector is not None:
+            existing = cfg.get("callbacks") or []
+            cfg["callbacks"] = list(existing) + [collector]
+        return cfg
+
+    def _finalize(self, collector: Any, result: Any, duration_ms: int) -> None:
+        ctx = current_context()
+        if ctx is None:
+            return
+
+        ctx.framework = FRAMEWORK_NAME
+        ctx.node_type = "workflow"
+        ctx.set_model(self._model, self._provider)
+
+        if collector is not None:
+            ctx.set_tokens(collector.total_prompt_tokens, collector.total_completion_tokens)
+            if collector.collected_spans:
+                last_llm = next(
+                    (s for s in reversed(collector.collected_spans) if s.get("model")),
+                    None,
+                )
+                if last_llm:
+                    ctx.set_model(last_llm["model"], self._provider)
+
+        input_str = ""
+        output_str = _safe_str(result)
+        if hasattr(result, "content"):
+            output_str = _safe_str(result.content)
+
+        ctx.set_io(input_str, output_str)
+
+        if collector is not None and collector.collected_spans:
+            emit_child_spans(
+                collector.collected_spans,
+                run_id=ctx.run_id,
+                parent_span_id=ctx.span_id,
+                workflow_name=self._name,
+                framework=FRAMEWORK_NAME,
+            )
+
+    async def _finalize_async(self, collector: Any, result: Any, duration_ms: int) -> None:
+        ctx = current_context()
+        if ctx is None:
+            return
+
+        ctx.framework = FRAMEWORK_NAME
+        ctx.node_type = "workflow"
+        ctx.set_model(self._model, self._provider)
+
+        if collector is not None:
+            ctx.set_tokens(collector.total_prompt_tokens, collector.total_completion_tokens)
+            if collector.collected_spans:
+                last_llm = next(
+                    (s for s in reversed(collector.collected_spans) if s.get("model")),
+                    None,
+                )
+                if last_llm:
+                    ctx.set_model(last_llm["model"], self._provider)
+
+        output_str = _safe_str(result)
+        if hasattr(result, "content"):
+            output_str = _safe_str(result.content)
+
+        ctx.set_io("", output_str)
+
+        if collector is not None and collector.collected_spans:
+            await emit_child_spans_async(
+                collector.collected_spans,
+                run_id=ctx.run_id,
+                parent_span_id=ctx.span_id,
+                workflow_name=self._name,
+                framework=FRAMEWORK_NAME,
+            )
+
+    def invoke(self, input: Any, config: Optional[Dict[str, Any]] = None, **kwargs) -> Any:
+        @instrument(name=self._name, governance=self._governance, kpis=self._kpis, metadata=self._metadata)
+        def _run(input_data: Any, cfg: Optional[Dict[str, Any]] = None, **kw) -> Any:
+            collector = self._make_collector()
+            merged_cfg = self._merge_config(cfg, collector)
+            t0 = time.time()
+            result = self._runnable.invoke(input_data, config=merged_cfg, **kw)
+            dur = int((time.time() - t0) * 1000)
+
+            ctx = current_context()
+            if ctx:
+                input_str = _extract_io(input_data, _INPUT_KEYS)
+                ctx.set_io(input_str, "")
+
+            self._finalize(collector, result, dur)
+            return result
+
+        return _run(input, cfg=config, **kwargs)
+
+    async def ainvoke(self, input: Any, config: Optional[Dict[str, Any]] = None, **kwargs) -> Any:
+        @instrument(name=self._name, governance=self._governance, kpis=self._kpis, metadata=self._metadata)
+        async def _run(input_data: Any, cfg: Optional[Dict[str, Any]] = None, **kw) -> Any:
+            collector = self._make_collector()
+            merged_cfg = self._merge_config(cfg, collector)
+            t0 = time.time()
+            result = await self._runnable.ainvoke(input_data, config=merged_cfg, **kw)
+            dur = int((time.time() - t0) * 1000)
+
+            ctx = current_context()
+            if ctx:
+                input_str = _extract_io(input_data, _INPUT_KEYS)
+                ctx.set_io(input_str, "")
+
+            await self._finalize_async(collector, result, dur)
+            return result
+
+        return await _run(input, cfg=config, **kwargs)
+
+    def stream(self, input: Any, config: Optional[Dict[str, Any]] = None, **kwargs) -> Iterator[Any]:
+        @instrument(name=self._name, governance=self._governance, kpis=self._kpis, metadata=self._metadata)
+        def _run(input_data: Any, cfg: Optional[Dict[str, Any]] = None, **kw) -> Any:
+            collector = self._make_collector()
+            merged_cfg = self._merge_config(cfg, collector)
+            t0 = time.time()
+            chunks = []
+            for chunk in self._runnable.stream(input_data, config=merged_cfg, **kw):
+                chunks.append(chunk)
+
+            dur = int((time.time() - t0) * 1000)
+            final = chunks[-1] if chunks else None
+
+            ctx = current_context()
+            if ctx:
+                input_str = _extract_io(input_data, _INPUT_KEYS)
+                ctx.set_io(input_str, "")
+
+            self._finalize(collector, final, dur)
+            return chunks
+
+        result_chunks = _run(input, cfg=config, **kwargs)
+        yield from result_chunks
+
+    async def astream(self, input: Any, config: Optional[Dict[str, Any]] = None, **kwargs) -> AsyncIterator[Any]:
+        @instrument(name=self._name, governance=self._governance, kpis=self._kpis, metadata=self._metadata)
+        async def _run(input_data: Any, cfg: Optional[Dict[str, Any]] = None, **kw) -> Any:
+            collector = self._make_collector()
+            merged_cfg = self._merge_config(cfg, collector)
+            t0 = time.time()
+            chunks = []
+            async for chunk in self._runnable.astream(input_data, config=merged_cfg, **kw):
+                chunks.append(chunk)
+
+            dur = int((time.time() - t0) * 1000)
+            final = chunks[-1] if chunks else None
+
+            ctx = current_context()
+            if ctx:
+                input_str = _extract_io(input_data, _INPUT_KEYS)
+                ctx.set_io(input_str, "")
+
+            await self._finalize_async(collector, final, dur)
+            return chunks
+
+        result_chunks = await _run(input, cfg=config, **kwargs)
+        for chunk in result_chunks:
+            yield chunk
+
+
+def instrument_langchain(
+    runnable: Any,
+    *,
+    name: str,
+    governance: Optional[GovernanceDirective] = None,
+    model: str = "gpt-4.1-mini",
+    provider: str = "openai",
+    kpis: Optional[Sequence] = None,
+    metadata: Optional[Dict[str, str]] = None,
+) -> _InstrumentedRunnable:
+    """Instrument a LangChain Runnable for TuringPulse observability.
+
+    Wraps any LangChain ``Runnable`` (chains, agents, ``RunnableSequence``,
+    ``AgentExecutor``, etc.) and returns an object with ``.invoke()``,
+    ``.ainvoke()``, ``.stream()``, and ``.astream()`` methods.
+
+    Internally injects a ``BaseCallbackHandler`` to capture per-step spans
+    including LLM calls, tool executions, retriever lookups, and sub-agent
+    invocations.
+
+    Args:
+        runnable: A LangChain ``Runnable`` instance.
+        name: Workflow display name for TuringPulse.
+        governance: Optional governance directive for policy enforcement.
+        model: Default LLM model name (auto-detected from callbacks when possible).
+        provider: LLM provider (default ``openai``).
+        kpis: Optional KPI configurations.
+        metadata: Optional metadata key-value pairs.
+
+    Returns:
+        An ``_InstrumentedRunnable`` with ``.invoke()`` / ``.ainvoke()`` /
+        ``.stream()`` / ``.astream()`` methods.
+    """
+    return _InstrumentedRunnable(
+        runnable,
+        name=name,
+        governance=governance,
+        model=model,
+        provider=provider,
+        kpis=kpis,
+        metadata=metadata,
+    )