memgraph-context-graph 0.5.0__py3-none-any.whl

memgraph_context_graph/adapters/openai.py

@@ -0,0 +1,240 @@
+"""OpenAI Agents SDK adapter for memgraph-context-graph.
+
+Translates OpenAI Agents SDK lifecycle hooks (``RunHooksBase``) into the
+common Event protocol and forwards them to the AgentLink hub.
+
+Usage::
+
+    from memgraph_context_graph import AgentLink
+    from memgraph_context_graph.adapters.openai import OpenAIAdapter
+
+    link = AgentLink()
+    adapter = OpenAIAdapter(link, session_id="s-1")
+    hooks = adapter.get_runtime_hooks()
+
+    # Pass hooks to Runner
+    result = await Runner.run(agent, "Hello", hooks=hooks)
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    HandoffEvent,
+    LLMEndEvent,
+    LLMStartEvent,
+    SessionEndEvent,
+    SessionStartEvent,
+    ToolEndEvent,
+    ToolStartEvent,
+)
+from memgraph_context_graph.protocols import RuntimeAdapter
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.link import AgentLink
+
+_SOURCE = "openai"
+
+
+class OpenAIAdapter(RuntimeAdapter):
+    """Adapter that converts OpenAI Agents SDK lifecycle hooks into memgraph-context-graph events.
+
+    Args:
+        link: The AgentLink hub to emit events to.
+        session_id: Session identifier for all events.
+        auto_session: If ``True``, emit SessionStartEvent on creation.
+        session_kwargs: Extra fields for SessionStartEvent (model, …).
+    """
+
+    def __init__(
+        self,
+        link: AgentLink,
+        session_id: str,
+        *,
+        auto_session: bool = True,
+        session_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._link = link
+        self._session_id = session_id
+
+        if auto_session:
+            kw = session_kwargs or {}
+            self._link.emit(
+                SessionStartEvent(
+                    session_id=session_id,
+                    source_sdk=_SOURCE,
+                    model=kw.get("model"),
+                    working_directory=kw.get("working_directory"),
+                    user_id=kw.get("user_id"),
+                    metadata=kw.get("metadata", {}),
+                )
+            )
+
+    def get_runtime_hooks(self) -> Any:
+        """Return a ``RunHooksBase`` subclass for ``Runner.run(..., hooks=...)``."""
+        try:
+            from agents.lifecycle import RunHooksBase
+        except ImportError:
+            msg = "openai-agents is required for OpenAIAdapter. Install it with: pip install memgraph-context-graph[openai]"
+            raise ImportError(msg)  # noqa: B904
+
+        adapter = self
+
+        class _Hooks(RunHooksBase):  # type: ignore[type-arg]
+            async def on_agent_start(
+                self,
+                context: Any,
+                agent: Any,
+            ) -> None:
+                adapter._link.emit(
+                    AgentStartEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        agent_name=getattr(agent, "name", str(agent)),
+                        agent_type=type(agent).__name__,
+                    )
+                )
+
+            async def on_agent_end(
+                self,
+                context: Any,
+                agent: Any,
+                output: Any,
+            ) -> None:
+                adapter._link.emit(
+                    AgentEndEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        agent_name=getattr(agent, "name", str(agent)),
+                        agent_type=type(agent).__name__,
+                        output=str(output) if output else None,
+                    )
+                )
+
+            async def on_tool_start(
+                self,
+                context: Any,
+                agent: Any,
+                tool: Any,
+            ) -> None:
+                tool_name = getattr(tool, "name", str(tool))
+                # ToolContext exposes tool_call_id and tool_arguments (JSON string)
+                tool_call_id = getattr(context, "tool_call_id", None)
+                tool_arguments = getattr(context, "tool_arguments", None)
+
+                # Parse JSON string to dict for downstream connectors
+                tool_input: Any = tool_arguments
+                if isinstance(tool_arguments, str):
+                    with contextlib.suppress(json.JSONDecodeError):
+                        tool_input = json.loads(tool_arguments)
+
+                adapter._link.emit(
+                    ToolStartEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        tool_name=tool_name,
+                        tool_input=tool_input,
+                        tool_use_id=tool_call_id,
+                        agent_name=getattr(agent, "name", None),
+                    )
+                )
+
+            async def on_tool_end(
+                self,
+                context: Any,
+                agent: Any,
+                tool: Any,
+                result: str,
+            ) -> None:
+                tool_name = getattr(tool, "name", str(tool))
+                tool_call_id = getattr(context, "tool_call_id", None)
+
+                adapter._link.emit(
+                    ToolEndEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        tool_name=tool_name,
+                        tool_use_id=tool_call_id,
+                        result=result,
+                        agent_name=getattr(agent, "name", None),
+                    )
+                )
+
+            async def on_handoff(
+                self,
+                context: Any,
+                from_agent: Any,
+                to_agent: Any,
+            ) -> None:
+                adapter._link.emit(
+                    HandoffEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        from_agent=getattr(from_agent, "name", str(from_agent)),
+                        to_agent=getattr(to_agent, "name", str(to_agent)),
+                    )
+                )
+
+            async def on_llm_start(
+                self,
+                context: Any,
+                agent: Any,
+                system_prompt: str | None,
+                input_items: list[Any],
+            ) -> None:
+                adapter._link.emit(
+                    LLMStartEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        agent_name=getattr(agent, "name", None),
+                        system_prompt=system_prompt,
+                        input_items=input_items,
+                    )
+                )
+
+            async def on_llm_end(
+                self,
+                context: Any,
+                agent: Any,
+                response: Any,
+            ) -> None:
+                # Extract usage from response if available
+                usage = getattr(response, "usage", None)
+                adapter._link.emit(
+                    LLMEndEvent(
+                        session_id=adapter._session_id,
+                        source_sdk=_SOURCE,
+                        agent_name=getattr(agent, "name", None),
+                        model=getattr(response, "model", None),
+                        input_tokens=getattr(usage, "input_tokens", None) if usage else None,
+                        output_tokens=getattr(usage, "output_tokens", None) if usage else None,
+                        response=response,
+                    )
+                )
+
+        return _Hooks()
+
+    def end_session(
+        self,
+        *,
+        status: str = "completed",
+        total_cost_usd: float | None = None,
+        total_input_tokens: int | None = None,
+        total_output_tokens: int | None = None,
+    ) -> None:
+        """Manually signal session end (call after Runner.run completes)."""
+        self._link.emit(
+            SessionEndEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                status=status,
+                total_cost_usd=total_cost_usd,
+                total_input_tokens=total_input_tokens,
+                total_output_tokens=total_output_tokens,
+            )
+        )

memgraph_context_graph/adapters/opencode.py

@@ -0,0 +1,168 @@
+"""OpenCode V2 plugin runtime adapter and installer."""
+
+from __future__ import annotations
+
+import json
+import shlex
+from importlib import resources
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    hook_command_argv,
+    session_start,
+    tool_start,
+    turn_end,
+)
+from memgraph_context_graph.events import ErrorOccurredEvent, MessageEvent, SessionEndEvent, ToolEndEvent
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from memgraph_context_graph.events import Event
+
+
+def _session_end(context: EventContext) -> SessionEndEvent:
+    return SessionEndEvent(**context.base(), status="completed")
+
+
+def _prompt(context: EventContext) -> MessageEvent:
+    return MessageEvent(**context.base(), role="user", content=context.value("prompt", ""))
+
+
+def _assistant_text(context: EventContext) -> MessageEvent:
+    return MessageEvent(**context.base(), role="assistant", content=context.payload.get("text", ""))
+
+
+def _tool_end(context: EventContext) -> ToolEndEvent:
+    error = context.payload.get("error")
+    error_dict = error if isinstance(error, dict) else {}
+    result, exit_code = _tool_result(context.value("tool_result"))
+    return ToolEndEvent(
+        **context.base(),
+        tool_name=context.text("tool_name"),
+        tool_use_id=context.optional_text("tool_use_id"),
+        result=result,
+        is_error=bool(context.payload.get("is_error")) or exit_code not in (None, 0),
+        error_message=str(error_dict.get("message", error)) if error else None,
+    )
+
+
+def _tool_result(tool_result: Any) -> tuple[Any, Any]:
+    """Return a V2 tool result's model-facing text and shell exit code, if any.
+
+    V2 results are ``{output, content: [{type: "text", text}], metadata}``;
+    ``content`` is what the model saw, ``output`` is tool-specific.
+    """
+    if not isinstance(tool_result, dict):
+        return tool_result, None
+    output = tool_result.get("output")
+    exit_code = output.get("exit") if isinstance(output, dict) else None
+    parts = tool_result.get("content")
+    if isinstance(parts, list):
+        texts = [part["text"] for part in parts if isinstance(part, dict) and isinstance(part.get("text"), str)]
+        if texts:
+            return "\n".join(texts), exit_code
+    return tool_result, exit_code
+
+
+def _execution_succeeded(context: EventContext) -> list[Event]:
+    # One prompt's execution finished; `opencode run` never deletes its
+    # session, so this is the only end signal it gives.
+    return turn_end(context)
+
+
+def _execution_failed(context: EventContext) -> list[Event]:
+    error = context.payload.get("error")
+    error_dict = error if isinstance(error, dict) else {}
+    details = {"status": error_dict["status"]} if error_dict.get("status") is not None else {}
+    failure = ErrorOccurredEvent(
+        **context.base(),
+        error_type=str(error_dict.get("type") or "opencode_error"),
+        error_message=str(error_dict.get("message") or error or "OpenCode session execution failed"),
+        error_details=details,
+        recoverable=True,
+    )
+    return [failure, *turn_end(context)]
+
+
+def _permission(context: EventContext) -> MessageEvent:
+    return MessageEvent(
+        **context.base(),
+        role="system",
+        content=context.payload.get("permission") or "permission_requested",
+    )
+
+
+SPEC = RuntimeSpec(
+    name="opencode",
+    source_sdk="opencode",
+    event_key="hook_event_name",
+    # OpenCode has no JSON command hooks: the installed V2 plugin subscribes to
+    # its hooks and bus events and pipes each one, normalized, to
+    # ``hook run opencode`` (see _opencode_plugin.js for the field mapping).
+    hooks=(),
+    rules={
+        "session.created": session_start,
+        "session.deleted": _session_end,
+        "session.prompt": _prompt,
+        # Emitted once per completed assistant text part, unlike the streamed
+        # session.text.delta, so each assistant message is recorded once.
+        "session.text.ended": _assistant_text,
+        "tool.execute.before": tool_start,
+        "tool.execute.after": _tool_end,
+        "session.execution.succeeded": _execution_succeeded,
+        "session.execution.failed": _execution_failed,
+        "permission.asked": _permission,
+    },
+    metadata_keys=("cwd", "model", "metadata"),
+    config=HookConfig(layout="flat"),
+    probe_payload={"hook_event_name": "session.deleted", "session_id": "doctor"},
+)
+
+
+class OpenCodeHooksAdapter(SpecAdapter):
+    """Convert normalized OpenCode V2 plugin callbacks into events."""
+
+    SPEC = SPEC
+
+
+_PLUGIN_PATH = ".opencode/plugins/memgraph-context-graph/index.js"
+
+
+def init(
+    project_dir: Path,
+    connectors: list[str],
+    *,
+    hook_command: str | None = None,
+    timeout: int = 30,
+    force: bool = False,
+) -> None:
+    """Install the dependency-free OpenCode V2 capture plugin.
+
+    The hook command is embedded as an argv array and spawned directly, so no
+    shell (and no login-shell profile) sits between OpenCode and the hook.
+    *timeout* is accepted for CLI symmetry; OpenCode plugins have no hook timeout.
+
+    Raises:
+        FileExistsError: if the plugin file exists and *force* is false.
+    """
+    target = project_dir / _PLUGIN_PATH
+    if target.exists() and not force:
+        raise FileExistsError(f"Refusing to overwrite existing OpenCode plugin: {target} (pass force=True)")
+
+    argv = shlex.split(hook_command) if hook_command else hook_command_argv(SPEC.name, connectors)
+    template = (
+        resources.files("memgraph_context_graph.adapters").joinpath("_opencode_plugin.js").read_text(encoding="utf-8")
+    )
+    plugin = template.replace("__MEMGRAPH_CONTEXT_GRAPH_COMMAND__", json.dumps(argv))
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(plugin, encoding="utf-8")
+    print(f"Wrote {target}")
+
+
+PLUGIN = SpecPlugin(SPEC, OpenCodeHooksAdapter, init=init)