cortexhub 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

cortexhub/adapters/langgraph.py

@@ -33,6 +33,11 @@ _ORIGINAL_CHAT_AINVOKE_ATTR = "__cortexhub_original_chat_ainvoke__"
 _PATCHED_LLM_ATTR = "__cortexhub_llm_patched__"
 _ORIGINAL_TOOLNODE_INIT_ATTR = "__cortexhub_original_toolnode_init__"
 _PATCHED_TOOLNODE_ATTR = "__cortexhub_toolnode_patched__"
+_ORIGINAL_GRAPH_INVOKE_ATTR = "__cortexhub_original_graph_invoke__"
+_ORIGINAL_GRAPH_AINVOKE_ATTR = "__cortexhub_original_graph_ainvoke__"
+_ORIGINAL_GRAPH_STREAM_ATTR = "__cortexhub_original_graph_stream__"
+_ORIGINAL_GRAPH_ASTREAM_ATTR = "__cortexhub_original_graph_astream__"
+_PATCHED_GRAPH_RUN_ATTR = "__cortexhub_graph_run_patched__"
 
 
 class LangGraphAdapter(ToolAdapter):
@@ -126,6 +131,9 @@ class LangGraphAdapter(ToolAdapter):
             # Patch LLM invoke for LLM call governance
             self._patch_llm_invoke(cortex_hub)
 
+            # Patch graph execution for run completion events
+            self._patch_run_completion(cortex_hub)
+
         except ImportError:
             logger.debug("LangGraph/LangChain not available, skipping adapter")
         except Exception as e:
@@ -241,6 +249,95 @@ class LangGraphAdapter(ToolAdapter):
         except Exception as e:
             logger.debug("LangGraph ToolNode patch skipped", reason=str(e))
 
+    def _patch_run_completion(self, cortex_hub) -> None:
+        """Patch LangGraph compiled graph execution to emit run completion."""
+        try:
+            from langgraph.graph.state import CompiledStateGraph
+
+            if getattr(CompiledStateGraph, _PATCHED_GRAPH_RUN_ATTR, False):
+                return
+
+            if not hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_INVOKE_ATTR):
+                setattr(CompiledStateGraph, _ORIGINAL_GRAPH_INVOKE_ATTR, CompiledStateGraph.invoke)
+            if not hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_AINVOKE_ATTR):
+                setattr(CompiledStateGraph, _ORIGINAL_GRAPH_AINVOKE_ATTR, CompiledStateGraph.ainvoke)
+            if not hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_STREAM_ATTR):
+                setattr(CompiledStateGraph, _ORIGINAL_GRAPH_STREAM_ATTR, CompiledStateGraph.stream)
+            if not hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_ASTREAM_ATTR):
+                setattr(CompiledStateGraph, _ORIGINAL_GRAPH_ASTREAM_ATTR, CompiledStateGraph.astream)
+
+            original_invoke = getattr(CompiledStateGraph, _ORIGINAL_GRAPH_INVOKE_ATTR)
+            original_ainvoke = getattr(CompiledStateGraph, _ORIGINAL_GRAPH_AINVOKE_ATTR)
+            original_stream = getattr(CompiledStateGraph, _ORIGINAL_GRAPH_STREAM_ATTR)
+            original_astream = getattr(CompiledStateGraph, _ORIGINAL_GRAPH_ASTREAM_ATTR)
+
+            def patched_invoke(self, *args, **kwargs):
+                status = "completed"
+                cortex_hub.start_run(framework="langgraph")
+                try:
+                    return original_invoke(self, *args, **kwargs)
+                except Exception:
+                    status = "failed"
+                    raise
+                finally:
+                    cortex_hub.finish_run(framework="langgraph", status=status)
+
+            async def patched_ainvoke(self, *args, **kwargs):
+                status = "completed"
+                cortex_hub.start_run(framework="langgraph")
+                try:
+                    return await original_ainvoke(self, *args, **kwargs)
+                except Exception:
+                    status = "failed"
+                    raise
+                finally:
+                    cortex_hub.finish_run(framework="langgraph", status=status)
+
+            def patched_stream(self, *args, **kwargs):
+                completed = False
+                failed = False
+                cortex_hub.start_run(framework="langgraph")
+                stream_iter = original_stream(self, *args, **kwargs)
+                try:
+                    for item in stream_iter:
+                        yield item
+                    completed = True
+                except Exception:
+                    failed = True
+                    completed = True
+                    raise
+                finally:
+                    if completed:
+                        status = "failed" if failed else "completed"
+                        cortex_hub.finish_run(framework="langgraph", status=status)
+
+            async def patched_astream(self, *args, **kwargs):
+                completed = False
+                failed = False
+                cortex_hub.start_run(framework="langgraph")
+                stream_iter = original_astream(self, *args, **kwargs)
+                try:
+                    async for item in stream_iter:
+                        yield item
+                    completed = True
+                except Exception:
+                    failed = True
+                    completed = True
+                    raise
+                finally:
+                    if completed:
+                        status = "failed" if failed else "completed"
+                        cortex_hub.finish_run(framework="langgraph", status=status)
+
+            CompiledStateGraph.invoke = patched_invoke
+            CompiledStateGraph.ainvoke = patched_ainvoke
+            CompiledStateGraph.stream = patched_stream
+            CompiledStateGraph.astream = patched_astream
+            setattr(CompiledStateGraph, _PATCHED_GRAPH_RUN_ATTR, True)
+            logger.info("LangGraph run completion patched successfully")
+        except Exception as e:
+            logger.debug("LangGraph run completion patch skipped", reason=str(e))
+
     def unpatch(self) -> None:
         """Restore original methods."""
         try:
@@ -272,6 +369,28 @@ class LangGraphAdapter(ToolAdapter):
                 setattr(ToolNode, _PATCHED_TOOLNODE_ATTR, False)
             except ImportError:
                 pass
+
+            # Restore graph execution methods
+            try:
+                from langgraph.graph.state import CompiledStateGraph
+
+                if hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_INVOKE_ATTR):
+                    CompiledStateGraph.invoke = getattr(CompiledStateGraph, _ORIGINAL_GRAPH_INVOKE_ATTR)
+                if hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_AINVOKE_ATTR):
+                    CompiledStateGraph.ainvoke = getattr(
+                        CompiledStateGraph, _ORIGINAL_GRAPH_AINVOKE_ATTR
+                    )
+                if hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_STREAM_ATTR):
+                    CompiledStateGraph.stream = getattr(
+                        CompiledStateGraph, _ORIGINAL_GRAPH_STREAM_ATTR
+                    )
+                if hasattr(CompiledStateGraph, _ORIGINAL_GRAPH_ASTREAM_ATTR):
+                    CompiledStateGraph.astream = getattr(
+                        CompiledStateGraph, _ORIGINAL_GRAPH_ASTREAM_ATTR
+                    )
+                setattr(CompiledStateGraph, _PATCHED_GRAPH_RUN_ATTR, False)
+            except ImportError:
+                pass
         except ImportError:
             pass
 

cortexhub/adapters/openai_agents.py

@@ -26,6 +26,13 @@ logger = structlog.get_logger(__name__)
 # Attribute names for storing originals
 _ORIGINAL_FUNCTION_TOOL_ATTR = "__cortexhub_original_function_tool__"
 _PATCHED_ATTR = "__cortexhub_patched__"
+_ORIGINAL_RUN_ATTR = "__cortexhub_original_run__"
+_ORIGINAL_RUN_SYNC_ATTR = "__cortexhub_original_run_sync__"
+_ORIGINAL_RUN_STREAMED_ATTR = "__cortexhub_original_run_streamed__"
+_PATCHED_RUN_ATTR = "__cortexhub_run_patched__"
+_ORIGINAL_RESPONSES_FETCH_ATTR = "__cortexhub_original_responses_fetch__"
+_ORIGINAL_CHAT_FETCH_ATTR = "__cortexhub_original_chat_fetch__"
+_PATCHED_LLM_ATTR = "__cortexhub_llm_patched__"
 
 
 class OpenAIAgentsAdapter(ToolAdapter):
@@ -132,18 +139,28 @@ class OpenAIAgentsAdapter(ToolAdapter):
                     
                     # Replace on_invoke_tool with governed version
                     # FunctionTool is a dataclass, so we need to create a new instance
+                    from dataclasses import fields
                     from agents.tool import FunctionTool
-                    
-                    governed_tool = FunctionTool(
-                        name=tool.name,
-                        description=tool.description,
-                        params_json_schema=tool.params_json_schema,
-                        on_invoke_tool=governed_invoke,
-                        strict_json_schema=tool.strict_json_schema,
-                        is_enabled=tool.is_enabled,
-                        tool_input_guardrails=tool.tool_input_guardrails,
-                        tool_output_guardrails=tool.tool_output_guardrails,
-                    )
+
+                    field_names = {field.name for field in fields(FunctionTool)}
+                    tool_kwargs = {
+                        "name": tool.name,
+                        "description": tool.description,
+                        "params_json_schema": tool.params_json_schema,
+                        "on_invoke_tool": governed_invoke,
+                        "strict_json_schema": tool.strict_json_schema,
+                        "is_enabled": tool.is_enabled,
+                    }
+                    if "tool_input_guardrails" in field_names:
+                        tool_kwargs["tool_input_guardrails"] = getattr(
+                            tool, "tool_input_guardrails", None
+                        )
+                    if "tool_output_guardrails" in field_names:
+                        tool_kwargs["tool_output_guardrails"] = getattr(
+                            tool, "tool_output_guardrails", None
+                        )
+
+                    governed_tool = FunctionTool(**tool_kwargs)
                     
                     return governed_tool
                 
@@ -158,6 +175,9 @@ class OpenAIAgentsAdapter(ToolAdapter):
             setattr(tool_module, _PATCHED_ATTR, True)
 
             logger.info("OpenAI Agents adapter patched successfully")
+
+            self._patch_run_completion(cortex_hub)
+            self._patch_llm_calls(cortex_hub)
             
         except ImportError:
             logger.debug("OpenAI Agents SDK not installed, skipping")
@@ -180,6 +200,35 @@ class OpenAIAgentsAdapter(ToolAdapter):
             setattr(tool_module, _PATCHED_ATTR, False)
             
             logger.info("OpenAI Agents adapter unpatched")
+
+            try:
+                from agents.run import Runner
+
+                if hasattr(Runner, _ORIGINAL_RUN_ATTR):
+                    Runner.run = getattr(Runner, _ORIGINAL_RUN_ATTR)
+                if hasattr(Runner, _ORIGINAL_RUN_SYNC_ATTR):
+                    Runner.run_sync = getattr(Runner, _ORIGINAL_RUN_SYNC_ATTR)
+                if hasattr(Runner, _ORIGINAL_RUN_STREAMED_ATTR):
+                    Runner.run_streamed = getattr(Runner, _ORIGINAL_RUN_STREAMED_ATTR)
+                setattr(Runner, _PATCHED_RUN_ATTR, False)
+            except ImportError:
+                pass
+            try:
+                from agents.models.openai_responses import OpenAIResponsesModel
+                from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+
+                if hasattr(OpenAIResponsesModel, _ORIGINAL_RESPONSES_FETCH_ATTR):
+                    OpenAIResponsesModel._fetch_response = getattr(
+                        OpenAIResponsesModel, _ORIGINAL_RESPONSES_FETCH_ATTR
+                    )
+                if hasattr(OpenAIChatCompletionsModel, _ORIGINAL_CHAT_FETCH_ATTR):
+                    OpenAIChatCompletionsModel._fetch_response = getattr(
+                        OpenAIChatCompletionsModel, _ORIGINAL_CHAT_FETCH_ATTR
+                    )
+                setattr(OpenAIResponsesModel, _PATCHED_LLM_ATTR, False)
+                setattr(OpenAIChatCompletionsModel, _PATCHED_LLM_ATTR, False)
+            except ImportError:
+                pass
         except ImportError:
             pass
     
@@ -190,3 +239,278 @@ class OpenAIAgentsAdapter(ToolAdapter):
     def _discover_tools(self) -> list[dict[str, Any]]:
         """Discover tools from OpenAI Agents SDK (best-effort)."""
         return []
+
+    def _patch_run_completion(self, cortex_hub) -> None:
+        """Patch Runner run methods to emit run completion."""
+        try:
+            from agents.run import Runner
+
+            if getattr(Runner, _PATCHED_RUN_ATTR, False):
+                return
+
+            if not hasattr(Runner, _ORIGINAL_RUN_ATTR):
+                setattr(Runner, _ORIGINAL_RUN_ATTR, Runner.__dict__.get("run", Runner.run))
+            if not hasattr(Runner, _ORIGINAL_RUN_SYNC_ATTR):
+                setattr(Runner, _ORIGINAL_RUN_SYNC_ATTR, Runner.__dict__.get("run_sync", Runner.run_sync))
+            if not hasattr(Runner, _ORIGINAL_RUN_STREAMED_ATTR):
+                setattr(
+                    Runner,
+                    _ORIGINAL_RUN_STREAMED_ATTR,
+                    Runner.__dict__.get("run_streamed", Runner.run_streamed),
+                )
+
+            original_run_descriptor = getattr(Runner, _ORIGINAL_RUN_ATTR)
+            original_run_sync_descriptor = getattr(Runner, _ORIGINAL_RUN_SYNC_ATTR)
+            original_run_streamed_descriptor = getattr(Runner, _ORIGINAL_RUN_STREAMED_ATTR)
+            original_run = (
+                original_run_descriptor.__get__(None, Runner)
+                if hasattr(original_run_descriptor, "__get__")
+                else original_run_descriptor
+            )
+            original_run_sync = (
+                original_run_sync_descriptor.__get__(None, Runner)
+                if hasattr(original_run_sync_descriptor, "__get__")
+                else original_run_sync_descriptor
+            )
+            original_run_streamed = (
+                original_run_streamed_descriptor.__get__(None, Runner)
+                if hasattr(original_run_streamed_descriptor, "__get__")
+                else original_run_streamed_descriptor
+            )
+
+            @classmethod
+            async def patched_run(cls, *args, **kwargs):
+                status = "completed"
+                cortex_hub.start_run(framework="openai_agents")
+                try:
+                    return await original_run(*args, **kwargs)
+                except Exception:
+                    status = "failed"
+                    raise
+                finally:
+                    cortex_hub.finish_run(framework="openai_agents", status=status)
+
+            @classmethod
+            def patched_run_sync(cls, *args, **kwargs):
+                status = "completed"
+                cortex_hub.start_run(framework="openai_agents")
+                try:
+                    return original_run_sync(*args, **kwargs)
+                except Exception:
+                    status = "failed"
+                    raise
+                finally:
+                    cortex_hub.finish_run(framework="openai_agents", status=status)
+
+            @classmethod
+            def patched_run_streamed(cls, *args, **kwargs):
+                cortex_hub.start_run(framework="openai_agents")
+                try:
+                    result = original_run_streamed(*args, **kwargs)
+                except Exception:
+                    cortex_hub.finish_run(framework="openai_agents", status="failed")
+                    raise
+
+                original_stream_events = getattr(result, "stream_events", None)
+                if not callable(original_stream_events):
+                    return result
+
+                async def wrapped_stream_events(*stream_args, **stream_kwargs):
+                    completed = False
+                    failed = False
+                    try:
+                        async for event in original_stream_events(*stream_args, **stream_kwargs):
+                            yield event
+                        completed = True
+                    except Exception:
+                        failed = True
+                        completed = True
+                        raise
+                    finally:
+                        if completed:
+                            status = "failed" if failed else "completed"
+                            cortex_hub.finish_run(framework="openai_agents", status=status)
+
+                result.stream_events = wrapped_stream_events
+                return result
+
+            Runner.run = patched_run
+            Runner.run_sync = patched_run_sync
+            Runner.run_streamed = patched_run_streamed
+            setattr(Runner, _PATCHED_RUN_ATTR, True)
+            logger.info("OpenAI Agents run completion patched successfully")
+        except ImportError:
+            logger.debug("OpenAI Agents run completion patch skipped")
+
+    def _patch_llm_calls(self, cortex_hub: "CortexHub") -> None:
+        """Patch OpenAI Agents models to emit llm.call spans."""
+        try:
+            from agents.models.openai_responses import OpenAIResponsesModel
+            from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+
+            if getattr(OpenAIResponsesModel, _PATCHED_LLM_ATTR, False):
+                return
+
+            if not hasattr(OpenAIResponsesModel, _ORIGINAL_RESPONSES_FETCH_ATTR):
+                setattr(
+                    OpenAIResponsesModel,
+                    _ORIGINAL_RESPONSES_FETCH_ATTR,
+                    OpenAIResponsesModel._fetch_response,
+                )
+            if not hasattr(OpenAIChatCompletionsModel, _ORIGINAL_CHAT_FETCH_ATTR):
+                setattr(
+                    OpenAIChatCompletionsModel,
+                    _ORIGINAL_CHAT_FETCH_ATTR,
+                    OpenAIChatCompletionsModel._fetch_response,
+                )
+
+            original_responses_fetch = getattr(
+                OpenAIResponsesModel, _ORIGINAL_RESPONSES_FETCH_ATTR
+            )
+            original_chat_fetch = getattr(
+                OpenAIChatCompletionsModel, _ORIGINAL_CHAT_FETCH_ATTR
+            )
+
+            def _with_system_prompt(system_instructions, input_payload):
+                if not system_instructions:
+                    return input_payload
+                if isinstance(input_payload, list):
+                    return [{"role": "system", "content": system_instructions}] + input_payload
+                return [{"role": "system", "content": system_instructions}, input_payload]
+
+            def _split_prompt_override(prompt_override, system_instructions, input_payload):
+                if prompt_override is None:
+                    return system_instructions, input_payload
+                if isinstance(prompt_override, list) and prompt_override:
+                    first = prompt_override[0]
+                    if (
+                        isinstance(first, dict)
+                        and first.get("role") == "system"
+                        and isinstance(first.get("content"), str)
+                    ):
+                        return first["content"], prompt_override[1:]
+                    return system_instructions, prompt_override
+                return system_instructions, prompt_override
+
+            async def patched_responses_fetch(
+                self,
+                system_instructions,
+                input,
+                model_settings,
+                tools,
+                output_schema,
+                handoffs,
+                previous_response_id,
+                stream=False,
+            ):
+                prompt = _with_system_prompt(system_instructions, input)
+                model_name = str(getattr(self, "model", "unknown"))
+
+                async def call_original(prompt_override):
+                    new_system, new_input = _split_prompt_override(
+                        prompt_override,
+                        system_instructions,
+                        input,
+                    )
+                    return await original_responses_fetch(
+                        self,
+                        new_system,
+                        new_input,
+                        model_settings,
+                        tools,
+                        output_schema,
+                        handoffs,
+                        previous_response_id,
+                        stream=stream,
+                    )
+
+                llm_metadata = {
+                    "kind": "llm",
+                    "framework": "openai_agents",
+                    "model": model_name,
+                    "prompt": prompt,
+                    "call_original": call_original,
+                }
+                governed = govern_execution(
+                    tool_fn=lambda *a, **kw: original_responses_fetch(
+                        self,
+                        system_instructions,
+                        input,
+                        model_settings,
+                        tools,
+                        output_schema,
+                        handoffs,
+                        previous_response_id,
+                        stream=stream,
+                    ),
+                    tool_metadata=llm_metadata,
+                    cortex_hub=cortex_hub,
+                )
+                return await governed()
+
+            async def patched_chat_fetch(
+                self,
+                system_instructions,
+                input,
+                model_settings,
+                tools,
+                output_schema,
+                handoffs,
+                span,
+                tracing,
+                stream=False,
+            ):
+                prompt = _with_system_prompt(system_instructions, input)
+                model_name = str(getattr(self, "model", "unknown"))
+
+                async def call_original(prompt_override):
+                    new_system, new_input = _split_prompt_override(
+                        prompt_override,
+                        system_instructions,
+                        input,
+                    )
+                    return await original_chat_fetch(
+                        self,
+                        new_system,
+                        new_input,
+                        model_settings,
+                        tools,
+                        output_schema,
+                        handoffs,
+                        span,
+                        tracing,
+                        stream=stream,
+                    )
+
+                llm_metadata = {
+                    "kind": "llm",
+                    "framework": "openai_agents",
+                    "model": model_name,
+                    "prompt": prompt,
+                    "call_original": call_original,
+                }
+                governed = govern_execution(
+                    tool_fn=lambda *a, **kw: original_chat_fetch(
+                        self,
+                        system_instructions,
+                        input,
+                        model_settings,
+                        tools,
+                        output_schema,
+                        handoffs,
+                        span,
+                        tracing,
+                        stream=stream,
+                    ),
+                    tool_metadata=llm_metadata,
+                    cortex_hub=cortex_hub,
+                )
+                return await governed()
+
+            OpenAIResponsesModel._fetch_response = patched_responses_fetch
+            OpenAIChatCompletionsModel._fetch_response = patched_chat_fetch
+            setattr(OpenAIResponsesModel, _PATCHED_LLM_ATTR, True)
+            setattr(OpenAIChatCompletionsModel, _PATCHED_LLM_ATTR, True)
+            logger.info("OpenAI Agents LLM interception patched successfully")
+        except Exception as e:
+            logger.debug("OpenAI Agents LLM interception skipped", reason=str(e))

cortexhub/client.py

@@ -26,6 +26,7 @@ Privacy Mode:
 - privacy=False: Raw data included (for testing policies in dev/staging)
 """
 
+import contextvars
 import json
 import os
 import time
@@ -65,6 +66,11 @@ from cortexhub.policy.models import (
 from cortexhub.version import __version__
 
 logger = structlog.get_logger(__name__)
+_run_depth: contextvars.ContextVar[int] = contextvars.ContextVar("cortexhub_run_depth", default=0)
+_session_id_var: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "cortexhub_session_id",
+    default=None,
+)
 
 
 class CortexHub:
@@ -138,7 +144,7 @@ class CortexHub:
         # Internal state
         self._project_id: str | None = None
         self._sdk_config = None  # SDKConfig from backend
-        self.session_id = self._generate_session_id()
+        self._session_id = self._generate_session_id()
 
         # Initialize OpenTelemetry
         self._tracer_provider = None
@@ -1998,6 +2004,83 @@ class CortexHub:
                 self._tracer_provider.force_flush()
         return True
 
+    @property
+    def session_id(self) -> str:
+        """Return the current session ID for this execution context."""
+        return _session_id_var.get() or self._session_id
+
+    def finish_run(
+        self,
+        *,
+        framework: str | None = None,
+        status: str = "completed",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Emit a run completion span and flush telemetry."""
+        depth = _run_depth.get()
+        if depth > 0:
+            _run_depth.set(depth - 1)
+            if depth > 1:
+                return
+
+        normalized_status = "failed" if status == "failed" else "completed"
+        span_name = "run.failed" if normalized_status == "failed" else "run.completed"
+
+        with self._tracer.start_as_current_span(
+            name=span_name,
+            kind=trace.SpanKind.INTERNAL,
+        ) as span:
+            span.set_attribute("cortexhub.session.id", self.session_id)
+            span.set_attribute("cortexhub.agent.id", self.agent_id)
+            span.set_attribute("cortexhub.run.status", normalized_status)
+
+            if framework:
+                span.set_attribute("cortexhub.run.framework", framework)
+            if metadata:
+                span.set_attribute(
+                    "cortexhub.run.metadata",
+                    json.dumps(metadata, default=str),
+                )
+
+            if normalized_status == "failed":
+                span.set_status(Status(StatusCode.ERROR, "Run failed"))
+            else:
+                span.set_status(Status(StatusCode.OK))
+
+        self.export_telemetry()
+
+    def start_run(
+        self,
+        *,
+        framework: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Emit a run started span."""
+        depth = _run_depth.get()
+        if depth == 0:
+            _session_id_var.set(self._generate_session_id())
+        _run_depth.set(depth + 1)
+        if depth > 0:
+            return
+
+        with self._tracer.start_as_current_span(
+            name="run.started",
+            kind=trace.SpanKind.INTERNAL,
+        ) as span:
+            span.set_attribute("cortexhub.session.id", self.session_id)
+            span.set_attribute("cortexhub.agent.id", self.agent_id)
+            span.set_attribute("cortexhub.run.status", "running")
+
+            if framework:
+                span.set_attribute("cortexhub.run.framework", framework)
+            if metadata:
+                span.set_attribute(
+                    "cortexhub.run.metadata",
+                    json.dumps(metadata, default=str),
+                )
+
+            span.set_status(Status(StatusCode.OK))
+
     def has_policies(self) -> bool:
         """Check if enforcement mode is active (policies loaded from CortexHub).
         

{cortexhub-0.1.3.dist-info → cortexhub-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexhub
-Version: 0.1.3
+Version: 0.1.4
 Summary: CortexHub Python SDK - Policy-as-Code for AI Agents
 Project-URL: Homepage, https://cortexhub.ai
 Project-URL: Documentation, https://docs.cortexhub.ai
@@ -39,12 +39,14 @@ Requires-Dist: crewai>=0.50.0; extra == 'all'
 Requires-Dist: langchain-core>=0.2.0; extra == 'all'
 Requires-Dist: langchain-openai>=0.1.0; extra == 'all'
 Requires-Dist: langgraph>=0.2.0; extra == 'all'
+Requires-Dist: litellm>=1.81.5; extra == 'all'
 Requires-Dist: openai-agents>=0.0.3; extra == 'all'
 Provides-Extra: claude-agents
 Requires-Dist: anthropic>=0.40.0; extra == 'claude-agents'
 Requires-Dist: claude-agent-sdk>=0.0.1; extra == 'claude-agents'
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.50.0; extra == 'crewai'
+Requires-Dist: litellm>=1.81.5; extra == 'crewai'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
@@ -105,6 +107,16 @@ from langgraph.prebuilt import create_react_agent
 | OpenAI Agents | `Framework.OPENAI_AGENTS` | `pip install cortexhub[openai-agents]` |
 | Claude Agents | `Framework.CLAUDE_AGENTS` | `pip install cortexhub[claude-agents]` |
 
+## Tracing Coverage
+
+All frameworks emit `run.started` and `run.completed`/`run.failed` for each run.
+Tool spans (`tool.invoke`) and model spans (`llm.call`) vary by SDK:
+
+- **LangGraph**: tool calls via `BaseTool.invoke`, LLM calls via `BaseChatModel.invoke/ainvoke`
+- **CrewAI**: tool calls via `CrewStructuredTool.invoke`/`BaseTool.run`, LLM calls via LiteLLM and `BaseLLM.call/acall`
+- **OpenAI Agents**: tool calls via `function_tool`, LLM calls via `OpenAIResponsesModel` and `OpenAIChatCompletionsModel`
+- **Claude Agents**: tool calls via `@tool` and built-in tool hooks; LLM calls run inside the Claude Code CLI and are not intercepted by the Python SDK
+
 ## Configuration
 
 ```bash