loopcaptain 0.3.1__py3-none-any.whl

loopcaptain/board/trend.py

@@ -0,0 +1,185 @@
+"""Small charts of a loop's rounds, drawn as SVG on the server: is it converging?
+
+No script and no chart library: the content policy allows neither, and a line of a dozen points
+needs neither. Each chart is one series over the rounds, with the loop's target where it gave one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from loopcaptain.protocol.state import LoopState
+
+WIDTH = 240
+HEIGHT = 64
+PAD = 6
+
+
+@dataclass(frozen=True)
+class Series:
+    name: str
+    values: tuple[tuple[int, float], ...]  # (round number, value), rounds without a value left out
+    unit: str = ""
+    target: float | None = None
+    better: str | None = None
+
+
+@dataclass(frozen=True)
+class Dot:
+    x: float
+    y: float
+    round: int
+    value: float
+
+
+@dataclass(frozen=True)
+class Chart:
+    series: Series
+    path: str
+    dots: tuple[Dot, ...]
+    target_y: float | None
+    width: int = WIDTH
+    height: int = HEIGHT
+
+    @property
+    def last(self) -> float:
+        return self.series.values[-1][1]
+
+    @property
+    def first(self) -> float:
+        return self.series.values[0][1]
+
+    @property
+    def improving(self) -> bool | None:
+        """Whether the last value is better than the first, where "better" is known."""
+        if self.series.better is None or len(self.series.values) < 2 or self.last == self.first:
+            return None
+        return (self.last < self.first) if self.series.better == "lower" else (self.last > self.first)
+
+
+def series_of(state: LoopState) -> list[Series]:
+    """What is worth a line: open material findings, cost (or tokens without a price), every metric."""
+    finished = [r for r in state.rounds if not r.running]
+    found: list[Series] = []
+    if any(run.findings for r in finished for run in r.runs):
+        found.append(
+            Series(
+                "open material findings",
+                tuple((r.number, float(sum(run.material_open for run in r.runs))) for r in finished),
+                better="lower",
+            )
+        )
+    if any(r.cost_usd for r in finished):
+        found.append(Series("cost", tuple((r.number, r.cost_usd) for r in finished), unit="$"))
+    elif any(r.tokens for r in finished):
+        found.append(Series("tokens", tuple((r.number, float(r.tokens)) for r in finished)))
+    names: list[str] = []
+    for r in finished:
+        names += [metric.name for metric in r.all_metrics if metric.name not in names]
+    for name in names:
+        points = [(r.number, m) for r in finished for m in r.all_metrics if m.name == name]
+        last = points[-1][1]
+        found.append(
+            Series(name, tuple((n, m.value) for n, m in points), last.unit, last.target, last.better)
+        )
+    return [series for series in found if series.values]
+
+
+def chart(series: Series, width: int = WIDTH, height: int = HEIGHT) -> Chart:
+    values = [value for _, value in series.values]
+    low = min([*values, *([series.target] if series.target is not None else [])])
+    high = max([*values, *([series.target] if series.target is not None else [])])
+    span = (high - low) or 1.0
+    count = len(series.values)
+
+    def x(index: int) -> float:
+        return PAD + (width - 2 * PAD) * (index / (count - 1) if count > 1 else 0.5)
+
+    def y(value: float) -> float:
+        return round(height - PAD - (height - 2 * PAD) * (value - low) / span, 1)
+
+    dots = tuple(
+        Dot(round(x(i), 1), y(value), number, value) for i, (number, value) in enumerate(series.values)
+    )
+    path = " ".join(f"{'M' if i == 0 else 'L'}{dot.x} {dot.y}" for i, dot in enumerate(dots))
+    target_y = y(series.target) if series.target is not None else None
+    return Chart(series, path, dots, target_y, width, height)
+
+
+def charts_of(state: LoopState) -> list[Chart]:
+    return [chart(series) for series in series_of(state)]
+
+
+#: From this share of a cap on, its bar warns.
+WARN_SHARE = 0.8
+
+
+@dataclass(frozen=True)
+class CapBar:
+    name: str
+    used: str
+    cap: str
+    share: float  # 0..1, clipped
+
+    @property
+    def warns(self) -> bool:
+        return self.share >= WARN_SHARE
+
+
+def caps_of(state: LoopState) -> list[CapBar]:
+    """Rounds, runtime and cost against the loop's own caps, for the caps it declares."""
+    manifest = state.manifest
+    bars = []
+    if manifest.round_cap:
+        used = state.rounds[-1].number if state.rounds else 0
+        bars.append(CapBar("rounds", str(used), str(manifest.round_cap), min(1.0, used / manifest.round_cap)))
+    if manifest.runtime_cap_minutes:
+        share = state.minutes / manifest.runtime_cap_minutes
+        bars.append(
+            CapBar("runtime", f"{state.minutes} min", f"{manifest.runtime_cap_minutes} min", min(1.0, share))
+        )
+    if manifest.cost_cap_usd:
+        share = state.cost_usd / manifest.cost_cap_usd
+        bars.append(
+            CapBar("cost", f"${state.cost_usd:,.2f}", f"${manifest.cost_cap_usd:,.2f}", min(1.0, share))
+        )
+    return bars
+
+
+#: How many of a loop's latest rounds the overview draws beside its count.
+TRAIL_ROUNDS = 12
+#: The darkest shade stands for this many open findings or more.
+HEAT_LEVELS = 4
+
+
+@dataclass(frozen=True)
+class TrailCell:
+    """One round on the overview: `live` while it runs, `clear` with nothing open, else `h1` to `h4`."""
+
+    number: int
+    look: str
+    label: str
+
+
+def trail_of(state: LoopState) -> list[TrailCell]:
+    """The loop's latest rounds, oldest first, each shaded by the findings it left open."""
+    cells = []
+    for round_ in state.rounds[-TRAIL_ROUNDS:]:
+        left_open = round_.findings_open
+        if round_.running:
+            look, what = "live", "under way"
+        elif left_open == 0:
+            look, what = "clear", "nothing open"
+        else:
+            look = f"h{min(left_open, HEAT_LEVELS)}"
+            what = f"{left_open} open finding{'s' if left_open != 1 else ''}"
+        cells.append(TrailCell(round_.number, look, f"round {round_.number}: {what}"))
+    return cells
+
+
+def figure(value: float, unit: str = "") -> str:
+    """A value as a person reads it: whole numbers without decimals, money with two."""
+    if unit == "$":
+        return f"${value:,.2f}"
+    text = f"{value:,.0f}" if float(value).is_integer() else f"{value:,.2f}"
+    return f"{text} {unit}".strip()

loopcaptain/cli.py

@@ -0,0 +1,204 @@
+"""The `loopcaptain` command: serve the board, check a folder, emit an event, run the MCP server."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib.metadata import version as package_version
+from pathlib import Path
+
+from pydantic import TypeAdapter, ValidationError
+
+from loopcaptain.agents import agent, agents, checkout_of, markdown
+from loopcaptain.board.discover import as_written, edit_config
+from loopcaptain.protocol import spec_text, store
+from loopcaptain.protocol.doctor import examine
+from loopcaptain.protocol.models import EVENT_NAMES, AnyEvent, InboxEntry, Manifest, now
+from loopcaptain.protocol.store import StoreError
+from loopcaptain.protocol.validate import validate_report
+
+#: This repository's folder, for the MCP command a checkout prints; an installed package has none.
+CHECKOUT = Path(__file__).resolve().parents[2]
+
+
+def write_schemas(target: Path) -> list[Path]:
+    """The protocol as JSON Schema, one file per file of a loop's folder."""
+    target.mkdir(parents=True, exist_ok=True)
+    schemas = {
+        "loop.schema.json": Manifest.model_json_schema(),
+        "event.schema.json": TypeAdapter(AnyEvent).json_schema(),
+        "inbox.schema.json": InboxEntry.model_json_schema(),
+    }
+    written = []
+    for name, schema in schemas.items():
+        path = target / name
+        path.write_text(json.dumps(schema, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        written.append(path)
+    return written
+
+
+def emit(repo: Path, loop_id: str, event: str, fields: list[str]) -> None:
+    """Append one event from `key=value` pairs; a value that parses as JSON is taken as JSON."""
+    data: dict[str, object] = {"ts": now().isoformat(), "event": event}
+    for pair in fields:
+        key, sep, raw = pair.partition("=")
+        if not sep:
+            raise StoreError(f"{pair!r}: expected key=value")
+        try:
+            data[key] = json.loads(raw)
+        except json.JSONDecodeError:
+            data[key] = raw
+    try:
+        parsed = store.parse_event(data)
+    except ValidationError as error:
+        raise StoreError(store.short_error(error)) from error
+    store.read_manifest(repo, loop_id)
+    store.append_event(repo, loop_id, parsed)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="loopcaptain", description="One board for every agent loop.")
+    parser.add_argument(
+        "--version", action="version", version=f"loopcaptain {package_version('loopcaptain')}"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    serve = commands.add_parser("serve", help="the board on 127.0.0.1")
+    serve.add_argument("--port", type=int, default=8484, help="the port on 127.0.0.1, default 8484")
+
+    validate = commands.add_parser("validate", help="check a repository's .loops folders")
+    validate.add_argument("repo", type=Path)
+    validate.add_argument("--strict", action="store_true", help="count warnings as problems")
+
+    emit_cmd = commands.add_parser(
+        "emit", help="append one event: loopcaptain emit <loop> <event> key=value ..."
+    )
+    emit_cmd.add_argument("loop")
+    emit_cmd.add_argument("event", choices=EVENT_NAMES)
+    emit_cmd.add_argument("fields", nargs="*")
+    emit_cmd.add_argument("--repo", type=Path, default=Path("."))
+
+    schema = commands.add_parser("schema", help="write the protocol as JSON Schema")
+    schema.add_argument("target", type=Path)
+
+    doctor = commands.add_parser("doctor", help="send a loop a stop and check that it takes it and ends")
+    doctor.add_argument("repo", type=Path)
+    doctor.add_argument("loop")
+    doctor.add_argument("--timeout", type=float, default=600, help="seconds to wait, default 600")
+
+    watch = commands.add_parser(
+        "watch", help="add a repository, or with --root a folder of them, to the board"
+    )
+    watch.add_argument("path", type=Path)
+    watch.add_argument("--root", action="store_true", help="every sub-folder with .loops/ is a repository")
+    unwatch = commands.add_parser("unwatch", help="take a folder off the board")
+    unwatch.add_argument("path", type=Path)
+
+    demo = commands.add_parser(
+        "demo", help="write the example loop into a folder and watch it; costs nothing"
+    )
+    demo.add_argument("--target", type=Path, default=Path("~/.local/share/loopcaptain/demo"))
+    demo.add_argument("--no-watch", action="store_true", help="write it, but leave the config alone")
+
+    mcp_config = commands.add_parser("mcp-config", help="how one coding agent adds the MCP server")
+    mcp_config.add_argument("agent", nargs="?", default="", help="claude-code, codex, gemini, cursor, ...")
+    mcp_config.add_argument(
+        "--checkout", default=checkout_of(CHECKOUT), help="the folder of this repository, if run from one"
+    )
+    mcp_config.add_argument("--markdown", action="store_true", help="print the page for every agent")
+
+    commands.add_parser("spec", help="print LOOPS.md, the protocol to paste into a loop")
+    commands.add_parser("mcp", help="run the MCP server on stdio")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return run(args)
+    except StoreError as error:
+        sys.stderr.write(f"loopcaptain: {error}\n")
+        return 1
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "validate":
+        report = validate_report(args.repo.expanduser().resolve())
+        problems = report.problems + (report.warnings if args.strict else [])
+        warnings = [] if args.strict else report.warnings
+        for line in problems:
+            sys.stdout.write(f"problem: {line}\n")
+        for line in warnings:
+            sys.stdout.write(f"warning: {line}\n")
+        if problems:
+            sys.stdout.write(f"{len(problems)} problem(s), {len(warnings)} warning(s)\n")
+        else:
+            sys.stdout.write(f"ok, {len(warnings)} warning(s)\n" if warnings else "ok\n")
+        return 1 if problems else 0
+    if args.command == "emit":
+        emit(args.repo.expanduser().resolve(), args.loop, args.event, args.fields)
+        return 0
+    if args.command == "schema":
+        for path in write_schemas(args.target):
+            sys.stdout.write(f"{path}\n")
+        return 0
+    if args.command == "doctor":
+        sys.stdout.write("waiting for the loop to take a stop; start it now if it is not running\n")
+        checkup = examine(args.repo.expanduser().resolve(), args.loop, args.timeout)
+        sys.stdout.write("".join(f"{line}\n" for line in checkup.lines()))
+        return 0 if checkup.passed else 1
+    if args.command in ("watch", "unwatch"):
+        entry = as_written(args.path)
+        if args.command == "watch":
+            if not args.path.expanduser().is_dir():
+                raise StoreError(f"{args.path} is not a folder")
+            changes = edit_config(args.path, add=("roots" if args.root else "repos", entry))
+        else:
+            changes = edit_config(args.path, remove=entry)
+        sys.stdout.write("".join(f"{line}\n" for line in changes))
+        return 0
+    if args.command == "demo":
+        from loopcaptain.demo import DemoError, write_demo
+
+        target = args.target.expanduser()
+        try:
+            write_demo(target)
+        except DemoError as error:
+            raise StoreError(str(error)) from error
+        sys.stdout.write(f"the example loop is in {target}\n")
+        if not args.no_watch:
+            sys.stdout.write(
+                "".join(f"{line}\n" for line in edit_config(target, add=("repos", as_written(target))))
+            )
+        sys.stdout.write("start the board with `loopcaptain serve` and open http://127.0.0.1:8484\n")
+        return 0
+    if args.command == "mcp-config":
+        if args.markdown:
+            sys.stdout.write(markdown())
+            return 0
+        if not args.agent:
+            sys.stdout.write("".join(f"{item.key:12} {item.name}\n" for item in agents(args.checkout)))
+            return 0
+        try:
+            item = agent(args.agent, args.checkout)
+        except KeyError as error:
+            raise StoreError(str(error.args[0])) from error
+        sys.stdout.write(f"{item.name}\n\n{item.add}\n\nunattended: {item.headless}\n")
+        return 0
+    if args.command == "spec":
+        sys.stdout.write(spec_text())
+        return 0
+    if args.command == "mcp":
+        from loopcaptain.mcp_server.server import serve_stdio
+
+        serve_stdio()
+        return 0
+    from loopcaptain.board.app import serve
+
+    serve(args.port)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

loopcaptain/demo/__init__.py

@@ -0,0 +1,59 @@
+"""`loopcaptain demo`: the example loop, written into a folder of its own with its first rounds.
+
+The folder gets `loop.py`, the example loop, and `loops.py`, the helper as LOOPS.md prints it: the
+same two files any loop needs. Its history is made by running the loop itself with past times.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from importlib import resources
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+CHECKOUT_HELPER = HERE.parents[2] / "standard" / "loops.py"
+SEEDED_ROUNDS = 2
+SEED_TIMEOUT_S = 60
+#: What the demo writes into its folder; only these are replaced on a second run.
+WRITTEN = (".loops", "work", "out")
+#: The file that marks a folder as the demo's own: only such a folder is ever cleared.
+MARKER = ".loopcaptain-demo"
+
+
+class DemoError(Exception):
+    """The target is not a folder the demo may write into."""
+
+
+def helper_source() -> str:
+    """The helper: packaged beside this file in a build (force-include), in standard/ in a checkout."""
+    packaged = resources.files(__name__).joinpath("loops.py")
+    if packaged.is_file():
+        return packaged.read_text(encoding="utf-8")
+    return CHECKOUT_HELPER.read_text(encoding="utf-8")
+
+
+def write_demo(target: Path) -> Path:
+    """Write the example loop into `target`, replacing what an earlier demo wrote there, and seed it.
+
+    A folder that holds anything and was not made by the demo is refused: it may be a real repository.
+    """
+    ours = (target / MARKER).is_file()
+    if target.exists() and any(target.iterdir()) and not ours:
+        raise DemoError(f"{target} is not empty and was not made by the demo; pick a new folder")
+    if ours:
+        for name in WRITTEN:
+            if (target / name).is_dir() and not (target / name).is_symlink():
+                shutil.rmtree(target / name)
+    target.mkdir(parents=True, exist_ok=True)
+    (target / MARKER).write_text("Written by `loopcaptain demo`; it may clear .loops, work and out here.\n")
+    (target / "loops.py").write_text(helper_source(), encoding="utf-8")
+    (target / "loop.py").write_text((HERE / "loop.py").read_text(encoding="utf-8"), encoding="utf-8")
+    subprocess.run(
+        [sys.executable, "loop.py", "--seed", str(SEEDED_ROUNDS)],
+        cwd=target,
+        check=True,
+        timeout=SEED_TIMEOUT_S,
+    )
+    return target