pdo-agent 2.0.0__py3-none-any.whl

pdo/agent/messages.py

@@ -0,0 +1,87 @@
+"""Message and tool-call data structures.
+
+These dataclasses are the in-memory representation of a conversation. They know
+how to serialise themselves into the shape the OpenAI chat API expects, which
+keeps that provider-specific detail out of the rest of the agent.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCall:
+    """A single tool invocation requested by the model.
+
+    ``arguments`` is the raw JSON string exactly as returned by the model; it is
+    only parsed at execution time so a malformed payload can be reported as a
+    tool error rather than crashing the loop.
+    """
+
+    id: str
+    name: str
+    arguments: str = "{}"
+
+    def to_openai(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "type": "function",
+            "function": {"name": self.name, "arguments": self.arguments},
+        }
+
+
+@dataclass
+class Message:
+    """A single chat message.
+
+    A message may be a plain text turn, an assistant turn that requests tool
+    calls, or a tool-result turn. The optional fields capture those variants
+    without needing subclasses.
+    """
+
+    role: str  # "system" | "user" | "assistant" | "tool"
+    # Either plain text or OpenAI multi-part content (e.g. text + image_url
+    # parts for vision models); lists are passed through to the API unchanged.
+    content: str | list[dict[str, Any]] | None = None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str | None = None  # set on tool-result messages
+    name: str | None = None  # tool name, set on tool-result messages
+
+    def to_openai(self) -> dict[str, Any]:
+        """Serialise to the dict shape expected by the OpenAI chat API."""
+        data: dict[str, Any] = {"role": self.role}
+
+        # An assistant message that only requests tool calls legitimately has
+        # ``content == None``; every other role needs a string content field.
+        if self.content is not None:
+            data["content"] = self.content
+        elif self.role != "assistant":
+            data["content"] = ""
+
+        if self.tool_calls:
+            data["tool_calls"] = [tc.to_openai() for tc in self.tool_calls]
+        if self.tool_call_id is not None:
+            data["tool_call_id"] = self.tool_call_id
+        if self.role == "tool" and self.name:
+            data["name"] = self.name
+        return data
+
+    # Convenience constructors keep call sites readable. ----------------------
+    @classmethod
+    def system(cls, content: str) -> Message:
+        return cls(role="system", content=content)
+
+    @classmethod
+    def user(cls, content: str) -> Message:
+        return cls(role="user", content=content)
+
+    @classmethod
+    def assistant(
+        cls, content: str | None = None, tool_calls: list[ToolCall] | None = None
+    ) -> Message:
+        return cls(role="assistant", content=content, tool_calls=tool_calls or [])
+
+    @classmethod
+    def tool(cls, content: str, tool_call_id: str, name: str) -> Message:
+        return cls(role="tool", content=content, tool_call_id=tool_call_id, name=name)

pdo/agent/planner.py

@@ -0,0 +1,38 @@
+"""Lightweight planner.
+
+For multi-step requests the planner asks the model for a short, ordered list of
+concrete steps. The plan is advisory: it is injected as context to keep the
+agent focused, not enforced as a rigid script. This stays thin on purpose —
+v1 does not build a planning framework.
+"""
+from __future__ import annotations
+
+import logging
+
+from ..llm import LLMClient
+from .messages import Message
+
+logger = logging.getLogger(__name__)
+
+_PLAN_SYSTEM_PROMPT = (
+    "You are a planning assistant. Break the user's goal into a short, ordered "
+    "list of concrete, actionable steps (at most six). Reply with only the "
+    "numbered list — no preamble, no commentary."
+)
+
+
+class Planner:
+    """Turns a goal into a short list of steps using the LLM."""
+
+    def __init__(self, llm: LLMClient) -> None:
+        self._llm = llm
+
+    def plan(self, goal: str) -> list[str]:
+        """Return a list of step strings, or an empty list on failure."""
+        messages = [Message.system(_PLAN_SYSTEM_PROMPT), Message.user(goal)]
+        try:
+            response = self._llm.complete(messages, tools=None, stream=False)
+        except Exception:  # noqa: BLE001 — planning is best-effort
+            logger.exception("Planning step failed; continuing without a plan")
+            return []
+        return [line.strip() for line in (response.content or "").splitlines() if line.strip()]

pdo/agent/reviewer.py

@@ -0,0 +1,25 @@
+"""Thin reviewer.
+
+A final sanity check on the answer before it reaches the user. For v1 this just
+guarantees a non-empty reply; it is the natural extension point for richer
+checks later (e.g. verifying claimed actions actually ran).
+"""
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Reviewer:
+    """Validates and, if necessary, repairs the agent's final answer."""
+
+    def review(self, user_input: str, answer: str) -> str:
+        text = (answer or "").strip()
+        if not text:
+            logger.warning("Empty final answer; substituting a fallback message")
+            return (
+                "I wasn't able to produce a response to that. "
+                "Could you rephrase or add a little more detail?"
+            )
+        return text

pdo/agent/router.py

@@ -0,0 +1,37 @@
+"""Thin router.
+
+The real routing happens inside the model: it decides — via native tool
+calling — whether any tool is needed. So this router always offers the tools and
+just adds one cheap heuristic on top: should we spend a planning call before the
+main loop? That is reserved for clearly multi-step task requests.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Verbs that typically signal a "do something" request rather than a chat.
+_TASK_HINTS = re.compile(
+    r"\b(build|create|make|generate|write|implement|set\s?up|install|run|fix|"
+    r"refactor|delete|remove|deploy|configure|scaffold|add|migrate|convert)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class RouteDecision:
+    """The router's verdict for a single turn."""
+
+    expose_tools: bool
+    should_plan: bool
+
+
+class Router:
+    """Decides whether tools are offered and whether to pre-plan."""
+
+    def route(self, user_input: str) -> RouteDecision:
+        text = user_input.strip()
+        # Plan only for substantial, task-shaped requests; trivial one-liners
+        # ("list files") don't benefit from a separate planning round-trip.
+        should_plan = bool(_TASK_HINTS.search(text)) and len(text.split()) >= 4
+        return RouteDecision(expose_tools=True, should_plan=should_plan)

pdo/api.py

@@ -0,0 +1,65 @@
+"""Embedding API: drive the PDO agent from Python.
+
+Example::
+
+    from pdo import run_agent
+
+    answer = run_agent("list the markdown files here and summarise the README")
+
+Configuration comes from the environment / ``.env`` exactly like the CLI
+(``OPENAI_API_KEY``, ``OPENAI_BASE_URL``, ``OPENAI_MODEL``, …), with keyword
+overrides for scripts. Each call uses an ephemeral memory, so it never touches
+your interactive sessions.
+"""
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from .agent.core import Agent
+from .agent.memory import MemoryStore
+from .config import load_config
+from .llm import LLMClient, OpenAIClient
+from .tools.registry import get_registry
+
+
+def run_agent(
+    prompt: str,
+    *,
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    temperature: float | None = None,
+    planning: bool = False,
+    llm: LLMClient | None = None,
+) -> str:
+    """Run one task through the PDO agent and return its final answer.
+
+    Args:
+        prompt: the task or question.
+        model / api_key / base_url / temperature: override the env config.
+        planning: enable the pre-planning step for multi-step tasks.
+        llm: supply a custom :class:`~pdo.llm.LLMClient` (e.g. a mock in tests
+            or another provider implementation); overrides the other LLM args.
+    """
+    config = load_config()
+    if model:
+        config.openai_model = model
+    if api_key:
+        config.openai_api_key = api_key
+    if base_url is not None:
+        config.openai_base_url = base_url
+    if temperature is not None:
+        config.temperature = temperature
+
+    if llm is None:
+        llm = OpenAIClient(
+            api_key=config.openai_api_key,
+            model=config.openai_model,
+            temperature=config.temperature,
+            base_url=config.openai_base_url,
+        )
+
+    memory = MemoryStore(Path(tempfile.mkdtemp(prefix="pdo-api-")))
+    agent = Agent(config, llm, get_registry(), memory, planning=planning)
+    return agent.run_turn(prompt)

pdo/banner.py

@@ -0,0 +1,53 @@
+"""Pixel-art logo for the startup splash screen.
+
+Each letter is a small bitmap (1 = filled pixel). Pixels are drawn as a pair of
+block characters (``██``) so they look roughly square in a terminal, where
+character cells are taller than they are wide.
+"""
+from __future__ import annotations
+
+# 4-wide x 5-tall bitmaps for the letters we need.
+_LETTERS: dict[str, list[str]] = {
+    "P": [
+        "1111",
+        "1001",
+        "1111",
+        "1000",
+        "1000",
+    ],
+    "D": [
+        "1110",
+        "1001",
+        "1001",
+        "1001",
+        "1110",
+    ],
+    "O": [
+        "1111",
+        "1001",
+        "1001",
+        "1001",
+        "1111",
+    ],
+}
+
+_ON = "██"
+_OFF = "  "
+_ROWS = 5
+
+
+def render_logo(word: str = "PDO", gap: str = "  ") -> str:
+    """Render ``word`` as multi-line pixel-block art.
+
+    Raises:
+        KeyError: if a character in ``word`` has no defined bitmap.
+    """
+    lines = ["" for _ in range(_ROWS)]
+    last = len(word) - 1
+    for index, char in enumerate(word):
+        bitmap = _LETTERS[char.upper()]
+        for row in range(_ROWS):
+            lines[row] += "".join(_ON if pixel == "1" else _OFF for pixel in bitmap[row])
+            if index != last:
+                lines[row] += gap
+    return "\n".join(lines)

pdo/config.py

@@ -0,0 +1,151 @@
+"""Application configuration.
+
+All configuration comes from environment variables (optionally loaded from a
+``.env`` file) and is validated at startup with ``pydantic``. We deliberately do
+not depend on ``pydantic-settings`` to keep the dependency surface small; reading
+the environment by hand is trivial and keeps the failure messages friendly.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+
+class ConfigError(RuntimeError):
+    """Raised when configuration is missing or invalid.
+
+    The message is intended to be shown directly to the user, so it must be
+    human-friendly rather than a stack trace.
+    """
+
+
+class Config(BaseModel):
+    """Validated runtime configuration."""
+
+    openai_api_key: str = Field(..., min_length=1)
+    openai_model: str = Field(default="gpt-4.1-mini", min_length=1)
+    # Optional override of the API endpoint. Set this to use an OpenAI-compatible
+    # provider such as OpenRouter, a local model server, etc. None = OpenAI.
+    openai_base_url: str | None = Field(default=None)
+    temperature: float = Field(default=0.2, ge=0.0, le=2.0)
+    # Render assistant replies as Markdown (vs. raw token streaming).
+    render_markdown: bool = Field(default=True)
+    # Accent color theme name (see pdo.theme.THEMES).
+    theme: str = Field(default="cyan")
+    # Per-tool permission policy: tools that are blocked, or require confirmation.
+    deny_tools: list[str] = Field(default_factory=list)
+    ask_tools: list[str] = Field(default_factory=list)
+
+    @field_validator("openai_api_key", "openai_model")
+    @classmethod
+    def _strip(cls, value: str) -> str:
+        return (value or "").strip()
+
+
+def load_config() -> Config:
+    """Load and validate configuration from the environment.
+
+    Raises:
+        ConfigError: if required values are missing or invalid. The message is
+            safe to print directly to the terminal.
+    """
+    load_dotenv()  # no-op if there is no .env file
+
+    api_key = os.getenv("OPENAI_API_KEY", "").strip()
+    if not api_key:
+        raise ConfigError(
+            "OPENAI_API_KEY is not set.\n\n"
+            "Set it before running PDO, for example:\n"
+            "  export OPENAI_API_KEY=sk-...\n\n"
+            "or copy .env.example to .env and fill it in."
+        )
+
+    raw_temperature = os.getenv("TEMPERATURE", "0.2") or "0.2"
+    try:
+        temperature = float(raw_temperature)
+    except ValueError as exc:
+        raise ConfigError(
+            f"TEMPERATURE must be a number between 0 and 2 (got {raw_temperature!r})."
+        ) from exc
+
+    markdown_raw = os.getenv("PDO_MARKDOWN", "1").strip().lower()
+    render_markdown = markdown_raw not in ("0", "false", "no", "off")
+
+    def _csv(name: str) -> list[str]:
+        return [item.strip() for item in os.getenv(name, "").split(",") if item.strip()]
+
+    try:
+        return Config(
+            openai_api_key=api_key,
+            openai_model=os.getenv("OPENAI_MODEL", "gpt-4.1-mini"),
+            openai_base_url=os.getenv("OPENAI_BASE_URL", "").strip() or None,
+            temperature=temperature,
+            render_markdown=render_markdown,
+            theme=os.getenv("PDO_THEME", "cyan").strip() or "cyan",
+            deny_tools=_csv("PDO_DENY_TOOLS"),
+            ask_tools=_csv("PDO_ASK_TOOLS"),
+        )
+    except ValidationError as exc:
+        # Surface the first, most relevant validation problem in plain language.
+        first = exc.errors()[0]
+        field = ".".join(str(p) for p in first["loc"])
+        raise ConfigError(f"Invalid configuration for {field}: {first['msg']}.") from exc
+
+
+# --- Filesystem locations -------------------------------------------------- #
+#
+# Runtime state (the JSON memory store and rotating logs) lives under a single
+# "home" directory. By default that is the installed package directory so a
+# freshly cloned repo "just works"; set PDO_HOME to relocate it (e.g. ~/.pdo).
+
+
+def get_home_dir() -> Path:
+    """Return the base directory for PDO runtime state."""
+    env = os.getenv("PDO_HOME")
+    if env:
+        return Path(env).expanduser()
+    return Path(__file__).resolve().parent
+
+
+def get_data_dir() -> Path:
+    """Return (creating if needed) the directory holding JSON state files."""
+    path = get_home_dir() / "data"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_logs_dir() -> Path:
+    """Return (creating if needed) the directory holding log files."""
+    path = get_home_dir() / "logs"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_plugins_dir() -> Path:
+    """Return (creating if needed) the directory scanned for user tool plugins.
+
+    Drop a ``.py`` file defining a ``Tool`` subclass here and PDO loads it on
+    startup. Defaults to ``<home>/plugins`` (override the home with ``PDO_HOME``).
+    """
+    path = get_home_dir() / "plugins"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_mcp_config_path() -> Path:
+    """Return the path to the MCP servers config file (``<home>/mcp.json``)."""
+    return get_home_dir() / "mcp.json"
+
+
+def get_skills_dir() -> Path:
+    """Return (creating if needed) the directory scanned for user skills.
+
+    Each ``.md`` file becomes a reusable slash command (e.g. ``review.md`` →
+    ``/review``). Defaults to ``<home>/skills``.
+    """
+    path = get_home_dir() / "skills"
+    path.mkdir(parents=True, exist_ok=True)
+    return path

pdo/llm.py

@@ -0,0 +1,211 @@
+"""LLM abstraction.
+
+The core agent depends only on the :class:`LLMClient` interface, never on a
+concrete provider. ``OpenAIClient`` is the single implementation shipped in v1;
+adding another provider (Anthropic, a local model, etc.) means writing a new
+class here without touching the agent.
+"""
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from .agent.messages import Message, ToolCall
+
+logger = logging.getLogger(__name__)
+
+
+class LLMError(RuntimeError):
+    """Raised when a request to the language model fails."""
+
+
+def _looks_like_tools_unsupported(exc: Exception) -> bool:
+    """Heuristic: does this provider error mean the model can't use tools?
+
+    Covers messages like "<model> does not support tools" returned by Ollama and
+    similar OpenAI-compatible endpoints for tool-less models.
+    """
+    message = str(exc).lower()
+    return "tool" in message and ("support" in message or "not supported" in message)
+
+
+@dataclass
+class LLMResponse:
+    """A normalised model response: free-text content and/or tool calls."""
+
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    # Token usage for this call, if the provider reported it.
+    usage: dict[str, int] | None = None
+
+
+class LLMClient(ABC):
+    """Provider-agnostic chat interface used by the agent."""
+
+    @abstractmethod
+    def complete(
+        self,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]] | None = None,
+        *,
+        stream: bool = False,
+        on_token: Callable[[str], None] | None = None,
+    ) -> LLMResponse:
+        """Send ``messages`` to the model and return its response.
+
+        Args:
+            messages: the conversation so far.
+            tools: JSON tool schemas the model may call, or ``None`` to disable
+                tool calling for this request.
+            stream: when ``True``, emit content tokens via ``on_token`` as they
+                arrive (the full response is still returned at the end).
+            on_token: callback invoked with each content token while streaming.
+        """
+
+
+class OpenAIClient(LLMClient):
+    """OpenAI implementation of :class:`LLMClient` using native tool calling."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        temperature: float = 0.2,
+        base_url: str | None = None,
+        client: Any | None = None,
+    ) -> None:
+        # ``client`` is injectable so tests can pass a fake without importing
+        # the SDK or hitting the network. ``base_url`` targets any OpenAI-
+        # compatible endpoint (OpenRouter, a local server, …); None = OpenAI.
+        if client is None:
+            from openai import OpenAI
+
+            client = OpenAI(api_key=api_key, base_url=base_url)
+        self._client = client
+        self._model = model
+        self._temperature = temperature
+        # Some models (e.g. small local Ollama models) reject tool schemas. Once
+        # we learn that, we stop sending tools to avoid repeated failed requests.
+        self._supports_tools = True
+
+    def complete(
+        self,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]] | None = None,
+        *,
+        stream: bool = False,
+        on_token: Callable[[str], None] | None = None,
+    ) -> LLMResponse:
+        kwargs: dict[str, Any] = {
+            "model": self._model,
+            "messages": [m.to_openai() for m in messages],
+            "temperature": self._temperature,
+        }
+        if tools and self._supports_tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "auto"
+
+        try:
+            return self._request(kwargs, stream, on_token)
+        except Exception as exc:  # noqa: BLE001 — normalise every provider error
+            # Degrade gracefully when the model doesn't support tool calling:
+            # drop the tools and retry once as a plain chat request.
+            if "tools" in kwargs and _looks_like_tools_unsupported(exc):
+                logger.warning("Model %r does not support tools; retrying without them", self._model)
+                self._supports_tools = False
+                kwargs.pop("tools", None)
+                kwargs.pop("tool_choice", None)
+                try:
+                    return self._request(kwargs, stream, on_token)
+                except Exception as retry_exc:  # noqa: BLE001
+                    logger.exception("LLM request failed (no-tools retry)")
+                    raise LLMError(f"LLM request failed: {retry_exc}") from retry_exc
+            logger.exception("LLM request failed")
+            raise LLMError(f"LLM request failed: {exc}") from exc
+
+    def _request(
+        self, kwargs: dict[str, Any], stream: bool, on_token: Callable[[str], None] | None
+    ) -> LLMResponse:
+        if stream:
+            return self._complete_stream(kwargs, on_token)
+        return self._complete_once(kwargs)
+
+    def _complete_once(self, kwargs: dict[str, Any]) -> LLMResponse:
+        response = self._client.chat.completions.create(**kwargs)
+        message = response.choices[0].message
+        tool_calls = [
+            ToolCall(id=tc.id, name=tc.function.name, arguments=tc.function.arguments or "{}")
+            for tc in (message.tool_calls or [])
+        ]
+        return LLMResponse(
+            content=message.content or "",
+            tool_calls=tool_calls,
+            usage=_usage_to_dict(getattr(response, "usage", None)),
+        )
+
+    def _complete_stream(
+        self, kwargs: dict[str, Any], on_token: Callable[[str], None] | None
+    ) -> LLMResponse:
+        # include_usage asks the API to emit a final usage chunk while streaming;
+        # some OpenAI-compatible endpoints reject it, so fall back without it.
+        try:
+            stream = self._client.chat.completions.create(
+                **kwargs, stream=True, stream_options={"include_usage": True}
+            )
+        except TypeError:
+            stream = self._client.chat.completions.create(**kwargs, stream=True)
+
+        content_parts: list[str] = []
+        # Tool-call deltas arrive in fragments keyed by ``index``; accumulate
+        # them until the stream completes.
+        tool_acc: dict[int, dict[str, str]] = {}
+        usage = None
+
+        for chunk in stream:
+            if getattr(chunk, "usage", None):
+                usage = chunk.usage
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta
+
+            text = getattr(delta, "content", None)
+            if text:
+                content_parts.append(text)
+                if on_token:
+                    on_token(text)
+
+            for tc in getattr(delta, "tool_calls", None) or []:
+                slot = tool_acc.setdefault(tc.index, {"id": "", "name": "", "arguments": ""})
+                if tc.id:
+                    slot["id"] = tc.id
+                if tc.function and tc.function.name:
+                    slot["name"] = tc.function.name
+                if tc.function and tc.function.arguments:
+                    slot["arguments"] += tc.function.arguments
+
+        tool_calls = [
+            ToolCall(
+                id=slot["id"] or f"call_{index}",
+                name=slot["name"],
+                arguments=slot["arguments"] or "{}",
+            )
+            for index, slot in sorted(tool_acc.items())
+            if slot["name"]
+        ]
+        return LLMResponse(
+            content="".join(content_parts), tool_calls=tool_calls, usage=_usage_to_dict(usage)
+        )
+
+
+def _usage_to_dict(usage: Any) -> dict[str, int] | None:
+    """Normalise a provider usage object into a plain dict, if present."""
+    if usage is None:
+        return None
+    return {
+        "prompt_tokens": getattr(usage, "prompt_tokens", 0) or 0,
+        "completion_tokens": getattr(usage, "completion_tokens", 0) or 0,
+        "total_tokens": getattr(usage, "total_tokens", 0) or 0,
+    }