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

abstractagent/agents/base.py

@@ -49,11 +49,42 @@ class BaseAgent(ABC):
         self.tools = tools or []
         self.on_step = on_step
         self.workflow = self._create_workflow()
+        self._ensure_workflow_registered()
         self._current_run_id: Optional[str] = None
         self.actor_id: Optional[str] = actor_id
         self.session_id: Optional[str] = session_id
         self.session_messages: List[Dict[str, Any]] = []
 
+    def _ensure_workflow_registered(self) -> None:
+        """Ensure this agent's workflow is registered for subworkflow composition.
+
+        START_SUBWORKFLOW requires a runtime workflow_registry. Registering here keeps
+        agent-created runtimes usable for delegation/subflows without extra host wiring.
+        """
+        try:
+            wf = getattr(self, "workflow", None)
+            wid = getattr(wf, "workflow_id", None)
+            if not isinstance(wid, str) or not wid.strip():
+                return
+
+            reg = getattr(self.runtime, "workflow_registry", None)
+            if reg is None:
+                from abstractruntime.scheduler.registry import WorkflowRegistry
+
+                reg = WorkflowRegistry()
+                setter = getattr(self.runtime, "set_workflow_registry", None)
+                if callable(setter):
+                    setter(reg)
+            getter = getattr(reg, "get", None)
+            if callable(getter) and getter(wid) is not None:
+                return
+            register = getattr(reg, "register", None)
+            if callable(register):
+                register(wf)
+        except Exception:
+            # Never block agent creation due to registry wiring; hosts can still inject their own registry.
+            return
+
     def _sync_session_caches_from_state(self, state: Optional[RunState]) -> None:
         if state is None or not hasattr(state, "vars") or not isinstance(state.vars, dict):
             return

abstractagent/agents/codeact.py

@@ -12,7 +12,9 @@ from ..adapters.codeact_runtime import create_codeact_workflow
 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,
@@ -85,11 +87,13 @@ class CodeActAgent(BaseAgent):
         tool_defs = _tool_definitions_from_callables(self.tools)
         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 = CodeActLogic(
@@ -108,6 +112,9 @@ class CodeActAgent(BaseAgent):
         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:
@@ -158,9 +165,38 @@ class CodeActAgent(BaseAgent):
             # Canonical _limits namespace for runtime awareness
             "_limits": limits,
         }
+        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
+        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
 
         run_id = self.runtime.start(
             workflow=self.workflow,

abstractagent/agents/memact.py

@@ -17,7 +17,9 @@ from ..adapters.memact_runtime import create_memact_workflow
 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,
@@ -97,11 +99,13 @@ class MemActAgent(BaseAgent):
         tool_defs = _tool_definitions_from_callables(self.tools)
         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 = MemActLogic(
@@ -131,6 +135,9 @@ class MemActAgent(BaseAgent):
         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:
@@ -168,6 +175,16 @@ class MemActAgent(BaseAgent):
             "review_mode": eff_review_mode,
             "review_max_rounds": eff_review_max_rounds,
         }
+        if temperature is not None:
+            try:
+                runtime_ns["temperature"] = float(temperature)
+            except Exception:
+                pass
+        if seed is not None:
+            try:
+                runtime_ns["seed"] = int(seed)
+            except Exception:
+                pass
         if isinstance(self.session_active_memory, dict):
             runtime_ns["active_memory"] = _deepcopy_json(self.session_active_memory)
         if isinstance(allowed_tools, list):
@@ -181,6 +198,25 @@ class MemActAgent(BaseAgent):
             "_temp": {},
             "_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
 
         run_id = self.runtime.start(
             workflow=self.workflow,
@@ -228,7 +264,7 @@ def create_memact_agent(
         provider=provider,
         model=model,
         llm_kwargs=llm_kwargs,
-        tools=MappingToolExecutor.from_tools(tools),
+        tool_executor=MappingToolExecutor.from_tools(list(tools)),
         run_store=run_store,
         ledger_store=ledger_store,
     )

abstractagent/agents/react.py

@@ -22,7 +22,9 @@ from ..adapters.react_runtime import create_react_workflow
 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,
@@ -96,11 +98,13 @@ class ReactAgent(BaseAgent):
         # Built-in ask_user is a schema-only tool (handled via ASK_USER effect in the adapter).
         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,
         ]
 
@@ -120,6 +124,9 @@ class ReactAgent(BaseAgent):
         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:
@@ -150,14 +157,16 @@ class ReactAgent(BaseAgent):
         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_tokens_override = int(self._max_tokens) if self._max_tokens is not None else None
+            max_output_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
+            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)},
@@ -172,6 +181,35 @@ class ReactAgent(BaseAgent):
             # Canonical _limits namespace for runtime awareness
             "_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

abstractagent/logic/builtins.py

@@ -25,6 +25,23 @@ ASK_USER_TOOL = ToolDefinition(
     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).",
@@ -113,6 +130,18 @@ RECALL_MEMORY_TOOL = ToolDefinition(
             "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="Use after compaction or when you need exact details from earlier context.",
 )
@@ -234,3 +263,32 @@ COMPACT_MEMORY_TOOL = ToolDefinition(
     },
     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)."
+    ),
+)

abstractagent/logic/codeact.py

@@ -101,6 +101,10 @@ class CodeActLogic:
             "- 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"
+            "- Efficiency: batch independent read-only tool calls into a single turn (multiple tool calls) to reduce iterations.\n"
+            "  Examples: read_file for multiple files/ranges, search_files with different queries, list_files across folders, analyze_code on multiple targets.\n"
+            "  Only split tool calls across turns when later calls depend on earlier outputs; avoid batching side-effectful tools (write/edit/execute).\n"
+            "- When context is getting large, use delegate_agent(task, context, tools) to offload an independent subtask with minimal context.\n"
             "- Never fabricate tool outputs.\n"
             "- Only ask the user a question when required information is missing.\n"
             f"{output_budget_line}"
@@ -170,4 +174,3 @@ class CodeActLogic:
         if success:
             return f"[{name}]: {out}"
         return f"[{name}]: Error: {out}"
-

abstractagent/logic/memact.py

@@ -72,6 +72,8 @@ class MemActLogic:
             "- 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 create/edit files, run commands, fetch URLs, or search, you MUST call an appropriate tool.\n"
+            "- Efficiency: batch independent read-only tool calls into a single turn (multiple tool calls) when possible.\n"
+            "- When context is getting large, use delegate_agent(task, context, tools) to offload an independent subtask with minimal context.\n"
             "- Never fabricate tool outputs.\n"
             "- Only ask the user a question when required information is missing.\n"
             f"{output_budget_line}"
@@ -124,4 +126,3 @@ class MemActLogic:
         if success:
             return f"[{name}]: {output}"
         return f"[{name}]: Error: {output}"
-

abstractagent/logic/react.py

@@ -71,9 +71,10 @@ class ReActLogic:
         - The user request belongs in the user-role message (prompt), not in the system prompt.
         - Conversation + tool history is provided via `messages` by the runtime adapter.
         """
-        _ = messages  # history is carried out-of-band via chat messages
+        # History is carried out-of-band via `messages`; keep logic pure.
+        _ = messages
 
-        task = str(task or "")
+        task = str(task or "").strip()
         guidance = str(guidance or "").strip()
 
         # Output token cap (provider max_tokens) comes from `_limits.max_output_tokens`.
@@ -84,64 +85,45 @@ class ReActLogic:
                 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"
-            )
+        if not isinstance(max_output_tokens, int) or max_output_tokens <= 0:
+            max_output_tokens = None
 
         system_prompt = (
             f"Iteration: {int(iteration)}/{int(max_iterations)}\n\n"
-            """## MY PERSONA
-I am a truthful and collaborative autonomous ReAct agent powered by the AbstractFramework. I am a creative critical thinker who balances ideas with constructive skepticism, always thinking of longer term consequences. I strive to be ethical and successful in all my actions and decisions. I am precise, clear, concise and direct in my responses, I avoid unnecessary verbosity. 
-
-## AGENCY / AUTONOMY
-- You always analyze the intent behind every request to identify what is expected of you
-- If the answer is straightforward and do not need you to take action, you answer directly
-- If you need to take actions, it means you need to request the execution of one or more of the tools provided to you
-- Remember that you are NOT the one executing the tools, you are REQUESTING their execution to your host and you have to wait for them to return the results so you can continue
-- after each tool call, you must determine if the tools were successful and produced the effect you expected or if they failed to determine your next step
-- if the tools were NOT successful, request again the execution of those tools with new parameters, based on the feedback given by your host
-- if the tools were successful and you still have actions to take, then request a next series of tool executions
-- if the tools were successful but you have enough information and don’t have any other actions to take, then provide your final answer
-- The goal of autonomy is to define, at each loop, which are the set of independent tools you could run concurrently without affecting the end result. Try to request as many tool executions as you can, as long as you don’t need the result of one of them to plan the other
-
-## EVIDENCE & ACTION (IMPORTANT)
-- Be truthful: only claim actions that are supported by tool outputs.
-- If the task requires reading/editing/running anything, call the relevant tools. Do not “announce” actions without doing them.
-""").strip()
+            "## MY PERSONA\n"
+            "You are an autonomous ReAct agent (Reason → Act → Observe).\n\n"
+            "Loop contract:\n"
+            "- THINK briefly using the full transcript and prior observations.\n"
+            "- If you need to ACT, CALL one or more tools (function calls).\n"
+            "- If you are DONE, respond with the final answer and NO tool calls.\n\n"
+            "Rules:\n"
+            "- Choose tools yourself; never ask the user which tool to run.\n"
+            "- Do not write a long plan before tool calls.\n"
+            "- Keep non-final responses short; do not draft large deliverables in chat when tools can build them.\n"
+            "- Efficiency (important): the runtime supports MULTIPLE tool calls in one response.\n"
+            "  Batch independent read-only tool calls to reduce iterations.\n"
+            "  Example: read multiple files/ranges or run multiple searches in one response.\n"
+            "  If reading nearby ranges of the same file, prefer ONE call with a wider range.\n"
+            "  Only split tool calls across turns when later calls depend on earlier outputs; do NOT batch side-effectful tools (write_file/edit_file/execute_command/send_email/send_whatsapp_message/send_telegram_message/send_telegram_artifact).\n"
+            "- When context is getting large, use delegate_agent(task, context, tools) to offload an independent subtask with minimal context.\n"
+            "- Keep tool call arguments small and valid; avoid embedding huge blobs (large file contents / giant JSON) directly in arguments.\n"
+            "- Attachments:\n"
+            "  - If you see an 'Active attachments' message or inline 'Content from <file>' blocks, treat those attachments as already available in-context.\n"
+            "    Do NOT call tools just to re-open/read them.\n"
+            "  - If you see 'Stored session attachments', those may not be included in the current call.\n"
+            "    Only if you truly need it, use the attachment-open tool with artifact_id and a bounded line range.\n"
+            "  - Never use filesystem tools on attachment filenames/paths or absolute paths outside the workspace.\n"
+            "- For fetch_url: use include_full_content=False for shorter previews; set keep_links=False to strip links when not needed.\n"
+            "- For large files, create a small skeleton first, then refine via multiple smaller edits/tool calls.\n"
+            "- Use tool outputs as evidence; do not claim actions without tool outputs.\n"
+            "- Continue iterating until the task is complete.\n"
+        ).strip()
 
         if guidance:
-            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,
-        )
+            system_prompt = f"{system_prompt}\n\nGuidance:\n{guidance}".strip()
+
+        # Note: prompt is unused by the runtime adapter (we supply chat `messages`).
+        return LLMRequest(prompt=task, system_prompt=system_prompt, tools=self.tools, max_tokens=max_output_tokens)
 
     def parse_response(self, response: Any) -> Tuple[str, List[ToolCall]]:
         if not isinstance(response, dict):
@@ -183,4 +165,3 @@ I am a truthful and collaborative autonomous ReAct agent powered by the Abstract
         if success:
             return f"[{name}]: {output}"
         return f"[{name}]: Error: {output}"
-

abstractagent/tools/__init__.py

@@ -7,8 +7,10 @@ Agent-specific tools (execute_python, self_improve) are defined locally.
 # Import common tools from AbstractCore (canonical source)
 from abstractcore.tools.common_tools import (
     list_files,
+    skim_folders,
     analyze_code,
     read_file,
+    skim_files,
     search_files,
     write_file,
     edit_file,
@@ -25,8 +27,10 @@ from .self_improve import self_improve
 ALL_TOOLS = [
     # File operations (from abstractcore)
     list_files,
+    skim_folders,
     analyze_code,
     read_file,
+    skim_files,
     search_files,
     write_file,
     edit_file,
@@ -43,8 +47,10 @@ ALL_TOOLS = [
 __all__ = [
     # File operations
     "list_files",
+    "skim_folders",
     "analyze_code",
     "read_file",
+    "skim_files",
     "search_files",
     "write_file",
     "edit_file",

abstractagent-0.3.1.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: abstractagent
+Version: 0.3.1
+Summary: Agent implementations using AbstractRuntime and AbstractCore
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: abstractcore[tools]
+Requires-Dist: abstractruntime
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# AbstractAgent
+
+Agent patterns (ReAct / CodeAct / MemAct) built on **AbstractRuntime** (durable execution) and **AbstractCore** (tools + LLM integration).
+
+Start here: [`docs/getting-started.md`](docs/getting-started.md) (then [`docs/README.md`](docs/README.md) for the full index)
+
+## Documentation
+
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- FAQ / troubleshooting: [`docs/faq.md`](docs/faq.md)
+- Architecture (diagrams): [`docs/architecture.md`](docs/architecture.md)
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- Acknowledgements: [`ACKNOWLEDMENTS.md`](ACKNOWLEDMENTS.md)
+
+## What you get
+
+- **ReAct**: tool-first Reason → Act → Observe loop
+- **CodeAct**: executes Python (tool call or fenced ` ```python``` ` blocks)
+- **MemAct**: memory-enhanced agent using runtime-owned Active Memory
+- **Durable runs**: pause/resume via `run_id` + runtime stores
+- **Tool control**: explicit tool bundles + per-run allowlists
+- **Observability**: durable ledger of LLM calls, tool calls, and waits
+
+## Installation
+
+From source (development):
+
+```bash
+pip install -e .
+```
+
+With dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+From PyPI:
+
+```bash
+pip install abstractagent
+```
+
+Note: the repository may be ahead of the latest published PyPI release. To verify what you installed:
+
+```bash
+python -c "import importlib.metadata as md; print(md.version('abstractagent'))"
+```
+
+## Quick start (ReAct)
+
+```python
+from abstractagent import create_react_agent
+
+agent = create_react_agent(provider="ollama", model="qwen3:1.7b-q4_K_M")
+agent.start("List the files in the current directory")
+state = agent.run_to_completion()
+print(state.output["answer"])
+```
+
+## Persistence (resume across restarts)
+
+By default, the factory helpers use an in-memory runtime store. For resume across process restarts,
+pass a persistent `RunStore`/`LedgerStore` (example below uses JSON files).
+
+```python
+from abstractagent import create_react_agent
+from abstractruntime.storage.json_files import JsonFileRunStore, JsonlLedgerStore
+
+run_store = JsonFileRunStore(".runs")
+ledger_store = JsonlLedgerStore(".runs")
+
+agent = create_react_agent(run_store=run_store, ledger_store=ledger_store)
+agent.start("Long running task")
+agent.save_state("agent_state.json")
+
+# ... later / after restart ...
+
+agent2 = create_react_agent(run_store=run_store, ledger_store=ledger_store)
+agent2.load_state("agent_state.json")
+state = agent2.run_to_completion()
+print(state.output["answer"])
+```
+
+More details: [`docs/persistence.md`](docs/persistence.md)
+
+## CLI
+
+This repository still installs a `react-agent` entrypoint, but it is **deprecated** and only prints a migration hint
+(see `src/abstractagent/repl.py` and `pyproject.toml`).
+
+Interactive UX lives in **AbstractCode**.
+
+## License
+
+MIT (see `LICENSE`).