cortexhub 0.1.3__tar.gz → 0.1.5__tar.gz

{cortexhub-0.1.3 → cortexhub-0.1.5}/.gitignore

@@ -99,3 +99,6 @@ pnpm-debug.log*
 Thumbs.db
 python/cortexhub_data
 
+.planning/
+.cursor/
+.claude/

{cortexhub-0.1.3 → cortexhub-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexhub
-Version: 0.1.3
+Version: 0.1.5
 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

{cortexhub-0.1.3 → cortexhub-0.1.5}/README.md

@@ -44,6 +44,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

{cortexhub-0.1.3 → cortexhub-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortexhub"
-version = "0.1.3"
+version = "0.1.5"
 description = "CortexHub Python SDK - Policy-as-Code for AI Agents"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
@@ -55,6 +55,7 @@ langgraph = [
 
 crewai = [
     "crewai>=0.50.0",
+    "litellm>=1.81.5",
 ]
 
 openai-agents = [
@@ -139,6 +140,7 @@ dev = [
     "langchain-openai>=0.1.0",
     "langgraph>=0.2.0",
     "crewai>=0.50.0",
+    "litellm>=1.81.5",
     "openai-agents>=0.0.3",
     "anthropic>=0.40.0",
     "claude-agent-sdk>=0.0.1",

{cortexhub-0.1.3 → cortexhub-0.1.5}/src/cortexhub/adapters/claude_agents.py

@@ -19,11 +19,13 @@ Architectural rules:
 - No governance logic in adapter
 """
 
+import json
 import os
 from functools import wraps
 from typing import TYPE_CHECKING, Any, Callable, Awaitable
 
 import structlog
+from opentelemetry.trace import SpanKind, Status, StatusCode
 
 from cortexhub.adapters.base import ToolAdapter
 from cortexhub.pipeline import govern_execution
@@ -36,6 +38,10 @@ logger = structlog.get_logger(__name__)
 # Attribute names for storing originals
 _ORIGINAL_TOOL_ATTR = "__cortexhub_original_tool__"
 _PATCHED_ATTR = "__cortexhub_patched__"
+_ORIGINAL_QUERY_ATTR = "__cortexhub_original_query__"
+_ORIGINAL_RECEIVE_RESPONSE_ATTR = "__cortexhub_original_receive_response__"
+_ORIGINAL_CLIENT_QUERY_ATTR = "__cortexhub_original_client_query__"
+_PATCHED_RUN_ATTR = "__cortexhub_run_patched__"
 
 
 class ClaudeAgentsAdapter(ToolAdapter):
@@ -64,6 +70,11 @@ class ClaudeAgentsAdapter(ToolAdapter):
     def framework_name(self) -> str:
         return "claude_agents"
 
+    def __init__(self, cortex_hub: Any):
+        super().__init__(cortex_hub)
+        self._hook_spans: dict[str, Any] = {}
+        self._active_run_session_id: str | None = None
+
     def _get_framework_modules(self) -> list[str]:
         return ["claude_agent_sdk"]
 
@@ -145,6 +156,8 @@ class ClaudeAgentsAdapter(ToolAdapter):
             setattr(claude_agent_sdk, _PATCHED_ATTR, True)
             
             logger.info("Claude Agent SDK @tool decorator patched successfully")
+
+            self._patch_run_completion(cortex_hub)
             
         except ImportError:
             logger.debug("Claude Agent SDK not installed, skipping adapter")
@@ -161,6 +174,23 @@ class ClaudeAgentsAdapter(ToolAdapter):
                 claude_agent_sdk.tool = original
                 setattr(claude_agent_sdk, _PATCHED_ATTR, False)
                 logger.info("Claude Agent SDK adapter unpatched")
+            
+            try:
+                from claude_agent_sdk import ClaudeSDKClient
+
+                if hasattr(claude_agent_sdk, _ORIGINAL_QUERY_ATTR):
+                    claude_agent_sdk.query = getattr(claude_agent_sdk, _ORIGINAL_QUERY_ATTR)
+                if hasattr(ClaudeSDKClient, _ORIGINAL_CLIENT_QUERY_ATTR):
+                    ClaudeSDKClient.query = getattr(
+                        ClaudeSDKClient, _ORIGINAL_CLIENT_QUERY_ATTR
+                    )
+                if hasattr(ClaudeSDKClient, _ORIGINAL_RECEIVE_RESPONSE_ATTR):
+                    ClaudeSDKClient.receive_response = getattr(
+                        ClaudeSDKClient, _ORIGINAL_RECEIVE_RESPONSE_ATTR
+                    )
+                setattr(claude_agent_sdk, _PATCHED_RUN_ATTR, False)
+            except ImportError:
+                pass
         except ImportError:
             pass
 
@@ -171,6 +201,94 @@ class ClaudeAgentsAdapter(ToolAdapter):
     def _discover_tools(self) -> list[dict[str, Any]]:
         """Discover tools from Claude Agent SDK (best-effort)."""
         return []
+
+    def _patch_run_completion(self, cortex_hub) -> None:
+        """Patch Claude Agent SDK runs to emit run completion."""
+        try:
+            import claude_agent_sdk
+            from claude_agent_sdk import ClaudeSDKClient, ResultMessage
+            adapter = self
+
+            if getattr(claude_agent_sdk, _PATCHED_RUN_ATTR, False):
+                return
+
+            if not hasattr(claude_agent_sdk, _ORIGINAL_QUERY_ATTR):
+                setattr(claude_agent_sdk, _ORIGINAL_QUERY_ATTR, claude_agent_sdk.query)
+            original_query = getattr(claude_agent_sdk, _ORIGINAL_QUERY_ATTR)
+
+            async def patched_query(*args, **kwargs):
+                status = None
+                failed = False
+                cortex_hub.start_run(framework="claude_agents")
+                adapter._active_run_session_id = cortex_hub.session_id
+                try:
+                    async for message in original_query(*args, **kwargs):
+                        if isinstance(message, ResultMessage):
+                            status = "failed" if message.is_error else "completed"
+                        yield message
+                except Exception:
+                    failed = True
+                    raise
+                finally:
+                    if status is None and failed:
+                        status = "failed"
+                    if status:
+                        cortex_hub.finish_run(framework="claude_agents", status=status)
+                    adapter._active_run_session_id = None
+
+            claude_agent_sdk.query = patched_query
+
+            if not hasattr(ClaudeSDKClient, _ORIGINAL_RECEIVE_RESPONSE_ATTR):
+                setattr(
+                    ClaudeSDKClient,
+                    _ORIGINAL_RECEIVE_RESPONSE_ATTR,
+                    ClaudeSDKClient.receive_response,
+                )
+            original_receive_response = getattr(ClaudeSDKClient, _ORIGINAL_RECEIVE_RESPONSE_ATTR)
+            if not hasattr(ClaudeSDKClient, _ORIGINAL_CLIENT_QUERY_ATTR):
+                setattr(
+                    ClaudeSDKClient,
+                    _ORIGINAL_CLIENT_QUERY_ATTR,
+                    ClaudeSDKClient.query,
+                )
+            original_client_query = getattr(ClaudeSDKClient, _ORIGINAL_CLIENT_QUERY_ATTR)
+
+            async def patched_client_query(self, *args, **kwargs):
+                cortex_hub.start_run(framework="claude_agents")
+                adapter._active_run_session_id = cortex_hub.session_id
+                try:
+                    return await original_client_query(self, *args, **kwargs)
+                except Exception:
+                    cortex_hub.finish_run(framework="claude_agents", status="failed")
+                    adapter._active_run_session_id = None
+                    raise
+
+            async def patched_receive_response(self, *args, **kwargs):
+                status = None
+                failed = False
+                try:
+                    async for message in original_receive_response(self, *args, **kwargs):
+                        if isinstance(message, ResultMessage):
+                            status = "failed" if message.is_error else "completed"
+                        yield message
+                except Exception:
+                    failed = True
+                    raise
+                finally:
+                    if status is None and failed:
+                        status = "failed"
+                    if status:
+                        cortex_hub.finish_run(framework="claude_agents", status=status)
+                    adapter._active_run_session_id = None
+
+            ClaudeSDKClient.query = patched_client_query
+            ClaudeSDKClient.receive_response = patched_receive_response
+            setattr(claude_agent_sdk, _PATCHED_RUN_ATTR, True)
+            logger.info("Claude Agent SDK run completion patched successfully")
+        except ImportError:
+            logger.debug("Claude Agent SDK run completion patch skipped")
+        except Exception as e:
+            logger.debug("Claude Agent SDK run completion patch failed", reason=str(e))
     
     def create_governance_hooks(self) -> dict[str, list]:
         """Create CortexHub governance hooks for Claude Agent SDK.
@@ -191,6 +309,65 @@ class ClaudeAgentsAdapter(ToolAdapter):
             )
         """
         cortex_hub = self.cortex_hub
+        span_store = self._hook_spans
+        adapter = self
+
+        def _current_session_id() -> str:
+            return adapter._active_run_session_id or cortex_hub.session_id
+
+        def _start_tool_span(
+            *,
+            tool_name: str,
+            tool_description: str,
+            policy_args: dict[str, Any],
+            raw_args: dict[str, Any],
+            tool_use_id: str | None,
+        ):
+            span = cortex_hub._tracer.start_span(
+                name="tool.invoke",
+                kind=SpanKind.INTERNAL,
+            )
+            span.set_attribute("cortexhub.session.id", _current_session_id())
+            span.set_attribute("cortexhub.agent.id", cortex_hub.agent_id)
+            span.set_attribute("cortexhub.tool.name", tool_name)
+            span.set_attribute("cortexhub.tool.framework", "claude_agents")
+            span.set_attribute("cortexhub.tool.description", tool_description)
+
+            if tool_use_id:
+                span.set_attribute("cortexhub.tool.use_id", tool_use_id)
+
+            if policy_args:
+                arg_names = list(policy_args.keys())
+                if arg_names:
+                    span.set_attribute("cortexhub.tool.arg_names", arg_names)
+                arg_schema = cortex_hub._infer_arg_schema(policy_args)
+                if arg_schema:
+                    span.set_attribute(
+                        "cortexhub.tool.arg_schema",
+                        json.dumps(arg_schema),
+                    )
+
+            if not cortex_hub.privacy and raw_args:
+                span.set_attribute("cortexhub.raw.args", json.dumps(raw_args, default=str))
+
+            return span
+
+        def _finish_tool_span(
+            span,
+            *,
+            success: bool,
+            error_message: str | None = None,
+            result: Any | None = None,
+        ) -> None:
+            span.set_attribute("cortexhub.result.success", success)
+            if error_message:
+                span.set_attribute("cortexhub.error.message", error_message)
+                span.set_status(Status(StatusCode.ERROR, error_message))
+            else:
+                span.set_status(Status(StatusCode.OK))
+            if result is not None and not cortex_hub.privacy:
+                span.set_attribute("cortexhub.raw.result", json.dumps(result, default=str))
+            span.end()
         
         async def pre_tool_governance(
             input_data: dict[str, Any],
@@ -204,12 +381,18 @@ class ClaudeAgentsAdapter(ToolAdapter):
             """
             tool_name = input_data.get("tool_name", "unknown")
             tool_input = input_data.get("tool_input", {})
+            if not isinstance(tool_input, dict):
+                tool_input = {"_raw": tool_input}
+            policy_args = cortex_hub._sanitize_policy_args(tool_input)
             
-            tool_metadata = {
-                "name": tool_name,
-                "description": f"Claude Agent SDK built-in tool: {tool_name}",
-                "framework": "claude_agents",
-            }
+            tool_description = f"Claude Agent SDK built-in tool: {tool_name}"
+            span = _start_tool_span(
+                tool_name=tool_name,
+                tool_description=tool_description,
+                policy_args=policy_args,
+                raw_args=tool_input,
+                tool_use_id=tool_use_id,
+            )
             
             # Build authorization request and evaluate
             from cortexhub.policy.models import (
@@ -222,7 +405,7 @@ class ClaudeAgentsAdapter(ToolAdapter):
                 principal=Principal(type="Agent", id=cortex_hub.agent_id),
                 action=Action(type="tool.invoke", name=tool_name),
                 resource=PolicyResource(type="Tool", id=tool_name),
-                args=tool_input,
+                args=policy_args,
                 framework="claude_agents",
             )
             
@@ -230,8 +413,23 @@ class ClaudeAgentsAdapter(ToolAdapter):
             if cortex_hub.enforce and cortex_hub.evaluator:
                 from cortexhub.policy.effects import Effect
                 decision = cortex_hub.evaluator.evaluate(request)
+
+                span.add_event(
+                    "policy.decision",
+                    attributes={
+                        "decision.effect": decision.effect.value,
+                        "decision.policy_id": decision.policy_id or "",
+                        "decision.reasoning": decision.reasoning,
+                        "decision.policy_name": decision.policy_name or "",
+                    },
+                )
                 
                 if decision.effect == Effect.DENY:
+                    _finish_tool_span(
+                        span,
+                        success=False,
+                        error_message=decision.reasoning,
+                    )
                     return {
                         "hookSpecificOutput": {
                             "hookEventName": "PreToolUse",
@@ -242,7 +440,7 @@ class ClaudeAgentsAdapter(ToolAdapter):
                 
                 if decision.effect == Effect.ESCALATE:
                     try:
-                        context_hash = cortex_hub._compute_context_hash(tool_name, tool_input)
+                        context_hash = cortex_hub._compute_context_hash(tool_name, policy_args)
                         approval_response = cortex_hub.backend.create_approval(
                             run_id=cortex_hub.session_id,
                             trace_id=cortex_hub._get_current_trace_id(),
@@ -260,6 +458,11 @@ class ClaudeAgentsAdapter(ToolAdapter):
                         approval_id = approval_response.get("approval_id", "unknown")
                     except Exception as e:
                         logger.error("Failed to create approval", error=str(e))
+                        _finish_tool_span(
+                            span,
+                            success=False,
+                            error_message=str(e),
+                        )
                         return {
                             "hookSpecificOutput": {
                                 "hookEventName": "PreToolUse",
@@ -270,6 +473,20 @@ class ClaudeAgentsAdapter(ToolAdapter):
                             }
                         }
 
+                    span.add_event(
+                        "approval.created",
+                        attributes={
+                            "approval_id": approval_id,
+                            "tool_name": tool_name,
+                            "policy_id": decision.policy_id or "",
+                            "expires_at": approval_response.get("expires_at", ""),
+                        },
+                    )
+                    _finish_tool_span(
+                        span,
+                        success=False,
+                        error_message="Approval required",
+                    )
                     return {
                         "hookSpecificOutput": {
                             "hookEventName": "PreToolUse",
@@ -281,6 +498,10 @@ class ClaudeAgentsAdapter(ToolAdapter):
                     }
             
             # Allow execution
+            if tool_use_id:
+                span_store[tool_use_id] = span
+            else:
+                span.end()
             return {}
         
         async def post_tool_governance(
@@ -294,6 +515,21 @@ class ClaudeAgentsAdapter(ToolAdapter):
             """
             tool_name = input_data.get("tool_name", "unknown")
             tool_response = input_data.get("tool_response", {})
+            tool_input = input_data.get("tool_input", {})
+            if not isinstance(tool_input, dict):
+                tool_input = {"_raw": tool_input}
+            policy_args = cortex_hub._sanitize_policy_args(tool_input)
+
+            span = span_store.pop(tool_use_id, None) if tool_use_id else None
+            if span is None:
+                tool_description = f"Claude Agent SDK built-in tool: {tool_name}"
+                span = _start_tool_span(
+                    tool_name=tool_name,
+                    tool_description=tool_description,
+                    policy_args=policy_args,
+                    raw_args=tool_input,
+                    tool_use_id=tool_use_id,
+                )
             
             # Log the tool execution
             logger.debug(
@@ -301,6 +537,8 @@ class ClaudeAgentsAdapter(ToolAdapter):
                 tool=tool_name,
                 framework="claude_agents",
             )
+
+            _finish_tool_span(span, success=True, result=tool_response)
             
             return {}