pdo-agent 2.0.0__py3-none-any.whl

pdo/__init__.py

@@ -0,0 +1,21 @@
+"""PDO (Python Do) — Think. Plan. Do.
+
+A terminal-first AI agent that reasons about a goal, plans the work, decides
+whether tools are needed, executes them safely, reviews the result, and replies
+clearly. The public surface intentionally stays small; everything is wired
+together in :mod:`pdo.main`.
+"""
+from __future__ import annotations
+
+__version__ = "2.0.0"
+__all__ = ["__version__", "run_agent"]
+
+
+def __getattr__(name: str):
+    # Lazy re-export so `import pdo` stays lightweight; the agent stack is only
+    # pulled in when run_agent is actually used.
+    if name == "run_agent":
+        from .api import run_agent
+
+        return run_agent
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pdo/agent/__init__.py

@@ -0,0 +1,6 @@
+"""The agent package: orchestration, planning, routing, execution and memory.
+
+Each module here is intentionally small and single-purpose. ``core.Agent`` wires
+them together; nothing in this package references concrete tools directly — it
+only talks to the tool registry.
+"""

pdo/agent/core.py

@@ -0,0 +1,275 @@
+"""The agent core.
+
+``Agent`` coordinates the other components and runs the ReAct-style loop:
+call the model with tools → if it requests tools, execute them and feed results
+back → repeat until the model returns a final answer. It holds no business logic
+of its own; routing, planning, execution and review live in their own modules.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from pathlib import Path
+
+from ..config import Config
+from ..llm import LLMClient
+from ..tools.registry import ToolRegistry
+from .executor import Executor
+from .memory import MemoryStore
+from .messages import Message
+from .planner import Planner
+from .reviewer import Reviewer
+from .router import Router
+
+logger = logging.getLogger(__name__)
+
+# Hard cap on tool round-trips per turn, to bound cost and avoid infinite loops.
+MAX_TOOL_ITERATIONS = 8
+# How many past turns of conversation to include as context.
+HISTORY_WINDOW = 20
+# When the active message list grows beyond this, summarise the overflow…
+SUMMARIZE_THRESHOLD = 24
+# …keeping this many of the most recent messages verbatim.
+SUMMARIZE_KEEP = 10
+
+
+def _load_system_prompt() -> str:
+    path = Path(__file__).resolve().parent.parent / "prompts" / "system.md"
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        logger.warning("Could not read system prompt at %s; using a minimal fallback", path)
+        return "You are PDO, a careful and helpful terminal AI agent."
+
+
+class Agent:
+    """Drives a single conversation: plan, call tools, review, respond."""
+
+    def __init__(
+        self,
+        config: Config,
+        llm: LLMClient,
+        registry: ToolRegistry,
+        memory: MemoryStore,
+        *,
+        on_token: Callable[[str], None] | None = None,
+        on_tool: Callable[[str, dict], None] | None = None,
+        on_tool_result: Callable[[str, str], None] | None = None,
+        planning: bool = True,
+        depth: int = 0,
+    ) -> None:
+        self._config = config
+        self._llm = llm
+        self._registry = registry
+        self._memory = memory
+        policy = {
+            **{name: "deny" for name in getattr(config, "deny_tools", [])},
+            **{name: "ask" for name in getattr(config, "ask_tools", [])},
+        }
+        self._executor = Executor(registry, policy=policy)
+        self._router = Router()
+        self._planner = Planner(llm)
+        self._reviewer = Reviewer()
+        self._on_token = on_token or (lambda _token: None)
+        self._on_tool = on_tool or (lambda _name, _args: None)
+        self._on_tool_result = on_tool_result or (lambda _name, _result: None)
+        self._planning = planning
+        self._depth = depth
+        self._system_prompt = _load_system_prompt()
+        # Running token totals for the session (shown in the UI footer).
+        self._usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+        # Only the top-level agent may delegate; children get a registry
+        # without the delegate tool, so delegation cannot recurse unbounded.
+        if depth == 0 and not registry.has("delegate_task"):
+            from .delegate import DelegateTool
+
+            registry.register(DelegateTool(self))
+
+    def token_usage(self) -> dict[str, int]:
+        """Return cumulative token usage for the session."""
+        return dict(self._usage)
+
+    def run_subtask(self, task: str, context: str = "") -> str:
+        """Run ``task`` in a fresh child agent and return its final answer.
+
+        The child gets the same tools (minus delegation), an ephemeral memory,
+        and no streaming; its token usage is folded into this agent's totals.
+        """
+        from .delegate import MAX_DELEGATION_DEPTH
+
+        if self._depth >= MAX_DELEGATION_DEPTH:
+            return "Error: maximum delegation depth reached; do the task yourself."
+
+        import tempfile
+
+        child_registry = ToolRegistry()
+        for tool in self._registry.all():
+            if tool.name != "delegate_task":
+                child_registry.register(tool)
+
+        child = Agent(
+            self._config,
+            self._llm,
+            child_registry,
+            MemoryStore(Path(tempfile.mkdtemp(prefix="pdo-subagent-"))),
+            on_tool=self._on_tool,  # nested tool activity stays visible
+            on_tool_result=self._on_tool_result,
+            planning=False,
+            depth=self._depth + 1,
+        )
+        prompt = f"{task}\n\nContext:\n{context}" if context.strip() else task
+        try:
+            answer = child.run_turn(prompt)
+        except Exception as exc:  # noqa: BLE001 — a failed subtask must not kill the parent
+            logger.exception("Sub-agent failed")
+            answer = f"Error: sub-agent failed: {exc}"
+        for key in self._usage:
+            self._usage[key] += child.token_usage().get(key, 0)
+        return answer
+
+    def set_llm(self, llm: LLMClient) -> None:
+        """Swap the active language model (used by the ``/models`` command)."""
+        self._llm = llm
+        self._planner = Planner(llm)
+
+    def run_turn(self, user_input: str, images: list[str] | None = None) -> str:
+        """Process one user turn and return the final (also streamed) answer.
+
+        ``images`` is an optional list of local image file paths attached to
+        this turn; they are sent to the model as data-URL image parts (only
+        vision-capable models will make use of them).
+        """
+        decision = self._router.route(user_input)
+
+        plan: list[str] = []
+        if self._planning and decision.should_plan:
+            plan = self._planner.plan(user_input)
+
+        self._memory.add_message("user", user_input)
+        self._maybe_summarize()
+        messages = self._build_messages(plan)
+        if images:
+            # The last built message is this turn's user text (just persisted);
+            # replace it with multi-part content carrying the encoded images.
+            parts: list[dict] = [{"type": "text", "text": user_input}]
+            for path in images:
+                encoded = _encode_image(path)
+                if encoded:
+                    parts.append({"type": "image_url", "image_url": {"url": encoded}})
+            messages[-1] = Message(role="user", content=parts)
+        tools = self._registry.schemas() if decision.expose_tools else None
+
+        final = ""
+        for _ in range(MAX_TOOL_ITERATIONS):
+            response = self._llm.complete(
+                messages, tools=tools, stream=True, on_token=self._on_token
+            )
+            if response.usage:
+                for key in self._usage:
+                    self._usage[key] += response.usage.get(key, 0)
+            messages.append(
+                Message.assistant(content=response.content or None, tool_calls=response.tool_calls)
+            )
+
+            if not response.tool_calls:
+                final = response.content or ""
+                break
+
+            for call in response.tool_calls:
+                self._on_tool(call.name, _safe_args(call.arguments))
+                tool_message = self._executor.execute(call)
+                self._on_tool_result(call.name, tool_message.content or "")
+                messages.append(tool_message)
+        else:
+            final = final or "Reached the tool-iteration limit before finishing the task."
+
+        final = self._reviewer.review(user_input, final)
+        self._memory.add_message("assistant", final)
+        return final
+
+    def _build_messages(self, plan: list[str]) -> list[Message]:
+        """Assemble the message list: system prompt, summary, plan, history."""
+        messages = [Message.system(self._system_prompt)]
+        summary = self._memory.summary()
+        if summary:
+            messages.append(Message.system("Summary of earlier conversation:\n" + summary))
+        if plan:
+            messages.append(Message.system("Suggested plan:\n" + "\n".join(plan)))
+        # Only conversational turns are persisted; within-turn tool messages are
+        # kept locally in `messages` during the loop, not across turns.
+        for entry in self._memory.history(limit=HISTORY_WINDOW):
+            if entry["role"] in ("user", "assistant"):
+                messages.append(Message(role=entry["role"], content=entry["content"]))
+        return messages
+
+    def _maybe_summarize(self) -> None:
+        """Compress old turns into the session summary to keep context bounded."""
+        messages = self._memory.history()
+        if len(messages) <= SUMMARIZE_THRESHOLD:
+            return
+        older = messages[:-SUMMARIZE_KEEP]
+        recent = messages[-SUMMARIZE_KEEP:]
+        summary = self._summarize(self._memory.summary(), older)
+        if summary:
+            self._memory.set_summary(summary)
+            self._memory.replace_messages(recent)
+
+    def _summarize(self, previous: str, older: list[dict]) -> str:
+        """Produce an updated running summary (best-effort; empty on failure)."""
+        convo = "\n".join(f"{m['role']}: {m['content']}" for m in older)
+        prompt = (
+            f"Existing summary (may be empty):\n{previous or '(none)'}\n\n"
+            f"New conversation turns to fold in:\n{convo}\n\n"
+            "Write an updated summary."
+        )
+        try:
+            response = self._llm.complete(
+                [
+                    Message.system(
+                        "You compress a conversation into a concise summary that "
+                        "preserves key facts, decisions, file paths and the user's "
+                        "goals. Reply with only the summary."
+                    ),
+                    Message.user(prompt),
+                ],
+                tools=None,
+                stream=False,
+            )
+        except Exception:  # noqa: BLE001 — summarisation is best-effort
+            logger.exception("Summarisation failed; keeping full history")
+            return ""
+        return (response.content or "").strip()
+
+
+_IMAGE_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+
+def _encode_image(path: str) -> str | None:
+    """Encode a local image file as a base64 data URL, or None on failure."""
+    import base64
+
+    file = Path(path).expanduser()
+    mime = _IMAGE_MIME.get(file.suffix.lower())
+    if mime is None or not file.is_file():
+        return None
+    try:
+        data = base64.b64encode(file.read_bytes()).decode("ascii")
+    except OSError:
+        logger.warning("Could not read image %s", path)
+        return None
+    return f"data:{mime};base64,{data}"
+
+
+def _safe_args(raw: str) -> dict:
+    try:
+        parsed = json.loads(raw or "{}")
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        return {}

pdo/agent/delegate.py

@@ -0,0 +1,56 @@
+"""Sub-agent delegation tool.
+
+``delegate_task`` lets the main agent hand a self-contained subtask to a fresh
+child agent that runs its own ReAct loop and returns only its final answer.
+This keeps the parent's context small on large multi-part jobs.
+
+The tool lives in the agent package (not ``pdo.tools``) because it is
+intrinsically coupled to the agent: it needs to spawn one. It is registered by
+the top-level agent itself, and deliberately excluded from the registries handed
+to children, so delegation cannot recurse without bound.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..tools.base import Tool
+
+logger = logging.getLogger(__name__)
+
+# Belt-and-braces recursion cap: children don't get the delegate tool at all,
+# but the depth check also guards any future registry changes.
+MAX_DELEGATION_DEPTH = 2
+
+
+class DelegateTool(Tool):
+    """Adapter exposing ``Agent.run_subtask`` as a model-callable tool."""
+
+    name = "delegate_task"
+    description = (
+        "Delegate a self-contained subtask to a fresh sub-agent that has the "
+        "same tools and reports back only its final result. Use it to keep "
+        "context small when a job has large independent parts (e.g. 'summarise "
+        "every file in docs/'). Include ALL information the sub-agent needs — "
+        "it cannot see this conversation."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "task": {
+                "type": "string",
+                "description": "The complete, self-contained task for the sub-agent.",
+            },
+            "context": {
+                "type": "string",
+                "description": "Optional extra context (paths, constraints, prior findings).",
+            },
+        },
+        "required": ["task"],
+    }
+
+    def __init__(self, parent: Any) -> None:  # Any avoids a circular import with core
+        self._parent = parent
+
+    def run(self, task: str, context: str = "", **_: Any) -> str:
+        return self._parent.run_subtask(task, context)

pdo/agent/executor.py

@@ -0,0 +1,87 @@
+"""Executes the tool calls requested by the model.
+
+Every call is wrapped in exception handling and argument validation: a failing
+or unknown tool returns an error string that is fed back to the model, so a
+single bad tool call never crashes the agent loop.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Callable
+
+from ..config import get_logs_dir
+from ..tools.base import default_confirm
+from ..tools.registry import ToolRegistry
+from .messages import Message, ToolCall
+
+logger = logging.getLogger(__name__)
+
+
+class Executor:
+    """Runs a single :class:`ToolCall` against the registry.
+
+    ``policy`` maps a tool name to ``"deny"`` (blocked) or ``"ask"`` (requires
+    confirmation). Tools not listed are allowed. ``confirm`` is the callback used
+    for ``"ask"`` decisions.
+    """
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        policy: dict[str, str] | None = None,
+        confirm: Callable[[str], bool] | None = None,
+    ) -> None:
+        self._registry = registry
+        self._policy = policy or {}
+        self._confirm = confirm or default_confirm
+
+    def execute(self, call: ToolCall) -> Message:
+        """Execute ``call`` and return a tool-result message for the model."""
+        result = self._run(call)
+        self._audit(call.name, call.arguments, result)
+        return Message.tool(content=result, tool_call_id=call.id, name=call.name)
+
+    def _audit(self, name: str, arguments: str, result: str) -> None:
+        """Append a structured record of the tool call to the audit log."""
+        try:
+            entry = {
+                "ts": time.time(),
+                "tool": name,
+                "args": arguments,
+                "result_preview": (result or "")[:200],
+            }
+            with (get_logs_dir() / "audit.log").open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        except Exception:  # noqa: BLE001 — auditing must never break a tool call
+            logger.debug("Could not write audit log", exc_info=True)
+
+    def _run(self, call: ToolCall) -> str:
+        if not self._registry.has(call.name):
+            return f"Error: unknown tool {call.name!r}."
+
+        decision = self._policy.get(call.name, "allow")
+        if decision == "deny":
+            logger.info("Tool %r blocked by policy", call.name)
+            return f"Error: tool {call.name!r} is disabled by the current permission policy."
+        if decision == "ask" and not self._confirm(
+            f"Allow tool {call.name}({call.arguments})?"
+        ):
+            return "Cancelled: tool call was not approved by the user."
+
+        try:
+            args = json.loads(call.arguments or "{}")
+            if not isinstance(args, dict):
+                raise ValueError("tool arguments must be a JSON object")
+        except (json.JSONDecodeError, ValueError) as exc:
+            logger.warning("Bad arguments for tool %r: %s", call.name, exc)
+            return f"Error: could not parse arguments for {call.name}: {exc}"
+
+        try:
+            tool = self._registry.get(call.name)
+            logger.info("Executing tool %r with args %s", call.name, args)
+            return tool.run(**args)
+        except Exception as exc:  # noqa: BLE001 — keep the loop alive on any tool error
+            logger.exception("Tool %r raised", call.name)
+            return f"Error: tool {call.name!r} failed: {exc}"

pdo/agent/memory.py

@@ -0,0 +1,191 @@
+"""Local JSON memory store.
+
+State is split across:
+
+* ``memory.json``        — durable facts, preferences, and the current session name.
+* ``sessions/<name>.json`` — one file per named conversation: a rolling summary
+  plus recent messages.
+
+Splitting conversations into named sessions lets the user keep separate threads
+(``/new``, ``/resume``) and lets the agent compress old turns into a summary so
+context stays bounded. :func:`get_memory_store` returns a process-wide singleton
+so the agent and the memory tools share the same data.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import uuid
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from ..config import get_data_dir
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MEMORY: dict[str, Any] = {
+    "preferences": {},
+    "facts": [],
+    "current_session": "default",
+}
+_DEFAULT_SESSION: dict[str, Any] = {"summary": "", "messages": []}
+
+
+def _safe_name(name: str) -> str:
+    """Sanitise a session name into a safe file stem."""
+    return re.sub(r"[^A-Za-z0-9_.-]", "_", name).strip("_") or "default"
+
+
+class MemoryStore:
+    """Read/write access to PDO's local JSON memory and named sessions."""
+
+    def __init__(self, data_dir: Path | None = None) -> None:
+        self._dir = Path(data_dir) if data_dir is not None else get_data_dir()
+        self._memory_path = self._dir / "memory.json"
+        self._sessions_dir = self._dir / "sessions"
+        self._sessions_dir.mkdir(parents=True, exist_ok=True)
+
+        self._memory: dict[str, Any] = self._load(self._memory_path, _DEFAULT_MEMORY)
+        self._current: str = self._memory.get("current_session") or "default"
+        self._migrate_legacy_history()
+        self._summary, self._history = self._load_session(self._current)
+
+    # --- persistence -------------------------------------------------------- #
+    def _load(self, path: Path, default: Any) -> Any:
+        try:
+            if path.exists():
+                return json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Could not read %s (%s); starting fresh", path, exc)
+        return json.loads(json.dumps(default))  # deep copy
+
+    def _save(self, path: Path, data: Any) -> None:
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        except OSError as exc:
+            logger.error("Could not write %s: %s", path, exc)
+
+    def _session_path(self, name: str) -> Path:
+        return self._sessions_dir / f"{_safe_name(name)}.json"
+
+    def _load_session(self, name: str) -> tuple[str, list[dict[str, Any]]]:
+        data = self._load(self._session_path(name), _DEFAULT_SESSION)
+        if isinstance(data, list):  # tolerate an old flat-list format
+            return "", data
+        return data.get("summary", ""), data.get("messages", [])
+
+    def _save_session(self) -> None:
+        self._save(
+            self._session_path(self._current),
+            {"summary": self._summary, "messages": self._history},
+        )
+
+    def _migrate_legacy_history(self) -> None:
+        """Migrate a pre-sessions history.json into the default session once."""
+        legacy = self._dir / "history.json"
+        default_path = self._session_path("default")
+        if legacy.exists() and not default_path.exists():
+            try:
+                data = json.loads(legacy.read_text(encoding="utf-8"))
+                if isinstance(data, list):
+                    self._save(default_path, {"summary": "", "messages": data})
+            except (json.JSONDecodeError, OSError):
+                logger.debug("No legacy history to migrate", exc_info=True)
+
+    # --- conversation history & summary ------------------------------------ #
+    def add_message(self, role: str, content: str) -> None:
+        self._history.append({"role": role, "content": content, "ts": time.time()})
+        self._save_session()
+
+    def history(self, limit: int | None = None) -> list[dict[str, Any]]:
+        if limit is not None and limit > 0:
+            return list(self._history[-limit:])
+        return list(self._history)
+
+    def clear_history(self) -> None:
+        self._history = []
+        self._summary = ""
+        self._save_session()
+
+    def summary(self) -> str:
+        return self._summary
+
+    def set_summary(self, text: str) -> None:
+        self._summary = text
+        self._save_session()
+
+    def replace_messages(self, messages: list[dict[str, Any]]) -> None:
+        """Replace the active message list (used after summarising old turns)."""
+        self._history = list(messages)
+        self._save_session()
+
+    # --- sessions ----------------------------------------------------------- #
+    def current_session(self) -> str:
+        return self._current
+
+    def list_sessions(self) -> list[str]:
+        names = {path.stem for path in self._sessions_dir.glob("*.json")}
+        names.add(_safe_name(self._current))
+        return sorted(names)
+
+    def switch_session(self, name: str) -> str:
+        self._save_session()  # persist the session we're leaving
+        self._current = _safe_name(name)
+        self._memory["current_session"] = self._current
+        self._save(self._memory_path, self._memory)
+        self._summary, self._history = self._load_session(self._current)
+        return self._current
+
+    def new_session(self, name: str | None = None) -> str:
+        return self.switch_session(name or f"session-{int(time.time())}")
+
+    # --- facts -------------------------------------------------------------- #
+    def save_fact(self, text: str, tags: list[str] | None = None) -> str:
+        fact_id = uuid.uuid4().hex[:8]
+        self._memory.setdefault("facts", []).append(
+            {"id": fact_id, "text": text, "tags": tags or [], "created": time.time()}
+        )
+        self._save(self._memory_path, self._memory)
+        return fact_id
+
+    def search_facts(self, query: str) -> list[dict[str, Any]]:
+        needle = query.lower().strip()
+        return [
+            fact
+            for fact in self._memory.get("facts", [])
+            if needle in fact["text"].lower()
+            or any(needle in tag.lower() for tag in fact.get("tags", []))
+        ]
+
+    def all_facts(self) -> list[dict[str, Any]]:
+        return list(self._memory.get("facts", []))
+
+    def delete_fact(self, fact_id: str) -> bool:
+        facts = self._memory.get("facts", [])
+        remaining = [fact for fact in facts if fact["id"] != fact_id]
+        if len(remaining) == len(facts):
+            return False
+        self._memory["facts"] = remaining
+        self._save(self._memory_path, self._memory)
+        return True
+
+    # --- preferences -------------------------------------------------------- #
+    def get_preference(self, key: str, default: Any = None) -> Any:
+        return self._memory.get("preferences", {}).get(key, default)
+
+    def set_preference(self, key: str, value: Any) -> None:
+        self._memory.setdefault("preferences", {})[key] = value
+        self._save(self._memory_path, self._memory)
+
+    def preferences(self) -> dict[str, Any]:
+        return dict(self._memory.get("preferences", {}))
+
+
+@lru_cache(maxsize=1)
+def get_memory_store() -> MemoryStore:
+    """Return the process-wide memory store (created on first call)."""
+    return MemoryStore()