leanlab 0.2.1__py3-none-any.whl

leanlab/__init__.py

@@ -0,0 +1 @@
+"""leanlab — a self-improving experiment-lab tool."""

leanlab/cli.py

@@ -0,0 +1,315 @@
+"""leanlab CLI — init, run, and serve labs.
+
+leanlab is a research tool used *inside* another project (like archik). Labs live in
+that project's `.leanlab/<name>/` folder and hold only the task-specific files the user
+edits: task.md, lab.json, evaluation.py, validate.py. The engine (loop + monitor) and the
+fixed agent specs live in the installed package and are never copied into the project.
+
+Usage (inside your project):
+    uvx leanlab init <name>           # interactively scaffold a lab (Claude drafts it)
+    uvx leanlab run <lab> --n 5       # run N experiments
+    uvx leanlab serve <lab>           # open the dashboard
+    uvx leanlab list                  # list labs in this project
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from .core.init import run_init
+
+
+def _version() -> str:
+    """The installed package version (falls back when running from an uninstalled checkout)."""
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        return version("leanlab")
+    except (ImportError, PackageNotFoundError):
+        return "0.2.1"
+
+
+def labs_dir() -> Path:
+    """Where labs live: the .leanlab/ folder of the project leanlab is run inside."""
+    return Path.cwd() / ".leanlab"
+
+
+def _install_agent_skill(project: Path) -> Path:
+    from importlib import resources
+    src = (resources.files("leanlab") / "templates" / "skill" / "SKILL.md").read_text()
+    dest = project / ".claude" / "skills" / "leanlab" / "SKILL.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(src)
+    return dest
+
+
+_CLAUDE_MD_MARKER = "<!-- leanlab:agent -->"
+_CLAUDE_MD_BLOCK = (
+    f"{_CLAUDE_MD_MARKER}\n"
+    "## Coding tasks — use leanlab\n\n"
+    "For feature / fix / refactor work on this repo, drive it through **leanlab** (the honest, "
+    "test-gated loop) instead of editing files directly. See `.claude/skills/leanlab/SKILL.md`.\n"
+    "Flow: `leanlab spec \"<task>\" --yes` → read the `slug:` line → `leanlab build <slug>` → report.\n"
+    f"{_CLAUDE_MD_MARKER}\n"
+)
+
+
+def _append_claude_md(project: Path) -> bool:
+    """Append the leanlab guidance to the project's CLAUDE.md (idempotent). True if it changed."""
+    p = project / "CLAUDE.md"
+    text = p.read_text() if p.exists() else ""
+    if _CLAUDE_MD_MARKER in text:
+        return False
+    sep = "" if (not text or text.endswith("\n")) else "\n"
+    p.write_text(text + sep + "\n" + _CLAUDE_MD_BLOCK)
+    return True
+
+
+def cmd_init(args):
+    if args.for_agent:
+        dest = _install_agent_skill(Path.cwd())
+        print(f"✓ leanlab skill installed at {dest}")
+        if _append_claude_md(Path.cwd()):
+            print("✓ added leanlab guidance to CLAUDE.md")
+        else:
+            print("• CLAUDE.md already mentions leanlab — left it as is")
+        print("Claude Code in this project can now drive leanlab (spec → build → merge).")
+        return
+    import questionary
+    if not args.name:
+        print("ERROR: a lab name is required (or use `leanlab init --for-agent`).", file=sys.stderr)
+        sys.exit(1)
+    lab = labs_dir() / args.name
+    if lab.exists():
+        print(f"ERROR: {lab} already exists.", file=sys.stderr)
+        sys.exit(1)
+    description = (args.describe
+                  or questionary.text("Describe the task you want to research:").ask() or "").strip()
+    if not description:
+        print("ERROR: a task description is required.", file=sys.stderr)
+        sys.exit(1)
+    run_init(lab, args.name, description, yes=args.yes)
+
+
+def cmd_spec(args):
+    from .core.coding.spec import spec_task
+    res = spec_task(Path.cwd(), args.task, yes=args.yes)
+    if res:
+        print(f"slug: {Path(res['worktree']).name}")     # plain line for an agent to parse
+    sys.exit(0 if res else 1)
+
+
+def cmd_build(args):
+    from .core.coding.engineer import build_task
+    cmds = [{"name": "tests", "cmd": args.test_cmd or "pytest -q"}]
+    if args.lint_cmd:
+        cmds.append({"name": "lint", "cmd": args.lint_cmd})
+    res = build_task(Path.cwd(), args.slug, gate_cmds=cmds, persona_set=args.persona_set,
+                     max_attempts=args.max_attempts, playbook=not args.no_playbook,
+                     min_quality=args.min_quality, isolate=not args.no_isolate,
+                     accept_cmd=args.accept_cmd, reviewers=args.reviewers)
+    sys.exit(0 if (res and res.get("merged")) else 1)
+
+
+def cmd_clean(args):
+    from .core.coding.spec import clean_worktrees
+    removed = clean_worktrees(Path.cwd(), args.slug, remove_all=args.all)
+    print(f"removed {len(removed)} worktree(s): {', '.join(removed) or '(none)'}")
+
+
+def cmd_board(args):
+    from .core.coding.board import serve_board
+    serve_board(Path.cwd(), port=args.port or 8766, open_browser=not args.no_open)
+
+
+def cmd_gate(args):
+    from .core.coding.gate import run_gate, report
+    wt = labs_dir() / "worktrees" / args.slug
+    if not wt.is_dir():
+        print(f"ERROR: no worktree at {wt} — run `leanlab spec` first.", file=sys.stderr)
+        sys.exit(1)
+    cmds = [{"name": "tests", "cmd": args.test_cmd or "pytest -q"}]
+    if args.lint_cmd:
+        cmds.append({"name": "lint", "cmd": args.lint_cmd})
+    res = run_gate(wt, cmds)
+    report(res)
+    sys.exit(0 if res.passed else 1)
+
+
+def cmd_check(args):
+    from .core.doctor import check_lab, RichReport, ok
+    lab = _resolve_lab(args.lab)
+    checks = check_lab(lab)
+    RichReport().report(checks)
+    sys.exit(0 if ok(checks) else 1)
+
+
+def cmd_fix(args):
+    from .core.doctor import fix_lab
+    lab = _resolve_lab(args.lab)
+    sys.exit(0 if fix_lab(lab) else 1)
+
+
+def cmd_run(args):
+    lab = _resolve_lab(args.lab)
+    if not args.skip_checks and not args.dry_run:
+        from .core.doctor import check_lab, RichReport, ok
+        checks = check_lab(lab)
+        if not ok(checks):
+            RichReport().report(checks)
+            print(f"\nRun blocked by failed checks. Fix them with:  leanlab fix {args.lab}\n"
+                  f"(or rerun with --skip-checks to ignore)", file=sys.stderr)
+            sys.exit(1)
+    cmd = [sys.executable, "-m", "leanlab.core.loop", "--lab", str(lab), "--n", str(args.n)]
+    if args.dry_run:
+        cmd.append("--dry-run")
+    sys.exit(subprocess.run(cmd).returncode)
+
+
+def cmd_serve(args):
+    lab = _resolve_lab(args.lab)
+    cmd = [sys.executable, "-m", "leanlab.core.monitor", "--lab", str(lab)]
+    if args.port:
+        cmd += ["--port", str(args.port)]
+    sys.exit(subprocess.run(cmd).returncode)
+
+
+def cmd_list(_args):
+    base = labs_dir()
+    if not base.exists():
+        print("(no labs yet — run `leanlab init <name>`)")
+        return
+    for d in sorted(base.iterdir()):
+        if (d / "lab.json").exists():
+            cfg = json.loads((d / "lab.json").read_text())
+            obj = cfg.get("objective", {})
+            print(f"  {d.name:20} objective: {obj.get('direction')} {obj.get('metric')}")
+
+
+def _evaluator(lab):
+    ev = lab / "evaluation.py"
+    if not ev.exists():
+        print(f"ERROR: no evaluation.py in {lab}", file=sys.stderr)
+        sys.exit(1)
+    return ev
+
+
+def cmd_lock(args):
+    """Make the lab's evaluation.py read-only — a guardrail against accidental edits.
+
+    Note: this is a speed bump, not a sandbox. An agent running as you with full
+    tools could chmod it back. For a hard wall, run the Worker as a separate user.
+    """
+    ev = _evaluator(_resolve_lab(args.lab))
+    ev.chmod(0o444)
+    print(f"🔒 locked {ev} read-only. Run `leanlab unlock {args.lab}` to edit it.")
+
+
+def cmd_unlock(args):
+    ev = _evaluator(_resolve_lab(args.lab))
+    ev.chmod(0o644)
+    print(f"🔓 unlocked {ev}. Edit it, then `leanlab lock {args.lab}` again.")
+
+
+def _resolve_lab(name):
+    p = Path(name)
+    if p.exists() and (p / "lab.json").exists():
+        return p.resolve()
+    if (labs_dir() / name / "lab.json").exists():
+        return (labs_dir() / name).resolve()
+    print(f"ERROR: lab '{name}' not found in {labs_dir()}.", file=sys.stderr)
+    sys.exit(1)
+
+
+def main():
+    p = argparse.ArgumentParser(description="leanlab CLI")
+    p.add_argument("--version", action="version", version=f"leanlab {_version()}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pi = sub.add_parser("init", help="scaffold a lab (Claude drafts it), or --for-agent to install the skill")
+    pi.add_argument("name", nargs="?", default=None)
+    pi.add_argument("--for-agent", action="store_true",
+                    help="install the leanlab skill into .claude/ so Claude Code can drive leanlab")
+    pi.add_argument("--describe", default=None, help="task description (skips the prompt)")
+    pi.add_argument("--yes", action="store_true", help="auto-approve the drafted evaluator (headless)")
+    pi.set_defaults(func=cmd_init)
+
+    pr = sub.add_parser("run", help="run N experiments in a lab")
+    pr.add_argument("lab")
+    pr.add_argument("--n", type=int, default=5)
+    pr.add_argument("--dry-run", action="store_true")
+    pr.add_argument("--skip-checks", action="store_true", help="skip the preflight doctor checks")
+    pr.set_defaults(func=cmd_run)
+
+    psp = sub.add_parser("spec", help="(coding) turn a task into approved, locked acceptance tests")
+    psp.add_argument("task", help="the coding task, e.g. \"create a /health endpoint\"")
+    psp.add_argument("--yes", action="store_true", help="auto-approve the drafted tests (headless)")
+    psp.set_defaults(func=cmd_spec)
+
+    pb = sub.add_parser("build", help="(coding) engineer the task to a green gate + review, then merge")
+    pb.add_argument("slug", help="the task worktree name under .leanlab/worktrees/")
+    pb.add_argument("--persona-set", default="coding", help="agent persona set (default: coding)")
+    pb.add_argument("--max-attempts", type=int, default=5)
+    pb.add_argument("--test-cmd", default=None, help="test command (default: pytest -q)")
+    pb.add_argument("--lint-cmd", default=None, help="optional lint/typecheck command")
+    pb.add_argument("--no-playbook", action="store_true", help="skip the tech-lead PLAYBOOK update")
+    pb.add_argument("--min-quality", type=float, default=0, help="reject merges below this 0-100 quality score")
+    pb.add_argument("--reviewers", type=int, default=1,
+                    help="adversarial reviewer panel size; >1 runs that many reviewers with "
+                         "different lenses (correctness/spec/security/robustness) and merges only "
+                         "if all approve")
+    pb.add_argument("--no-isolate", action="store_true",
+                    help="skip the isolated acceptance re-run (which disables engineer conftest)")
+    pb.add_argument("--accept-cmd", default="pytest --noconftest -q",
+                    help="isolated acceptance command (pristine test paths are appended)")
+    pb.set_defaults(func=cmd_build)
+
+    pcl = sub.add_parser("clean", help="(coding) remove task worktrees + branches (merged only by default)")
+    pcl.add_argument("slug", nargs="?", default=None, help="a specific task to remove (force)")
+    pcl.add_argument("--all", action="store_true", help="remove ALL task worktrees (force)")
+    pcl.set_defaults(func=cmd_clean)
+
+    pbd = sub.add_parser("board", help="(coding) live dashboard of tasks, status, and the playbook")
+    pbd.add_argument("--port", type=int, default=0)
+    pbd.add_argument("--no-open", action="store_true")
+    pbd.set_defaults(func=cmd_board)
+
+    pg = sub.add_parser("gate", help="(coding) run the pass/fail gate on a task's worktree")
+    pg.add_argument("slug", help="the task worktree name under .leanlab/worktrees/")
+    pg.add_argument("--test-cmd", default=None, help="test command (default: pytest -q)")
+    pg.add_argument("--lint-cmd", default=None, help="optional lint/typecheck command")
+    pg.set_defaults(func=cmd_gate)
+
+    pc = sub.add_parser("check", help="preflight: verify the lab is wired correctly")
+    pc.add_argument("lab")
+    pc.set_defaults(func=cmd_check)
+
+    pf = sub.add_parser("fix", help="use Claude to fix lab wiring problems the checks found")
+    pf.add_argument("lab")
+    pf.set_defaults(func=cmd_fix)
+
+    ps = sub.add_parser("serve", help="open the dashboard for a lab")
+    ps.add_argument("lab")
+    ps.add_argument("--port", type=int, default=0)
+    ps.set_defaults(func=cmd_serve)
+
+    pl = sub.add_parser("list", help="list labs")
+    pl.set_defaults(func=cmd_list)
+
+    pk = sub.add_parser("lock", help="make a lab's evaluation.py read-only (frozen)")
+    pk.add_argument("lab")
+    pk.set_defaults(func=cmd_lock)
+
+    pu = sub.add_parser("unlock", help="restore write access to a lab's evaluation.py")
+    pu.add_argument("lab")
+    pu.set_defaults(func=cmd_unlock)
+
+    args = p.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

leanlab/core/__init__.py

@@ -0,0 +1 @@
+"""leanlab engine — the generic loop, dashboard, and agent layer."""

leanlab/core/agents/__init__.py

@@ -0,0 +1,10 @@
+"""Agent ports & adapters — the backend-agnostic agent layer the loop depends on."""
+
+from .claude import ClaudeAgent
+from .port import AgentResult, AgentRunner, AgentTransport
+from .protocol import StructuredRunner, extract_json
+
+__all__ = [
+    "AgentResult", "AgentRunner", "AgentTransport",
+    "StructuredRunner", "extract_json", "ClaudeAgent",
+]

leanlab/core/agents/claude.py

@@ -0,0 +1,38 @@
+"""ClaudeAgent — an AgentTransport backed by the Claude Code CLI (claude -p).
+
+One concrete backend. Hermes / custom backends would be sibling AgentTransports;
+the loop, which depends only on AgentRunner, would not change.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from .port import AgentTransport
+
+
+class ClaudeAgent(AgentTransport):
+    """Runs one agent turn via `claude -p --output-format json`, in a lab's cwd."""
+
+    def __init__(self, cwd, *, max_turns: int = 250, permission_mode: str = "bypassPermissions"):
+        self._cwd = Path(cwd)
+        self._max_turns = max_turns
+        self._permission_mode = permission_mode
+
+    def send(self, prompt: str, *, session: str | None = None) -> tuple[str | None, str]:
+        cmd = ["claude", "-p", prompt,
+               "--permission-mode", self._permission_mode,
+               "--max-turns", str(self._max_turns),
+               "--output-format", "json"]
+        if session:
+            cmd += ["--resume", session]
+        proc = subprocess.run(cmd, cwd=self._cwd, capture_output=True, text=True)
+        if proc.returncode != 0 and not proc.stdout.strip():
+            raise RuntimeError(proc.stderr.strip() or "claude CLI failed")
+        try:
+            env = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            return None, proc.stdout  # let the protocol treat it as malformed
+        return env.get("session_id"), env.get("result", "")

leanlab/core/agents/port.py

@@ -0,0 +1,49 @@
+"""Agent ports — the abstraction the loop depends on (Dependency Inversion).
+
+The loop never talks to a concrete agent backend. It depends on `AgentRunner`.
+A backend implements the low-level `AgentTransport` (send one prompt, get text);
+`StructuredRunner` (protocol.py) adapts a transport into an `AgentRunner` by
+adding JSON validation and retry. Swapping in Hermes or a custom backend means a
+new `AgentTransport` — nothing in the loop changes (open/closed).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentResult:
+    """The outcome of one structured agent turn."""
+
+    data: dict              # validated JSON the agent returned ({} if it never produced valid output)
+    session_id: str | None = None   # to resume the same agent session
+    raw: str = ""           # the agent's last raw reply, for diagnostics
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.data)
+
+
+class AgentTransport(ABC):
+    """Low-level: send one prompt to an agent backend, get back (session_id, text)."""
+
+    @abstractmethod
+    def send(self, prompt: str, *, session: str | None = None) -> tuple[str | None, str]:
+        """Run one turn. Return (session_id, final_text). Raise on transport failure."""
+        raise NotImplementedError
+
+
+class AgentRunner(ABC):
+    """High-level: what the loop depends on — structured output and fire-and-forget."""
+
+    @abstractmethod
+    def run_structured(self, prompt: str, required_keys, *, session: str | None = None) -> AgentResult:
+        """Run a turn and return a JSON object that contains all `required_keys`."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def run_plain(self, prompt: str) -> None:
+        """Run a fire-and-forget turn (e.g. the Director or Critic writing a file)."""
+        raise NotImplementedError

leanlab/core/agents/protocol.py

@@ -0,0 +1,64 @@
+"""StructuredRunner — turns any AgentTransport into an AgentRunner.
+
+It enforces the structured-output contract: parse the agent's reply as JSON,
+check the required keys, and on malformed output re-prompt the SAME session
+("reply with ONLY that JSON object") up to a retry limit. This is the one place
+the "agent must return valid structured output" rule lives.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from .port import AgentResult, AgentRunner, AgentTransport
+
+
+def extract_json(text: str, required_keys) -> dict | None:
+    """Return a JSON object in `text` containing all `required_keys`, or None.
+
+    Tries the whole text first, then the last embedded {...} block — agents
+    sometimes wrap the object in prose or code fences.
+    """
+    if not text:
+        return None
+    text = text.strip()
+    candidates = []
+    try:
+        candidates.append(json.loads(text))
+    except json.JSONDecodeError:
+        pass
+    for m in re.finditer(r"\{[^{}]*\}", text, re.DOTALL):
+        try:
+            candidates.append(json.loads(m.group(0)))
+        except json.JSONDecodeError:
+            continue
+    for obj in reversed(candidates):
+        if isinstance(obj, dict) and all(k in obj for k in required_keys):
+            return obj
+    return None
+
+
+class StructuredRunner(AgentRunner):
+    """Wraps a transport: validate the JSON reply, re-prompt on malformed output."""
+
+    def __init__(self, transport: AgentTransport, max_retries: int = 2):
+        self._transport = transport
+        self._max_retries = max_retries
+
+    def run_structured(self, prompt, required_keys, *, session=None) -> AgentResult:
+        attempt_prompt, session_id, last_text = prompt, session, ""
+        for _attempt in range(self._max_retries + 1):
+            session_id, last_text = self._transport.send(attempt_prompt, session=session_id)
+            data = extract_json(last_text, required_keys)
+            if data is not None:
+                return AgentResult(data=data, session_id=session_id, raw=last_text)
+            # Malformed — correct and retry in the SAME session.
+            attempt_prompt = (
+                "Your last reply was NOT a valid JSON object with keys "
+                f"{list(required_keys)}. Reply with ONLY that JSON object — no prose, no code fence."
+            )
+        return AgentResult(data={}, session_id=session_id, raw=last_text)
+
+    def run_plain(self, prompt) -> None:
+        self._transport.send(prompt)

leanlab/core/coding/__init__.py

@@ -0,0 +1 @@
+"""Coding lab — Worker/Director/Critic over a real repo, judged by tests + quality."""