veille-supervisor 0.3.0__py3-none-any.whl

supervisor/__init__.py

@@ -0,0 +1,3 @@
+"""AI Runtime Supervisor — control plane for production agent work."""
+
+__version__ = "0.2.0"

supervisor/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Framework and provider adapter ports."""
+
+from supervisor.adapters.langgraph.port import LangGraphAdapter, LangGraphEventHook
+from supervisor.adapters.litellm.mock import LiteLLMMockAdapter, MockCompletionResult
+
+__all__ = [
+    "LangGraphAdapter",
+    "LangGraphEventHook",
+    "LiteLLMMockAdapter",
+    "MockCompletionResult",
+]

supervisor/adapters/generic.py

@@ -0,0 +1,52 @@
+"""Generic framework adapter base.
+
+Wraps any Python agent/callable so it executes *through* Veille's runtime and
+emits normalized events. OpenAI Agents SDK and OpenAI Responses API adapters
+build on this; SDK-specific tracing hooks (handoffs, traces) are future
+integration points layered on top of ``InstrumentedAgent``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Protocol, runtime_checkable
+
+from supervisor.sdk import Supervisor
+
+
+@runtime_checkable
+class FrameworkAgent(Protocol):
+    def run(self, input: Any, **kwargs: Any) -> Any: ...
+    def invoke(self, input: Any, **kwargs: Any) -> Any: ...
+
+
+class InstrumentedAgent:
+    """Runs an agent callable under Veille's run lifecycle."""
+
+    def __init__(self, agent_fn: Any, supervisor: Supervisor) -> None:
+        self._agent_fn = agent_fn
+        self._supervisor = supervisor
+
+    def run(self, input: Any, **kwargs: Any) -> Any:
+        self._supervisor.start_run()
+        try:
+            return self._agent_fn(input, self._supervisor)
+        finally:
+            self._supervisor.finish_run("pass")
+
+    def invoke(self, input: Any, **kwargs: Any) -> Any:
+        return self.run(input, **kwargs)
+
+
+class GenericFrameworkAdapter:
+    """Implements the framework-neutral :class:`FrameworkAdapter` port."""
+
+    def attach(self, target: Any, supervisor: Supervisor, **kwargs: Any) -> InstrumentedAgent:
+        return InstrumentedAgent(target, supervisor)
+
+    def extract_run_id(self, config: dict[str, Any] | None) -> str:
+        if config and config.get("run_id"):
+            return str(config["run_id"])
+        if config and config.get("configurable", {}).get("run_id"):
+            return str(config["configurable"]["run_id"])
+        return str(uuid.uuid4())

supervisor/adapters/langgraph/__init__.py

@@ -0,0 +1,20 @@
+"""LangGraph adapter package."""
+
+from __future__ import annotations
+
+from supervisor.adapters.langgraph.adapter import (
+    InstrumentedGraph,
+    LangGraphCallbackHandler,
+    LangGraphInstrumentedAdapter,
+)
+from supervisor.adapters.langgraph.port import LangGraphAdapter, LangGraphEventHook
+from supervisor.adapters.langgraph.stub import LangGraphAdapterStub
+
+__all__ = [
+    "InstrumentedGraph",
+    "LangGraphCallbackHandler",
+    "LangGraphInstrumentedAdapter",
+    "LangGraphAdapter",
+    "LangGraphEventHook",
+    "LangGraphAdapterStub",
+]

supervisor/adapters/langgraph/adapter.py

@@ -0,0 +1,132 @@
+"""LangGraph adapter implementation (Phase 1).
+
+Wraps a compiled LangGraph graph so that a supervised run is captured
+automatically: run lifecycle via the wrapper, and model/tool/retry events via
+a LangChain callback handler for graphs that use LangChain-native LLM/Tool
+primitives. The cited-market-research demo uses the ``Supervisor`` helpers for
+its manual mock calls, so the callback handler is dormant there but available
+for any LangChain-based agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from supervisor.contracts.events import EventType
+from supervisor.sdk.supervisor import Supervisor
+
+
+class LangGraphCallbackHandler(BaseCallbackHandler):
+    """Maps LangChain callback events to normalized supervisor ``RunEvent`` facts."""
+
+    def __init__(self, supervisor: Supervisor) -> None:
+        super().__init__()
+        self._supervisor = supervisor
+
+    def on_llm_start(
+        self, serialized: Any, prompts: Any, *, run_id: Any = None, **kwargs: Any
+    ) -> None:
+        invocation = kwargs.get("invocation_params") or {}
+        model = invocation.get("model") or invocation.get("model_name") or "unknown"
+        preview = ""
+        if isinstance(prompts, (list, tuple)) and prompts:
+            preview = str(prompts[0])[:120]
+        self._supervisor.collector.emit(
+            EventType.MODEL_REQUESTED,
+            model_name=str(model),
+            attributes={"prompt_preview": preview},
+        )
+
+    def on_llm_end(self, response: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        tokens_in = tokens_out = None
+        try:
+            usage = getattr(response, "llm_output", {}) or {}
+            token_usage = usage.get("token_usage", {}) or {}
+            tokens_in = token_usage.get("prompt_tokens")
+            tokens_out = token_usage.get("completion_tokens")
+        except Exception:
+            pass
+        self._supervisor.collector.emit(
+            EventType.MODEL_COMPLETED,
+            input_tokens=tokens_in,
+            output_tokens=tokens_out,
+            status="ok",
+        )
+
+    def on_tool_start(
+        self, serialized: Any, input_str: Any, *, run_id: Any = None, **kwargs: Any
+    ) -> None:
+        name = (
+            serialized.get("name")
+            if isinstance(serialized, dict)
+            else getattr(serialized, "name", None)
+        )
+        self._supervisor.collector.emit(
+            EventType.TOOL_REQUESTED,
+            tool_name=name,
+            attributes={"input": {"input": str(input_str)[:500]}},
+        )
+
+    def on_tool_end(self, output: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._supervisor.collector.emit(EventType.TOOL_COMPLETED, status="ok")
+
+    def on_tool_error(self, error: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._supervisor.collector.emit(
+            EventType.TOOL_COMPLETED,
+            status="error",
+            error_message=str(error)[:500],
+        )
+
+    def on_retry(self, retry_state: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._supervisor.collector.emit(EventType.RETRY_SCHEDULED)
+
+
+class InstrumentedGraph:
+    """A compiled graph wrapped so supervisor run lifecycle is captured."""
+
+    def __init__(
+        self, graph: Any, supervisor: Supervisor, *, auto_run_lifecycle: bool = True
+    ) -> None:
+        self._graph = graph
+        self._supervisor = supervisor
+        self._handler = LangGraphCallbackHandler(supervisor)
+        self._auto = auto_run_lifecycle
+
+    def _merge_config(self, config: Any) -> dict[str, Any]:
+        base: dict[str, Any] = dict(config) if isinstance(config, dict) else {}
+        callbacks = list(base.get("callbacks") or [])
+        callbacks.append(self._handler)
+        base["callbacks"] = callbacks
+        return base
+
+    def invoke(self, input: Any, config: Any = None, **kwargs: Any) -> Any:
+        if self._auto:
+            self._supervisor.start_run()
+        try:
+            out = self._graph.invoke(input, config=self._merge_config(config), **kwargs)
+        except Exception:
+            if self._auto:
+                self._supervisor.finish_run("error")
+            raise
+        if self._auto:
+            self._supervisor.finish_run("ok")
+        return out
+
+
+class LangGraphInstrumentedAdapter:
+    """Phase 1 LangGraph adapter: implements the port's ``attach`` contract."""
+
+    def attach(
+        self, graph: Any, supervisor: Supervisor, *, auto_run_lifecycle: bool = True
+    ) -> InstrumentedGraph:
+        return InstrumentedGraph(graph, supervisor, auto_run_lifecycle=auto_run_lifecycle)
+
+    def extract_run_id(self, config: dict[str, Any] | None) -> str:
+        if config and "configurable" in config:
+            run_id = config["configurable"].get("run_id")
+            if isinstance(run_id, str):
+                return run_id
+        return str(uuid4())

supervisor/adapters/langgraph/port.py

@@ -0,0 +1,53 @@
+"""LangGraph adapter port — Phase 1 will implement full instrumentation."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from supervisor.contracts.events import RunEvent
+
+
+@runtime_checkable
+class LangGraphEventHook(Protocol):
+    """Callback surface for LangGraph lifecycle events."""
+
+    def on_run_started(self, run_id: str, task_id: str, metadata: dict[str, Any]) -> None: ...
+
+    def on_run_finished(self, run_id: str, status: str, metadata: dict[str, Any]) -> None: ...
+
+    def on_agent_event(
+        self, run_id: str, agent_id: str, event_type: str, metadata: dict[str, Any]
+    ) -> None: ...
+
+    def on_tool_event(
+        self,
+        run_id: str,
+        tool_name: str,
+        event_type: str,
+        input_data: dict[str, Any],
+        metadata: dict[str, Any],
+    ) -> None: ...
+
+    def on_model_event(
+        self,
+        run_id: str,
+        model_name: str,
+        event_type: str,
+        token_usage: dict[str, int],
+        metadata: dict[str, Any],
+    ) -> None: ...
+
+    def flush(self) -> list[RunEvent]: ...
+
+
+@runtime_checkable
+class LangGraphAdapter(Protocol):
+    """Port for wrapping LangGraph agents with supervisor instrumentation."""
+
+    def attach(self, graph: Any, hook: LangGraphEventHook) -> Any:
+        """Return an instrumented graph. Phase 1 implementation."""
+        ...
+
+    def extract_run_id(self, config: dict[str, Any] | None) -> str:
+        """Extract or generate a stable run identifier."""
+        ...

supervisor/adapters/langgraph/stub.py

@@ -0,0 +1,26 @@
+"""LangGraph adapter stub — returns graph unchanged until Phase 1."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from supervisor.adapters.langgraph.port import LangGraphEventHook
+
+
+class LangGraphAdapterStub:
+    """Phase 0 stub: documents the adapter contract without modifying execution."""
+
+    def attach(self, graph: Any, hook: LangGraphEventHook) -> Any:
+        _ = hook
+        return graph
+
+    def extract_run_id(self, config: dict[str, Any] | None) -> str:
+        if config and "configurable" in config:
+            run_id = config["configurable"].get("run_id")
+            if isinstance(run_id, str):
+                return run_id
+        return str(uuid4())
+
+
+# LangGraphAdapterStub implements the LangGraphAdapter protocol.

supervisor/adapters/litellm/mock.py

@@ -0,0 +1,50 @@
+"""LiteLLM mock adapter — deterministic costs without API calls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MockCompletionResult:
+    model: str
+    content: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+    latency_ms: float
+
+
+class LiteLLMMockAdapter:
+    """Returns deterministic token counts and costs for demo and tests."""
+
+    DEFAULT_PRICING: dict[str, tuple[float, float]] = {
+        "mock-research": (0.000001, 0.000002),
+        "mock-synthesis": (0.000002, 0.000004),
+        "mock-review": (0.000003, 0.000005),
+    }
+
+    def __init__(self, use_mock: bool = True) -> None:
+        self.use_mock = use_mock
+
+    def complete(
+        self, model: str, prompt: str, max_output_tokens: int = 512
+    ) -> MockCompletionResult:
+        if not self.use_mock:
+            raise RuntimeError(
+                "Real LiteLLM calls are opt-in. Set USE_MOCK_MODELS=true or install litellm extra."
+            )
+
+        input_tokens = max(50, len(prompt) // 4)
+        output_tokens = min(max_output_tokens, max(80, len(prompt) // 8))
+        input_rate, output_rate = self.DEFAULT_PRICING.get(model, (0.000001, 0.000002))
+        cost = (input_tokens * input_rate) + (output_tokens * output_rate)
+
+        return MockCompletionResult(
+            model=model,
+            content=f"[mock response from {model}]",
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=round(cost, 6),
+            latency_ms=120.0,
+        )

supervisor/adapters/openai_agents/__init__.py

@@ -0,0 +1,3 @@
+from supervisor.adapters.openai_agents.adapter import OpenAIAgentsAdapter
+
+__all__ = ["OpenAIAgentsAdapter"]

supervisor/adapters/openai_agents/adapter.py

@@ -0,0 +1,37 @@
+"""OpenAI Agents SDK adapter.
+
+Executes OpenAI Agents SDK agents through Veille's runtime. The base
+``GenericFrameworkAdapter`` runs the agent and emits normalized events; SDK-specific
+tracing (handoffs, guardrails, session traces) is layered on here when the
+``openai-agents`` package is installed. Until then, any Python agent callable is
+run through Veille unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from supervisor.adapters.generic import GenericFrameworkAdapter, InstrumentedAgent
+from supervisor.sdk import Supervisor
+
+
+class OpenAIAgentsAdapter(GenericFrameworkAdapter):
+    """Adapter for OpenAI Agents SDK agents."""
+
+    name = "openai_agents"
+
+    def attach(self, target: Any, supervisor: Supervisor, **kwargs: Any) -> InstrumentedAgent:
+        # If the real SDK is present, prefer its Runner so tracing integrates;
+        # otherwise fall back to the generic instrumented callable.
+        try:  # pragma: no cover - optional dependency
+            from agents import Runner  # type: ignore
+
+            if hasattr(target, "run") or hasattr(target, "invoke"):
+
+                def _run(input: Any, sup: Supervisor) -> Any:
+                    return Runner.run(target, input)
+
+                return InstrumentedAgent(_run, supervisor)
+        except Exception:  # noqa: BLE001
+            pass
+        return super().attach(target, supervisor)

supervisor/adapters/openai_responses/__init__.py

@@ -0,0 +1,3 @@
+from supervisor.adapters.openai_responses.adapter import OpenAIResponsesAdapter
+
+__all__ = ["OpenAIResponsesAdapter"]

supervisor/adapters/openai_responses/adapter.py

@@ -0,0 +1,36 @@
+"""OpenAI Responses API adapter.
+
+Runs agents built on the OpenAI Responses API through Veille's runtime. Shares
+the generic instrumented execution; Responses-API tracing (response objects,
+tool calls) is integrated here when the SDK is available.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from supervisor.adapters.generic import GenericFrameworkAdapter, InstrumentedAgent
+from supervisor.sdk import Supervisor
+
+
+class OpenAIResponsesAdapter(GenericFrameworkAdapter):
+    """Adapter for OpenAI Responses API agents."""
+
+    name = "openai_responses"
+
+    def attach(self, target: Any, supervisor: Supervisor, **kwargs: Any) -> InstrumentedAgent:
+        # When the real SDK is present, route through the Responses client so the
+        # native trace is captured; otherwise run the generic instrumented callable.
+        try:  # pragma: no cover - optional dependency
+            from openai import OpenAI  # type: ignore
+
+            if hasattr(target, "run") or hasattr(target, "invoke"):
+
+                def _run(input: Any, sup: Supervisor) -> Any:
+                    client = OpenAI()
+                    return client.responses.create(model="gpt-4o", input=input)
+
+                return InstrumentedAgent(_run, supervisor)
+        except Exception:  # noqa: BLE001
+            pass
+        return super().attach(target, supervisor)

supervisor/adapters/ports.py

@@ -0,0 +1,59 @@
+"""Framework-neutral adapter ports.
+
+Generalizes the LangGraph-specific port pair into provider-agnostic contracts so
+every future agent framework (CrewAI, AutoGen, Semantic Kernel, Mastra, PydanticAI,
+custom Python agents) implements the same interface. Adapters turn framework-native
+lifecycle into normalized ``RunEvent``s through the supervisor's collector.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from supervisor.contracts.events import RunEvent
+
+
+@runtime_checkable
+class RunEventHook(Protocol):
+    """Sink for normalized runtime events emitted by any framework adapter."""
+
+    def on_run_started(self, run_id: str, task_id: str, metadata: dict[str, Any]) -> None: ...
+
+    def on_run_finished(self, run_id: str, status: str, metadata: dict[str, Any]) -> None: ...
+
+    def on_agent_event(
+        self, run_id: str, agent_id: str, event_type: str, metadata: dict[str, Any]
+    ) -> None: ...
+
+    def on_tool_event(
+        self,
+        run_id: str,
+        tool_name: str,
+        event_type: str,
+        input_data: dict[str, Any],
+        metadata: dict[str, Any],
+    ) -> None: ...
+
+    def on_model_event(
+        self,
+        run_id: str,
+        model_name: str,
+        event_type: str,
+        token_usage: dict[str, int],
+        metadata: dict[str, Any],
+    ) -> None: ...
+
+    def flush(self) -> list[RunEvent]: ...
+
+
+@runtime_checkable
+class FrameworkAdapter(Protocol):
+    """Port for wrapping any agent framework with supervisor instrumentation."""
+
+    def attach(self, graph: Any, hook: RunEventHook) -> Any:
+        """Return an instrumented graph/agent bound to the hook."""
+        ...
+
+    def extract_run_id(self, config: dict[str, Any] | None) -> str:
+        """Extract or generate a stable run identifier."""
+        ...