mutiny-openai-agents 0.1.0__tar.gz

mutiny_openai_agents-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.DS_Store
+*.sqlite
+*.db
+data/
+.coverage
+htmlcov/
+node_modules/
+.next/
+.worktrees/
+.mutiny/
+!examples/openai_support_agent/.mutiny/
+!examples/openai_support_agent/.mutiny/**
+
+
+.vscode/
+.idea/

mutiny_openai_agents-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: mutiny-openai-agents
+Version: 0.1.0
+Summary: Mutiny Adapter #1 — OpenAI Agents SDK TargetAdapter
+Project-URL: Homepage, https://github.com/CodewithJha/mutiny
+Project-URL: Repository, https://github.com/CodewithJha/mutiny
+Project-URL: Issues, https://github.com/CodewithJha/mutiny/issues
+Author-email: Priyanshu Jha <155089480+CodewithJha@users.noreply.github.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: mutiny-core>=0.1.0
+Requires-Dist: openai-agents>=0.19

mutiny_openai_agents-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "mutiny-openai-agents"
+version = "0.1.0"
+description = "Mutiny Adapter #1 — OpenAI Agents SDK TargetAdapter"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Priyanshu Jha", email = "155089480+CodewithJha@users.noreply.github.com" },
+]
+dependencies = [
+    "mutiny-core>=0.1.0",
+    "openai-agents>=0.19",
+]
+
+[project.urls]
+Homepage = "https://github.com/CodewithJha/mutiny"
+Repository = "https://github.com/CodewithJha/mutiny"
+Issues = "https://github.com/CodewithJha/mutiny/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mutiny_openai_agents"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/pyproject.toml",
+]

mutiny_openai_agents-0.1.0/src/mutiny_openai_agents/__init__.py

@@ -0,0 +1,12 @@
+"""OpenAI Agents SDK adapter — Mutiny Adapter #1 (ADR-018)."""
+
+from mutiny_openai_agents.adapter import OpenAIAgentsAdapter
+from mutiny_openai_agents.loader import load_agent_from_ref, load_callable
+from mutiny_openai_agents.sample import make_openai_support_adapter
+
+__all__ = [
+    "OpenAIAgentsAdapter",
+    "load_agent_from_ref",
+    "load_callable",
+    "make_openai_support_adapter",
+]

mutiny_openai_agents-0.1.0/src/mutiny_openai_agents/adapter.py

@@ -0,0 +1,138 @@
+"""OpenAIAgentsAdapter — TargetAdapter for OpenAI Agents SDK projects."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Callable
+from typing import Any
+
+from agents import Agent, Runner
+from agents.memory.sqlite_session import SQLiteSession
+
+from mutiny_core.adapter.port import TargetAdapter, ToolsNotObservableError
+from mutiny_core.trace.models import AdapterTurnResult
+
+from mutiny_openai_agents.extract import (
+    extract_assistant_message,
+    extract_tool_calls,
+    extract_tool_results,
+    summarize_items,
+    tools_observable,
+)
+from mutiny_openai_agents.loader import load_agent_from_ref
+
+
+class OpenAIAgentsAdapter(TargetAdapter):
+    """Drive an OpenAI Agents SDK ``Agent`` and observe tool calls.
+
+    Framework-specific imports stay inside this package (ADR-018). Core only
+    sees ``TargetAdapter`` / ``AdapterTurnResult``.
+    """
+
+    def __init__(
+        self,
+        agent: Agent[Any] | None = None,
+        *,
+        agent_ref: str | None = None,
+        agent_factory: Callable[[], Agent[Any]] | None = None,
+        context: dict[str, Any] | None = None,
+        context_provider: Callable[[], dict[str, Any]] | None = None,
+        session_factory: Callable[[str], Any] | None = None,
+        on_reset: Callable[[], None] | None = None,
+        max_turns: int = 10,
+    ) -> None:
+        if agent is None and agent_ref is None and agent_factory is None:
+            raise ValueError(
+                "OpenAIAgentsAdapter requires agent=, agent_ref=, or agent_factory="
+            )
+        self._agent = agent
+        self._agent_ref = agent_ref
+        self._agent_factory = agent_factory
+        self._context = context or {}
+        self._context_provider = context_provider
+        self._session_factory = session_factory or (
+            lambda sid: SQLiteSession(sid, db_path=":memory:")
+        )
+        self._on_reset = on_reset
+        self._max_turns = max_turns
+        self._sessions: dict[str, Any] = {}
+        self._resolved_agent: Agent[Any] | None = None
+
+    def reset(self, session_id: str) -> None:
+        """Start a fresh conversation session (in-memory SQLite by default)."""
+        if self._on_reset is not None:
+            self._on_reset()
+        previous = self._sessions.pop(session_id, None)
+        if previous is not None and hasattr(previous, "close"):
+            try:
+                previous.close()
+            except Exception:  # noqa: BLE001
+                pass
+        self._sessions[session_id] = self._session_factory(session_id)
+
+    def step(self, session_id: str, user_message: str) -> AdapterTurnResult:
+        """Run one user turn via ``Runner.run_sync``; map tools → Mutiny traces."""
+        if session_id not in self._sessions:
+            self.reset(session_id)
+
+        agent = self._get_agent()
+        session = self._sessions[session_id]
+
+        try:
+            result = Runner.run_sync(
+                agent,
+                user_message,
+                session=session,
+                max_turns=self._max_turns,
+            )
+        except ToolsNotObservableError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            # Surface SDK failures without inventing tool evidence
+            raise RuntimeError(
+                f"OpenAI Agents SDK run failed for session={session_id}: {exc}"
+            ) from exc
+
+        if not tools_observable(result):
+            raise ToolsNotObservableError(
+                "OpenAI Agents SDK result does not expose new_items; "
+                "cannot observe tool calls for policy evidence"
+            )
+
+        tool_calls = extract_tool_calls(result)
+        tool_results = extract_tool_results(result)
+        assistant = extract_assistant_message(result)
+
+        return AdapterTurnResult(
+            assistant_message=assistant,
+            tool_calls=tool_calls,
+            tool_results=tool_results,
+            raw={
+                "session_id": session_id,
+                "adapter": "openai_agents",
+                "item_summary": summarize_items(result),
+                "last_agent": getattr(
+                    getattr(result, "last_agent", None), "name", None
+                ),
+            },
+        )
+
+    def context(self, session_id: str | None = None) -> dict[str, Any]:
+        """Deterministic facts for policy evaluation."""
+        _ = session_id
+        if self._context_provider is not None:
+            return copy.deepcopy(self._context_provider())
+        return copy.deepcopy(self._context)
+
+    def _get_agent(self) -> Agent[Any]:
+        if self._resolved_agent is not None:
+            return self._resolved_agent
+        if self._agent is not None:
+            self._resolved_agent = self._agent
+            return self._resolved_agent
+        if self._agent_factory is not None:
+            self._resolved_agent = self._agent_factory()
+            return self._resolved_agent
+        assert self._agent_ref is not None
+        self._resolved_agent = load_agent_from_ref(self._agent_ref)
+        return self._resolved_agent

mutiny_openai_agents-0.1.0/src/mutiny_openai_agents/extract.py

@@ -0,0 +1,144 @@
+"""Map OpenAI Agents SDK RunResult items → Mutiny ToolCall / messages.
+
+All OpenAI Agents SDK imports stay here (and in adapter.py) — never in Core.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agents import ItemHelpers
+from agents.items import MessageOutputItem, ToolCallItem, ToolCallOutputItem
+from agents.result import RunResultBase
+
+from mutiny_core.trace.models import ToolCall
+
+
+def extract_assistant_message(result: RunResultBase) -> str | None:
+    """Best-effort assistant text from a run result."""
+    if result.final_output is not None:
+        out = result.final_output
+        if isinstance(out, str):
+            return out
+        return str(out)
+    try:
+        text = ItemHelpers.text_message_outputs(list(result.new_items))
+    except Exception:  # noqa: BLE001
+        text = ""
+    return text or None
+
+
+def extract_tool_calls(result: RunResultBase) -> list[ToolCall]:
+    """Collect function/tool calls observed during the run."""
+    calls: list[ToolCall] = []
+    for item in result.new_items:
+        if not _is_tool_call_item(item):
+            continue
+        name = getattr(item, "tool_name", None) or _raw_name(
+            getattr(item, "raw_item", None)
+        )
+        if not name:
+            continue
+        call_id = getattr(item, "call_id", None) or f"oa-tc-{len(calls) + 1}"
+        arguments = _parse_arguments(getattr(item, "raw_item", None))
+        calls.append(ToolCall(id=str(call_id), name=name, arguments=arguments))
+    return calls
+
+
+def extract_tool_results(result: RunResultBase) -> list[dict[str, Any]]:
+    """Collect tool outputs paired with call ids when available."""
+    results: list[dict[str, Any]] = []
+    for item in result.new_items:
+        if not _is_tool_output_item(item):
+            continue
+        payload: dict[str, Any] = {
+            "call_id": getattr(item, "call_id", None),
+            "output": _normalize_output(getattr(item, "output", None)),
+        }
+        results.append(payload)
+    return results
+
+
+def tools_observable(result: RunResultBase) -> bool:
+    """True if this run path can surface tool call evidence.
+
+    Empty tool_calls is fine (agent may not call tools). We fail only when
+    the result object lacks the observation surfaces Mutiny requires.
+    """
+    return hasattr(result, "new_items")
+
+
+def summarize_items(result: RunResultBase) -> list[str]:
+    """Debug helper: item type names from the run."""
+    names: list[str] = []
+    for item in result.new_items:
+        if _is_tool_call_item(item):
+            names.append(f"tool_call:{getattr(item, 'tool_name', None)}")
+        elif _is_tool_output_item(item):
+            names.append(f"tool_output:{getattr(item, 'call_id', None)}")
+        elif isinstance(item, MessageOutputItem) or getattr(
+            item, "type", None
+        ) == "message_output_item":
+            names.append("message")
+        else:
+            names.append(type(item).__name__)
+    return names
+
+
+def _is_tool_call_item(item: Any) -> bool:
+    if isinstance(item, ToolCallItem):
+        return True
+    return getattr(item, "type", None) == "tool_call_item"
+
+
+def _is_tool_output_item(item: Any) -> bool:
+    if isinstance(item, ToolCallOutputItem):
+        return True
+    return getattr(item, "type", None) == "tool_call_output_item"
+
+
+def _raw_name(raw_item: Any) -> str | None:
+    if raw_item is None:
+        return None
+    if isinstance(raw_item, dict):
+        name = raw_item.get("name")
+        return str(name) if name else None
+    name = getattr(raw_item, "name", None)
+    return str(name) if name else None
+
+
+def _parse_arguments(raw_item: Any) -> dict[str, Any]:
+    if raw_item is None:
+        return {}
+    raw_args: Any
+    if isinstance(raw_item, dict):
+        raw_args = raw_item.get("arguments", {})
+    else:
+        raw_args = getattr(raw_item, "arguments", {})
+    if raw_args is None:
+        return {}
+    if isinstance(raw_args, dict):
+        return dict(raw_args)
+    if isinstance(raw_args, str):
+        if not raw_args.strip():
+            return {}
+        try:
+            parsed = json.loads(raw_args)
+        except json.JSONDecodeError:
+            return {"_raw": raw_args}
+        if isinstance(parsed, dict):
+            return parsed
+        return {"value": parsed}
+    return {"value": raw_args}
+
+
+def _normalize_output(output: Any) -> Any:
+    if isinstance(output, (dict, list, str, int, float, bool)) or output is None:
+        return output
+    if hasattr(output, "model_dump"):
+        try:
+            return output.model_dump()
+        except Exception:  # noqa: BLE001
+            return str(output)
+    return str(output)

mutiny_openai_agents-0.1.0/src/mutiny_openai_agents/loader.py

@@ -0,0 +1,99 @@
+"""Load customer agent modules by ``module:attr`` reference."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+
+def ensure_project_on_path(project_root: str | Path) -> None:
+    """Prepend a customer project root to ``sys.path`` for local imports."""
+    root = str(Path(project_root).resolve())
+    if root not in sys.path:
+        sys.path.insert(0, root)
+
+
+def load_callable(ref: str) -> Any:
+    """Import ``module:attr`` and return the attribute (object or callable)."""
+    if ":" not in ref:
+        raise ValueError(
+            f"invalid ref {ref!r}; expected 'module:attribute' "
+            "(e.g. 'agent:support_agent' or 'agent:build_agent')"
+        )
+    module_name, attr_name = ref.split(":", 1)
+    if not module_name or not attr_name:
+        raise ValueError(f"invalid ref {ref!r}; module and attribute required")
+    module = importlib.import_module(module_name)
+    try:
+        return getattr(module, attr_name)
+    except AttributeError as exc:
+        raise AttributeError(
+            f"module {module_name!r} has no attribute {attr_name!r}"
+        ) from exc
+
+
+def load_agent_from_ref(ref: str) -> Any:
+    """Resolve an OpenAI Agents SDK Agent from ``module:attr``.
+
+    If the attribute is callable (and not already an Agent-like instance with
+    ``name`` + ``tools``), it is called with no arguments.
+    """
+    obj = load_callable(ref)
+    if callable(obj) and not _looks_like_agent(obj):
+        obj = obj()
+    if not _looks_like_agent(obj):
+        raise TypeError(
+            f"{ref!r} did not resolve to an OpenAI Agents SDK Agent "
+            f"(got {type(obj)!r})"
+        )
+    return obj
+
+
+def load_adapter_factory(
+    project_root: str | Path,
+    *,
+    module: str = ".mutiny.adapter",
+    attr: str = "create_adapter",
+) -> Callable[[], Any]:
+    """Load ``create_adapter`` from the customer's ``.mutiny/adapter.py``.
+
+    Supports either package-style ``.mutiny.adapter`` (if ``.mutiny`` is a
+    package) or a direct file load of ``.mutiny/adapter.py``.
+    """
+    root = Path(project_root).resolve()
+    ensure_project_on_path(root)
+
+    adapter_file = root / ".mutiny" / "adapter.py"
+    if not adapter_file.exists():
+        raise FileNotFoundError(
+            f"missing {adapter_file}; run `mutiny init` first"
+        )
+
+    # Load as a unique module from file path so `.mutiny` need not be a package
+    spec_name = "mutiny_project_adapter"
+    import importlib.util
+
+    spec = importlib.util.spec_from_file_location(spec_name, adapter_file)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load adapter module from {adapter_file}")
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[spec_name] = mod
+    spec.loader.exec_module(mod)
+
+    factory = getattr(mod, attr, None)
+    if factory is None or not callable(factory):
+        raise AttributeError(
+            f"{adapter_file} must define callable {attr}() → TargetAdapter"
+        )
+    return factory  # type: ignore[return-value]
+
+
+def _looks_like_agent(obj: Any) -> bool:
+    return (
+        hasattr(obj, "name")
+        and hasattr(obj, "tools")
+        and not isinstance(obj, type)
+    )

mutiny_openai_agents-0.1.0/src/mutiny_openai_agents/sample.py

@@ -0,0 +1,34 @@
+"""Hosted / CLI helpers for the sample OpenAI Agents SDK project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mutiny_openai_agents.adapter import OpenAIAgentsAdapter
+from mutiny_openai_agents.loader import load_adapter_factory
+
+
+def sample_project_root(repo_root: Path | None = None) -> Path:
+    """Locate ``examples/openai_support_agent`` from the Mutiny repo root."""
+    if repo_root is None:
+        # packages/mutiny_openai_agents/src/mutiny_openai_agents/sample.py
+        repo_root = Path(__file__).resolve().parents[4]
+    return repo_root / "examples" / "openai_support_agent"
+
+
+def make_openai_support_adapter(
+    *,
+    repo_root: Path | None = None,
+    project_root: Path | None = None,
+    enforce_refund_policy: bool = False,
+) -> OpenAIAgentsAdapter:
+    """Build adapter from the sample project's ``.mutiny/adapter.py``.
+
+    Same loader Hosted uses for any customer OpenAI Agents SDK project.
+    Always returns ``OpenAIAgentsAdapter`` — never the legacy in-process demo.
+    """
+    root = project_root or sample_project_root(repo_root)
+    if not root.exists():
+        raise FileNotFoundError(f"sample project not found: {root}")
+    factory = load_adapter_factory(root)
+    return factory(enforce_refund_policy=enforce_refund_policy)