abstractagent 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

abstractagent/agents/react.py

@@ -15,11 +15,18 @@ from __future__ import annotations
 from typing import Any, Callable, Dict, List, Optional
 
 from abstractcore.tools import ToolDefinition
-from abstractruntime import RunState, Runtime, WorkflowSpec
+from abstractruntime import RunState, RunStatus, Runtime, WorkflowSpec
 
 from .base import BaseAgent
 from ..adapters.react_runtime import create_react_workflow
-from ..logic.builtins import ASK_USER_TOOL
+from ..logic.builtins import (
+    ASK_USER_TOOL,
+    COMPACT_MEMORY_TOOL,
+    INSPECT_VARS_TOOL,
+    RECALL_MEMORY_TOOL,
+    REMEMBER_TOOL,
+    REMEMBER_NOTE_TOOL,
+)
 from ..logic.react import ReActLogic
 
 
@@ -54,7 +61,10 @@ class ReactAgent(BaseAgent):
         on_step: Optional[Callable[[str, Dict[str, Any]], None]] = None,
         max_iterations: int = 25,
         max_history_messages: int = -1,
-        max_tokens: Optional[int] = 32768,
+        max_tokens: Optional[int] = None,
+        plan_mode: bool = False,
+        review_mode: bool = True,
+        review_max_rounds: int = 3,
         actor_id: Optional[str] = None,
         session_id: Optional[str] = None,
     ):
@@ -66,6 +76,11 @@ class ReactAgent(BaseAgent):
         if self._max_history_messages != -1 and self._max_history_messages < 1:
             self._max_history_messages = 1
         self._max_tokens = max_tokens
+        self._plan_mode = bool(plan_mode)
+        self._review_mode = bool(review_mode)
+        self._review_max_rounds = int(review_max_rounds)
+        if self._review_max_rounds < 0:
+            self._review_max_rounds = 0
 
         self.logic: Optional[ReActLogic] = None
         super().__init__(
@@ -79,7 +94,15 @@ class ReactAgent(BaseAgent):
     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]
+        tool_defs = [
+            ASK_USER_TOOL,
+            RECALL_MEMORY_TOOL,
+            INSPECT_VARS_TOOL,
+            REMEMBER_TOOL,
+            REMEMBER_NOTE_TOOL,
+            COMPACT_MEMORY_TOOL,
+            *tool_defs,
+        ]
 
         logic = ReActLogic(
             tools=tool_defs,
@@ -89,27 +112,69 @@ class ReactAgent(BaseAgent):
         self.logic = logic
         return create_react_workflow(logic=logic, on_step=self.on_step)
 
-    def start(self, task: str) -> str:
+    def start(
+        self,
+        task: str,
+        *,
+        plan_mode: Optional[bool] = None,
+        review_mode: Optional[bool] = None,
+        review_max_rounds: Optional[int] = None,
+        allowed_tools: Optional[List[str]] = None,
+    ) -> str:
         task = str(task or "").strip()
         if not task:
             raise ValueError("task must be a non-empty string")
 
+        eff_plan_mode = self._plan_mode if plan_mode is None else bool(plan_mode)
+        eff_review_mode = self._review_mode if review_mode is None else bool(review_mode)
+        eff_review_max_rounds = self._review_max_rounds if review_max_rounds is None else int(review_max_rounds)
+        if eff_review_max_rounds < 0:
+            eff_review_max_rounds = 0
+
+        # Base limits come from the Runtime config so model capabilities (max context)
+        # are respected by default, unless explicitly overridden by the agent/session.
+        try:
+            base_limits = dict(self.runtime.config.to_limits_dict())
+        except Exception:
+            base_limits = {}
+        limits: Dict[str, Any] = dict(base_limits)
+        limits.setdefault("warn_iterations_pct", 80)
+        limits.setdefault("warn_tokens_pct", 80)
+        limits["max_iterations"] = int(self._max_iterations)
+        limits["current_iteration"] = 0
+        limits["max_history_messages"] = int(self._max_history_messages)
+        # Message-size guards for LLM-visible context (character-level).
+        # These are applied when building the provider payload; the durable run history
+        # still preserves full message text.
+        # Disabled by default (-1): enable by setting a positive character budget.
+        limits.setdefault("max_message_chars", -1)
+        limits.setdefault("max_tool_message_chars", -1)
+        limits["estimated_tokens_used"] = 0
+        try:
+            max_tokens_override = int(self._max_tokens) if self._max_tokens is not None else None
+        except Exception:
+            max_tokens_override = None
+        if isinstance(max_tokens_override, int) and max_tokens_override > 0:
+            limits["max_tokens"] = max_tokens_override
+        if not isinstance(limits.get("max_tokens"), int) or int(limits.get("max_tokens") or 0) <= 0:
+            limits["max_tokens"] = 32768
+
         vars: Dict[str, Any] = {
             "context": {"task": task, "messages": _copy_messages(self.session_messages)},
             "scratchpad": {"iteration": 0, "max_iterations": int(self._max_iterations)},
-            "_runtime": {"inbox": []},
+            "_runtime": {
+                "inbox": [],
+                "plan_mode": eff_plan_mode,
+                "review_mode": eff_review_mode,
+                "review_max_rounds": eff_review_max_rounds,
+            },
             "_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,
-            },
+            "_limits": limits,
         }
+        if isinstance(allowed_tools, list):
+            normalized = [str(t).strip() for t in allowed_tools if isinstance(t, str) and t.strip()]
+            vars["_runtime"]["allowed_tools"] = normalized
 
         run_id = self.runtime.start(
             workflow=self.workflow,
@@ -154,7 +219,10 @@ class ReactAgent(BaseAgent):
     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)
+        state = self.runtime.tick(workflow=self.workflow, run_id=self._current_run_id, max_steps=1)
+        if state.status in (RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.CANCELLED):
+            self._sync_session_caches_from_state(state)
+        return state
 
 
 def create_react_agent(
@@ -165,7 +233,10 @@ def create_react_agent(
     on_step: Optional[Callable[[str, Dict[str, Any]], None]] = None,
     max_iterations: int = 25,
     max_history_messages: int = -1,
-    max_tokens: Optional[int] = 32768,
+    max_tokens: Optional[int] = None,
+    plan_mode: bool = False,
+    review_mode: bool = True,
+    review_max_rounds: int = 3,
     llm_kwargs: Optional[Dict[str, Any]] = None,
     run_store: Optional[Any] = None,
     ledger_store: Optional[Any] = None,
@@ -197,6 +268,9 @@ def create_react_agent(
         max_iterations=max_iterations,
         max_history_messages=max_history_messages,
         max_tokens=max_tokens,
+        plan_mode=plan_mode,
+        review_mode=review_mode,
+        review_max_rounds=review_max_rounds,
         actor_id=actor_id,
         session_id=session_id,
     )
@@ -207,4 +281,3 @@ __all__ = [
     "create_react_workflow",
     "create_react_agent",
 ]
-

abstractagent/logic/__init__.py

@@ -6,6 +6,7 @@ workflow wiring lives under `abstractagent.adapters`.
 
 from .builtins import ASK_USER_TOOL
 from .codeact import CodeActLogic
+from .memact import MemActLogic
 from .react import ReActLogic
 from .types import AskUserAction, FinalAnswer, LLMRequest
 
@@ -16,4 +17,5 @@ __all__ = [
     "FinalAnswer",
     "ReActLogic",
     "CodeActLogic",
+    "MemActLogic",
 ]

abstractagent/logic/builtins.py

@@ -9,10 +9,7 @@ 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."
-    ),
+    description="Ask the user a question.",
     parameters={
         "question": {
             "type": "string",
@@ -22,8 +19,218 @@ ASK_USER_TOOL = ToolDefinition(
             "type": "array",
             "items": {"type": "string"},
             "description": "Optional list of choices for the user to pick from",
+            "default": None,
+        },
+    },
+    when_to_use="Use when the task is ambiguous or you need user input to proceed.",
+)
+
+RECALL_MEMORY_TOOL = ToolDefinition(
+    name="recall_memory",
+    description="Recall archived memory spans with provenance (by span_id/query/tags/time range).",
+    parameters={
+        "span_id": {
+            "type": "string",
+            "description": (
+                "Optional span identifier (artifact id) or 1-based index into archived spans. "
+                "If a summary includes span_id=..., use that exact value."
+            ),
+            "default": None,
+        },
+        "query": {
+            "type": "string",
+            "description": "Optional keyword query (topic/person/etc). Performs metadata-first search with bounded deep scan over archived messages.",
+            "default": None,
+        },
+        "since": {
+            "type": "string",
+            "description": "Optional ISO8601 start timestamp for time-range filtering.",
+            "default": None,
+        },
+        "until": {
+            "type": "string",
+            "description": "Optional ISO8601 end timestamp for time-range filtering.",
+            "default": None,
+        },
+        "tags": {
+            "type": "object",
+            "description": (
+                "Optional metadata tag filters.\n"
+                "- Values may be a string or a list of strings.\n"
+                "- Example: {\"topic\":\"api\",\"person\":[\"alice\",\"bob\"]}\n"
+                "Use tags_mode to control AND/OR across tag keys."
+            ),
+            "default": None,
+        },
+        "tags_mode": {
+            "type": "string",
+            "description": (
+                "How to combine tag keys: all (AND across keys) | any (OR across keys). "
+                "Within a key, list values are treated as OR."
+            ),
+            "default": "all",
+        },
+        "usernames": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": (
+                "Optional author filter (actor ids / usernames). Matches spans created_by case-insensitively. "
+                "Semantics: OR (any listed author)."
+            ),
+            "default": None,
+        },
+        "locations": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": (
+                "Optional location filter. Matches spans by explicit location metadata (or tags.location). "
+                "Semantics: OR (any listed location)."
+            ),
+            "default": None,
+        },
+        "limit_spans": {
+            "type": "integer",
+            "description": "Maximum number of spans to return (default 5).",
+            "default": 5,
+        },
+        "connected": {
+            "type": "boolean",
+            "description": "If true, also include connected spans (time neighbors and shared-tag neighbors).",
+            "default": False,
+        },
+        "neighbor_hops": {
+            "type": "integer",
+            "description": "When connected=true, include up to this many neighbor spans on each side (default 1).",
+            "default": 1,
+        },
+        "max_messages": {
+            "type": "integer",
+            "description": "Maximum total messages to render in the recall output across all spans (-1 = no truncation).",
+            "default": -1,
+        },
+        "scope": {
+            "type": "string",
+            "description": "Memory scope to query: run | session | global | all (default run).",
+            "default": "run",
+        },
+    },
+    when_to_use="Use after compaction or when you need exact details from earlier context.",
+)
+
+INSPECT_VARS_TOOL = ToolDefinition(
+    name="inspect_vars",
+    description="Inspect durable run-state variables by path (e.g., scratchpad/runtime vars).",
+    parameters={
+        "path": {
+            "type": "string",
+            "description": (
+                "Path to inspect (default 'scratchpad'). Supports dot paths like 'scratchpad.foo[0]' "
+                "or JSON pointer paths like '/scratchpad/foo/0'."
+            ),
+            "default": "scratchpad",
+        },
+        "keys_only": {
+            "type": "boolean",
+            "description": "If true, return keys/length instead of the full value (useful to navigate large objects).",
+            "default": False,
+        },
+        "target_run_id": {
+            "type": "string",
+            "description": "Optional run id to inspect (defaults to the current run).",
+            "default": None,
+        },
+    },
+    when_to_use=(
+        "Use to debug or inspect scratchpad/runtime vars (prefer keys_only=true first)."
+    ),
+)
+
+REMEMBER_TOOL = ToolDefinition(
+    name="remember",
+    description="Tag an archived memory span for later recall.",
+    parameters={
+        "span_id": {
+            "type": "string",
+            "description": (
+                "Span identifier (artifact id) or 1-based index into archived spans. "
+                "If a summary includes span_id=..., use that exact value."
+            ),
+        },
+        "tags": {
+            "type": "object",
+            "description": (
+                "Tags to set on the span (JSON-safe dict[str,str]), e.g. {\"topic\":\"api\",\"person\":\"alice\"}. "
+                "At least one tag is required."
+            ),
+        },
+        "merge": {
+            "type": "boolean",
+            "description": "If true (default), merges tags into existing tags. If false, replaces existing tags.",
+            "default": True,
+        },
+    },
+    when_to_use=(
+        "Use when you want to label a recalled/compacted span with durable tags."
+    ),
+)
+
+REMEMBER_NOTE_TOOL = ToolDefinition(
+    name="remember_note",
+    description="Store a durable memory note (decision/fact) with optional tags and sources.",
+    parameters={
+        "note": {
+            "type": "string",
+            "description": "The note to remember (required). Keep it short and specific.",
+        },
+        "tags": {
+            "type": "object",
+            "description": "Optional tags (dict[str,str]) to help recall later, e.g. {\"topic\":\"api\",\"person\":\"alice\"}.",
+            "default": None,
+        },
+        "sources": {
+            "type": "object",
+            "description": (
+                "Optional provenance sources for this note. Use span_ids/message_ids when available.\n"
+                "Example: {\"span_ids\":[\"span_...\"], \"message_ids\":[\"msg_...\"]}"
+            ),
+            "default": None,
+        },
+        "location": {
+            "type": "string",
+            "description": "Optional location for this memory note (user perspective).",
+            "default": None,
+        },
+        "scope": {
+            "type": "string",
+            "description": "Where to store this note: run | session | global (default run).",
+            "default": "run",
         },
     },
-    when_to_use="When the task is ambiguous or you need user input to proceed",
+    when_to_use=(
+        "When you want to persist a key insight/decision/fact for later recall by time/topic/person, "
+        "especially before any compaction span exists."
+    ),
 )
 
+COMPACT_MEMORY_TOOL = ToolDefinition(
+    name="compact_memory",
+    description="Compact older conversation context into an archived span and insert a summary handle.",
+    parameters={
+        "preserve_recent": {
+            "type": "integer",
+            "description": "Number of most recent non-system messages to keep verbatim (default 6).",
+            "default": 6,
+        },
+        "compression_mode": {
+            "type": "string",
+            "description": "Compression mode: light | standard | heavy (default standard).",
+            "default": "standard",
+        },
+        "focus": {
+            "type": "string",
+            "description": "Optional focus/topic to prioritize in the summary.",
+            "default": None,
+        },
+    },
+    when_to_use="Use when the active context is too large and you need to reduce it while keeping provenance.",
+)

abstractagent/logic/codeact.py

@@ -1,7 +1,11 @@
 """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.
+This module implements a conventional CodeAct loop:
+- the model primarily acts by producing Python code (or calling execute_python)
+- tool results are appended to chat history
+- the model iterates until it can answer directly
+
+CodeAct is intentionally *not* a memory-enhanced agent.
 """
 
 from __future__ import annotations
@@ -26,7 +30,6 @@ class CodeActLogic:
     ):
         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
@@ -35,6 +38,23 @@ class CodeActLogic:
     def tools(self) -> List[ToolDefinition]:
         return list(self._tools)
 
+    def add_tools(self, tools: List[ToolDefinition]) -> int:
+        if not isinstance(tools, list) or not tools:
+            return 0
+
+        existing = {str(t.name) for t in self._tools if getattr(t, "name", None)}
+        added = 0
+        for t in tools:
+            name = getattr(t, "name", None)
+            if not isinstance(name, str) or not name.strip():
+                continue
+            if name in existing:
+                continue
+            self._tools.append(t)
+            existing.add(name)
+            added += 1
+        return added
+
     def build_request(
         self,
         *,
@@ -45,58 +65,70 @@ class CodeActLogic:
         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.
-        """
+        _ = messages  # history is carried out-of-band via chat messages
+
         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"
+        max_output_tokens = limits.get("max_output_tokens", None)
+        if max_output_tokens is not None:
+            try:
+                max_output_tokens = int(max_output_tokens)
+            except Exception:
+                max_output_tokens = None
+
+        runtime_ns = (vars or {}).get("_runtime", {})
+        scratchpad = (vars or {}).get("scratchpad", {})
+        plan_mode = bool(runtime_ns.get("plan_mode")) if isinstance(runtime_ns, dict) else False
+        plan_text = scratchpad.get("plan") if isinstance(scratchpad, dict) else None
+        plan = str(plan_text).strip() if isinstance(plan_text, str) and plan_text.strip() else ""
+
+        prompt = task.strip()
+
+        output_budget_line = ""
+        if isinstance(max_output_tokens, int) and max_output_tokens > 0:
+            output_budget_line = f"- Output token limit for this response: {max_output_tokens}.\n"
+
+        system_prompt = (
             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"
+            "You are CodeAct: you solve tasks by writing and executing Python when needed.\n\n"
+            "Evidence & action (IMPORTANT):\n"
+            "- Be truthful: only claim actions supported by tool outputs.\n"
+            "- If the task requires code execution or file edits, do it now (call a tool or output a fenced ```python``` block).\n"
+            "- Do not “announce” actions without executing them.\n\n"
+            "Rules:\n"
+            "- Be truthful: only claim actions supported by tool outputs.\n"
+            "- Be autonomous: do not ask the user for confirmation to proceed; keep going until the task is done.\n"
+            "- If you need to run code, call `execute_python` (preferred) or output a fenced ```python code block.\n"
+            "- Never fabricate tool outputs.\n"
+            "- Only ask the user a question when required information is missing.\n"
+            f"{output_budget_line}"
+        ).strip()
 
         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"
+            system_prompt = (system_prompt + "\n\nGuidance:\n" + guidance).strip()
+
+        if plan_mode and plan:
+            system_prompt = (system_prompt + "\n\nCurrent plan:\n" + plan).strip()
+
+        if plan_mode:
+            system_prompt = (
+                system_prompt
+                + "\n\nPlan mode:\n"
+                "- Maintain and update the plan as you work.\n"
+                "- If the plan changes, include a final section at the END of your message:\n"
+                "  Plan Update:\n"
+                "  <markdown checklist>\n"
+            ).strip()
+
+        return LLMRequest(
+            prompt=prompt,
+            system_prompt=system_prompt,
+            tools=self.tools,
+            max_tokens=max_output_tokens,
         )
 
-        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 "", []
@@ -104,6 +136,11 @@ class CodeActLogic:
         content = response.get("content")
         content = "" if content is None else str(content)
 
+        if not content.strip():
+            reasoning = response.get("reasoning")
+            if isinstance(reasoning, str) and reasoning.strip():
+                content = reasoning.strip()
+
         tool_calls_raw = response.get("tool_calls") or []
         tool_calls: List[ToolCall] = []
         if isinstance(tool_calls_raw, list):
@@ -118,15 +155,6 @@ class CodeActLogic:
                     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:
@@ -138,29 +166,8 @@ class CodeActLogic:
         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}"
+        out = "" if output is None else str(output)
+        if success:
+            return f"[{name}]: {out}"
+        return f"[{name}]: Error: {out}"