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

abstractagent/agents/react.py

@@ -15,11 +15,20 @@ 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,
+    DELEGATE_AGENT_TOOL,
+    INSPECT_VARS_TOOL,
+    OPEN_ATTACHMENT_TOOL,
+    RECALL_MEMORY_TOOL,
+    REMEMBER_TOOL,
+    REMEMBER_NOTE_TOOL,
+)
 from ..logic.react import ReActLogic
 
 
@@ -54,7 +63,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 +78,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 +96,17 @@ 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,
+            OPEN_ATTACHMENT_TOOL,
+            RECALL_MEMORY_TOOL,
+            INSPECT_VARS_TOOL,
+            REMEMBER_TOOL,
+            REMEMBER_NOTE_TOOL,
+            COMPACT_MEMORY_TOOL,
+            DELEGATE_AGENT_TOOL,
+            *tool_defs,
+        ]
 
         logic = ReActLogic(
             tools=tool_defs,
@@ -89,27 +116,103 @@ 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,
+        temperature: Optional[float] = None,
+        seed: Optional[int] = None,
+        attachments: Optional[List[Any]] = 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
+        # ReAct output-token capping is controlled via `_limits.max_output_tokens`.
+        # Policy: unset by default (None) to avoid artificial truncation.
+        try:
+            max_output_tokens_override = int(self._max_tokens) if self._max_tokens is not None else None
+        except Exception:
+            max_output_tokens_override = None
+        if isinstance(max_output_tokens_override, int) and max_output_tokens_override > 0:
+            limits["max_output_tokens"] = max_output_tokens_override
+        else:
+            limits.setdefault("max_output_tokens", None)
+
         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 attachments:
+            items: list[Any]
+            if isinstance(attachments, tuple):
+                items = list(attachments)
+            else:
+                items = attachments if isinstance(attachments, list) else []
+            normalized: list[Any] = []
+            for item in items:
+                if isinstance(item, str) and item.strip():
+                    normalized.append(item.strip())
+                    continue
+                if isinstance(item, dict):
+                    aid = item.get("$artifact")
+                    if not (isinstance(aid, str) and aid.strip()):
+                        aid = item.get("artifact_id")
+                    if isinstance(aid, str) and aid.strip():
+                        normalized.append(dict(item))
+            if normalized:
+                vars["context"]["attachments"] = normalized
+        if temperature is not None:
+            try:
+                vars["_runtime"]["temperature"] = float(temperature)
+            except Exception:
+                pass
+        if seed is not None:
+            try:
+                vars["_runtime"]["seed"] = int(seed)
+            except Exception:
+                pass
+        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 +257,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 +271,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 +306,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 +319,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,276 @@ 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.",
+)
+
+OPEN_ATTACHMENT_TOOL = ToolDefinition(
+    name="open_attachment",
+    description="Read an attachment (artifact) from the current session with bounded output.",
+    parameters={
+        "artifact_id": {"type": "string", "description": "Attachment artifact id (preferred).", "default": None},
+        "handle": {"type": "string", "description": "Attachment handle (usually '@path').", "default": None},
+        "expected_sha256": {"type": "string", "description": "Optional sha256 to disambiguate versions.", "default": None},
+        "start_line": {"type": "integer", "description": "1-based start line (default 1).", "default": 1},
+        "end_line": {"type": "integer", "description": "Optional end line (inclusive).", "default": None},
+        "max_chars": {"type": "integer", "description": "Maximum characters to return (default 8000).", "default": 8000},
+    },
+    when_to_use=(
+        "Use only to open stored (non-active) session attachments or to fetch a bounded, line-numbered excerpt when the "
+        "attachment is not already provided in this call. Prefer artifact_id when available; otherwise use handle."
+    ),
+)
+
+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",
+        },
+        "recall_level": {
+            "type": "string",
+            "enum": ["urgent", "standard", "deep"],
+            "description": (
+                "Optional recall effort policy.\n"
+                "- urgent: fastest, tight budgets\n"
+                "- standard: bounded but more thorough\n"
+                "- deep: may be slow/expensive\n"
+                "No silent downgrade: budgets/permissions are enforced by the runtime."
+            ),
+            "default": None,
         },
     },
-    when_to_use="When the task is ambiguous or you need user input to proceed",
+    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 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.",
+)
+
+DELEGATE_AGENT_TOOL = ToolDefinition(
+    name="delegate_agent",
+    description="Delegate a subtask to a fresh agent run with smaller context and restricted tools.",
+    parameters={
+        "task": {
+            "type": "string",
+            "description": "The delegated task (required). Keep it specific and self-contained.",
+        },
+        "context": {
+            "type": "string",
+            "description": "Minimal supporting context for the delegated task (optional).",
+            "default": "",
+        },
+        "tools": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": (
+                "Tool allowlist for the delegated agent (optional). "
+                "When omitted, the delegated agent inherits the current allowlist."
+            ),
+            "default": None,
+        },
+    },
+    when_to_use=(
+        "Use when you can split off a subtask that can be completed with a small context (e.g., "
+        "inspect a few files, search for specific symbols, summarize findings)."
+    ),
+)