marcus-toolkit 0.1.0__py3-none-any.whl

marcus_toolkit/pricing.py

@@ -0,0 +1,96 @@
+"""
+One price table for every extension.
+
+The Minecraft plumbing and the numerical verifier each carried their own
+(``cost_lib.py``, 129 lines, and ``numeric_cost_lib.py``, 183 lines, 240
+differing lines between them). This is the only copy.
+
+Prices are dollars per million tokens as ``(input, output, cache_read,
+cache_write)``; cache read is a tenth of input and cache write is one and a
+quarter times input, which is Anthropic's published rule, with the exact
+figures where a model lists one.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+#: $/M tokens: (input, output, cache read, cache write).
+PRICES: dict[str, tuple[float, float, float, float]] = {
+    "claude-sonnet-4-5": (3.0, 15.0, 0.30, 3.75),
+    "claude-sonnet-5": (2.0, 10.0, 0.20, 2.50),
+    "claude-haiku-4-5": (1.0, 5.0, 0.10, 1.25),
+    "claude-opus-5": (5.0, 25.0, 0.50, 6.25),
+}
+
+#: Short names the Minecraft runs recorded, kept so their records price the same.
+ALIASES: dict[str, str] = {
+    "sonnet": "claude-sonnet-4-5",
+    "haiku": "claude-haiku-4-5",
+    "sonnet-5": "claude-sonnet-5",
+    "opus": "claude-opus-5",
+    "opus-5": "claude-opus-5",
+}
+
+_DATE_SUFFIX = re.compile(r"-\d{8}$")
+
+USAGE_KEYS: tuple[str, str, str, str] = ("input", "output", "cacheRead", "cacheWrite")
+
+
+def resolve(model: str) -> str:
+    """
+    Map a model name, alias or dated id to a price-table key.
+
+    Parameters
+    ----------
+    model : str
+        ``sonnet``, ``claude-sonnet-5``, ``claude-haiku-4-5-20251001``, and so on.
+
+    Returns
+    -------
+    str
+        A key of :data:`PRICES`.
+
+    Raises
+    ------
+    KeyError
+        When no price is known for the model; a run must not be priced by guess.
+    """
+    name = model.strip().lower()
+    name = ALIASES.get(name, name)
+    name = name.split("/", 1)[1] if name.startswith("anthropic/") else name
+    name = _DATE_SUFFIX.sub("", name)
+    name = ALIASES.get(name, name)
+    if name not in PRICES:
+        raise KeyError(
+            f"no price for model {model!r}; add it to marcus_toolkit.pricing.PRICES"
+        )
+    return name
+
+
+def price(usage: Mapping[str, int], model: str) -> float:
+    """
+    Price one usage row.
+
+    Parameters
+    ----------
+    usage : Mapping[str, int]
+        ``{input, output, cacheRead, cacheWrite}`` token counts; a missing key
+        counts as zero.
+    model : str
+        The model the row was billed at.
+
+    Returns
+    -------
+    float
+        Dollars, rounded to six places.
+    """
+    rate_in, rate_out, rate_read, rate_write = PRICES[resolve(model)]
+    dollars = (
+        int(usage.get("input") or 0) * rate_in
+        + int(usage.get("output") or 0) * rate_out
+        + int(usage.get("cacheRead") or 0) * rate_read
+        + int(usage.get("cacheWrite") or 0) * rate_write
+    ) / 1_000_000
+    return round(dollars, 6)

marcus_toolkit/record.py

@@ -0,0 +1,84 @@
+"""
+The run record: one directory per run, every default that applied, every file.
+
+The Minecraft runs settled the layout: ``runs/<stamp>/`` holding
+``run-config.txt`` (one ``key: value`` line per setting), ``marcus-version.txt``,
+the logs, the JSONL event streams, and at the end a copy of the board and the
+agents' state. Every figure in a write-up is read from this directory.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+
+def stamp_now() -> str:
+    """Return a run stamp: ``YYYYMMDDTHHMMSS`` in local time, as Minecraft does."""
+    return time.strftime("%Y%m%dT%H%M%S")
+
+
+class RunRecord:
+    """
+    The directory a run writes into.
+
+    Parameters
+    ----------
+    root : Path
+        The ``runs/`` directory.
+    stamp : Optional[str]
+        The run's stamp; now by default.
+    """
+
+    def __init__(self, root: Path, stamp: str | None = None) -> None:
+        self.stamp = stamp or stamp_now()
+        self.dir = root / self.stamp
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def path(self, name: str) -> Path:
+        """Return a file path inside the record."""
+        return self.dir / name
+
+    def config_line(self, key: str, value: Any) -> None:
+        """Append one ``key: value`` line to ``run-config.txt``."""
+        with self.path("run-config.txt").open("a") as handle:
+            handle.write(f"{key + ':':<20}{value}\n")
+
+    def config(self) -> dict[str, str]:
+        """Read ``run-config.txt`` back as a mapping (last value wins)."""
+        out: dict[str, str] = {}
+        file = self.path("run-config.txt")
+        if not file.is_file():
+            return out
+        for line in file.read_text().splitlines():
+            if ":" in line:
+                key, _, value = line.partition(":")
+                out[key.strip()] = value.strip()
+        return out
+
+    def write(self, name: str, text: str) -> Path:
+        """Write a text file into the record."""
+        target = self.path(name)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text)
+        return target
+
+    def append_jsonl(self, name: str, row: dict[str, Any]) -> None:
+        """Append one row to a JSONL stream, flushed at once."""
+        with self.path(name).open("a") as handle:
+            handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+            handle.flush()
+
+    def copy_in(self, source: Path, name: str | None = None) -> Path | None:
+        """Copy a file or directory into the record; ``None`` if it is missing."""
+        if not source.exists():
+            return None
+        target = self.path(name or source.name)
+        if source.is_dir():
+            shutil.copytree(source, target, dirs_exist_ok=True)
+        else:
+            shutil.copy2(source, target)
+        return target

marcus_toolkit/sampler.py

@@ -0,0 +1,169 @@
+"""
+Sample the board while a run is going, so frontier width has a time series.
+
+Marcus reports its own ready-frontier width (``tasks_claimable``) only on a
+``request_next_task`` reply that is not an assignment (#804), so on a healthy
+wide board the agents' logs say little about the frontier. This sampler reads
+the run's SQLite board read-only every few seconds and applies the rule the
+drain verdict applies:
+
+* DONE is done;
+* BLOCKED or DECLINED is blocked, and nobody is coming back to it;
+* IN_PROGRESS, or TODO with a name on it, is in flight;
+* a TODO whose dependencies are not all done is unclaimable;
+* everything else is claimable, and that count is the frontier width.
+
+Lifted from the Minecraft plumbing's ``sample_board.py``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+#: Statuses nobody comes back to; the drain verdict counts both as blocked
+#: (ADR-0013 K5).
+TERMINAL = frozenset({"blocked", "declined"})
+
+
+def find_board(where: Path) -> Path | None:
+    """
+    Resolve the board file from a path that may be the file or its directory.
+
+    Parameters
+    ----------
+    where : Path
+        The ``kanban.db`` file, or a data directory to search.
+
+    Returns
+    -------
+    Optional[Path]
+        The board file, or ``None`` when there is not one yet.
+    """
+    if where.is_file():
+        return where
+    if not where.is_dir():
+        return None
+    found = [p for p in where.rglob("kanban.db") if "backups" not in p.parts]
+    return min(found, key=lambda p: len(p.parts)) if found else None
+
+
+def sample(db: Path, project_id: str | None = None) -> dict[str, Any]:
+    """
+    Take one sample of the board.
+
+    Parameters
+    ----------
+    db : Path
+        The run's SQLite board file.
+    project_id : Optional[str]
+        Count only this project's tasks; a data directory persists across
+        runs and holds every past run's tasks too.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Counts, the claimable task names, the blocked names and who holds what.
+    """
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=5)
+    try:
+        query = (
+            "select id, name, status, assigned_to from tasks"
+            " where name not like 'About:%'"
+        )
+        params: tuple[str, ...] = ()
+        if project_id:
+            query += " and project_id = ?"
+            params = (project_id,)
+        rows = con.execute(query, params).fetchall()
+        deps = con.execute(
+            "select task_id, depends_on_id from task_dependencies"
+        ).fetchall()
+    finally:
+        con.close()
+
+    status = {row[0]: row[2] for row in rows}
+    dependencies: dict[str, list[str]] = {}
+    for task_id, depends_on in deps:
+        dependencies.setdefault(task_id, []).append(depends_on)
+
+    done: list[str] = []
+    in_flight: list[str] = []
+    blocked: list[str] = []
+    unclaimable: list[str] = []
+    claimable: list[str] = []
+    holders: dict[str, str] = {}
+    for task_id, name, state, assignee in rows:
+        if state == "done":
+            done.append(name)
+        elif state in TERMINAL:
+            blocked.append(name)
+        elif state == "in_progress" or (state == "todo" and assignee):
+            in_flight.append(name)
+            if assignee:
+                holders[assignee] = name
+        elif any(status.get(dep) != "done" for dep in dependencies.get(task_id, [])):
+            unclaimable.append(name)
+        else:
+            claimable.append(name)
+    return {
+        "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "tasks_total": len(rows),
+        "tasks_done": len(done),
+        "tasks_in_flight": len(in_flight),
+        "tasks_blocked": len(blocked),
+        "tasks_unclaimable": len(unclaimable),
+        "tasks_claimable": len(claimable),
+        "claimable": sorted(claimable),
+        "blocked": sorted(blocked),
+        "holders": holders,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Sample until the deadline. Returns an exit code."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--db", required=True, help="the board file or the data directory holding it"
+    )
+    parser.add_argument("--project", default=None)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--every", type=float, default=15.0)
+    parser.add_argument("--minutes", type=float, default=30.0)
+    args = parser.parse_args(argv)
+
+    where = Path(args.db)
+    out = Path(args.out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    deadline = time.time() + args.minutes * 60
+    db = find_board(where)
+    with out.open("a") as handle:
+        while time.time() < deadline:
+            if db is None:
+                db = find_board(where)
+                if db is None:
+                    time.sleep(args.every)
+                    continue
+            try:
+                handle.write(json.dumps(sample(db, args.project)) + "\n")
+            except sqlite3.Error as error:
+                handle.write(
+                    json.dumps(
+                        {
+                            "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+                            "error": str(error),
+                        }
+                    )
+                    + "\n"
+                )
+            handle.flush()
+            time.sleep(args.every)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

marcus_toolkit/seed.py

@@ -0,0 +1,189 @@
+"""
+Seed a project with exactly the tasks an extension names, through MCP.
+
+``create_project(options.tasks)`` with ``options.path = "direct"`` puts the
+listed tasks on the board and runs no model decomposition. The two traps the
+Minecraft runs found are enforced here: the criteria key is
+``completion_criteria``, ``depends_on`` names tasks by name, and an extra key
+on a spec breaks the call (six of seven promotions in Minecraft run 6).
+
+No label from the ``build`` family goes on any task: those labels switch on
+the software validation gate, which rejects a task with no source files
+(ADR-0013 K3, issue #798).
+
+Every seeded project also carries one extra done card, ``About: <name>``,
+which Marcus creates itself; counts read back from the board are seeded + 1.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .client import MarcusMCPClient
+
+#: The keys a task spec may carry on ``create_project`` and ``create_tasks``.
+TASK_KEYS = frozenset(
+    {
+        "name",
+        "description",
+        "labels",
+        "depends_on",
+        "completion_criteria",
+        "estimated_hours",
+        "priority",
+    }
+)
+#: Labels that switch on the software validation gate (K3); never on a board-only task.
+FORBIDDEN_LABELS = frozenset({"build", "create", "implement", "develop", "feature"})
+PRIORITIES = frozenset({"high", "medium", "low"})
+
+
+@dataclass
+class SeedResult:
+    """What seeding produced."""
+
+    project_id: str
+    task_names: list[str]
+    total_tasks: int | None
+    reply: dict[str, Any] = field(default_factory=dict)
+
+
+def validate_specs(specs: Sequence[dict[str, Any]]) -> None:
+    """
+    Refuse a task list the board would mis-handle.
+
+    Parameters
+    ----------
+    specs : Sequence[Dict[str, Any]]
+        Task specs.
+
+    Raises
+    ------
+    ValueError
+        On an unknown key, a forbidden label, a bad priority, a duplicate
+        name, or a ``depends_on`` that names no task in the list.
+    """
+    names = [str(s.get("name") or "") for s in specs]
+    if len(set(names)) != len(names) or any(not n for n in names):
+        raise ValueError("every task needs a distinct, non-empty name")
+    for spec in specs:
+        unknown = set(spec) - TASK_KEYS
+        if unknown:
+            raise ValueError(
+                f"task {spec['name']!r}: unknown keys {sorted(unknown)};"
+                f" allowed {sorted(TASK_KEYS)}"
+            )
+        bad = {
+            str(label).lower() for label in spec.get("labels") or []
+        } & FORBIDDEN_LABELS
+        if bad:
+            raise ValueError(
+                f"task {spec['name']!r}: label(s) {sorted(bad)} switch on the"
+                " software validation gate (K3)"
+            )
+        if "priority" in spec and spec["priority"] not in PRIORITIES:
+            raise ValueError(
+                f"task {spec['name']!r}: priority must be one of {sorted(PRIORITIES)}"
+            )
+        for dep in spec.get("depends_on") or []:
+            if dep not in names:
+                raise ValueError(
+                    f"task {spec['name']!r}: depends_on {dep!r} names no task"
+                    " in this list"
+                )
+        criteria = spec.get("completion_criteria")
+        if criteria is not None and not isinstance(criteria, list):
+            raise ValueError(
+                f"task {spec['name']!r}: completion_criteria must be a list"
+                " of sentences"
+            )
+
+
+def seed_project(
+    client: MarcusMCPClient,
+    *,
+    name: str,
+    description: str,
+    tasks: Sequence[dict[str, Any]],
+    project_root: Path,
+    objective: str | None = None,
+    wait_seconds: float = 120.0,
+    sleep_seconds: float = 2.0,
+) -> SeedResult:
+    """
+    Create a project holding exactly ``tasks``, and read back that it did.
+
+    Parameters
+    ----------
+    client : MarcusMCPClient
+        A connected client.
+    name : str
+        The project name. Never contains "test".
+    description : str
+        The project description.
+    tasks : Sequence[Dict[str, Any]]
+        Task specs, validated by :func:`validate_specs`.
+    project_root : Path
+        Where artifacts are written; the kernel refuses a project without one
+        (``project_root_required``). Created if missing, resolved to an absolute
+        path, and deliberately not a repository.
+    objective : Optional[str]
+        A human-written objective every agent reads once at registration.
+    wait_seconds : float
+        How long to wait for the board to show the tasks.
+    sleep_seconds : float
+        The poll interval while waiting.
+
+    Returns
+    -------
+    SeedResult
+
+    Raises
+    ------
+    ValueError
+        On a bad task list or a project name containing "test".
+    RuntimeError
+        When the server returns no project id.
+    """
+    if "test" in name.lower():
+        raise ValueError(
+            "a project name containing 'test' changes Marcus's behaviour;"
+            " pick another name"
+        )
+    validate_specs(tasks)
+    root = Path(project_root).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    options: dict[str, Any] = {
+        "provider": "sqlite",
+        "complexity": "prototype",
+        "path": "direct",
+        "project_root": str(root),
+        "tasks": list(tasks),
+    }
+    if objective:
+        options["objective"] = objective
+    reply = client.call(
+        "create_project",
+        {"description": description, "project_name": name, "options": options},
+    )
+    project_id = reply.get("project_id")
+    if not project_id:
+        raise RuntimeError(f"create_project returned no project id: {reply}")
+    total: int | None = None
+    deadline = time.time() + wait_seconds
+    while time.time() < deadline:
+        status = (client.call_tool("get_project_status") or {}).get("project") or {}
+        if (status.get("total_tasks") or 0) >= len(tasks):
+            total = int(status["total_tasks"])
+            break
+        time.sleep(sleep_seconds)
+    return SeedResult(
+        project_id=str(project_id),
+        task_names=[str(t["name"]) for t in tasks],
+        total_tasks=total,
+        reply=reply,
+    )