ellements 0.2.0__py3-none-any.whl

ellements/__init__.py

@@ -0,0 +1,57 @@
+"""Curated root API and namespace bootstrap for the public Ellements repo."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from pkgutil import extend_path
+from typing import Any
+
+__path__ = extend_path(__path__, __name__)
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_SOURCE_ROOTS = [
+    "ellements-agents/src/ellements",
+    "ellements-benchmarking/src/ellements",
+    "ellements-cli/src/ellements",
+    "ellements-core/src/ellements",
+    "ellements-domain-specific/src/ellements",
+    "ellements-execution/src/ellements",
+    "ellements-fslm/src/ellements",
+    "ellements-reporting/src/ellements",
+    "ellements-standard-tools/src/ellements",
+]
+
+for relative_root in _SOURCE_ROOTS:
+    candidate = _REPO_ROOT / relative_root
+    if candidate.is_dir():
+        candidate_str = str(candidate)
+        if candidate_str not in __path__:
+            __path__.append(candidate_str)
+
+_ROOT_EXPORTS: dict[str, tuple[str, str]] = {
+    "Conversation": ("ellements.core", "Conversation"),
+    "ImageInput": ("ellements.core", "ImageInput"),
+    "LLMClient": ("ellements.core", "LLMClient"),
+    "SimpleTool": ("ellements.core", "SimpleTool"),
+}
+
+try:
+    __version__ = version("ellements")
+except PackageNotFoundError:
+    __version__ = "0.2.0"
+
+__all__ = [*sorted(_ROOT_EXPORTS), "__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve curated public root exports lazily."""
+    if name not in _ROOT_EXPORTS:
+        raise AttributeError(f"module 'ellements' has no attribute {name!r}")
+    module_name, attr_name = _ROOT_EXPORTS[name]
+    return getattr(import_module(module_name), attr_name)
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_ROOT_EXPORTS))

ellements/agents/__init__.py

@@ -0,0 +1,45 @@
+"""Agent framework integration for ellements.
+
+The package is built around the :class:`AgentBackend` Protocol so any
+agent runtime (OpenAI Agents SDK, Anthropic Claude Agents, future
+others) can be wired in without changing higher-level code. Two
+concrete backends ship with the package:
+
+- :class:`OpenAIAgentsBackend`
+- :class:`ClaudeAgentsBackend`
+
+Higher-level helpers (:class:`AgentBuilder`, :class:`AgentController`,
+:class:`AgentRunStats`, :class:`AgentRunResult`,
+:func:`run_agent_with_progress`) are backend-agnostic and operate
+through the protocol.
+"""
+
+from .backend import AgentBackend, AgentEvent
+from .builder import AgentBuilder, check_openai_api_key, load_prompt_file
+from .claude_backend import ClaudeAgentsBackend
+from .controller import AgentController, ControllerConfig
+from .openai_backend import OpenAIAgentsBackend
+from .runner import (
+    DEFAULT_MAX_TURNS,
+    AgentRunResult,
+    AgentRunStats,
+    run_agent_with_progress,
+)
+from .tools import create_tool_from_method
+
+__all__ = [
+    "AgentBackend",
+    "AgentBuilder",
+    "AgentController",
+    "AgentEvent",
+    "AgentRunResult",
+    "AgentRunStats",
+    "ClaudeAgentsBackend",
+    "ControllerConfig",
+    "DEFAULT_MAX_TURNS",
+    "OpenAIAgentsBackend",
+    "check_openai_api_key",
+    "create_tool_from_method",
+    "load_prompt_file",
+    "run_agent_with_progress",
+]

ellements/agents/backend.py

@@ -0,0 +1,100 @@
+"""The :class:`AgentBackend` Protocol — the single integration point.
+
+Any agent framework that satisfies this Protocol can be plugged into
+:class:`~ellements.agents.AgentBuilder`, :class:`AgentController`, and
+:func:`run_agent_with_progress` without further changes.
+
+:class:`AgentEvent` — the uniform vocabulary backends use to surface
+streaming events — lives in :mod:`ellements.core.observability.events`
+alongside the other observability primitives. It is re-exported from
+this module for backend authors who only deal with the agent surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Protocol, runtime_checkable
+
+from ellements.core import ToolRegistry
+from ellements.core.observability import AgentEvent
+
+
+@runtime_checkable
+class AgentBackend(Protocol):
+    """Adapts an agent runtime to ellements' uniform agent surface."""
+
+    name: str
+    """Stable backend identifier, e.g. ``"openai_agents"``."""
+
+    def create_agent(
+        self,
+        *,
+        name: str,
+        instructions: str,
+        tools: ToolRegistry,
+        model: str,
+    ) -> Any:
+        """Construct a runtime-native agent instance.
+
+        *tools* is the canonical :class:`~ellements.core.ToolRegistry`;
+        each backend adapts the contained :class:`~ellements.core.ToolSpec`
+        instances to its native tool type.
+        """
+
+    def create_session(
+        self, session_id: str | None = None, **kwargs: Any
+    ) -> Any | None:
+        """Construct a runtime-native session object, or ``None``.
+
+        Backends that don't support sessions return ``None``. Backends
+        that support sessions but were given ``None`` for *session_id*
+        should also return ``None`` (caller wants no session).
+
+        Extra backend-specific options (e.g. ``storage_path`` for
+        ``OpenAIAgentsBackend``) are passed via ``**kwargs``; backends
+        ignore options they don't recognize.
+        """
+
+    async def run(
+        self,
+        agent: Any,
+        task: str,
+        *,
+        max_turns: int = 10,
+        session: Any | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Run *agent* on *task* and return its native result object.
+
+        Implementations should propagate :class:`asyncio.CancelledError`
+        unchanged.
+        """
+
+    def stream_run(
+        self,
+        agent: Any,
+        task: str,
+        *,
+        max_turns: int = 10,
+        session: Any | None = None,
+        **kwargs: Any,
+    ) -> AgentStream:
+        """Run *agent* on *task* and return a streaming handle.
+
+        Use :class:`AgentStream` as both an async iterator (over
+        :class:`AgentEvent`) and a final-result holder accessible via
+        :attr:`AgentStream.result` after iteration completes.
+        """
+
+
+class AgentStream(Protocol):
+    """Combined async-iterator + final-result handle for streaming runs."""
+
+    def __aiter__(self) -> AsyncIterator[AgentEvent]: ...
+
+    @property
+    def result(self) -> Any:
+        """The native runtime result, populated once streaming completes."""
+
+
+__all__ = ["AgentBackend", "AgentEvent", "AgentStream"]

ellements/agents/builder.py

@@ -0,0 +1,303 @@
+"""Fluent builder for assembling agents on top of any :class:`AgentBackend`.
+
+The builder unifies three concerns:
+
+1. **Instructions** — direct text, a file, or a rendered template.
+2. **Persona + Guideline** — composed through
+   :class:`ellements.core.PromptContext` + :class:`PersonaLibrary` /
+   :class:`GuidelineLibrary`.
+3. **Tools** — accumulated in a :class:`~ellements.core.ToolRegistry`
+   and forwarded to the backend, which adapts them to its native
+   tool format.
+
+There are **no** alias methods, **no** ``run_sync`` flavours, **no**
+``.mustache.md`` legacy branch, and **no** lazy circular-import hacks.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+from ellements.core import (
+    GuidelineLibrary,
+    PersonaLibrary,
+    ToolRegistry,
+)
+from ellements.core.prompting import PromptContext
+from ellements.core.templating import render_prompt_template
+
+from .backend import AgentBackend
+
+
+class AgentBuilder:
+    """Compose an agent backend with tools, instructions, and prompt context.
+
+    Example:
+        >>> from ellements.agents import AgentBuilder, OpenAIAgentsBackend
+        >>> agent = (
+        ...     AgentBuilder("YouTubeExpert", backend=OpenAIAgentsBackend())
+        ...     .with_instructions("Find the best YouTube videos")
+        ...     .with_model("gpt-4o-mini")
+        ...     .with_tools(youtube_search_tools())
+        ...     .build()
+        ... )
+    """
+
+    def __init__(self, name: str, *, backend: AgentBackend) -> None:
+        self.name = name
+        self.backend = backend
+        self.model: str | None = None
+        self.tools = ToolRegistry()
+        self.instructions: str | None = None
+        self.instruction_template: str | None = None
+        self.template_renderer: Callable[..., str] | None = None
+        self.prompt_context = PromptContext()
+
+    # ── Identity / model ───────────────────────────────────────────
+
+    def with_model(self, model: str) -> AgentBuilder:
+        self.model = model
+        return self
+
+    # ── Tools ──────────────────────────────────────────────────────
+
+    def with_tools(self, tools: ToolRegistry | Mapping[str, Any]) -> AgentBuilder:
+        """Bulk-add tools from a :class:`ToolRegistry` or ``{name: callable}`` mapping."""
+        for name, tool in tools.items():
+            self.tools.register(tool, name=name)
+        return self
+
+    def with_tool(self, name: str, tool: Any) -> AgentBuilder:
+        """Add a single tool under *name*."""
+        self.tools.register(tool, name=name)
+        return self
+
+    # ── Instructions ───────────────────────────────────────────────
+
+    def with_instructions(self, instructions: str) -> AgentBuilder:
+        """Set inline instructions text."""
+        self.instructions = instructions
+        return self
+
+    def with_instructions_from_file(
+        self, path: Path | str, *, fallback: str | None = None
+    ) -> AgentBuilder:
+        """Load instructions from *path*.
+
+        Raises:
+            FileNotFoundError: When the file is missing and no
+                ``fallback`` is provided.
+        """
+        try:
+            self.instructions = Path(path).read_text(encoding="utf-8")
+        except FileNotFoundError:
+            if fallback is None:
+                raise
+            self.instructions = fallback
+        return self
+
+    def with_instructions_template(
+        self,
+        template_name: str,
+        *,
+        renderer: Callable[..., str] | None = None,
+    ) -> AgentBuilder:
+        """Render instructions from a Mustache template.
+
+        For split templates the builder loads
+        ``{template_name}.system.mustache.md`` for instructions and
+        ``{template_name}.user.mustache.md`` (when present) for the
+        guideline message returned by
+        :meth:`get_guideline_user_message`.
+
+        Args:
+            template_name: Template basename. May be qualified with a
+                package-relative path (e.g. ``"writing/poem"``).
+            renderer: Override the default ``render_prompt_template``
+                helper (which loads from this package's ``prompts/``).
+        """
+        self.instruction_template = template_name
+        self.template_renderer = renderer or _default_template_renderer
+        return self
+
+    # ── Persona ────────────────────────────────────────────────────
+
+    def with_persona(self, persona_folder: Path | str) -> AgentBuilder:
+        """Attach a :class:`PersonaLibrary` loaded from *persona_folder*."""
+        self.prompt_context.attach_persona_library(
+            PersonaLibrary(persona_folder), fallback_to_first=True
+        )
+        return self
+
+    def with_persona_id(self, persona_id: str) -> AgentBuilder:
+        """Select an active persona by its registered ID."""
+        if self.prompt_context.persona_library is None:
+            raise ValueError(
+                "Persona library not attached. Call .with_persona(folder) first."
+            )
+        self.prompt_context.set_persona_by_id(persona_id)
+        return self
+
+    def with_persona_data(self, persona_data: dict[str, Any]) -> AgentBuilder:
+        """Activate a persona from inline data (no library required)."""
+        self.prompt_context.set_persona_from_data(persona_data)
+        return self
+
+    def with_persona_from_path(self, path: Path | str) -> AgentBuilder:
+        """Activate a persona from an arbitrary file path."""
+        self.prompt_context.set_persona_from_path(path)
+        return self
+
+    # ── Guideline ──────────────────────────────────────────────────
+
+    def with_guideline(self, guideline_folder: Path | str) -> AgentBuilder:
+        """Attach a :class:`GuidelineLibrary` loaded from *guideline_folder*."""
+        self.prompt_context.attach_guideline_library(
+            GuidelineLibrary(guideline_folder)
+        )
+        return self
+
+    def with_guideline_id(self, guideline_id: str) -> AgentBuilder:
+        """Select an active guideline by its registered ID."""
+        if self.prompt_context.guideline_library is None:
+            raise ValueError(
+                "Guideline library not attached. Call .with_guideline(folder) first."
+            )
+        self.prompt_context.set_guideline_by_id(guideline_id)
+        return self
+
+    def with_guideline_text(self, text: str) -> AgentBuilder:
+        """Activate a guideline from inline text."""
+        self.prompt_context.set_guideline_from_text(text)
+        return self
+
+    def with_guideline_from_path(self, path: Path | str) -> AgentBuilder:
+        """Activate a guideline from an arbitrary file path."""
+        self.prompt_context.set_guideline_from_path(path)
+        return self
+
+    def clear_guideline(self) -> None:
+        """Deactivate the currently selected guideline."""
+        self.prompt_context.clear_guideline()
+
+    # ── Convenience read-out ───────────────────────────────────────
+
+    @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
+
+    def get_guideline_user_message(self) -> str | None:
+        """Return the rendered guideline user-message, if available.
+
+        Only meaningful when both a guideline is active and the
+        instructions are template-driven with a sibling
+        ``{template}.user.mustache.md`` file.
+        """
+        guideline_text = self.prompt_context.get_guideline_text()
+        if not guideline_text or self.instruction_template is None:
+            return None
+        if self.template_renderer is None:
+            return None
+        user_template = f"{self.instruction_template}.user.mustache.md"
+        try:
+            rendered = self.template_renderer(
+                user_template, guideline=guideline_text
+            )
+        except FileNotFoundError:
+            return None
+        return rendered.strip() or None
+
+    # ── Build ──────────────────────────────────────────────────────
+
+    def build(self) -> Any:
+        """Materialize the agent through the configured backend."""
+        if self.model is None:
+            raise ValueError(
+                "Model must be set before building. Call .with_model(...)"
+            )
+
+        instructions = self._resolve_instructions()
+        return self.backend.create_agent(
+            name=self.name,
+            instructions=instructions,
+            tools=self.tools,
+            model=self.model,
+        )
+
+    async def run(self, task: str, *, max_turns: int = 10, **kwargs: Any) -> Any:
+        """Build and run the agent on *task* using the backend."""
+        agent = self.build()
+        return await self.backend.run(
+            agent, task, max_turns=max_turns, **kwargs
+        )
+
+    # ── Internals ──────────────────────────────────────────────────
+
+    def _resolve_instructions(self) -> str:
+        if self.instruction_template is not None:
+            if self.template_renderer is None:
+                raise ValueError("Template renderer is not set")
+            persona_text = self.prompt_context.get_persona_text()
+            if persona_text is None:
+                raise ValueError(
+                    "Template-mode instructions require an active persona. "
+                    "Call .with_persona(...) and select a persona first."
+                )
+            system_template = f"{self.instruction_template}.system.mustache.md"
+            return self.template_renderer(
+                system_template, persona=persona_text, guideline=""
+            )
+        if self.instructions is not None:
+            return self.instructions
+        raise ValueError(
+            "Instructions are not set. Use .with_instructions(...) "
+            "or .with_instructions_template(...)."
+        )
+
+
+# ── Module-level helpers ───────────────────────────────────────────
+
+
+def _default_template_renderer(template_name: str, /, **context: Any) -> str:
+    """Default template renderer rooted at this package's ``prompts/``."""
+    return render_prompt_template(
+        template_name,
+        package="ellements.agents",
+        resource_root="prompts",
+        **context,
+    )
+
+
+def check_openai_api_key() -> bool:
+    """Return whether ``OPENAI_API_KEY`` is set; print a hint when not."""
+    if os.getenv("OPENAI_API_KEY"):
+        return True
+    print("Error: OPENAI_API_KEY environment variable not set.")
+    print("  export OPENAI_API_KEY='your-api-key'")
+    return False
+
+
+def load_prompt_file(
+    path: Path | str, *, fallback: str | None = None
+) -> str:
+    """Load a prompt file with an optional fallback string."""
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        if fallback is None:
+            raise
+        return fallback
+
+
+__all__ = [
+    "AgentBuilder",
+    "check_openai_api_key",
+    "load_prompt_file",
+]