ovos-agentic-loop 0.1.0__tar.gz

ovos_agentic_loop-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ovos-agentic-loop
+Version: 0.1.0
+Summary: AgenticLoopEngine base and ReAct implementation for OVOS, with SKILL.md and AGENTS.md runtime consumption
+Author-email: OpenVoiceOS <openvoiceos@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-agentic-loop
+Project-URL: Repository, https://github.com/OpenVoiceOS/ovos-agentic-loop
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.3.0a1
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: web
+Requires-Dist: duckduckgo-search>=6.0; extra == "web"
+
+# ovos-agentic-loop
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-agentic-loop)](https://pypi.org/project/ovos-agentic-loop/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
+
+Agent-loop `ChatEngine` plugins for [OVOS](https://openvoiceos.org). Implements seven agentic reasoning patterns (ReAct, Plan-and-Execute, Reflexion, Self-Ask, Chain-of-Thought, CRITIC, Tree-of-Thoughts), five built-in toolboxes, SKILL.md integration, and AGENTS.md context management — all as standard OPM plugins.
+
+---
+
+## Features
+
+- **7 loop architectures** — from simple Chain-of-Thought to full Reflexion and Tree-of-Thoughts beam search
+- **5 built-in toolboxes** — filesystem, shell, web search, clock, math (calculator + unit conversion + statistics)
+- **SKILL.md toolbox** — turns any installed SKILL.md file into an agent tool
+- **AGENTS.md context manager** — loads structured system prompts from AGENTS.md files at runtime
+- **No LLM bundled** — wire any OPM `ChatEngine` as the inner brain
+- **No persona bundled** — compose your own persona using the provided primitives
+
+---
+
+## Installation
+
+```bash
+pip install ovos-agentic-loop
+
+# Optional: web search support
+pip install 'ovos-agentic-loop[web]'
+```
+
+---
+
+## Quick Start
+
+### Minimal ReAct agent with a calculator
+
+```python
+from ovos_agentic_loop.react import ReActLoopEngine
+from ovos_agentic_loop.tools.math import MathToolBox
+from ovos_plugin_manager.templates.agents import AgentMessage, MessageRole
+
+# Wire a local LLM as the brain (any OPM ChatEngine works)
+engine = ReActLoopEngine({
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+        "api_url": "http://localhost:11434/v1/chat/completions",
+    },
+    "max_iterations": 8,
+})
+engine.load_toolboxes([MathToolBox()])
+
+response = engine.continue_chat([
+    AgentMessage(role=MessageRole.USER, content="What is 17 * 23 + sqrt(144)?")
+])
+print(response.content)
+```
+
+### Persona JSON (all-in-one config)
+
+```json
+{
+  "name": "MyAgent",
+  "solvers": ["ovos-react-loop"],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions"
+    },
+    "toolboxes": ["ovos-math-tools", "ovos-web-search-tools", "ovos-clock-tools"],
+    "max_iterations": 10
+  }
+}
+```
+
+---
+
+## Loop Architectures
+
+| Entry point | Class | Best for |
+|---|---|---|
+| `ovos-react-loop` | `ReActLoopEngine` | General tool-using Q&A |
+| `ovos-plan-execute-loop` | `PlanAndExecuteEngine` | Multi-step tasks requiring a plan |
+| `ovos-reflexion-loop` | `ReflexionEngine` | Tasks requiring self-critique and retry |
+| `ovos-self-ask-loop` | `SelfAskEngine` | Compositional questions needing sub-questions |
+| `ovos-chain-of-thought-loop` | `ChainOfThoughtEngine` | Reasoning without tools (math, logic) |
+| `ovos-critic-loop` | `CRITICEngine` | Factual tasks requiring claim verification |
+| `ovos-tree-of-thoughts-loop` | `TreeOfThoughtsEngine` | Exploration-heavy problems (beam search) |
+
+---
+
+## Built-in Toolboxes
+
+| Entry point | Class | Tools |
+|---|---|---|
+| `ovos-math-tools` | `MathToolBox` | `evaluate_expression`, `unit_convert`, `statistics_summary`, `solve_equation` |
+| `ovos-filesystem-tools` | `FileSystemToolBox` | `read_file`, `write_file`, `list_directory`, `search_in_files`, `find_files` |
+| `ovos-shell-tools` | `ShellToolBox` | `run_command` (disabled by default; set `allow_shell: true` to enable) |
+| `ovos-web-search-tools` | `WebSearchToolBox` | `web_search` (requires `ovos-agentic-loop[web]`) |
+| `ovos-clock-tools` | `ClockToolBox` | `get_current_datetime` |
+| `ovos-skill-md-toolbox` | `SkillMDToolBox` | One tool per installed SKILL.md |
+
+---
+
+## SKILL.md Integration
+
+Any package that ships a `SKILL.md` file is automatically discovered and exposed as an agent tool:
+
+```markdown
+---
+name: my-skill
+description: Does something useful.
+---
+You are a helpful assistant specialised in...
+```
+
+The tool name is the slugified `name` field; the SKILL.md body becomes the system prompt for a sub-LLM call.
+
+---
+
+## AGENTS.md Context Management
+
+`AgentsMDContextManager` assembles system prompts from `AGENTS.md` files at runtime — the same files Claude Code reads at dev-time:
+
+```python
+from ovos_agentic_loop.context.agents_md import AgentsMDContextManager
+
+ctx = AgentsMDContextManager({
+    "agents_md_sources": ["auto"],          # auto-discover from installed packages
+    "include_sections": ["Rules", "Style"], # filter to specific headings
+})
+messages = ctx.build_conversation_context(utterance, session_id="s1")
+```
+
+---
+
+## Security Notes
+
+- **`ShellToolBox`** — `allow_shell` defaults to `False`. Only enable with fully-trusted LLMs; the command string is passed directly to `/bin/sh`.
+- **`FileSystemToolBox`** — set `root_path` to restrict file access to a subtree. Without it, the agent can read any world-readable file.
+- **`MathToolBox`** — uses `ast.parse` with an allowlist; `eval()` is never called.
+
+---
+
+## Documentation
+
+- [docs/loop-architectures.md](docs/loop-architectures.md) — all 7 loop engines with algorithm details
+- [docs/react-loop.md](docs/react-loop.md) — ReAct prompt format and parsing
+- [docs/toolboxes.md](docs/toolboxes.md) — all toolbox schemas and config keys
+- [docs/skill-md.md](docs/skill-md.md) — SKILL.md authoring and packaging guide
+- [docs/agents-md.md](docs/agents-md.md) — AGENTS.md context manager reference
+- [docs/opm-integration.md](docs/opm-integration.md) — OPM entry points and persona wiring
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_agentic_loop-0.1.0/README.md

@@ -0,0 +1,157 @@
+# ovos-agentic-loop
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-agentic-loop)](https://pypi.org/project/ovos-agentic-loop/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
+
+Agent-loop `ChatEngine` plugins for [OVOS](https://openvoiceos.org). Implements seven agentic reasoning patterns (ReAct, Plan-and-Execute, Reflexion, Self-Ask, Chain-of-Thought, CRITIC, Tree-of-Thoughts), five built-in toolboxes, SKILL.md integration, and AGENTS.md context management — all as standard OPM plugins.
+
+---
+
+## Features
+
+- **7 loop architectures** — from simple Chain-of-Thought to full Reflexion and Tree-of-Thoughts beam search
+- **5 built-in toolboxes** — filesystem, shell, web search, clock, math (calculator + unit conversion + statistics)
+- **SKILL.md toolbox** — turns any installed SKILL.md file into an agent tool
+- **AGENTS.md context manager** — loads structured system prompts from AGENTS.md files at runtime
+- **No LLM bundled** — wire any OPM `ChatEngine` as the inner brain
+- **No persona bundled** — compose your own persona using the provided primitives
+
+---
+
+## Installation
+
+```bash
+pip install ovos-agentic-loop
+
+# Optional: web search support
+pip install 'ovos-agentic-loop[web]'
+```
+
+---
+
+## Quick Start
+
+### Minimal ReAct agent with a calculator
+
+```python
+from ovos_agentic_loop.react import ReActLoopEngine
+from ovos_agentic_loop.tools.math import MathToolBox
+from ovos_plugin_manager.templates.agents import AgentMessage, MessageRole
+
+# Wire a local LLM as the brain (any OPM ChatEngine works)
+engine = ReActLoopEngine({
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+        "api_url": "http://localhost:11434/v1/chat/completions",
+    },
+    "max_iterations": 8,
+})
+engine.load_toolboxes([MathToolBox()])
+
+response = engine.continue_chat([
+    AgentMessage(role=MessageRole.USER, content="What is 17 * 23 + sqrt(144)?")
+])
+print(response.content)
+```
+
+### Persona JSON (all-in-one config)
+
+```json
+{
+  "name": "MyAgent",
+  "solvers": ["ovos-react-loop"],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions"
+    },
+    "toolboxes": ["ovos-math-tools", "ovos-web-search-tools", "ovos-clock-tools"],
+    "max_iterations": 10
+  }
+}
+```
+
+---
+
+## Loop Architectures
+
+| Entry point | Class | Best for |
+|---|---|---|
+| `ovos-react-loop` | `ReActLoopEngine` | General tool-using Q&A |
+| `ovos-plan-execute-loop` | `PlanAndExecuteEngine` | Multi-step tasks requiring a plan |
+| `ovos-reflexion-loop` | `ReflexionEngine` | Tasks requiring self-critique and retry |
+| `ovos-self-ask-loop` | `SelfAskEngine` | Compositional questions needing sub-questions |
+| `ovos-chain-of-thought-loop` | `ChainOfThoughtEngine` | Reasoning without tools (math, logic) |
+| `ovos-critic-loop` | `CRITICEngine` | Factual tasks requiring claim verification |
+| `ovos-tree-of-thoughts-loop` | `TreeOfThoughtsEngine` | Exploration-heavy problems (beam search) |
+
+---
+
+## Built-in Toolboxes
+
+| Entry point | Class | Tools |
+|---|---|---|
+| `ovos-math-tools` | `MathToolBox` | `evaluate_expression`, `unit_convert`, `statistics_summary`, `solve_equation` |
+| `ovos-filesystem-tools` | `FileSystemToolBox` | `read_file`, `write_file`, `list_directory`, `search_in_files`, `find_files` |
+| `ovos-shell-tools` | `ShellToolBox` | `run_command` (disabled by default; set `allow_shell: true` to enable) |
+| `ovos-web-search-tools` | `WebSearchToolBox` | `web_search` (requires `ovos-agentic-loop[web]`) |
+| `ovos-clock-tools` | `ClockToolBox` | `get_current_datetime` |
+| `ovos-skill-md-toolbox` | `SkillMDToolBox` | One tool per installed SKILL.md |
+
+---
+
+## SKILL.md Integration
+
+Any package that ships a `SKILL.md` file is automatically discovered and exposed as an agent tool:
+
+```markdown
+---
+name: my-skill
+description: Does something useful.
+---
+You are a helpful assistant specialised in...
+```
+
+The tool name is the slugified `name` field; the SKILL.md body becomes the system prompt for a sub-LLM call.
+
+---
+
+## AGENTS.md Context Management
+
+`AgentsMDContextManager` assembles system prompts from `AGENTS.md` files at runtime — the same files Claude Code reads at dev-time:
+
+```python
+from ovos_agentic_loop.context.agents_md import AgentsMDContextManager
+
+ctx = AgentsMDContextManager({
+    "agents_md_sources": ["auto"],          # auto-discover from installed packages
+    "include_sections": ["Rules", "Style"], # filter to specific headings
+})
+messages = ctx.build_conversation_context(utterance, session_id="s1")
+```
+
+---
+
+## Security Notes
+
+- **`ShellToolBox`** — `allow_shell` defaults to `False`. Only enable with fully-trusted LLMs; the command string is passed directly to `/bin/sh`.
+- **`FileSystemToolBox`** — set `root_path` to restrict file access to a subtree. Without it, the agent can read any world-readable file.
+- **`MathToolBox`** — uses `ast.parse` with an allowlist; `eval()` is never called.
+
+---
+
+## Documentation
+
+- [docs/loop-architectures.md](docs/loop-architectures.md) — all 7 loop engines with algorithm details
+- [docs/react-loop.md](docs/react-loop.md) — ReAct prompt format and parsing
+- [docs/toolboxes.md](docs/toolboxes.md) — all toolbox schemas and config keys
+- [docs/skill-md.md](docs/skill-md.md) — SKILL.md authoring and packaging guide
+- [docs/agents-md.md](docs/agents-md.md) — AGENTS.md context manager reference
+- [docs/opm-integration.md](docs/opm-integration.md) — OPM entry points and persona wiring
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_agentic_loop-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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."""