autodevloop 0.1.0__py3-none-any.whl

autodevloop/llm.py

@@ -0,0 +1,259 @@
+"""Provider-agnostic LLM CLI invocation with retry, backoff, and cost tracking.
+
+Only the CLI command differs between providers (claude / codex / gemini); no
+API keys are handled here. Users authenticate their CLI of choice beforehand.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import re
+import shutil
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass
+class LLMResult:
+    text: str
+    cost_usd: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    duration_s: float = 0.0
+    raw: str = ""
+    attempts: int = 1
+
+
+@dataclass
+class CallStats:
+    cost_usd: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    calls: int = 0
+    by_label: dict[str, Any] = field(default_factory=dict)
+
+    def add(self, label: str, result: LLMResult) -> None:
+        self.cost_usd += result.cost_usd
+        self.input_tokens += result.input_tokens
+        self.output_tokens += result.output_tokens
+        self.calls += 1
+        bucket = self.by_label.setdefault(label, {"cost_usd": 0.0, "input_tokens": 0, "output_tokens": 0, "calls": 0})
+        bucket["cost_usd"] += result.cost_usd
+        bucket["input_tokens"] += result.input_tokens
+        bucket["output_tokens"] += result.output_tokens
+        bucket["calls"] += 1
+
+
+class TransientError(RuntimeError):
+    pass
+
+
+def _split_command(command: str) -> list[str]:
+    if os.name == "nt":
+        parts = [next(g for g in m if g) for m in re.findall(r'"([^"]+)"|\'([^\']+)\'|(\S+)', command)]
+    else:
+        import shlex
+
+        parts = shlex.split(command)
+    return parts or ["claude"]
+
+
+def resolve_command(command: str) -> list[str]:
+    parts = _split_command(command)
+    executable = parts[0]
+    expanded = Path(executable).expanduser()
+    if expanded.exists():
+        parts[0] = str(expanded.resolve())
+        return parts
+    resolved = shutil.which(executable)
+    if resolved:
+        parts[0] = resolved
+        return parts
+    if os.name == "nt" and executable.lower() in {"claude", "claude.exe", "claude.cmd", "claude.bat"}:
+        home = Path.home()
+        for candidate in [
+            home / ".local" / "bin" / "claude.exe",
+            home / ".local" / "bin" / "claude.cmd",
+            home / "AppData" / "Roaming" / "npm" / "claude.cmd",
+            home / "AppData" / "Roaming" / "npm" / "claude.exe",
+        ]:
+            if candidate.exists():
+                parts[0] = str(candidate.resolve())
+                return parts
+    return parts
+
+
+def _parse_claude_json(stdout: str) -> tuple[str, float, int, int]:
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError:
+        return stdout, 0.0, 0, 0
+    if not isinstance(data, dict):
+        return stdout, 0.0, 0, 0
+    text = data.get("result") or data.get("text") or ""
+    cost = float(data.get("total_cost_usd") or data.get("cost_usd") or 0.0)
+    usage = data.get("usage") or {}
+    in_tok = int(usage.get("input_tokens", 0) or 0) + int(usage.get("cache_read_input_tokens", 0) or 0) + int(usage.get("cache_creation_input_tokens", 0) or 0)
+    out_tok = int(usage.get("output_tokens", 0) or 0)
+    return text if isinstance(text, str) else stdout, cost, in_tok, out_tok
+
+
+_TRANSIENT_PATTERNS = (
+    "overloaded", "rate limit", "rate_limit", "429", "503", "502", "500",
+    "timeout", "timed out", "connection reset", "temporarily", "try again",
+    "econnreset", "etimedout", "service unavailable",
+)
+
+
+def _looks_transient(text: str) -> bool:
+    low = text.lower()
+    return any(p in low for p in _TRANSIENT_PATTERNS)
+
+
+def call(
+    profile: dict[str, Any],
+    prompt: str,
+    cwd: Path,
+    *,
+    label: str = "LLM",
+    timeout: int = 1800,
+    retries: int = 3,
+    backoff_seconds: float = 5.0,
+    debug_file: Path | None = None,
+    on_status: Callable[[str], None] | None = None,
+) -> LLMResult:
+    """Invoke the configured provider CLI once, with retry on transient errors."""
+    last_error = ""
+    for attempt in range(1, max(1, retries) + 1):
+        try:
+            result = _invoke_once(
+                profile, prompt, cwd, label=label, timeout=timeout,
+                debug_file=debug_file, on_status=on_status,
+            )
+            result.attempts = attempt
+            return result
+        except TransientError as exc:
+            last_error = str(exc)
+            if attempt >= retries:
+                break
+            delay = backoff_seconds * (2 ** (attempt - 1)) + random.uniform(0, backoff_seconds)
+            if on_status:
+                on_status(f"transient failure (attempt {attempt}/{retries}); retrying in {int(delay)}s")
+            time.sleep(delay)
+    raise RuntimeError(f"{label}: provider call failed after {retries} attempts. Last error:\n{last_error}")
+
+
+def _invoke_once(
+    profile: dict[str, Any],
+    prompt: str,
+    cwd: Path,
+    *,
+    label: str,
+    timeout: int,
+    debug_file: Path | None,
+    on_status: Callable[[str], None] | None,
+) -> LLMResult:
+    command = resolve_command(str(profile.get("command") or "claude"))
+    args = list(profile.get("args") or [])
+    full = [*command, *args]
+    model = profile.get("model")
+    if model:
+        full.extend([str(profile.get("model_flag") or "--model"), str(model)])
+    full.extend(list(profile.get("extra_args") or []))
+    if debug_file is not None and profile.get("name") == "claude":
+        full.extend(["--debug-file", str(debug_file)])
+
+    prompt_via = str(profile.get("prompt_via", "stdin"))
+    use_stdin = prompt_via == "stdin"
+    if not use_stdin:
+        full.append(prompt)
+
+    start = time.time()
+    try:
+        process = subprocess.Popen(
+            full,
+            cwd=str(cwd),
+            stdin=subprocess.PIPE if use_stdin else subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            f"Provider command not found: {profile.get('command')!r}. Install the CLI "
+            "and add it to PATH, or change the provider command in settings."
+        ) from exc
+
+    stderr_lines: list[str] = []
+    last_activity = [time.time()]
+    done = threading.Event()
+
+    def drain_stderr() -> None:
+        assert process.stderr is not None
+        for line in process.stderr:
+            stripped = line.rstrip()
+            stderr_lines.append(stripped)
+            if stripped:
+                last_activity[0] = time.time()
+                if on_status and any(kw in stripped.lower() for kw in ("write", "edit", "read", "tool", "error", "warn", "create")):
+                    on_status(stripped[:160])
+
+    def feed_stdin() -> None:
+        if not use_stdin or process.stdin is None:
+            return
+        try:
+            process.stdin.write(prompt)
+            process.stdin.close()
+        except (BrokenPipeError, OSError):
+            pass
+
+    # No periodic heartbeat events: the dashboard shows a live per-agent timer
+    # client-side. We only surface meaningful tool-activity lines via on_status.
+    threads = [
+        threading.Thread(target=drain_stderr, daemon=True),
+        threading.Thread(target=feed_stdin, daemon=True),
+    ]
+    for thread in threads:
+        thread.start()
+
+    try:
+        stdout, _ = process.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        done.set()
+        raise TransientError(f"{label}: provider timed out after {timeout}s")
+    finally:
+        done.set()
+
+    stderr_text = "\n".join(stderr_lines)
+    if process.returncode != 0:
+        tail = "\n".join(stderr_lines[-20:])
+        if _looks_transient(stderr_text):
+            raise TransientError(f"{label}: exit {process.returncode}. {tail}")
+        raise RuntimeError(f"{label}: provider exited with code {process.returncode}.\n{tail}")
+
+    duration = time.time() - start
+    if profile.get("output") == "claude-json":
+        text, cost, in_tok, out_tok = _parse_claude_json(stdout)
+    else:
+        text, cost, in_tok, out_tok = stdout, 0.0, 0, 0
+
+    if not text.strip() and _looks_transient(stderr_text):
+        raise TransientError(f"{label}: empty result with transient signal")
+
+    return LLMResult(
+        text=text,
+        cost_usd=cost,
+        input_tokens=in_tok,
+        output_tokens=out_tok,
+        duration_s=duration,
+        raw=stdout,
+    )

autodevloop/prompts.py

@@ -0,0 +1,342 @@
+"""Editable prompt templates.
+
+Templates use ``{{placeholder}}`` markers so literal JSON braces in the body
+stay untouched. Defaults are written into ``.autodev/prompts/templates`` on
+first run; users (or the web settings page) can edit those files freely. The
+fixed pipeline stays standardised while the prompt wording remains open for
+the model to exercise judgement.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from .util import read_text, write_text
+
+_PLACEHOLDER = re.compile(r"{{\s*(\w+)\s*}}")
+
+DEFAULT_TEMPLATES: dict[str, str] = {
+    "arch": """
+You are AgentARCH, the founding architect for this project.
+
+User goal:
+{{goal}}
+
+Extra architecture hints from the user (may be empty):
+{{arch_hint}}
+
+Choose a mainstream, well-supported technology stack, a clean directory
+layout, a run strategy, a test strategy, and acceptance criteria. Favour
+conventional, popular frameworks and project structures over exotic choices.
+Keep the architecture general enough that future versions can evolve the
+product without drifting from the user's goal.
+
+Create or update docs/project_design.md in the working directory with the
+chosen design. Then return a concise Markdown architecture report covering:
+- Project type
+- Tech stack (and why it is a mainstream choice)
+- Directory layout
+- Run instructions
+- Test strategy and pass criteria
+- How future versions should split work across agents
+- Product boundaries: what to add only when it clearly serves the goal
+""".strip(),
+    "plan": """
+You are AgentPLAN for version v{{version}} (phase: {{phase}}).
+
+User goal:
+{{goal}}
+
+Architecture contract (stay consistent with this):
+{{architecture}}
+
+{{phase_guidance}}
+
+Accepted feature backlog (pick from here when in the expand phase):
+{{backlog}}
+
+Previous iteration context:
+{{previous}}
+
+Current project context:
+{{context}}
+
+Decide what THIS version should deliver. If tests fail or there are real
+bugs, fixing them comes first. Otherwise advance the product meaningfully.
+You may dynamically choose how many development agents to use and what each
+one does — split work only when it can be merged safely (ideally each agent
+owns distinct files/areas).
+
+Return ONLY JSON:
+{
+  "version_goal": "...",
+  "acceptance_criteria": ["..."],
+  "dev_agents": [
+    {"name": "AgentDEV_BACKEND", "role": "backend/frontend/docs/...", "task": "...", "owns": ["path/glob", "..."]}
+  ],
+  "test_focus": ["..."],
+  "risks": ["..."]
+}
+""".strip(),
+    "dev": """
+You are {{agent_name}} for version v{{version}}.
+
+User goal:
+{{goal}}
+
+Architecture contract (do not violate the chosen stack/layout):
+{{architecture}}
+
+Version plan:
+{{plan}}
+
+Your specific task:
+{{task}}
+
+Files you own (prefer editing only these to avoid clobbering peers):
+{{owns}}
+
+Work only inside this workspace and produce runnable code. Preserve existing
+working behaviour unless the plan says to change it. Keep the project aligned
+with the user's goal; avoid unrelated features. Choose implementation details
+appropriate to the project type. Update files directly, then end with:
+
+SUMMARY:
+Added: [...]
+Changed: [...]
+Fixed: [...]
+Known issues: [...]
+""".strip(),
+    "doc": """
+You are AgentDOC for version v{{version}}.
+
+User goal:
+{{goal}}
+
+Version plan:
+{{plan}}
+
+Maintain documentation only. Update README.md and docs/project_design.md so
+run instructions stay accurate (if a local server is required, do not claim
+double-clicking the HTML works). Do not edit source code except embedded docs.
+""".strip(),
+    "test": """
+You are AgentTEST for version v{{version}}.
+
+User goal:
+{{goal}}
+
+Version plan:
+{{plan}}
+
+Detected built-in test candidates:
+{{candidates}}
+
+Current project context:
+{{context}}
+
+Decide the minimum credible test command(s) and what counts as pass. Prefer
+existing project test/build commands; otherwise pick a built-in smoke marker
+from the candidates.
+
+Return ONLY JSON:
+{
+  "commands": ["command or __builtin_marker__"],
+  "pass_criteria": ["..."],
+  "reason": "...",
+  "requires_manual_check": false
+}
+""".strip(),
+    "review": """
+You are AgentREVIEW for version v{{version}} (phase: {{phase}}).
+
+User goal:
+{{goal}}
+
+Version plan:
+{{plan}}
+
+Test result:
+{{test_result}}
+
+Development agent summaries:
+{{dev_summaries}}
+
+Current project context:
+{{context}}
+
+Score strictly but fairly. Focus on runtime breakage, missing core
+requirements, test gaps, maintainability, architecture consistency, and
+whether the work drifts from the user goal. Also judge how complete the
+ORIGINAL user goal now is (goal_met = the core requested product is fully
+usable and feature-complete, not merely bug-free). Write a short
+human-readable summary of what this version delivers.
+
+SCALE (important): "score" and "goal_progress" are integers from 0 to 100.
+Do NOT use a 0-10 scale and do NOT use a 0-1 fraction. Score guide:
+90-100 production-ready; 80-89 solid with minor issues; 60-79 works but has
+notable gaps; 40-59 partly working; 0-39 broken or far from the goal.
+goal_progress is the percent of the ORIGINAL user goal that is now done.
+
+Return ONLY JSON:
+{
+  "score": 0,
+  "blocking": false,
+  "goal_met": false,
+  "goal_progress": 0,
+  "issues": ["..."],
+  "good_points": ["..."],
+  "feature_summary": "one or two sentences on what this version does",
+  "whats_new": ["concise bullet of what changed vs the previous version"],
+  "suggestions_for_next_version": ["..."]
+}
+""".strip(),
+    "fix": """
+You are AgentFIX for version v{{version}}, attempt {{attempt}}.
+
+User goal:
+{{goal}}
+
+Original plan:
+{{plan}}
+
+Failing tests:
+{{test_result}}
+
+Review:
+{{review}}
+
+Fix only what is required to make this version usable and aligned with the
+goal. Do not add unrelated new features in a fix pass. Update files directly.
+""".strip(),
+    "scout": """
+You are AgentSCOUT for version v{{version}}. The core user goal is already
+met, so propose genuinely valuable NEW features that extend the product into
+adjacent territory a real user of this product would appreciate.
+
+User goal (already satisfied):
+{{goal}}
+
+Latest review:
+{{review}}
+
+Existing backlog (avoid duplicates):
+{{backlog}}
+
+Current project context:
+{{context}}
+
+Return ONLY JSON with candidate features (do not implement anything yet):
+{
+  "candidates": [
+    {"title": "...", "description": "...", "rationale": "why a user benefits"}
+  ]
+}
+""".strip(),
+    "evaluate": """
+You are AgentEVALUATE, an independent product reviewer. Score each candidate
+feature for whether it is worth building on top of this product.
+
+User goal:
+{{goal}}
+
+Candidate features:
+{{candidates}}
+
+For each candidate give value (0-100), effort (low/medium/high), and a verdict.
+A feature is "accepted" only when value >= {{threshold}} and it clearly serves
+or sensibly extends the product. Reject vanity or unrelated features.
+
+Return ONLY JSON:
+{
+  "evaluations": [
+    {"title": "...", "value": 0, "effort": "low|medium|high", "accepted": false, "reason": "..."}
+  ]
+}
+""".strip(),
+    "goal_check": """
+You are AgentGOALCHECK. Judge ONLY how complete the original user goal is.
+
+User goal:
+{{goal}}
+
+Latest review:
+{{review}}
+
+Current project context:
+{{context}}
+
+"goal_progress" is an integer from 0 to 100 (percent of the original user goal
+that is done). Do NOT use a 0-10 scale or a 0-1 fraction.
+
+Return ONLY JSON:
+{
+  "goal_met": false,
+  "goal_progress": 0,
+  "missing_for_goal": ["..."],
+  "reason": "..."
+}
+""".strip(),
+}
+
+TEMPLATE_NAMES = list(DEFAULT_TEMPLATES.keys())
+
+# Tokens every template MUST keep so the engine can inject context and parse the
+# reply. Users can rewrite the wording freely (any language), but removing these
+# breaks the pipeline, so the web settings page refuses to save without them.
+# - ``{{placeholder}}`` entries are context the engine substitutes in.
+# - bare-word entries are JSON keys the engine reads back out of the reply.
+REQUIRED_TOKENS: dict[str, list[str]] = {
+    "arch": ["{{goal}}", "{{arch_hint}}"],
+    "plan": ["{{version}}", "{{goal}}", "{{phase}}", "{{architecture}}",
+             "{{context}}", "version_goal", "dev_agents"],
+    "dev": ["{{agent_name}}", "{{version}}", "{{goal}}", "{{plan}}", "{{task}}"],
+    "doc": ["{{version}}", "{{goal}}", "{{plan}}"],
+    "test": ["{{version}}", "{{goal}}", "{{candidates}}", "{{context}}", "commands"],
+    "review": ["{{version}}", "{{goal}}", "{{plan}}", "{{test_result}}", "{{context}}",
+               "score", "goal_met", "goal_progress", "feature_summary", "whats_new"],
+    "fix": ["{{version}}", "{{goal}}", "{{plan}}", "{{test_result}}", "{{review}}"],
+    "scout": ["{{goal}}", "{{review}}", "{{context}}", "candidates"],
+    "evaluate": ["{{goal}}", "{{candidates}}", "{{threshold}}", "evaluations", "value", "accepted"],
+    "goal_check": ["{{goal}}", "{{review}}", "{{context}}", "goal_met", "goal_progress"],
+}
+
+
+def validate_template(name: str, body: str) -> list[str]:
+    """Return the list of required tokens missing from ``body`` (empty = valid)."""
+    required = REQUIRED_TOKENS.get(name, [])
+    text = body or ""
+    return [tok for tok in required if tok not in text]
+
+
+def templates_dir(app_dir: Path) -> Path:
+    return app_dir / "prompts" / "templates"
+
+
+def ensure_templates(app_dir: Path) -> None:
+    base = templates_dir(app_dir)
+    base.mkdir(parents=True, exist_ok=True)
+    for name, body in DEFAULT_TEMPLATES.items():
+        path = base / f"{name}.md"
+        if not path.exists():
+            write_text(path, body + "\n")
+
+
+def load_template(app_dir: Path, name: str) -> str:
+    path = templates_dir(app_dir) / f"{name}.md"
+    text = read_text(path)
+    return text if text.strip() else DEFAULT_TEMPLATES.get(name, "")
+
+
+def render(template: str, values: dict[str, Any]) -> str:
+    def repl(match: "re.Match[str]") -> str:
+        key = match.group(1)
+        return str(values.get(key, ""))
+
+    return _PLACEHOLDER.sub(repl, template).strip()
+
+
+def render_template(app_dir: Path, name: str, values: dict[str, Any]) -> str:
+    return render(load_template(app_dir, name), values)

autodevloop/registry.py

@@ -0,0 +1,37 @@
+"""A small registry of known project directories, stored in the user home.
+
+Lets the web dashboard list every project that was started via the CLI or the
+web UI, regardless of where it lives on disk.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .util import load_json, now_text, save_json
+
+
+def registry_path() -> Path:
+    return Path.home() / ".autodevloop" / "registry.json"
+
+
+def load() -> list[dict[str, Any]]:
+    data = load_json(registry_path(), {"projects": []})
+    projects = data.get("projects", []) if isinstance(data, dict) else []
+    return [p for p in projects if isinstance(p, dict)]
+
+
+def register(root: Path, name: str = "") -> None:
+    root = root.resolve()
+    projects = load()
+    entry = {"dir": str(root), "name": name or root.name, "registered_at": now_text()}
+    projects = [p for p in projects if p.get("dir") != str(root)]
+    projects.insert(0, entry)
+    save_json(registry_path(), {"projects": projects[:100]}, stamp=False)
+
+
+def remove(root: Path) -> None:
+    root = root.resolve()
+    projects = [p for p in load() if p.get("dir") != str(root)]
+    save_json(registry_path(), {"projects": projects}, stamp=False)