abstractagent 0.2.0__py3-none-any.whl

abstractagent/agents/react.py

@@ -0,0 +1,210 @@
+"""ReAct agent implementation.
+
+This module wires:
+- Pure ReAct reasoning logic (abstractagent.logic)
+- To an AbstractRuntime workflow (abstractagent.adapters)
+
+The public API is intentionally stable:
+- ReactAgent
+- create_react_workflow
+- create_react_agent
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from abstractcore.tools import ToolDefinition
+from abstractruntime import RunState, Runtime, WorkflowSpec
+
+from .base import BaseAgent
+from ..adapters.react_runtime import create_react_workflow
+from ..logic.builtins import ASK_USER_TOOL
+from ..logic.react import ReActLogic
+
+
+def _tool_definitions_from_callables(tools: List[Callable[..., Any]]) -> List[ToolDefinition]:
+    tool_defs: List[ToolDefinition] = []
+    for t in tools:
+        tool_def = getattr(t, "_tool_definition", None)
+        if tool_def is None:
+            tool_def = ToolDefinition.from_function(t)
+        tool_defs.append(tool_def)
+    return tool_defs
+
+
+def _copy_messages(messages: Any) -> List[Dict[str, Any]]:
+    if not isinstance(messages, list):
+        return []
+    out: List[Dict[str, Any]] = []
+    for m in messages:
+        if isinstance(m, dict):
+            out.append(dict(m))
+    return out
+
+
+class ReactAgent(BaseAgent):
+    """Reason-Act-Observe agent with tool calling."""
+
+    def __init__(
+        self,
+        *,
+        runtime: Runtime,
+        tools: Optional[List[Callable[..., Any]]] = None,
+        on_step: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+        max_iterations: int = 25,
+        max_history_messages: int = -1,
+        max_tokens: Optional[int] = 32768,
+        actor_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ):
+        self._max_iterations = int(max_iterations)
+        if self._max_iterations < 1:
+            self._max_iterations = 1
+        self._max_history_messages = int(max_history_messages)
+        # -1 means unlimited (send all messages), otherwise must be >= 1
+        if self._max_history_messages != -1 and self._max_history_messages < 1:
+            self._max_history_messages = 1
+        self._max_tokens = max_tokens
+
+        self.logic: Optional[ReActLogic] = None
+        super().__init__(
+            runtime=runtime,
+            tools=tools,
+            on_step=on_step,
+            actor_id=actor_id,
+            session_id=session_id,
+        )
+
+    def _create_workflow(self) -> WorkflowSpec:
+        tool_defs = _tool_definitions_from_callables(self.tools)
+        # Built-in ask_user is a schema-only tool (handled via ASK_USER effect in the adapter).
+        tool_defs = [ASK_USER_TOOL, *tool_defs]
+
+        logic = ReActLogic(
+            tools=tool_defs,
+            max_history_messages=self._max_history_messages,
+            max_tokens=self._max_tokens,
+        )
+        self.logic = logic
+        return create_react_workflow(logic=logic, on_step=self.on_step)
+
+    def start(self, task: str) -> str:
+        task = str(task or "").strip()
+        if not task:
+            raise ValueError("task must be a non-empty string")
+
+        vars: Dict[str, Any] = {
+            "context": {"task": task, "messages": _copy_messages(self.session_messages)},
+            "scratchpad": {"iteration": 0, "max_iterations": int(self._max_iterations)},
+            "_runtime": {"inbox": []},
+            "_temp": {},
+            # Canonical _limits namespace for runtime awareness
+            "_limits": {
+                "max_iterations": int(self._max_iterations),
+                "current_iteration": 0,
+                "max_tokens": self._max_tokens,
+                "max_history_messages": int(self._max_history_messages),
+                "estimated_tokens_used": 0,
+                "warn_iterations_pct": 80,
+                "warn_tokens_pct": 80,
+            },
+        }
+
+        run_id = self.runtime.start(
+            workflow=self.workflow,
+            vars=vars,
+            actor_id=self._ensure_actor_id(),
+            session_id=self._ensure_session_id(),
+        )
+        self._current_run_id = run_id
+        return run_id
+
+    def get_limit_status(self) -> Dict[str, Any]:
+        """Get current limit status for the active run.
+
+        Returns a structured dict with information about iterations, tokens,
+        and history limits, including whether warning thresholds are reached.
+
+        Returns:
+            Dict with "iterations", "tokens", and "history" status info,
+            or empty dict if no active run.
+        """
+        if self._current_run_id is None:
+            return {}
+        return self.runtime.get_limit_status(self._current_run_id)
+
+    def update_limits(self, **updates: Any) -> None:
+        """Update limits mid-session.
+
+        Only allowed limit keys are updated; unknown keys are ignored.
+        Allowed keys: max_iterations, max_tokens, max_output_tokens,
+        max_history_messages, warn_iterations_pct, warn_tokens_pct.
+
+        Args:
+            **updates: Limit key-value pairs to update
+
+        Raises:
+            RuntimeError: If no active run
+        """
+        if self._current_run_id is None:
+            raise RuntimeError("No active run. Call start() first.")
+        self.runtime.update_limits(self._current_run_id, updates)
+
+    def step(self) -> RunState:
+        if not self._current_run_id:
+            raise RuntimeError("No active run. Call start() first.")
+        return self.runtime.tick(workflow=self.workflow, run_id=self._current_run_id, max_steps=1)
+
+
+def create_react_agent(
+    *,
+    provider: str = "ollama",
+    model: str = "qwen3:1.7b-q4_K_M",
+    tools: Optional[List[Callable[..., Any]]] = None,
+    on_step: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+    max_iterations: int = 25,
+    max_history_messages: int = -1,
+    max_tokens: Optional[int] = 32768,
+    llm_kwargs: Optional[Dict[str, Any]] = None,
+    run_store: Optional[Any] = None,
+    ledger_store: Optional[Any] = None,
+    actor_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+) -> ReactAgent:
+    """Factory: create a ReactAgent with a local AbstractCore-backed runtime."""
+
+    from abstractruntime.integrations.abstractcore import MappingToolExecutor, create_local_runtime
+
+    if tools is None:
+        from ..tools import ALL_TOOLS as _DEFAULT_TOOLS
+
+        tools = list(_DEFAULT_TOOLS)
+
+    runtime = create_local_runtime(
+        provider=provider,
+        model=model,
+        llm_kwargs=llm_kwargs,
+        run_store=run_store,
+        ledger_store=ledger_store,
+        tool_executor=MappingToolExecutor.from_tools(list(tools)),
+    )
+
+    return ReactAgent(
+        runtime=runtime,
+        tools=list(tools),
+        on_step=on_step,
+        max_iterations=max_iterations,
+        max_history_messages=max_history_messages,
+        max_tokens=max_tokens,
+        actor_id=actor_id,
+        session_id=session_id,
+    )
+
+
+__all__ = [
+    "ReactAgent",
+    "create_react_workflow",
+    "create_react_agent",
+]
+

abstractagent/logic/__init__.py

@@ -0,0 +1,19 @@
+"""Pure agent logic (no runtime imports).
+
+This package contains portable, unit-testable logic for agents. Runtime-specific
+workflow wiring lives under `abstractagent.adapters`.
+"""
+
+from .builtins import ASK_USER_TOOL
+from .codeact import CodeActLogic
+from .react import ReActLogic
+from .types import AskUserAction, FinalAnswer, LLMRequest
+
+__all__ = [
+    "ASK_USER_TOOL",
+    "LLMRequest",
+    "AskUserAction",
+    "FinalAnswer",
+    "ReActLogic",
+    "CodeActLogic",
+]

abstractagent/logic/builtins.py

@@ -0,0 +1,29 @@
+"""Built-in tool specs used by agents.
+
+These are tool *definitions* (schemas), not executable tool callables.
+"""
+
+from __future__ import annotations
+
+from abstractcore.tools import ToolDefinition
+
+ASK_USER_TOOL = ToolDefinition(
+    name="ask_user",
+    description=(
+        "Ask the user a question when you need clarification or input. "
+        "Use this when the task is ambiguous or you need the user to make a choice."
+    ),
+    parameters={
+        "question": {
+            "type": "string",
+            "description": "The question to ask the user (required)",
+        },
+        "choices": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Optional list of choices for the user to pick from",
+        },
+    },
+    when_to_use="When the task is ambiguous or you need user input to proceed",
+)
+

abstractagent/logic/codeact.py

@@ -0,0 +1,166 @@
+"""CodeAct logic (pure; no runtime imports).
+
+CodeAct is a ReAct-like loop where the main action is executing Python code
+instead of calling many specialized tools.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from abstractcore.tools import ToolCall, ToolDefinition
+
+from .types import LLMRequest
+
+_CODE_BLOCK_RE = re.compile(r"```(?:python|py)?\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL)
+
+
+class CodeActLogic:
+    def __init__(
+        self,
+        *,
+        tools: List[ToolDefinition],
+        max_history_messages: int = -1,
+        max_tokens: Optional[int] = None,
+    ):
+        self._tools = list(tools)
+        self._max_history_messages = int(max_history_messages)
+        # -1 means unlimited (send all messages), otherwise must be >= 1
+        if self._max_history_messages != -1 and self._max_history_messages < 1:
+            self._max_history_messages = 1
+        self._max_tokens = max_tokens
+
+    @property
+    def tools(self) -> List[ToolDefinition]:
+        return list(self._tools)
+
+    def build_request(
+        self,
+        *,
+        task: str,
+        messages: List[Dict[str, Any]],
+        guidance: str = "",
+        iteration: int = 1,
+        max_iterations: int = 20,
+        vars: Optional[Dict[str, Any]] = None,
+    ) -> LLMRequest:
+        """Build an LLM request for the CodeAct agent.
+
+        Args:
+            task: The task to perform
+            messages: Conversation history
+            guidance: Optional guidance text to inject
+            iteration: Current iteration number
+            max_iterations: Maximum allowed iterations
+            vars: Optional run.vars dict. If provided, limits are read from
+                  vars["_limits"] (canonical) with fallback to instance defaults.
+        """
+        task = str(task or "")
+        guidance = str(guidance or "").strip()
+
+        # Get limits from vars if available, else use instance defaults
+        limits = (vars or {}).get("_limits", {})
+        max_history = int(limits.get("max_history_messages", self._max_history_messages) or self._max_history_messages)
+        max_tokens = limits.get("max_tokens", self._max_tokens)
+        if max_tokens is not None:
+            max_tokens = int(max_tokens)
+
+        # -1 means unlimited (use all messages)
+        if max_history == -1:
+            history = messages if messages else []
+        else:
+            history = messages[-max_history:] if messages else []
+        history_text = "\n".join(
+            [f"{m.get('role', 'unknown')}: {m.get('content', '')}" for m in history]
+        )
+
+        prompt = (
+            "You are CodeAct: you can solve tasks by writing and executing Python code.\n"
+            "Use the tool `execute_python` to run Python snippets. Prefer small, focused scripts.\n"
+            "Print any intermediate results you need.\n"
+            "When you are confident, provide the final answer without calling tools.\n\n"
+            f"Iteration: {int(iteration)}/{int(max_iterations)}\n\n"
+            f"Task: {task}\n\n"
+        )
+        if history_text:
+            prompt += f"History:\n{history_text}\n\n"
+
+        if guidance:
+            prompt += f"[User guidance]: {guidance}\n\n"
+
+        prompt += (
+            "If you need to run code, either:\n"
+            "- Call `execute_python` with the Python code, or\n"
+            "- If tool calling is unavailable, include a fenced ```python code block.\n"
+        )
+
+        return LLMRequest(prompt=prompt, tools=self.tools, max_tokens=max_tokens)
+
+    def parse_response(self, response: Any) -> Tuple[str, List[ToolCall]]:
+        if not isinstance(response, dict):
+            return "", []
+
+        content = response.get("content")
+        content = "" if content is None else str(content)
+
+        tool_calls_raw = response.get("tool_calls") or []
+        tool_calls: List[ToolCall] = []
+        if isinstance(tool_calls_raw, list):
+            for tc in tool_calls_raw:
+                if isinstance(tc, ToolCall):
+                    tool_calls.append(tc)
+                    continue
+                if isinstance(tc, dict):
+                    name = str(tc.get("name", "") or "")
+                    args = tc.get("arguments", {})
+                    call_id = tc.get("call_id")
+                    if isinstance(args, dict):
+                        tool_calls.append(ToolCall(name=name, arguments=dict(args), call_id=call_id))
+
+        # FALLBACK: Parse from content if no native tool calls
+        # Handles <|tool_call|>, <function_call>, ```tool_code, etc.
+        if not tool_calls and content:
+            from abstractcore.tools.parser import parse_tool_calls, detect_tool_calls
+            if detect_tool_calls(content):
+                # Pass model name for architecture-specific parsing
+                model_name = response.get("model")
+                tool_calls = parse_tool_calls(content, model_name=model_name)
+
+        return content, tool_calls
+
+    def extract_code(self, text: str) -> str | None:
+        text = str(text or "")
+        m = _CODE_BLOCK_RE.search(text)
+        if not m:
+            return None
+        code = m.group(1).strip("\n")
+        return code.strip() or None
+
+    def format_observation(self, *, name: str, output: Any, success: bool) -> str:
+        if name != "execute_python":
+            out = "" if output is None else str(output)
+            return f"[{name}]: {out}" if success else f"[{name}]: Error: {out}"
+
+        if not isinstance(output, dict):
+            out = "" if output is None else str(output)
+            return f"[execute_python]: {out}" if success else f"[execute_python]: Error: {out}"
+
+        stdout = str(output.get("stdout") or "")
+        stderr = str(output.get("stderr") or "")
+        exit_code = output.get("exit_code")
+        error = output.get("error")
+
+        parts: List[str] = []
+        if error:
+            parts.append(f"error={error}")
+        if exit_code is not None:
+            parts.append(f"exit_code={exit_code}")
+        if stdout:
+            parts.append("stdout:\n" + stdout)
+        if stderr:
+            parts.append("stderr:\n" + stderr)
+
+        rendered = "\n".join(parts).strip() or "(no output)"
+        return f"[execute_python]: {rendered}"
+

abstractagent/logic/react.py

@@ -0,0 +1,126 @@
+"""ReAct logic (pure; no runtime imports)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from abstractcore.tools import ToolCall, ToolDefinition
+
+from .types import LLMRequest
+
+
+class ReActLogic:
+    def __init__(
+        self,
+        *,
+        tools: List[ToolDefinition],
+        max_history_messages: int = -1,
+        max_tokens: Optional[int] = None,
+    ):
+        self._tools = list(tools)
+        self._max_history_messages = int(max_history_messages)
+        # -1 means unlimited (send all messages), otherwise must be >= 1
+        if self._max_history_messages != -1 and self._max_history_messages < 1:
+            self._max_history_messages = 1
+        self._max_tokens = max_tokens
+
+    @property
+    def tools(self) -> List[ToolDefinition]:
+        return list(self._tools)
+
+    def build_request(
+        self,
+        *,
+        task: str,
+        messages: List[Dict[str, Any]],
+        guidance: str = "",
+        iteration: int = 1,
+        max_iterations: int = 20,
+        vars: Optional[Dict[str, Any]] = None,
+    ) -> LLMRequest:
+        """Build an LLM request for the ReAct agent.
+
+        Args:
+            task: The task to perform
+            messages: Conversation history
+            guidance: Optional guidance text to inject
+            iteration: Current iteration number
+            max_iterations: Maximum allowed iterations
+            vars: Optional run.vars dict. If provided, limits are read from
+                  vars["_limits"] (canonical) with fallback to instance defaults.
+        """
+        task = str(task or "")
+        guidance = str(guidance or "").strip()
+
+        # Get limits from vars if available, else use instance defaults
+        limits = (vars or {}).get("_limits", {})
+        max_history = int(limits.get("max_history_messages", self._max_history_messages) or self._max_history_messages)
+        max_tokens = limits.get("max_tokens", self._max_tokens)
+        if max_tokens is not None:
+            max_tokens = int(max_tokens)
+
+        if len(messages) <= 1:
+            prompt = (
+                f"Task: {task}\n\n"
+                "Use the available tools to complete this task. When done, provide your final answer."
+            )
+        else:
+            # -1 means unlimited (use all messages)
+            if max_history == -1:
+                history = messages
+            else:
+                history = messages[-max_history:]
+            history_text = "\n".join(
+                [f"{m.get('role', 'unknown')}: {m.get('content', '')}" for m in history]
+            )
+            prompt = (
+                "You have access to the conversation history below as context.\n"
+                "Do not claim you have no memory of it; it is provided to you here.\n\n"
+                f"Iteration: {int(iteration)}/{int(max_iterations)}\n\n"
+                f"History:\n{history_text}\n\n"
+                "Continue the conversation and work on the user's latest request.\n"
+                "Use tools when needed, or provide a final answer."
+            )
+
+        if guidance:
+            prompt += "\n\n[User guidance]: " + guidance
+
+        return LLMRequest(prompt=prompt, tools=self.tools, max_tokens=max_tokens)
+
+    def parse_response(self, response: Any) -> Tuple[str, List[ToolCall]]:
+        if not isinstance(response, dict):
+            return "", []
+
+        content = response.get("content")
+        content = "" if content is None else str(content)
+
+        tool_calls_raw = response.get("tool_calls") or []
+        tool_calls: List[ToolCall] = []
+        if isinstance(tool_calls_raw, list):
+            for tc in tool_calls_raw:
+                if isinstance(tc, ToolCall):
+                    tool_calls.append(tc)
+                    continue
+                if isinstance(tc, dict):
+                    name = str(tc.get("name", "") or "")
+                    args = tc.get("arguments", {})
+                    call_id = tc.get("call_id")
+                    if isinstance(args, dict):
+                        tool_calls.append(ToolCall(name=name, arguments=dict(args), call_id=call_id))
+
+        # FALLBACK: Parse from content if no native tool calls
+        # Handles <|tool_call|>, <function_call>, ```tool_code, etc.
+        if not tool_calls and content:
+            from abstractcore.tools.parser import parse_tool_calls, detect_tool_calls
+            if detect_tool_calls(content):
+                # Pass model name for architecture-specific parsing
+                model_name = response.get("model")
+                tool_calls = parse_tool_calls(content, model_name=model_name)
+
+        return content, tool_calls
+
+    def format_observation(self, *, name: str, output: str, success: bool) -> str:
+        if success:
+            return f"[{name}]: {output}"
+        return f"[{name}]: Error: {output}"
+

abstractagent/logic/types.py

@@ -0,0 +1,30 @@
+"""Pure logic types shared across agents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from abstractcore.tools import ToolDefinition
+
+
+@dataclass(frozen=True)
+class LLMRequest:
+    """What to ask the LLM (portable; runtime-agnostic)."""
+
+    prompt: str
+    tools: List[ToolDefinition]
+    system_prompt: Optional[str] = None
+    max_tokens: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class AskUserAction:
+    question: str
+    choices: Optional[List[str]] = None
+
+
+@dataclass(frozen=True)
+class FinalAnswer:
+    content: str
+