ellements 0.2.0__py3-none-any.whl

ellements/agents/claude_backend.py

@@ -0,0 +1,200 @@
+"""Anthropic Claude Agents backend implementing :class:`AgentBackend`.
+
+This backend wraps the ``claude_agents`` (or ``anthropic-agents``) SDK
+when installed. The shape mirrors :class:`OpenAIAgentsBackend` so
+higher-level code never branches on backend identity.
+
+If the Anthropic SDK is not installed, instantiating
+:class:`ClaudeAgentsBackend` raises :class:`ImportError` — the same
+contract as :class:`OpenAIAgentsBackend`.
+
+Note:
+    The Claude Agents SDK is still evolving; this adapter targets the
+    interface published as of writing (``claude_agents.Agent`` +
+    ``claude_agents.Runner`` with ``run``/``run_streamed``). When that
+    interface changes, only this file needs to follow.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from ellements.core import ToolRegistry, ToolSpec
+from ellements.core.tools import bind_json_invoker
+
+from .backend import AgentEvent
+
+
+class ClaudeAgentsBackend:
+    """Backend that adapts Anthropic's Claude Agents SDK to ellements."""
+
+    name: str = "claude_agents"
+
+    def __init__(self) -> None:
+        Agent, Runner = _load_sdk()
+        self._Agent = Agent
+        self._Runner = Runner
+
+    # ── Agent construction ─────────────────────────────────────────
+
+    def create_agent(
+        self,
+        *,
+        name: str,
+        instructions: str,
+        tools: ToolRegistry,
+        model: str,
+    ) -> Any:
+        return self._Agent(
+            name=name,
+            instructions=instructions,
+            tools=[_adapt_spec_for_claude(spec) for spec in tools.values()],
+            model=model,
+        )
+
+    # ── Session construction ───────────────────────────────────────
+
+    def create_session(
+        self, session_id: str | None = None, **kwargs: Any
+    ) -> Any | None:
+        """Claude Agents has no native session shape; always returns ``None``."""
+        return None
+
+    # ── Run (non-streaming) ────────────────────────────────────────
+
+    async def run(
+        self,
+        agent: Any,
+        task: str,
+        *,
+        max_turns: int = 10,
+        session: Any | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self._Runner.run(
+            agent, task, max_turns=max_turns, session=session, **kwargs
+        )
+
+    # ── Run (streaming) ────────────────────────────────────────────
+
+    def stream_run(
+        self,
+        agent: Any,
+        task: str,
+        *,
+        max_turns: int = 10,
+        session: Any | None = None,
+        **kwargs: Any,
+    ) -> _ClaudeAgentStream:
+        streaming_result = self._Runner.run_streamed(
+            agent, task, max_turns=max_turns, session=session, **kwargs
+        )
+        return _ClaudeAgentStream(streaming_result)
+
+
+def _load_sdk() -> tuple[Any, Any]:
+    try:
+        from claude_agents import Agent, Runner
+    except ImportError as exc:
+        raise ImportError(
+            "Claude Agents SDK not installed. "
+            "Install the appropriate Anthropic agents package "
+            "(currently 'claude_agents')."
+        ) from exc
+    return Agent, Runner
+
+
+class _ClaudeAgentStream:
+    """:class:`AgentStream` impl translating Claude SDK events to AgentEvent.
+
+    Translation rules mirror :class:`_OpenAIAgentStream` so consumers
+    receive the same uniform event vocabulary.
+    """
+
+    def __init__(self, streaming_result: Any) -> None:
+        self._streaming_result = streaming_result
+
+    def __aiter__(self) -> AsyncIterator[AgentEvent]:
+        return self._iter()
+
+    async def _iter(self) -> AsyncIterator[AgentEvent]:
+        async for raw in self._streaming_result.stream_events():
+            event = _translate_event(raw)
+            if event is not None:
+                yield event
+
+    @property
+    def result(self) -> Any:
+        return self._streaming_result
+
+
+def _translate_event(raw: Any) -> AgentEvent | None:
+    event_type = getattr(raw, "type", None) or getattr(raw, "kind", None)
+    if event_type in {None, "raw", "raw_response"}:
+        return None
+    if event_type in {"agent_active", "agent_updated"}:
+        return AgentEvent(
+            type="agent_active",
+            payload={"name": getattr(raw, "name", "Agent")},
+        )
+    if event_type in {"tool_call", "tool_use"}:
+        return AgentEvent(
+            type="tool_call",
+            payload={
+                "name": getattr(raw, "tool_name", None)
+                or getattr(raw, "name", "unknown"),
+                "arguments": getattr(raw, "arguments", None)
+                or getattr(raw, "input", "{}"),
+            },
+        )
+    if event_type in {"tool_output", "tool_result"}:
+        return AgentEvent(
+            type="tool_output",
+            payload={
+                "output": getattr(raw, "output", None)
+                or getattr(raw, "result", None)
+            },
+        )
+    if event_type in {"message", "text", "completion"}:
+        text = getattr(raw, "text", None) or getattr(raw, "content", "")
+        if not text:
+            return None
+        return AgentEvent(
+            type="message",
+            payload={
+                "text": str(text),
+                "final": bool(getattr(raw, "final", False)),
+            },
+        )
+    return None
+
+
+class _ClaudeToolView:
+    """Surface a :class:`ToolSpec` as the SimpleTool-like attributes the SDK reads.
+
+    The Claude Agents SDK consumes objects exposing ``name``,
+    ``description``, ``params_json_schema``, and ``on_invoke_tool``. We
+    construct a thin adapter from each :class:`ToolSpec` rather than
+    forcing the SDK to learn ellements' canonical type.
+    """
+
+    __slots__ = ("name", "description", "params_json_schema", "_invoke", "on_invoke_tool")
+
+    def __init__(self, spec: ToolSpec) -> None:
+        self.name = spec.name
+        self.description = spec.description
+        self.params_json_schema = spec.params_json_schema
+        self._invoke = spec.invoke
+        self.on_invoke_tool = bind_json_invoker(spec.invoke)
+
+    async def invoke(self, **kwargs: Any) -> Any:
+        return await self._invoke(**kwargs)
+
+
+def _adapt_spec_for_claude(spec: ToolSpec) -> Any:
+    """Adapt a canonical :class:`ToolSpec` to the Claude Agents SDK shape."""
+    return _ClaudeToolView(spec)
+
+
+__all__ = ["ClaudeAgentsBackend"]

ellements/agents/controller.py

@@ -0,0 +1,237 @@
+"""Backend-agnostic agent controller for testable agent behavior.
+
+Controllers encapsulate agent lifecycle, conversation state (via a
+backend-provided session object), persona/guideline composition, and
+statistics tracking — separately from any presentation layer (TUI,
+HTTP, etc.). They operate purely through the :class:`AgentBackend`
+Protocol, so the same controller works against any backend that
+implements it.
+"""
+
+from __future__ import annotations
+
+import inspect
+import uuid
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ellements.core import (
+    GuidelineLibrary,
+    PersonaLibrary,
+    ToolRegistry,
+)
+from ellements.core.prompting import PromptContext
+
+from .backend import AgentBackend
+from .runner import AgentRunResult, AgentRunStats, run_agent_with_progress
+
+ProgressCallback = Callable[[str], Awaitable[None] | None]
+StatsCallback = Callable[[AgentRunStats], Awaitable[None] | None]
+
+
+@dataclass
+class ControllerConfig:
+    """Static configuration for an :class:`AgentController`."""
+
+    model: str
+    max_turns: int = 200
+    show_activity_log: bool = True
+    persona_folder: Path | None = None
+    guideline_folder: Path | None = None
+    default_persona_id: str | None = None
+    default_guideline_id: str | None = None
+    session_storage_path: Path | None = None
+
+
+class AgentController(ABC):
+    """Base class encapsulating the run-loop and state for one agent.
+
+    Subclasses implement :meth:`_build_agent` and
+    :meth:`_get_fallback_instructions`. The controller can be shared
+    across UIs (CLI, TUI, HTTP), tests, or batch jobs because it
+    exposes no presentation concerns.
+    """
+
+    def __init__(
+        self, backend: AgentBackend, config: ControllerConfig
+    ) -> None:
+        self.backend = backend
+        self.config = config
+        self.prompt_context = self._build_prompt_context(config)
+
+        self._session = self._create_session()
+        self._conversation_history: list[dict[str, Any]] = []
+        self._session_stats = AgentRunStats()
+
+    @staticmethod
+    def _build_prompt_context(config: ControllerConfig) -> PromptContext:
+        """Wire the configured persona / guideline folders into a fresh context.
+
+        Extracted from ``__init__`` so the assembly is described once,
+        in one place, instead of inline with the other initialization
+        bookkeeping. Subclasses can override this hook if they want to
+        substitute different libraries or pre-populate additional
+        slots.
+        """
+        context = PromptContext()
+        if config.persona_folder is not None:
+            context.attach_persona_library(
+                PersonaLibrary(config.persona_folder),
+                default_persona=config.default_persona_id,
+                fallback_to_first=True,
+            )
+        if config.guideline_folder is not None:
+            context.attach_guideline_library(
+                GuidelineLibrary(config.guideline_folder),
+                default_guideline=config.default_guideline_id,
+            )
+        return context
+
+    # ── Subclass hooks ─────────────────────────────────────────────
+
+    @abstractmethod
+    def _build_agent(self) -> Any:
+        """Build and return the runtime-native agent instance."""
+
+    @abstractmethod
+    def _get_fallback_instructions(self) -> str:
+        """Return fallback instructions used when :meth:`_build_agent` fails."""
+
+    # ── Public surface ─────────────────────────────────────────────
+
+    async def run(
+        self,
+        query: str,
+        *,
+        progress_callback: ProgressCallback | None = None,
+        stats_callback: StatsCallback | None = None,
+    ) -> AgentRunResult:
+        """Run one query through the agent and capture stats."""
+        try:
+            agent = self._build_agent()
+        except Exception as exc:  # noqa: BLE001
+            if progress_callback is not None:
+                _maybe_await = progress_callback(
+                    f"⚠️  Build error: {exc}. Using fallback agent.\n"
+                )
+                if inspect.isawaitable(_maybe_await):
+                    await _maybe_await
+            agent = self._build_fallback_agent()
+
+        prepared_query = self._prepare_query(query)
+        result = await run_agent_with_progress(
+            self.backend,
+            agent,
+            prepared_query,
+            progress_callback=progress_callback,
+            stats_callback=stats_callback,
+            max_turns=self.config.max_turns,
+            session=self._session,
+            show_activity_log=self.config.show_activity_log,
+        )
+
+        self._conversation_history.append(
+            {
+                "query": query,
+                "response": result.final_output,
+                "stats": result.stats.to_dict(),
+            }
+        )
+        self._session_stats.merge(result.stats)
+        return result
+
+    async def reset_conversation(self) -> None:
+        """Clear the underlying session and reset accumulated stats."""
+        clear = getattr(self._session, "clear_session", None)
+        if clear is not None:
+            clear_result = clear()
+            if hasattr(clear_result, "__await__"):
+                await clear_result
+        self._conversation_history = []
+        self._session_stats = AgentRunStats()
+
+    # ── Persona / guideline pass-throughs ──────────────────────────
+
+    def set_persona_by_id(self, persona_id: str) -> None:
+        self.prompt_context.set_persona_by_id(persona_id)
+
+    def set_persona_from_data(self, persona_data: dict[str, Any]) -> None:
+        self.prompt_context.set_persona_from_data(persona_data)
+
+    def set_persona_from_path(self, path: Path | str) -> None:
+        self.prompt_context.set_persona_from_path(path)
+
+    def set_guideline_by_id(self, guideline_id: str) -> None:
+        self.prompt_context.set_guideline_by_id(guideline_id)
+
+    def set_guideline_from_text(self, text: str) -> None:
+        self.prompt_context.set_guideline_from_text(text)
+
+    def set_guideline_from_path(self, path: Path | str) -> None:
+        self.prompt_context.set_guideline_from_path(path)
+
+    def clear_guideline(self) -> None:
+        self.prompt_context.clear_guideline()
+
+    @property
+    def current_persona_id(self) -> str | None:
+        return self.prompt_context.current_persona_id
+
+    @property
+    def current_guideline_id(self) -> str | None:
+        return self.prompt_context.current_guideline_id
+
+    @property
+    def persona_library(self) -> PersonaLibrary | None:
+        return self.prompt_context.persona_library
+
+    @property
+    def guideline_library(self) -> GuidelineLibrary | None:
+        return self.prompt_context.guideline_library
+
+    def get_current_persona_text(self) -> str | None:
+        return self.prompt_context.get_persona_text()
+
+    def get_current_guideline_text(self) -> str | None:
+        return self.prompt_context.get_guideline_text()
+
+    # ── Stats / history ────────────────────────────────────────────
+
+    def get_session_stats(self) -> AgentRunStats:
+        return self._session_stats
+
+    def get_conversation_history(self) -> list[dict[str, Any]]:
+        return list(self._conversation_history)
+
+    def get_session(self) -> Any:
+        return self._session
+
+    # ── Internals ──────────────────────────────────────────────────
+
+    def _prepare_query(self, query: str) -> str:
+        return self.prompt_context.apply_guideline(query)
+
+    def _build_fallback_agent(self) -> Any:
+        return self.backend.create_agent(
+            name=self.__class__.__name__,
+            instructions=self._get_fallback_instructions(),
+            tools=ToolRegistry(),
+            model=self.config.model,
+        )
+
+    def _create_session(self) -> Any:
+        """Create a per-controller session via the backend.
+
+        The session shape is backend-specific; the controller never
+        introspects it directly.
+        """
+        session_id = f"controller_{uuid.uuid4().hex}"
+        return self.backend.create_session(
+            session_id, storage_path=self.config.session_storage_path
+        )
+
+
+__all__ = ["AgentController", "ControllerConfig"]

ellements/agents/openai_backend.py

@@ -0,0 +1,187 @@
+"""OpenAI Agents SDK backend implementing :class:`AgentBackend`."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Any
+
+from ellements.core import ToolRegistry, ToolSpec
+from ellements.core.tools import bind_json_invoker
+
+from .backend import AgentEvent
+
+
+class OpenAIAgentsBackend:
+    """Backend that adapts the ``openai-agents`` SDK to ellements."""
+
+    name: str = "openai_agents"
+
+    def __init__(self) -> None:
+        try:
+            from agents import Agent, Runner
+
+            self._Agent = Agent
+            self._Runner = Runner
+        except ImportError as exc:
+            raise ImportError(
+                "openai-agents package not installed. "
+                "Install with: pip install 'ellements[agents]'"
+            ) from exc
+
+    # ── Agent construction ─────────────────────────────────────────
+
+    def create_agent(
+        self,
+        *,
+        name: str,
+        instructions: str,
+        tools: ToolRegistry,
+        model: str,
+    ) -> Any:
+        return self._Agent(
+            name=name,
+            instructions=instructions,
+            tools=[_adapt_spec_for_openai(spec) for spec in tools.values()],
+            model=model,
+        )
+
+    # ── Session construction ───────────────────────────────────────
+
+    def create_session(
+        self,
+        session_id: str | None = None,
+        *,
+        storage_path: Path | str | None = None,
+    ) -> Any | None:
+        """Create an ``openai-agents`` ``SQLiteSession`` instance.
+
+        Returns ``None`` if the SDK does not expose ``SQLiteSession``.
+        """
+        try:
+            from agents import SQLiteSession
+        except ImportError:
+            return None
+        sid = session_id or f"openai_agents_{uuid.uuid4().hex}"
+        if storage_path is None:
+            return SQLiteSession(sid)
+        return SQLiteSession(sid, str(storage_path))
+
+    # ── Run (non-streaming) ────────────────────────────────────────
+
+    async def run(
+        self,
+        agent: Any,
+        task: str,
+        *,
+        max_turns: int = 10,
+        session: Any | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self._Runner.run(
+            agent, task, max_turns=max_turns, session=session, **kwargs
+        )
+
+    # ── Run (streaming) ────────────────────────────────────────────
+
+    def stream_run(
+        self,
+        agent: Any,
+        task: str,
+        *,
+        max_turns: int = 10,
+        session: Any | None = None,
+        **kwargs: Any,
+    ) -> _OpenAIAgentStream:
+        streaming_result = self._Runner.run_streamed(
+            agent, task, max_turns=max_turns, session=session, **kwargs
+        )
+        return _OpenAIAgentStream(streaming_result)
+
+
+class _OpenAIAgentStream:
+    """:class:`AgentStream` impl that translates SDK events to AgentEvent."""
+
+    def __init__(self, streaming_result: Any) -> None:
+        self._streaming_result = streaming_result
+
+    def __aiter__(self) -> AsyncIterator[AgentEvent]:
+        return self._iter()
+
+    async def _iter(self) -> AsyncIterator[AgentEvent]:
+        async for raw in self._streaming_result.stream_events():
+            event = _translate_event(raw)
+            if event is not None:
+                yield event
+
+    @property
+    def result(self) -> Any:
+        return self._streaming_result
+
+
+def _translate_event(raw: Any) -> AgentEvent | None:
+    """Map an OpenAI Agents SDK event into a uniform :class:`AgentEvent`."""
+    event_type = getattr(raw, "type", None)
+    if event_type == "raw_response_event":
+        return None
+    if event_type == "agent_updated_stream_event":
+        new_agent = getattr(raw, "new_agent", None)
+        return AgentEvent(
+            type="agent_active",
+            payload={"name": getattr(new_agent, "name", "Agent")},
+        )
+    if event_type != "run_item_stream_event":
+        return None
+    item = getattr(raw, "item", None)
+    if item is None:
+        return None
+    item_type = getattr(item, "type", None)
+    if item_type == "tool_call_item":
+        raw_item = getattr(item, "raw_item", None) or item
+        return AgentEvent(
+            type="tool_call",
+            payload={
+                "name": getattr(raw_item, "name", "unknown"),
+                "arguments": getattr(raw_item, "arguments", "{}"),
+            },
+        )
+    if item_type == "tool_call_output_item":
+        return AgentEvent(
+            type="tool_output",
+            payload={"output": getattr(item, "output", None)},
+        )
+    if item_type == "message_output_item":
+        raw_item = getattr(item, "raw_item", None)
+        text = _extract_message_text(raw_item)
+        if not text:
+            return None
+        return AgentEvent(
+            type="message",
+            payload={"text": text, "final": False},
+        )
+    return None
+
+
+def _extract_message_text(raw_item: Any) -> str:
+    if raw_item is None or not hasattr(raw_item, "content"):
+        return ""
+    content_items = raw_item.content or []
+    return "\n".join(
+        getattr(c, "text", "") for c in content_items if hasattr(c, "text")
+    )
+
+
+def _adapt_spec_for_openai(spec: ToolSpec) -> Any:
+    """Adapt a canonical :class:`ToolSpec` to the OpenAI Agents SDK shape."""
+    from agents.tool import FunctionTool
+
+    return FunctionTool(
+        name=spec.name,
+        description=spec.description,
+        params_json_schema=spec.params_json_schema,
+        on_invoke_tool=bind_json_invoker(spec.invoke),
+    )
+
+
+__all__ = ["OpenAIAgentsBackend"]