aria-code 4.1.3__py3-none-any.whl

plan_utils.py

@@ -0,0 +1,194 @@
+"""
+plan_utils.py — Plan parsing helpers for Aria Code CLI workflow commands.
+
+Supports several natural input styles:
+
+  Numbered steps (most common):
+      1. Fetch AAPL quote
+      2. Generate 6-month chart
+      3. Output analysis report
+
+  Bullet list:
+      - Fetch quote
+      - Generate chart
+      - Output report
+
+  Inline arrow / semicolon chain:
+      fetch quote -> generate chart -> output report
+      fetch quote; generate chart; output report
+
+  Mixed (numbered + description):
+      Step 1: Fetch AAPL quote
+      Step 2: Generate chart with SMA20
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+# ── Data model ────────────────────────────────────────────────────────────────
+
+@dataclass
+class PlanStep:
+    """A single executable step in a plan."""
+    index:       int                   # 1-based position
+    description: str                   # human-readable description
+    name:        Optional[str] = None  # optional short name / label
+    deps:        List[int] = field(default_factory=list)  # dependency indices
+
+    def __str__(self) -> str:
+        dep_str = f" [deps: {','.join(str(d) for d in self.deps)}]" if self.deps else ""
+        return f"{self.index}. {self.description}{dep_str}"
+
+
+# ── Patterns ──────────────────────────────────────────────────────────────────
+
+# "1. text", "1) text", "Step 1: text", "Step 1 — text"
+_RE_NUMBERED = re.compile(
+    r"^(?:step\s*)?(\d+)[.):\-–—]\s*(.+)$",
+    re.IGNORECASE,
+)
+
+# "- text", "• text", "* text", "· text"
+_RE_BULLET = re.compile(r"^[-•*·]\s+(.+)$")
+
+# Metadata tags like [name: Build] or [deps: 1,3]
+_RE_META_NAME = re.compile(r"\[name:\s*([^\]]+)\]", re.IGNORECASE)
+_RE_META_DEPS = re.compile(r"\[deps:\s*([^\]]+)\]",  re.IGNORECASE)
+
+
+def _strip_meta(text: str) -> tuple[str, Optional[str], List[int]]:
+    """Extract and remove [name:...] and [deps:...] metadata from text."""
+    name: Optional[str] = None
+    deps: List[int] = []
+
+    m = _RE_META_NAME.search(text)
+    if m:
+        name = m.group(1).strip()
+        text = text[:m.start()] + text[m.end():]
+
+    m = _RE_META_DEPS.search(text)
+    if m:
+        raw = m.group(1)
+        deps = [int(x.strip()) for x in re.split(r"[,;\s]+", raw) if x.strip().isdigit()]
+        text = text[:m.start()] + text[m.end():]
+
+    return text.strip(), name, deps
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def parse_plan_steps(raw: str) -> List[str]:
+    """
+    Parse '/plan' argument string into a list of plain step description strings.
+
+    This is the backwards-compatible API used by aria_cli.py.
+
+    Returns a list of non-empty step strings, in order.
+    """
+    return [s.description for s in parse_plan(raw)]
+
+
+def parse_plan(raw: str) -> List[PlanStep]:
+    """
+    Full parser — returns a list of PlanStep objects with index, description,
+    optional name, and dependency list.
+
+    Handles mixed input styles (numbered, bulleted, arrow/semicolon chained).
+    """
+    if not raw or not raw.strip():
+        return []
+
+    text = raw.strip()
+
+    # ── Strategy 1: multiline numbered or bulleted steps ─────────────────────
+    lines = [ln.strip() for ln in text.splitlines() if ln.strip()]
+    if len(lines) >= 2:
+        steps = _parse_lines(lines)
+        if steps:
+            return steps
+
+    # ── Strategy 2: inline arrow chain  fetch quote -> chart -> report ───────
+    # Also handles semicolons within arrow-separated parts:
+    #   "git status -> rg TODO . ; pytest -q"  →  3 steps
+    if "->" in text:
+        arrow_parts = [p.strip() for p in text.replace("→", "->").split("->") if p.strip()]
+        parts: List[str] = []
+        for ap in arrow_parts:
+            if ";" in ap:
+                parts.extend(p.strip() for p in ap.split(";") if p.strip())
+            else:
+                parts.append(ap)
+        return [PlanStep(index=i + 1, description=p) for i, p in enumerate(parts)]
+
+    # ── Strategy 3: semicolon-separated steps ────────────────────────────────
+    if ";" in text:
+        parts = [p.strip() for p in text.split(";") if p.strip()]
+        return [PlanStep(index=i + 1, description=p) for i, p in enumerate(parts)]
+
+    # ── Strategy 4: single step ───────────────────────────────────────────────
+    desc, name, deps = _strip_meta(text)
+    return [PlanStep(index=1, description=desc, name=name, deps=deps)] if desc else []
+
+
+def _parse_lines(lines: List[str]) -> List[PlanStep]:
+    """Try to extract ordered steps from a list of text lines."""
+    steps: List[PlanStep] = []
+    expected_idx = 1
+
+    for line in lines:
+        # Try numbered pattern
+        m = _RE_NUMBERED.match(line)
+        if m:
+            idx = int(m.group(1))
+            desc_raw = m.group(2).strip()
+            desc, name, deps = _strip_meta(desc_raw)
+            if desc:
+                steps.append(PlanStep(index=idx, description=desc, name=name, deps=deps))
+            expected_idx = idx + 1
+            continue
+
+        # Try bullet pattern
+        m = _RE_BULLET.match(line)
+        if m:
+            desc_raw = m.group(1).strip()
+            desc, name, deps = _strip_meta(desc_raw)
+            if desc:
+                steps.append(PlanStep(index=expected_idx, description=desc, name=name, deps=deps))
+                expected_idx += 1
+            continue
+
+    return steps
+
+
+# ── Formatting helpers ────────────────────────────────────────────────────────
+
+def format_plan(steps: List[PlanStep], title: str = "Plan") -> str:
+    """Format a plan for terminal display."""
+    if not steps:
+        return f"[{title}] (empty)"
+    lines = [f"── {title} ({len(steps)} steps) ──"]
+    for s in steps:
+        dep_str = f"  (after {', '.join(str(d) for d in s.deps)})" if s.deps else ""
+        label   = f" [{s.name}]" if s.name else ""
+        lines.append(f"  {s.index}.{label} {s.description}{dep_str}")
+    return "\n".join(lines)
+
+
+def steps_to_prompt(steps: List[PlanStep], context: str = "") -> str:
+    """
+    Convert a list of PlanStep objects to a structured prompt string
+    that the AI can execute step-by-step.
+    """
+    intro = f"{context}\n\n" if context else ""
+    numbered = "\n".join(f"{s.index}. {s.description}" for s in steps)
+    return (
+        f"{intro}"
+        f"Execute the following plan steps in order:\n\n"
+        f"{numbered}\n\n"
+        "Complete each step fully before moving to the next. "
+        "After all steps, provide a brief summary of what was accomplished."
+    )

plugin_loader.py

@@ -0,0 +1,328 @@
+"""
+plugin_loader.py — Auto-discovery of custom tool plugins for Aria Code.
+
+Scans the current directory and its parents for ``aria_tools.py`` files and
+loads any tools they export.  This lets project-specific tools appear
+automatically in the model's tool loop without modifying aria_cli.py.
+
+Plugin contract (aria_tools.py)::
+
+    # Minimal example
+    def get_my_tools():
+        return [
+            {
+                "name":        "my_custom_tool",
+                "description": "Does something useful for this project",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "input": {"type": "string", "description": "Input data"},
+                    },
+                    "required": ["input"],
+                },
+                "handler": lambda params: {"result": params["input"].upper()},
+            }
+        ]
+
+    # Extended example with finance tools
+    import akshare as ak
+
+    def get_my_tools():
+        def fetch_my_positions(params):
+            # read from broker API / local file
+            return {"positions": [...]}
+
+        return [
+            {
+                "name":        "get_my_positions",
+                "description": "Return current portfolio positions from local CSV",
+                "parameters":  {"type": "object", "properties": {}, "required": []},
+                "handler":     fetch_my_positions,
+            },
+        ]
+
+Discovery order
+---------------
+1. ``./aria_tools.py``  (current working directory)
+2. ``../aria_tools.py`` (one level up)
+3. …up to $HOME
+
+The first file found is used.  Set ``ARIA_TOOLS_PATH`` env var to override.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import os
+import pathlib
+import sys
+import traceback
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Env override
+ARIA_TOOLS_ENV = "ARIA_TOOLS_PATH"
+PLUGIN_FILENAME = "aria_tools.py"
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+def find_plugin_file(start_dir: Optional[str] = None) -> Optional[pathlib.Path]:
+    """
+    Walk upward from *start_dir* looking for aria_tools.py.
+    Returns the first match, or None.
+    """
+    # Env var override takes priority
+    env_path = os.getenv(ARIA_TOOLS_ENV)
+    if env_path:
+        p = pathlib.Path(env_path).expanduser().resolve()
+        if p.exists():
+            return p
+
+    home    = pathlib.Path.home()
+    current = pathlib.Path(start_dir or os.getcwd()).resolve()
+
+    while True:
+        candidate = current / PLUGIN_FILENAME
+        if candidate.exists() and candidate.is_file():
+            return candidate
+        if current == home or current.parent == current:
+            break
+        current = current.parent
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Loader
+# ---------------------------------------------------------------------------
+
+def load_plugin(plugin_path: pathlib.Path) -> List[Dict[str, Any]]:
+    """
+    Import *plugin_path* as a module and call its ``get_my_tools()`` function.
+
+    Returns list of tool dicts with keys:
+        name, description, parameters (JSON Schema), handler (callable)
+    """
+    try:
+        spec   = importlib.util.spec_from_file_location("aria_tools_plugin", plugin_path)
+        module = importlib.util.module_from_spec(spec)
+        # Add plugin directory to sys.path so it can import local modules
+        plugin_dir = str(plugin_path.parent)
+        if plugin_dir not in sys.path:
+            sys.path.insert(0, plugin_dir)
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        logger.warning("Plugin load error (%s): %s", plugin_path, exc)
+        logger.debug(traceback.format_exc())
+        return []
+
+    # Try standard function name first, then fallback names
+    for fn_name in ("get_my_tools", "get_tools", "register_tools", "tools"):
+        fn = getattr(module, fn_name, None)
+        if callable(fn):
+            try:
+                tools = fn()
+                if isinstance(tools, list):
+                    logger.info("Plugin %s: loaded %d tools via %s()", plugin_path.name, len(tools), fn_name)
+                    return _validate_tools(tools, plugin_path)
+            except Exception as exc:
+                logger.warning("Plugin %s: %s() raised: %s", plugin_path.name, fn_name, exc)
+                continue
+        # Also support module-level TOOLS list
+        if fn_name == "tools" and isinstance(fn, list):
+            return _validate_tools(fn, plugin_path)
+
+    logger.warning("Plugin %s: no get_my_tools() / get_tools() function found", plugin_path.name)
+    return []
+
+
+def _validate_tools(raw: List[Any], plugin_path: pathlib.Path) -> List[Dict[str, Any]]:
+    """Validate and normalise plugin tool definitions."""
+    valid = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        name    = item.get("name", "").strip()
+        desc    = item.get("description", "")
+        handler = item.get("handler") or item.get("fn") or item.get("function")
+        params  = item.get("parameters") or item.get("params") or {
+            "type": "object", "properties": {}, "required": []
+        }
+        if not name:
+            logger.debug("Plugin tool missing 'name', skipping")
+            continue
+        if not callable(handler):
+            logger.debug("Plugin tool %r has no callable handler, skipping", name)
+            continue
+        valid.append({
+            "name":        name,
+            "description": desc,
+            "parameters":  params,
+            "handler":     handler,
+            "source":      str(plugin_path),
+        })
+    return valid
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+def register_plugin_tools(
+    tool_registry: Dict,
+    schema_registry: List,
+    start_dir: Optional[str] = None,
+    overwrite: bool = False,
+) -> Tuple[int, Optional[pathlib.Path]]:
+    """
+    Auto-discover and register plugin tools.
+
+    Returns (count_registered, plugin_path_or_None).
+    """
+    plugin_path = find_plugin_file(start_dir)
+    if plugin_path is None:
+        return 0, None
+
+    tools = load_plugin(plugin_path)
+    if not tools:
+        return 0, plugin_path
+
+    added = 0
+    existing_names = set(tool_registry.keys())
+    existing_schema_names = {
+        s.get("function", {}).get("name") for s in schema_registry
+    }
+
+    for tool in tools:
+        name    = tool["name"]
+        handler = tool["handler"]
+        desc    = tool["description"]
+        params  = tool["parameters"]
+
+        if name in existing_names and not overwrite:
+            logger.debug("Plugin tool %r skipped (already registered)", name)
+            continue
+
+        # Wrap handler with error guard
+        def _safe_handler(p: dict, h: Callable = handler) -> dict:
+            try:
+                result = h(p)
+                if not isinstance(result, dict):
+                    result = {"result": result}
+                return result
+            except Exception as exc:
+                return {"success": False, "error": str(exc), "source": "plugin"}
+
+        tool_registry[name] = (_safe_handler, desc)
+        added += 1
+
+        if name not in existing_schema_names:
+            schema_registry.append({
+                "type": "function",
+                "function": {
+                    "name":        name,
+                    "description": desc,
+                    "parameters":  params,
+                },
+            })
+
+    if added:
+        logger.info("Plugin %s: registered %d tools", plugin_path.name, added)
+
+    return added, plugin_path
+
+
+# ---------------------------------------------------------------------------
+# Hot-reload support
+# ---------------------------------------------------------------------------
+
+class PluginWatcher:
+    """
+    Watch the plugin file for changes and reload tools automatically.
+    Uses simple mtime polling (no watchdog dependency needed).
+    """
+
+    def __init__(
+        self,
+        tool_registry: Dict,
+        schema_registry: List,
+        start_dir: Optional[str] = None,
+        poll_interval: float = 3.0,
+    ):
+        self._tool_registry   = tool_registry
+        self._schema_registry = schema_registry
+        self._start_dir       = start_dir
+        self._poll_interval   = poll_interval
+        self._plugin_path:    Optional[pathlib.Path] = None
+        self._last_mtime:     float = 0.0
+        self._task:           Optional[Any] = None  # asyncio.Task
+        self._plugin_tool_names: List[str] = []
+
+    async def start(self):
+        """Start the background polling task."""
+        import asyncio
+        # Initial load
+        n, path = register_plugin_tools(
+            self._tool_registry, self._schema_registry, self._start_dir
+        )
+        if path:
+            self._plugin_path = path
+            self._last_mtime  = path.stat().st_mtime
+            self._plugin_tool_names = [
+                t["name"] for t in load_plugin(path)
+            ]
+            if n:
+                logger.info("PluginWatcher: initial load %d tools from %s", n, path.name)
+
+        self._task = asyncio.create_task(self._watch_loop())
+
+    async def _watch_loop(self):
+        import asyncio
+        while True:
+            await asyncio.sleep(self._poll_interval)
+            if self._plugin_path is None:
+                # Try to find newly created plugin
+                found = find_plugin_file(self._start_dir)
+                if found:
+                    self._plugin_path = found
+                    self._last_mtime  = 0.0
+            if self._plugin_path and self._plugin_path.exists():
+                mtime = self._plugin_path.stat().st_mtime
+                if mtime != self._last_mtime:
+                    self._last_mtime = mtime
+                    await self._reload()
+
+    async def _reload(self):
+        if not self._plugin_path:
+            return
+        # Remove previously registered plugin tools
+        for name in self._plugin_tool_names:
+            self._tool_registry.pop(name, None)
+        # Remove from schema registry
+        self._schema_registry[:] = [
+            s for s in self._schema_registry
+            if s.get("function", {}).get("name") not in self._plugin_tool_names
+        ]
+        # Re-register
+        n, _ = register_plugin_tools(
+            self._tool_registry, self._schema_registry,
+            str(self._plugin_path.parent), overwrite=True
+        )
+        self._plugin_tool_names = [
+            t["name"] for t in load_plugin(self._plugin_path)
+        ]
+        logger.info("PluginWatcher: hot-reloaded %d tools from %s", n, self._plugin_path.name)
+
+    async def stop(self):
+        if self._task:
+            self._task.cancel()
+            try:
+                import asyncio
+                await asyncio.wait_for(self._task, timeout=1.0)
+            except Exception:
+                pass
+            self._task = None