abstractagent 0.3.0__tar.gz → 0.3.1__tar.gz

abstractagent-0.3.1/PKG-INFO

@@ -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`).

abstractagent-0.3.1/README.md

@@ -0,0 +1,99 @@
+# 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`).

{abstractagent-0.3.0 → abstractagent-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "abstractagent"
-version = "0.3.0"
+version = "0.3.1"
 description = "Agent implementations using AbstractRuntime and AbstractCore"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,3 +23,10 @@ where = ["src"]
 
 [project.scripts]
 react-agent = "abstractagent.repl:main"
+
+[tool.pytest.ini_options]
+markers = [
+    "basic: Level A (contract/unit) tests",
+    "integration: Level B (integration/local) tests",
+    "e2e: Level C (end-to-end/real infra) tests (opt-in)",
+]

{abstractagent-0.3.0 → abstractagent-0.3.1}/src/abstractagent/adapters/codeact_runtime.py

@@ -11,6 +11,8 @@ from abstractruntime import Effect, EffectType, RunState, StepPlan, WorkflowSpec
 from abstractruntime.core.vars import ensure_limits, ensure_namespaces
 from abstractruntime.memory.active_context import ActiveContextPolicy
 
+from .generation_params import runtime_llm_params
+from .media import extract_media_from_context
 from ..logic.codeact import CodeActLogic
 
 
@@ -215,6 +217,7 @@ def create_codeact_workflow(
             if keep < 200:
                 keep = max_chars
                 suffix = ""
+            #[WARNING:TRUNCATION] bounded message content for LLM payload
             return text[:keep].rstrip() + suffix
 
         out: List[Dict[str, str]] = []
@@ -335,7 +338,10 @@ def create_codeact_workflow(
 
         emit("plan_request", {"tools": allow})
 
-        payload: Dict[str, Any] = {"prompt": prompt, "params": {"temperature": 0.2}}
+        payload: Dict[str, Any] = {"prompt": prompt, "params": runtime_llm_params(runtime_ns, extra={"temperature": 0.2})}
+        media = extract_media_from_context(context)
+        if media:
+            payload["media"] = media
         sys = _system_prompt(runtime_ns)
         if isinstance(sys, str) and sys.strip():
             payload["system_prompt"] = sys
@@ -431,11 +437,16 @@ def create_codeact_workflow(
             "messages": _sanitize_llm_messages(messages_view, limits=limits),
             "tools": list(tool_specs),
         }
+        media = extract_media_from_context(context)
+        if media:
+            payload["media"] = media
         sys = _system_prompt(runtime_ns) or req.system_prompt
         if isinstance(sys, str) and sys.strip():
             payload["system_prompt"] = sys
+        params: Dict[str, Any] = {}
         if req.max_tokens is not None:
-            payload["params"] = {"max_tokens": req.max_tokens}
+            params["max_tokens"] = req.max_tokens
+        payload["params"] = runtime_llm_params(runtime_ns, extra=params)
 
         return StepPlan(
             node_id="reason",
@@ -560,6 +571,7 @@ def create_codeact_workflow(
             "remember",
             "remember_note",
             "compact_memory",
+            "delegate_agent",
         }
 
         tool_queue: List[Dict[str, Any]] = []
@@ -635,6 +647,68 @@ def create_codeact_workflow(
                     next_node="handle_user_response",
                 )
 
+            if name == "delegate_agent":
+                delegated_task = str(args.get("task") or "").strip()
+                delegated_context = str(args.get("context") or "").strip()
+
+                tools_raw = args.get("tools")
+                if tools_raw is None:
+                    # Inherit the current allowlist, but avoid recursive delegation and avoid waiting on ask_user
+                    # unless explicitly enabled.
+                    child_allow = [t for t in allow if t not in {"delegate_agent", "ask_user"}]
+                else:
+                    child_allow = _normalize_allowlist(tools_raw)
+
+                if not delegated_task:
+                    temp["tool_results"] = {
+                        "results": [
+                            {
+                                "call_id": str(tc.get("call_id") or ""),
+                                "name": "delegate_agent",
+                                "success": False,
+                                "output": None,
+                                "error": "delegate_agent requires a non-empty task",
+                            }
+                        ]
+                    }
+                    return StepPlan(node_id="act", next_node="observe")
+
+                combined_task = delegated_task
+                if delegated_context:
+                    combined_task = f"{delegated_task}\n\nContext:\n{delegated_context}"
+
+                sub_vars: Dict[str, Any] = {
+                    "context": {"task": combined_task, "messages": []},
+                    "_runtime": {
+                        "allowed_tools": list(child_allow),
+                        "system_prompt_extra": (
+                            "You are a delegated sub-agent.\n"
+                            "- Focus ONLY on the delegated task.\n"
+                            "- Use ONLY the allowed tools when needed.\n"
+                            "- Do not ask the user questions; if blocked, state assumptions and proceed.\n"
+                            "- Return a concise result suitable for the parent agent to act on.\n"
+                        ),
+                    },
+                    "_limits": {"max_iterations": 10},
+                }
+
+                payload = {
+                    "workflow_id": str(getattr(run, "workflow_id", "") or "codeact_agent"),
+                    "vars": sub_vars,
+                    "async": False,
+                    "include_traces": False,
+                    # Tool-mode wrapper so the parent receives a normal tool observation (no run failure on child failure).
+                    "wrap_as_tool_result": True,
+                    "tool_name": "delegate_agent",
+                    "call_id": str(tc.get("call_id") or ""),
+                }
+                emit("delegate_agent", {"tools": list(child_allow), "call_id": payload.get("call_id")})
+                return StepPlan(
+                    node_id="act",
+                    effect=Effect(type=EffectType.START_SUBWORKFLOW, payload=payload, result_key="_temp.tool_results"),
+                    next_node="observe",
+                )
+
             if name == "recall_memory":
                 payload = dict(args)
                 payload.setdefault("tool_name", "recall_memory")
@@ -730,13 +804,14 @@ def create_codeact_workflow(
         )
 
     def execute_code_node(run: RunState, ctx) -> StepPlan:
-        _, _, _, temp, _ = ensure_codeact_vars(run)
+        _, _, runtime_ns, temp, _ = ensure_codeact_vars(run)
         code = temp.get("pending_code")
         if not isinstance(code, str) or not code.strip():
             return StepPlan(node_id="execute_code", next_node="reason")
 
         temp.pop("pending_code", None)
         emit("act", {"tool": "execute_python", "args": {"code": "(inline)", "timeout_s": 10.0}})
+        allow = _effective_allowlist(runtime_ns)
 
         return StepPlan(
             node_id="execute_code",
@@ -749,7 +824,8 @@ def create_codeact_workflow(
                             "arguments": {"code": code, "timeout_s": 10.0},
                             "call_id": "code",
                         }
-                    ]
+                    ],
+                    "allowed_tools": list(allow),
                 },
                 result_key="_temp.tool_results",
             ),
@@ -794,6 +870,7 @@ def create_codeact_workflow(
             # Keep a bounded preview for huge tool outputs to avoid bloating traces/ledgers.
             preview = rendered
             if len(preview) > 1000:
+                #[WARNING:TRUNCATION] bounded preview for observability payloads
                 preview = preview[:1000] + f"\n… (truncated, {len(rendered):,} chars total)"
             emit("observe", {"tool": name, "success": success, "result": preview})
             context["messages"].append(
@@ -870,6 +947,7 @@ def create_codeact_workflow(
             if keep < 200:
                 keep = max_chars
                 suffix = ""
+            #[WARNING:TRUNCATION] bounded transcript blocks for prompt reconstruction
             return s[:keep].rstrip() + suffix
 
         def _format_allowed_tools() -> str:
@@ -1002,8 +1080,11 @@ def create_codeact_workflow(
             "prompt": prompt,
             "response_schema": schema,
             "response_schema_name": "CodeActVerifier",
-            "params": {"temperature": 0.2},
+            "params": runtime_llm_params(runtime_ns, extra={"temperature": 0.2}),
         }
+        media = extract_media_from_context(context)
+        if media:
+            payload["media"] = media
         sys = _system_prompt(runtime_ns)
         if sys is not None:
             payload["system_prompt"] = sys

abstractagent-0.3.1/src/abstractagent/adapters/generation_params.py

@@ -0,0 +1,82 @@
+"""Helpers for consistent generation params in AbstractAgent adapters.
+
+These adapters build `EffectType.LLM_CALL` payloads for AbstractRuntime. We want
+to expose a uniform `(temperature, seed)` interface across agents while keeping
+backward compatibility with older runs that may not have these keys in
+`vars["_runtime"]`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+def normalize_seed(seed: Any) -> Optional[int]:
+    """Return a provider-ready seed or None when unset/random.
+
+    Policy:
+    - None or any negative value -> None (meaning: do not send seed).
+    - bool values are ignored (JSON booleans are ints in Python).
+    - numeric-ish values -> int(seed) if >= 0.
+    """
+    try:
+        if seed is None or isinstance(seed, bool):
+            return None
+        seed_i = int(seed)
+        return seed_i if seed_i >= 0 else None
+    except Exception:
+        return None
+
+
+def runtime_llm_params(
+    runtime_ns: Dict[str, Any],
+    *,
+    extra: Optional[Dict[str, Any]] = None,
+    default_temperature: float = 0.7,
+) -> Dict[str, Any]:
+    """Merge `runtime_ns` sampling controls into an LLM_CALL params dict.
+
+    Precedence:
+    1) `runtime_ns.temperature` / `runtime_ns.seed` when present
+    2) `extra.temperature` / `extra.seed` (step-specific defaults)
+    3) `default_temperature` (only for temperature)
+    """
+    out: Dict[str, Any] = dict(extra or {})
+
+    # Temperature: always provide a float (provider-agnostic).
+    temp_val = runtime_ns.get("temperature") if isinstance(runtime_ns, dict) else None
+    if temp_val is None:
+        temp_val = out.get("temperature")
+    if temp_val is None:
+        temp_val = default_temperature
+    try:
+        out["temperature"] = float(temp_val)
+    except Exception:
+        out["temperature"] = float(default_temperature)
+
+    # Seed: only include when explicitly set (>= 0).
+    seed_val = runtime_ns.get("seed") if isinstance(runtime_ns, dict) else None
+    if seed_val is None:
+        seed_val = out.get("seed")
+    seed_norm = normalize_seed(seed_val)
+    if seed_norm is not None:
+        out["seed"] = seed_norm
+    else:
+        out.pop("seed", None)
+
+    # Pass-through media policies (runtime-owned defaults).
+    #
+    # This keeps thin clients simple: they can set `_runtime.audio_policy` (and
+    # optional language hints) once at run start, and all LLM_CALL steps inherit it.
+    if isinstance(runtime_ns, dict):
+        audio_policy = runtime_ns.get("audio_policy")
+        if "audio_policy" not in out and isinstance(audio_policy, str) and audio_policy.strip():
+            out["audio_policy"] = audio_policy.strip()
+
+        stt_language = runtime_ns.get("stt_language")
+        if stt_language is None:
+            stt_language = runtime_ns.get("audio_language")
+        if "stt_language" not in out and isinstance(stt_language, str) and stt_language.strip():
+            out["stt_language"] = stt_language.strip()
+
+    return out

abstractagent-0.3.1/src/abstractagent/adapters/media.py

@@ -0,0 +1,45 @@
+"""Helpers for attachment/media plumbing in runtime-backed agents."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def extract_media_from_context(context: Dict[str, Any]) -> Optional[List[Any]]:
+    """Return a normalized `media` list from a runtime `context` dict.
+
+    Supported keys (best-effort):
+    - `context["attachments"]`: preferred (artifact refs)
+    - `context["media"]`: legacy/alternate
+    """
+    raw = context.get("attachments")
+    if raw is None:
+        raw = context.get("media")
+
+    if isinstance(raw, tuple):
+        items = list(raw)
+    else:
+        items = raw
+
+    if not isinstance(items, list) or not items:
+        return None
+
+    out: List[Any] = []
+    for item in items:
+        if isinstance(item, str):
+            s = item.strip()
+            if s:
+                out.append(s)
+            continue
+
+        if isinstance(item, dict):
+            # Prefer artifact refs; accept both {"$artifact": "..."} and {"artifact_id": "..."}.
+            aid = item.get("$artifact")
+            if not (isinstance(aid, str) and aid.strip()):
+                aid = item.get("artifact_id")
+            if isinstance(aid, str) and aid.strip():
+                out.append(dict(item))
+            continue
+
+    return out or None
+