ovos-agentic-loop 0.1.0__py3-none-any.whl

ovos_agentic_loop/__init__.py

@@ -0,0 +1,16 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ovos-agentic-loop — AgenticLoopEngine base and ReAct implementation."""
+from ovos_agentic_loop.version import __version__
+
+__all__ = ["__version__"]

ovos_agentic_loop/base.py

@@ -0,0 +1,143 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""AgenticLoopEngine — base class for agent-loop ChatEngine plugins."""
+import abc
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from ovos_plugin_manager.templates.agents import AgentMessage, ChatEngine
+from ovos_utils.log import LOG
+
+if TYPE_CHECKING:
+    from ovos_plugin_manager.templates.agent_tools import ToolBox
+
+
+class AgenticLoopEngine(ChatEngine):
+    """
+    A ``ChatEngine`` subclass for plugins that implement an internal agent loop
+    (e.g. ReAct, tool-call/observe cycles, background worker agents).
+
+    From the perspective of a ``PersonaService`` or any caller, an
+    ``AgenticLoopEngine`` is identical to a ``ChatEngine`` — it receives a list
+    of ``AgentMessage`` objects and returns one.  All loop mechanics, tool
+    dispatch, retries, and background tasks are implementation details hidden
+    inside the plugin.
+
+    The ``toolboxes`` attribute gives persona configs a standard place to inject
+    ``ToolBox`` instances.  Plugins are free to discover and load additional
+    toolboxes internally via ``_load_toolboxes_from_config``.
+
+    Entry point group: ``opm.agents.chat``
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Initialise the engine and optionally load toolboxes from config.
+
+        Args:
+            config: Plugin-specific configuration dictionary.  May contain a
+                ``"toolboxes"`` key listing toolbox plugin IDs to load.
+        """
+        super().__init__(config=config)
+        self.toolboxes: "List[ToolBox]" = []
+        self._load_toolboxes_from_config()
+
+    def load_toolboxes(self, toolboxes: List[Any]) -> None:
+        """
+        Register a list of ``ToolBox`` instances with this engine.
+
+        Replaces any previously registered toolboxes.  If the engine already
+        has a ``brain`` wired in, it is propagated to toolboxes that expose a
+        ``set_brain`` method (e.g. ``SkillMDToolBox``).
+
+        Args:
+            toolboxes: Instantiated ``ToolBox`` objects to make available to
+                the agent loop.
+        """
+        self.toolboxes = list(toolboxes)
+        brain = getattr(self, "_brain", None)
+        if brain is not None:
+            self._inject_brain_into_toolboxes(brain)
+
+    def _inject_brain_into_toolboxes(self, brain: Any) -> None:
+        """
+        Propagate a brain ``ChatEngine`` to toolboxes that require one.
+
+        Calls ``toolbox.set_brain(brain)`` on every registered toolbox that
+        exposes a ``set_brain`` method (duck-type check).  This ensures that
+        toolboxes like ``SkillMDToolBox`` — which use an inner LLM for
+        tool-call routing — receive the brain automatically when it is set on
+        the engine, regardless of load order.
+
+        Args:
+            brain: The ``ChatEngine`` instance to propagate.
+        """
+        for tb in self.toolboxes:
+            if callable(getattr(tb, "set_brain", None)):
+                try:
+                    tb.set_brain(brain)
+                except Exception as exc:  # noqa: BLE001
+                    LOG.warning(
+                        f"AgenticLoopEngine: failed to inject brain into "
+                        f"{type(tb).__name__}: {exc}"
+                    )
+
+    def _load_toolboxes_from_config(self) -> None:
+        """
+        Discover and instantiate toolboxes declared in ``config["toolboxes"]``.
+
+        Reads a list of toolbox plugin IDs from the plugin config, calls OPM to
+        find matching ``ToolBox`` plugins, and populates ``self.toolboxes``.
+        Brain injection is deferred — toolboxes are wired after the engine's
+        ``_brain`` attribute is set (see ``_inject_brain_into_toolboxes``).
+        Does nothing if the config key is absent or OPM is unavailable.
+        """
+        toolbox_ids: List[str] = self.config.get("toolboxes", [])
+        if not toolbox_ids:
+            return
+        try:
+            from ovos_plugin_manager.agent_tools import load_toolbox_plugin
+        except ImportError:
+            LOG.debug("AgenticLoopEngine: ovos_plugin_manager.agent_tools not available; "
+                      "skipping toolbox auto-load")
+            return
+
+        for tid in toolbox_ids:
+            try:
+                plugin = load_toolbox_plugin(tid, config=self.config.get(tid, {}))
+                if plugin is not None:
+                    self.toolboxes.append(plugin)
+            except Exception as exc:  # noqa: BLE001
+                LOG.warning(f"AgenticLoopEngine: failed to load toolbox '{tid}': {exc}")
+
+    @abc.abstractmethod
+    def continue_chat(self, messages: List[AgentMessage],
+                      session_id: str = "default",
+                      lang: Optional[str] = None,
+                      units: Optional[str] = None) -> AgentMessage:
+        """
+        Run the agent loop and return the final response.
+
+        The implementation is responsible for all internal steps: tool
+        selection, execution, observation, and iteration.  The caller always
+        receives a single ``AgentMessage`` with ``MessageRole.ASSISTANT``.
+
+        Args:
+            messages: Full conversation history including the latest user turn.
+            session_id: Conversation session identifier.
+            lang: BCP-47 language code.
+            units: Preferred measurement system (``"metric"`` / ``"imperial"``).
+
+        Returns:
+            The assistant's final response after the loop has completed.
+        """
+        raise NotImplementedError()

ovos_agentic_loop/chain_of_thought.py

@@ -0,0 +1,182 @@
+# Copyright 2025, OpenVoiceOS
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""ChainOfThoughtEngine — structured step-by-step reasoning without tool calls.
+
+Based on "Chain-of-Thought Prompting Elicits Reasoning in Large Language Models"
+(Wei et al., 2022 — https://arxiv.org/abs/2201.11903) and the follow-up
+zero-shot variant "Large Language Models are Zero-Shot Reasoners" (Kojima et al.,
+2022 — https://arxiv.org/abs/2205.11916).
+
+Algorithm
+---------
+A single LLM call is made with a system prompt that instructs the model to
+reason step by step before giving its final answer.  The final answer is
+extracted from a ``FINAL ANSWER:`` marker; if absent the full response is
+returned.
+
+This is the **simplest possible agent loop** — one LLM call, no tools, no
+iteration.  It is the recommended baseline for reasoning-heavy tasks that do
+not require external information, and it is the inner building block used by
+all more complex engines.
+
+Key differences from ReAct
+--------------------------
+- No tools, no observation loop.
+- Single LLM call — fastest and cheapest.
+- Produces human-readable reasoning traces naturally.
+- Best for arithmetic, logic, common-sense reasoning, multi-step instructions.
+"""
+from typing import Any, Dict, List, Optional
+
+from ovos_plugin_manager.templates.agents import AgentMessage, ChatEngine, MessageRole
+
+from ovos_agentic_loop.base import AgenticLoopEngine
+
+_COT_SYSTEM_PROMPT = """\
+Think through the problem step by step before giving your final answer.
+
+Format your response as:
+Step 1: <reasoning>
+Step 2: <reasoning>
+...
+FINAL ANSWER: <concise answer>
+
+Rules:
+- Work through every relevant step explicitly.
+- Do not skip steps.
+- Put ONLY the final answer after "FINAL ANSWER:" — no extra reasoning.
+"""
+
+_FINAL_ANSWER_MARKER = "FINAL ANSWER:"
+
+
+def _extract_final_answer(text: str) -> Optional[str]:
+    """
+    Extract the text following ``FINAL ANSWER:`` in LLM output.
+
+    Args:
+        text: Raw LLM output.
+
+    Returns:
+        The answer string, or ``None`` if the marker is absent.
+    """
+    idx = text.upper().find(_FINAL_ANSWER_MARKER.upper())
+    if idx == -1:
+        return None
+    return text[idx + len(_FINAL_ANSWER_MARKER):].strip()
+
+
+class ChainOfThoughtEngine(AgenticLoopEngine):
+    """
+    ``AgenticLoopEngine`` implementing zero-shot Chain-of-Thought prompting.
+
+    Adds a "think step by step" system prompt to every request and extracts
+    the ``FINAL ANSWER:`` from the structured response.  No tools, no loop —
+    a single LLM call per ``continue_chat`` invocation.
+
+    This is the recommended baseline for reasoning tasks (arithmetic, logic,
+    multi-step instructions) that do not require external information.
+    Registered toolboxes are ignored.
+
+    Config keys:
+
+    - ``brain`` (str): ChatEngine plugin ID used as the inner LLM.
+    - ``system_prompt`` (str): Optional extra system context prepended before
+      the CoT instruction.
+
+    Entry point group: ``opm.agents.chat``
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Initialise the Chain-of-Thought engine.
+
+        Args:
+            config: Plugin configuration dict.
+        """
+        super().__init__(config=config)
+        self._brain: Optional[ChatEngine] = None
+
+    @property
+    def brain(self) -> Optional[ChatEngine]:
+        """The inner ChatEngine used for the single LLM call."""
+        if self._brain is None:
+            self._brain = self._load_brain()
+        return self._brain
+
+    def set_brain(self, brain: ChatEngine) -> None:
+        """
+        Inject a ChatEngine instance as the inner LLM.
+
+        Args:
+            brain: Instantiated ``ChatEngine``.
+        """
+        self._brain = brain
+        self._inject_brain_into_toolboxes(brain)
+
+    def _load_brain(self) -> Optional[ChatEngine]:
+        """
+        Load the brain ChatEngine from config using OPM.
+
+        Returns:
+            Instantiated ``ChatEngine``, or ``None`` if loading fails.
+        """
+        brain_id: str = self.config.get("brain", "")
+        if not brain_id:
+            return None
+        try:
+            from ovos_plugin_manager.agents import load_chat_plugin
+            return load_chat_plugin(brain_id, config=self.config.get(brain_id, {}))
+        except Exception:  # noqa: BLE001
+            return None
+
+    def continue_chat(self, messages: List[AgentMessage],
+                      session_id: str = "default",
+                      lang: Optional[str] = None,
+                      units: Optional[str] = None) -> AgentMessage:
+        """
+        Run a single CoT-prompted LLM call and return the final answer.
+
+        Prepends the CoT system instruction (and any ``system_prompt`` config
+        value) to the message list, calls the brain once, and extracts the
+        ``FINAL ANSWER:`` text.  If the marker is absent the full response is
+        returned as-is.
+
+        Args:
+            messages: Conversation history including the latest user turn.
+            session_id: Session identifier forwarded to the brain.
+            lang: BCP-47 language code forwarded to the brain.
+            units: Measurement system forwarded to the brain.
+
+        Returns:
+            ``AgentMessage`` with ``MessageRole.ASSISTANT`` containing the
+            extracted final answer or the full CoT response.
+        """
+        if self.brain is None:
+            return AgentMessage(role=MessageRole.ASSISTANT,
+                                content="Error: no brain configured.")
+
+        extra_prompt = self.config.get("system_prompt", "")
+        system_content = (extra_prompt + "\n\n" if extra_prompt else "") + _COT_SYSTEM_PROMPT
+
+        loop_messages = [
+            AgentMessage(role=MessageRole.SYSTEM, content=system_content),
+            *messages,
+        ]
+        response = self.brain.continue_chat(
+            loop_messages, session_id=session_id, lang=lang, units=units
+        )
+        final = _extract_final_answer(response.content)
+        content = final if final is not None else response.content
+        return AgentMessage(role=MessageRole.ASSISTANT, content=content)

ovos_agentic_loop/context/__init__.py

@@ -0,0 +1,13 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""AGENTS.md context manager integration."""

ovos_agentic_loop/context/agents_md.py

@@ -0,0 +1,274 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""AgentsMDContextManager — builds agent system prompts from AGENTS.md files."""
+import importlib.metadata
+import os
+import re
+from typing import Dict, List, Optional
+
+from ovos_plugin_manager.templates.agents import AgentContextManager, AgentMessage, MessageRole
+from ovos_utils.log import LOG
+
+
+def _parse_sections(text: str) -> Dict[str, str]:
+    """
+    Parse a markdown document into a dict mapping heading titles to section bodies.
+
+    Headings at any level (``#``, ``##``, etc.) are recognised.  The section
+    body is everything from the heading line up to (but not including) the next
+    heading of the same or higher level.
+
+    Args:
+        text: Full markdown document text.
+
+    Returns:
+        ``{heading_title: section_body_text}`` — headings are stripped of
+        leading ``#`` characters and whitespace.
+    """
+    sections: Dict[str, str] = {}
+    pattern = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
+    matches = list(pattern.finditer(text))
+
+    for i, match in enumerate(matches):
+        heading = match.group(2).strip()
+        start = match.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        sections[heading] = text[start:end].strip()
+
+    return sections
+
+
+def _discover_agents_md_paths() -> List[str]:
+    """
+    Discover AGENTS.md files from installed package data.
+
+    Walks every installed distribution's recorded files looking for files
+    named ``AGENTS.md``.
+
+    Returns:
+        List of absolute paths that exist on disk.
+    """
+    paths: List[str] = []
+    try:
+        dists = importlib.metadata.distributions()
+    except Exception as exc:  # noqa: BLE001
+        LOG.debug(f"AgentsMDContextManager: could not enumerate distributions: {exc}")
+        return paths
+
+    for dist in dists:
+        try:
+            files = dist.files or []
+            for f in files:
+                if f.name == "AGENTS.md":
+                    abs_path = str(f.locate().resolve())
+                    if os.path.isfile(abs_path):
+                        paths.append(abs_path)
+        except Exception as exc:  # noqa: BLE001
+            LOG.debug(f"AgentsMDContextManager: error scanning dist files: {exc}")
+            continue
+    return paths
+
+
+class AgentsMDContextManager(AgentContextManager):
+    """
+    An ``AgentContextManager`` that assembles the agent system prompt by
+    loading selected sections from one or more ``AGENTS.md`` files.
+
+    The same AGENTS.md that governs Claude Code at dev-time can govern a
+    runtime LLM agent — both consumers read the same document.
+
+    Per-session conversation history is stored in an in-memory dict keyed by
+    ``session_id``.
+
+    Discovery:
+
+    1. Config ``agents_md_sources`` — list of paths or ``["auto"]`` to trigger
+       automatic package-data discovery.
+    2. ``extra_paths`` constructor argument — additional ad-hoc paths.
+
+    Config keys:
+
+    - ``agents_md_sources`` (List[str]): Paths to load, or ``["auto"]``.
+    - ``include_sections`` (List[str]): Heading titles to include (substring
+      match).  If empty, all sections are included.
+    - ``system_prompt_prefix`` (str): Text prepended before the assembled
+      AGENTS.md content.
+
+    Entry point group: ``opm.agents.memory``
+    """
+
+    plugin_id = "ovos-agents-md-context-plugin"
+
+    def __init__(self, config: Optional[Dict] = None,
+                 extra_paths: Optional[List[str]] = None) -> None:
+        """
+        Initialise the context manager.
+
+        Args:
+            config: Plugin configuration dictionary.
+            extra_paths: Additional AGENTS.md file paths to load.
+        """
+        super().__init__(config=config)
+        self._extra_paths: List[str] = list(extra_paths or [])
+        # Per-session history: {session_id: [AgentMessage, ...]}
+        self._sessions: Dict[str, List[AgentMessage]] = {}
+        self._system_prompt_cache: Optional[str] = None
+
+    # ------------------------------------------------------------------
+    # Configuration helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def include_sections(self) -> List[str]:
+        """Heading substrings that filter which sections are included."""
+        return list((self.config or {}).get("include_sections", []))
+
+    @property
+    def system_prompt_prefix(self) -> str:
+        """Text prepended before assembled AGENTS.md content."""
+        return str((self.config or {}).get("system_prompt_prefix", ""))
+
+    # ------------------------------------------------------------------
+    # Path resolution
+    # ------------------------------------------------------------------
+
+    def _resolve_paths(self) -> List[str]:
+        """
+        Return deduplicated list of AGENTS.md paths to load.
+
+        Returns:
+            Absolute path list.
+        """
+        sources: List[str] = list((self.config or {}).get("agents_md_sources", ["auto"]))
+        paths: List[str] = []
+
+        if "auto" in sources:
+            paths.extend(_discover_agents_md_paths())
+        for src in sources:
+            if src != "auto" and os.path.isfile(src):
+                paths.append(src)
+        paths.extend(self._extra_paths)
+
+        # Deduplicate while preserving order.
+        seen: set = set()
+        result: List[str] = []
+        for p in paths:
+            if p not in seen:
+                seen.add(p)
+                result.append(p)
+        return result
+
+    # ------------------------------------------------------------------
+    # System prompt construction
+    # ------------------------------------------------------------------
+
+    def _build_system_prompt(self) -> str:
+        """
+        Load all AGENTS.md files, filter sections, and concatenate.
+
+        Returns:
+            The assembled system prompt string.
+        """
+        parts: List[str] = []
+        if self.system_prompt_prefix:
+            parts.append(self.system_prompt_prefix)
+
+        for path in self._resolve_paths():
+            try:
+                with open(path, encoding="utf-8") as fh:
+                    text = fh.read()
+            except OSError as exc:
+                LOG.warning(f"AgentsMDContextManager: could not read '{path}': {exc}")
+                continue
+
+            sections = _parse_sections(text)
+            for heading, body in sections.items():
+                if self.include_sections:
+                    if not any(inc.lower() in heading.lower()
+                               for inc in self.include_sections):
+                        continue
+                parts.append(f"## {heading}\n\n{body}")
+
+        return "\n\n".join(parts)
+
+    @property
+    def system_prompt(self) -> str:
+        """
+        Assembled system prompt derived from AGENTS.md sections.
+
+        Lazily computed and cached after the first access.
+        """
+        if self._system_prompt_cache is None:
+            self._system_prompt_cache = self._build_system_prompt()
+        return self._system_prompt_cache
+
+    def invalidate_cache(self) -> None:
+        """Force the system prompt to be rebuilt on next access."""
+        self._system_prompt_cache = None
+
+    # ------------------------------------------------------------------
+    # AgentContextManager protocol (full ABC compliance)
+    # ------------------------------------------------------------------
+
+    def get_history(self, session_id: str) -> List[AgentMessage]:
+        """
+        Retrieve the message history for a given session.
+
+        Args:
+            session_id: Conversation session identifier.
+
+        Returns:
+            Snapshot of the session's message list in chronological order.
+        """
+        return list(self._sessions.get(session_id, []))
+
+    def update_history(self, new_messages: List[AgentMessage], session_id: str) -> None:
+        """
+        Append new messages to a session's history.
+
+        Args:
+            new_messages: Messages to append.
+            session_id: Conversation session identifier.
+        """
+        if session_id not in self._sessions:
+            self._sessions[session_id] = []
+        self._sessions[session_id].extend(new_messages)
+
+    def build_conversation_context(
+        self,
+        utterance: str,
+        session_id: str,
+    ) -> List[AgentMessage]:
+        """
+        Assemble the full message list for an LLM call.
+
+        Prepends the system prompt (assembled from AGENTS.md), appends the
+        session's conversation history, and adds the current user utterance
+        as the final message.
+
+        Args:
+            utterance: The user's current input.
+            session_id: Conversation session identifier used to retrieve history.
+
+        Returns:
+            Ordered list of ``AgentMessage`` objects ready for a ChatEngine.
+        """
+        messages: List[AgentMessage] = []
+
+        prompt = self.system_prompt
+        if prompt:
+            messages.append(AgentMessage(role=MessageRole.SYSTEM, content=prompt))
+
+        messages.extend(self.get_history(session_id))
+        messages.append(AgentMessage(role=MessageRole.USER, content=utterance))
+        return messages