agent2 0.1.0__py3-none-any.whl

agent2/__init__.py

@@ -0,0 +1,6 @@
+"""Agent2 - A modular agent system framework for learning and research."""
+
+from agent2.utils.config import Settings
+
+__version__ = "0.1.0"
+__all__ = ["Settings"]

agent2/agent/__init__.py

@@ -0,0 +1,21 @@
+"""Agent module — reasoning cores for LLM-powered agents.
+
+Available agent types:
+
+- :class:`ReActAgent` — Thought → Action → Observation loop
+- :class:`PlannerAgent` — Plan-and-Execute pattern
+- :class:`ReflectionMixin` — Self-critique mixin for any agent
+"""
+
+from agent2.agent.base import BaseAgent, MaxIterationsExceeded
+from agent2.agent.react import ReActAgent
+from agent2.agent.planner import PlannerAgent
+from agent2.agent.reflection import ReflectionMixin
+
+__all__ = [
+    "BaseAgent",
+    "MaxIterationsExceeded",
+    "ReActAgent",
+    "PlannerAgent",
+    "ReflectionMixin",
+]

agent2/agent/base.py

@@ -0,0 +1,131 @@
+"""Base Agent class — the foundation for all agent types."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from agent2.llm.base import BaseLLM
+from agent2.llm.message import Message
+from agent2.tools.base import Tool
+from agent2.tools.registry import ToolRegistry
+from agent2.utils.config import settings
+from agent2.utils.logging import AgentLogger
+
+
+class BaseAgent(ABC):
+    """Abstract base class for all agents.
+
+    An agent combines an LLM with tools and a system prompt to perform
+    tasks through an iterative reasoning loop.
+
+    Parameters
+    ----------
+    name : str
+        Human-readable agent name.
+    llm : BaseLLM
+        The language model to use for reasoning.
+    system_prompt : str
+        Instructions defining the agent's role and behaviour.
+    tools : list[Tool] | None
+        Tools available to this agent.
+    max_iterations : int
+        Safety limit for the reasoning loop.
+    verbose : bool
+        Enable detailed logging of the reasoning process.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        llm: BaseLLM,
+        system_prompt: str = "You are a helpful AI assistant.",
+        tools: list[Tool] | None = None,
+        max_iterations: int | None = None,
+        verbose: bool | None = None,
+    ) -> None:
+        self.name = name
+        self.llm = llm
+        self.system_prompt = system_prompt
+        self.max_iterations = max_iterations or settings.agent_max_iterations
+        self.verbose = verbose if verbose is not None else settings.agent_verbose
+
+        # Set up tool registry
+        self.tool_registry = ToolRegistry()
+        if tools:
+            for t in tools:
+                self.tool_registry.register(t)
+
+        # Set up logger
+        self.log = AgentLogger(name, verbose=self.verbose)
+
+        # Conversation history for the current run
+        self._messages: list[Message] = []
+
+    # ── Public API ──────────────────────────────────────────────────
+
+    async def run(self, task: str) -> str:
+        """Execute a task and return the final answer.
+
+        Parameters
+        ----------
+        task : str
+            The user's task or question.
+
+        Returns
+        -------
+        str
+            The agent's final response.
+        """
+        self.log.start(task)
+
+        # Initialize conversation
+        self._messages = [
+            Message.system(self.system_prompt),
+            Message.user(task),
+        ]
+
+        try:
+            result = await self._run_loop()
+        except MaxIterationsExceeded:
+            result = (
+                f"I was unable to complete the task within {self.max_iterations} steps. "
+                f"Here is what I've done so far based on the conversation."
+            )
+            self.log.observation(result, is_error=True)
+
+        self.log.finish(result)
+        return result
+
+    # ── Abstract method for subclasses ──────────────────────────────
+
+    @abstractmethod
+    async def _run_loop(self) -> str:
+        """The core reasoning loop. Subclasses implement this.
+
+        Returns the final answer string.
+        """
+        ...
+
+    # ── Helpers ─────────────────────────────────────────────────────
+
+    async def _execute_tool_calls(self, tool_calls: list[Any]) -> list[Message]:
+        """Execute a list of tool calls and return result messages."""
+        results: list[Message] = []
+        for tc in tool_calls:
+            self.log.action(tc.name, tc.arguments)
+            output = await self.tool_registry.execute(tc.name, **tc.arguments)
+            is_error = output.startswith("Error")
+            self.log.observation(output, is_error=is_error)
+            results.append(Message.tool(tc.id, output, is_error=is_error))
+        return results
+
+    def __repr__(self) -> str:
+        tools = [t.name for t in self.tool_registry.list_tools()]
+        return f"{self.__class__.__name__}(name={self.name!r}, llm={self.llm!r}, tools={tools})"
+
+
+class MaxIterationsExceeded(Exception):
+    """Raised when agent exceeds its maximum iteration count."""
+    pass

agent2/agent/planner.py

@@ -0,0 +1,251 @@
+"""Plan-and-Execute Agent — separates planning from execution.
+
+The agent first generates a high-level plan (list of steps), then
+executes each step sequentially. It can revise the plan dynamically
+based on intermediate results.
+
+This pattern improves reliability for complex, multi-step tasks
+compared to pure ReAct.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agent2.agent.base import BaseAgent, MaxIterationsExceeded
+from agent2.llm.base import BaseLLM
+from agent2.llm.message import Message
+from agent2.tools.base import Tool
+
+
+_PLANNER_PROMPT = """You are a planning agent. Given a task, create a detailed step-by-step plan.
+
+Respond ONLY with a JSON array of strings, where each string is one step.
+Example: ["Step 1: Search for ...", "Step 2: Analyse ...", "Step 3: Summarise ..."]
+
+Keep the plan concise (3-7 steps). Each step should be actionable and specific.
+"""
+
+_EXECUTOR_PROMPT = """You are a helpful AI assistant executing one step of a larger plan.
+
+The overall task is:
+{task}
+
+The full plan is:
+{plan}
+
+You are currently executing step {step_number}: {step_description}
+
+Previous step results:
+{previous_results}
+
+Execute this step using the available tools. Provide your result clearly.
+When done, respond with your findings (no tool calls).
+"""
+
+_REPLANNER_PROMPT = """You are a replanning agent. Based on the results so far, decide if the remaining plan needs adjustment.
+
+Original task: {task}
+Original plan: {plan}
+Completed steps and results: {completed}
+Remaining steps: {remaining}
+
+If the remaining plan is still good, respond with: {{"action": "continue"}}
+If you need to revise, respond with: {{"action": "revise", "new_remaining_steps": ["step 1", "step 2", ...]}}
+"""
+
+
+class PlannerAgent(BaseAgent):
+    """Agent using the Plan-and-Execute pattern.
+
+    1. Generate a plan (list of steps)
+    2. Execute each step using a ReAct-style sub-loop
+    3. Optionally re-plan after each step
+
+    Usage::
+
+        agent = PlannerAgent("planner", llm=llm, tools=[web_search])
+        result = await agent.run("Compare Python and Rust for web development")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        llm: BaseLLM,
+        system_prompt: str | None = None,
+        tools: list[Tool] | None = None,
+        max_iterations: int | None = None,
+        verbose: bool | None = None,
+        enable_replan: bool = True,
+        max_step_iterations: int = 5,
+    ) -> None:
+        super().__init__(
+            name,
+            llm=llm,
+            system_prompt=system_prompt or "You are a helpful planning assistant.",
+            tools=tools,
+            max_iterations=max_iterations,
+            verbose=verbose,
+        )
+        self.enable_replan = enable_replan
+        self.max_step_iterations = max_step_iterations
+
+    async def _run_loop(self) -> str:
+        """Plan → Execute each step → Synthesise."""
+        task = self._messages[-1].content or ""
+
+        # Phase 1: Generate plan
+        plan = await self._generate_plan(task)
+        self.log.plan(plan)
+
+        # Phase 2: Execute steps
+        step_results: list[dict[str, str]] = []
+
+        while plan:
+            step_desc = plan.pop(0)
+            step_num = len(step_results) + 1
+            self.log.plan_step_start(step_num, step_desc)
+
+            result = await self._execute_step(
+                task=task,
+                plan_overview=[r["step"] for r in step_results] + [step_desc] + plan,
+                step_number=step_num,
+                step_description=step_desc,
+                previous_results=step_results,
+            )
+
+            step_results.append({"step": step_desc, "result": result})
+            self.log.plan_step_done(step_num)
+
+            # Phase 2.5: Optionally re-plan
+            if self.enable_replan and plan:
+                plan = await self._maybe_replan(task, step_results, plan)
+
+        # Phase 3: Synthesise final answer
+        return await self._synthesise(task, step_results)
+
+    async def _generate_plan(self, task: str) -> list[str]:
+        """Use the LLM to create an execution plan."""
+        response = await self.llm.chat([
+            Message.system(_PLANNER_PROMPT),
+            Message.user(task),
+        ])
+
+        content = response.content or "[]"
+        # Extract JSON from possible markdown code blocks
+        if "```" in content:
+            content = content.split("```")[1]
+            if content.startswith("json"):
+                content = content[4:]
+
+        try:
+            plan = json.loads(content.strip())
+            if isinstance(plan, list):
+                return [str(s) for s in plan]
+        except json.JSONDecodeError:
+            pass
+
+        # Fallback: split by newlines
+        return [line.strip() for line in content.strip().split("\n") if line.strip()]
+
+    async def _execute_step(
+        self,
+        task: str,
+        plan_overview: list[str],
+        step_number: int,
+        step_description: str,
+        previous_results: list[dict[str, str]],
+    ) -> str:
+        """Execute a single plan step using a mini ReAct loop."""
+        prev_text = "\n".join(
+            f"Step {i+1} ({r['step']}): {r['result'][:200]}"
+            for i, r in enumerate(previous_results)
+        ) or "None yet."
+
+        system = _EXECUTOR_PROMPT.format(
+            task=task,
+            plan="\n".join(f"{i+1}. {s}" for i, s in enumerate(plan_overview)),
+            step_number=step_number,
+            step_description=step_description,
+            previous_results=prev_text,
+        )
+
+        messages = [
+            Message.system(system),
+            Message.user(f"Execute step {step_number}: {step_description}"),
+        ]
+
+        tool_schemas = self.tool_registry.list_schemas() or None
+
+        for _ in range(self.max_step_iterations):
+            response = await self.llm.chat(messages, tools=tool_schemas)
+
+            if response.has_tool_calls:
+                if response.content:
+                    self.log.thought(response.content)
+                messages.append(response.message)
+                tool_results = await self._execute_tool_calls(response.tool_calls)
+                messages.extend(tool_results)
+                continue
+
+            return response.content or ""
+
+        return "(Step execution reached iteration limit)"
+
+    async def _maybe_replan(
+        self,
+        task: str,
+        completed: list[dict[str, str]],
+        remaining: list[str],
+    ) -> list[str]:
+        """Ask the LLM if the remaining plan needs revision."""
+        prompt = _REPLANNER_PROMPT.format(
+            task=task,
+            plan="(see completed + remaining)",
+            completed=json.dumps(completed, ensure_ascii=False, indent=2),
+            remaining=json.dumps(remaining, ensure_ascii=False),
+        )
+
+        response = await self.llm.chat([
+            Message.system("You are a replanning agent. Respond in JSON only."),
+            Message.user(prompt),
+        ])
+
+        content = response.content or ""
+        try:
+            data = json.loads(content.strip())
+            if data.get("action") == "revise" and "new_remaining_steps" in data:
+                new_plan = [str(s) for s in data["new_remaining_steps"]]
+                self.log.plan(new_plan)
+                return new_plan
+        except (json.JSONDecodeError, AttributeError):
+            pass
+
+        return remaining
+
+    async def _synthesise(
+        self, task: str, step_results: list[dict[str, str]]
+    ) -> str:
+        """Synthesise a final answer from all step results."""
+        results_text = "\n\n".join(
+            f"### Step {i+1}: {r['step']}\n{r['result']}"
+            for i, r in enumerate(step_results)
+        )
+
+        response = await self.llm.chat([
+            Message.system(
+                "Synthesise all the step results into a clear, comprehensive final answer. "
+                "Be concise but thorough."
+            ),
+            Message.user(
+                f"Original task: {task}\n\n"
+                f"Step results:\n{results_text}\n\n"
+                f"Provide a final comprehensive answer."
+            ),
+        ])
+
+        answer = response.content or ""
+        self.log.final_answer(answer)
+        return answer

agent2/agent/react.py

@@ -0,0 +1,104 @@
+"""ReAct Agent — Reasoning + Acting pattern.
+
+The ReAct loop alternates between:
+  1. **Thought**: The LLM reasons about what to do next
+  2. **Action**: The LLM calls a tool
+  3. **Observation**: The tool result is fed back to the LLM
+  4. **Repeat** until the LLM provides a final answer (no tool calls)
+
+Reference: Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models" (2022)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent2.agent.base import BaseAgent, MaxIterationsExceeded
+from agent2.llm.base import BaseLLM
+from agent2.llm.message import Message
+from agent2.tools.base import Tool
+
+
+_DEFAULT_REACT_PROMPT = """You are a helpful AI assistant that can use tools to accomplish tasks.
+
+When you need information or need to perform an action, use the available tools.
+Think step by step about what you need to do.
+When you have gathered enough information to answer the user's question, provide your final answer directly without calling any more tools.
+
+Important:
+- Always think before acting.
+- Use tools when you need external information or capabilities.
+- When you're ready to give the final answer, respond with text only (no tool calls).
+"""
+
+
+class ReActAgent(BaseAgent):
+    """Agent implementing the ReAct (Reasoning + Acting) pattern.
+
+    This is the most fundamental agent type. It iteratively reasons
+    and acts until it arrives at a final answer.
+
+    Usage::
+
+        from agent2.llm import create_llm
+        from agent2.agent import ReActAgent
+        from agent2.tools.builtin import web_search
+
+        llm = create_llm("openai", model="gpt-4o-mini")
+        agent = ReActAgent("researcher", llm=llm, tools=[web_search])
+        result = await agent.run("What is the capital of France?")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        llm: BaseLLM,
+        system_prompt: str | None = None,
+        tools: list[Tool] | None = None,
+        max_iterations: int | None = None,
+        verbose: bool | None = None,
+    ) -> None:
+        super().__init__(
+            name,
+            llm=llm,
+            system_prompt=system_prompt or _DEFAULT_REACT_PROMPT,
+            tools=tools,
+            max_iterations=max_iterations,
+            verbose=verbose,
+        )
+
+    async def _run_loop(self) -> str:
+        """Execute the ReAct loop: Thought → Action → Observation → repeat."""
+        tool_schemas = self.tool_registry.list_schemas() or None
+
+        for iteration in range(1, self.max_iterations + 1):
+            # Ask the LLM to think and optionally call tools
+            response = await self.llm.chat(
+                self._messages,
+                tools=tool_schemas,
+            )
+
+            # If the LLM wants to call tools → Action + Observation
+            if response.has_tool_calls:
+                # Log the thinking (if any content accompanies tool calls)
+                if response.content:
+                    self.log.thought(response.content)
+
+                # Record the assistant message with tool calls
+                self._messages.append(response.message)
+
+                # Execute each tool call
+                tool_results = await self._execute_tool_calls(response.tool_calls)
+                self._messages.extend(tool_results)
+                continue
+
+            # No tool calls → this is the final answer
+            final_answer = response.content or ""
+            self.log.final_answer(final_answer)
+            return final_answer
+
+        # Exceeded max iterations
+        raise MaxIterationsExceeded(
+            f"Agent '{self.name}' exceeded {self.max_iterations} iterations"
+        )

agent2/agent/reflection.py

@@ -0,0 +1,117 @@
+"""Reflection mixin — self-critique and iterative refinement.
+
+Adds a reflection capability that lets an agent evaluate its own output
+and retry if quality is insufficient. Can be mixed into any agent type.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent2.llm.base import BaseLLM
+from agent2.llm.message import Message
+from agent2.utils.logging import AgentLogger
+
+
+_REFLECTION_PROMPT = """You are a critical reviewer. Evaluate the following response to the given task.
+
+Task: {task}
+Response: {response}
+
+Evaluate the response on these criteria:
+1. **Correctness**: Is the information accurate?
+2. **Completeness**: Does it fully address the task?
+3. **Clarity**: Is it well-structured and easy to understand?
+
+Respond in this exact JSON format:
+{{
+    "score": <1-10>,
+    "passed": <true if score >= 7, false otherwise>,
+    "feedback": "<specific suggestions for improvement>"
+}}
+"""
+
+
+class ReflectionMixin:
+    """Mixin that adds self-reflection capability to any agent.
+
+    After the agent produces an answer, it evaluates the answer and
+    retries with the feedback if the quality is below threshold.
+
+    Usage::
+
+        class MyReflectiveAgent(ReflectionMixin, ReActAgent):
+            pass
+
+        agent = MyReflectiveAgent("reflector", llm=llm, max_reflections=2)
+    """
+
+    max_reflections: int = 2
+    reflection_threshold: int = 7  # Minimum score (1-10) to pass
+
+    async def run(self, task: str) -> str:
+        """Override run() to add reflection loop."""
+        # Get the base agent's run result
+        result = await super().run(task)  # type: ignore[misc]
+
+        # Access the logger from the base agent
+        log: AgentLogger = getattr(self, "log", AgentLogger("reflection"))
+        llm: BaseLLM = getattr(self, "llm")
+
+        for attempt in range(self.max_reflections):
+            evaluation = await self._reflect(llm, task, result)
+
+            if evaluation.get("passed", True):
+                return result
+
+            feedback = evaluation.get("feedback", "Try to improve your response.")
+            score = evaluation.get("score", "?")
+            log.thought(
+                f"Reflection {attempt + 1}/{self.max_reflections}: "
+                f"Score {score}/10 — {feedback}"
+            )
+
+            # Retry with feedback
+            result = await self._retry_with_feedback(llm, task, result, feedback)
+            log.final_answer(result)
+
+        return result
+
+    @staticmethod
+    async def _reflect(
+        llm: BaseLLM, task: str, response: str
+    ) -> dict[str, Any]:
+        """Ask the LLM to evaluate a response."""
+        import json
+
+        prompt = _REFLECTION_PROMPT.format(task=task, response=response)
+        llm_response = await llm.chat([
+            Message.system("You are a critical reviewer. Respond in JSON only."),
+            Message.user(prompt),
+        ])
+
+        content = llm_response.content or ""
+        try:
+            return json.loads(content.strip())
+        except json.JSONDecodeError:
+            # If parsing fails, assume it passed
+            return {"score": 10, "passed": True, "feedback": ""}
+
+    @staticmethod
+    async def _retry_with_feedback(
+        llm: BaseLLM, task: str, previous: str, feedback: str
+    ) -> str:
+        """Generate an improved response incorporating feedback."""
+        response = await llm.chat([
+            Message.system(
+                "You previously answered a task but your answer needs improvement. "
+                "Generate an improved response based on the feedback."
+            ),
+            Message.user(
+                f"Original task: {task}\n\n"
+                f"Your previous answer:\n{previous}\n\n"
+                f"Reviewer feedback:\n{feedback}\n\n"
+                f"Please provide an improved answer."
+            ),
+        ])
+        return response.content or previous

agent2/app/__init__.py

@@ -0,0 +1 @@
+"""Agent2 applications — CLI tools built on the agent2 framework."""