agentpace 0.9.2__py3-none-any.whl

agentpace/forecasts.py

@@ -0,0 +1,284 @@
+"""A local ledger of forecasts, so a user can later see how often their own estimates held.
+
+`estimate --record` appends one forecast record to `~/.agentpace/forecasts.jsonl`. Scores are
+appended later as separate records, never edited in place. The file is local only: `share` never
+reads it. It may hold free text, such as task ids and a quoted human-scale timeline, but no file
+paths, no data sources and nothing derived from the local secret.
+
+A quote such as "3 weeks" is calendar time as someone said it. It is stored as given, and turned
+into seconds only when it parses exactly, by fixed units. No other conversion is ever applied.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import statistics
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+Record = dict[str, Any]
+
+FORECAST, SCORE = "forecast", "score"
+_UNITS = {
+    "min": 60,
+    "minute": 60,
+    "minutes": 60,
+    "h": 3600,
+    "hour": 3600,
+    "hours": 3600,
+    "d": 86_400,
+    "day": 86_400,
+    "days": 86_400,
+    "w": 7 * 86_400,
+    "week": 7 * 86_400,
+    "weeks": 7 * 86_400,
+    "mo": 30 * 86_400,
+    "month": 30 * 86_400,
+    "months": 30 * 86_400,
+}
+_DURATION = re.compile(
+    r"^\s*(\d+(?:\.\d+)?)\s*(min|minutes?|h|hours?|d|days?|w|weeks?|mo|months?)\s*$",
+    re.IGNORECASE,
+)
+
+
+def parse_duration(text: str) -> int | None:
+    """Seconds for an exact "<number> <unit>", by fixed units (1 d = 86,400 s, 1 w = 7 d,
+    1 mo = 30 d). Anything else is None, never a guess."""
+    match = _DURATION.match(text)
+    if match is None:
+        return None
+    seconds = float(match.group(1)) * _UNITS[match.group(2).lower()]
+    return round(seconds) if seconds >= 1 else None
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _canonical(record: Mapping[str, Any]) -> str:
+    return json.dumps(record, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def record_id(record: Mapping[str, Any]) -> str:
+    """Derived from the content and the time it was issued, so no random draw is needed."""
+    body = {key: value for key, value in record.items() if key != "id"}
+    return hashlib.sha256((record["issued_at"] + _canonical(body)).encode("utf-8")).hexdigest()[:8]
+
+
+def forecast_record(
+    *,
+    issued_at: str,
+    version: str,
+    plan_document: Mapping[str, Any],
+    result: Mapping[str, Any],
+    quoted: str | None,
+) -> Record:
+    """`result` is the dict `render.plan_json` prints, so the ledger holds what the user saw."""
+    record: Record = {
+        "kind": FORECAST,
+        "issued_at": issued_at,
+        "version": version,
+        "method": result["method"],
+        "seed": result["seed"],
+        "draws": result["draws"],
+        "rows_used": result["rows_used"],
+        "rows_excluded": result["rows_excluded"],
+        "plan": plan_document,
+        "p50": result["p50"],
+        "p80": result["p80"],
+        "p90": result["p90"],
+        "tasks": [
+            {"id": t["id"], "p50": t["p50"], "p80": t["p80"], "p90": t["p90"], "cell": t["cell"]}
+            for t in result["tasks"]
+        ],
+        "human": result["human"],
+    }
+    if quoted is not None:
+        record["quoted"] = quoted
+        seconds = parse_duration(quoted)
+        if seconds is not None:
+            record["quoted_s"] = seconds
+    record["id"] = record_id(record)
+    return record
+
+
+def append(path: Path, record: Mapping[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8", newline="\n") as handle:
+        handle.write(_canonical(record) + "\n")
+
+
+@dataclass
+class Ledger:
+    forecasts: dict[str, Record] = field(default_factory=dict)
+    scores: list[Record] = field(default_factory=list)
+    skipped: int = 0
+
+
+def _valid(record: Any) -> bool:
+    if not isinstance(record, dict) or not isinstance(record.get("id"), str):
+        return False
+    if record.get("kind") == FORECAST:
+        return all(isinstance(record.get(key), (int, float)) for key in ("p50", "p80", "p90"))
+    if record.get("kind") == SCORE:
+        return isinstance(record.get("actual_s"), int)
+    return False
+
+
+def read(path: Path) -> Ledger:
+    """Every valid record. A damaged or unknown line is skipped and counted, never fatal."""
+    ledger = Ledger()
+    if not path.exists():
+        return ledger
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except ValueError:
+                record = None
+            if not _valid(record):
+                ledger.skipped += 1
+            elif record["kind"] == FORECAST:
+                ledger.forecasts[record["id"]] = record
+            else:
+                ledger.scores.append(record)
+    return ledger
+
+
+def latest_scores(scores: Sequence[Record]) -> dict[str, Record]:
+    """The latest score per forecast wins, so a correction never needs an edit in place."""
+    latest: dict[str, Record] = {}
+    for score in scores:
+        latest[score["id"]] = score
+    return latest
+
+
+# Scoring. A score compares a forecast with what happened. With a session, the actual is that
+# session's span on its own clock: agent runs plus the gaps between them, each gap up to the idle
+# cap. That is the same quantity the forecast predicts and the backtest scores. It is not wall
+# clock, and no allowance for the human part is added to it. With `--actual`, the user attests the
+# figure themselves.
+
+MIN_RATED = 5
+QUANTILE_KEYS = (("p50", 0.5), ("p80", 0.8), ("p90", 0.9))
+
+
+class ScoreRefused(ValueError):
+    """A score that cannot be made honestly, with the reason as its message."""
+
+
+def parse_issued(text: str) -> float:
+    return datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc).timestamp()
+
+
+def iso_week_of(epoch: float) -> str:
+    year, week, _ = datetime.fromtimestamp(epoch, tz=timezone.utc).isocalendar()
+    return f"{year}-W{week:02d}"
+
+
+def session_span(rows: Sequence[Mapping[str, Any]]) -> int:
+    """`max(offset + duration) - min(offset)` on the session clock, as in the backtest."""
+    end = max(int(row["offset_s"]) + int(row["duration_s"]) for row in rows)
+    return max(1, end - min(int(row["offset_s"]) for row in rows))
+
+
+def _quote_closer(forecast: Mapping[str, Any], actual_s: int) -> bool | None:
+    """Whether the quoted timeline was closer to the actual than the P50, by ratio."""
+    quoted = forecast.get("quoted_s")
+    if not isinstance(quoted, int) or quoted <= 0 or forecast["p50"] <= 0 or actual_s <= 0:
+        return None
+    return abs(math.log(quoted / actual_s)) < abs(math.log(forecast["p50"] / actual_s))
+
+
+def score_record(
+    forecast: Mapping[str, Any],
+    *,
+    actual_s: int,
+    source: str,
+    verified: bool,
+    scored_at: str,
+    session: str | None = None,
+) -> Record:
+    record: Record = {
+        "kind": SCORE,
+        "id": forecast["id"],
+        "scored_at": scored_at,
+        "actual_s": actual_s,
+        "source": source,
+        "verified": verified,
+        "quote_closer": _quote_closer(forecast, actual_s),
+    }
+    if session is not None:
+        record["session"] = session
+    return record
+
+
+def check_session(
+    forecast: Mapping[str, Any], rows: Sequence[Mapping[str, Any]], first_start: float | None
+) -> int:
+    """The actual for a session score, or a refusal. A session scores only when it provably
+    started after the forecast was issued."""
+    if len(rows) < 2:
+        raise ScoreRefused(
+            "that session has fewer than 2 completed local runs; run `agentpace ingest`"
+        )
+    issued = parse_issued(forecast["issued_at"])
+    if min(row["week"] for row in rows) < iso_week_of(issued):
+        raise ScoreRefused("that session ran before the forecast was issued, so it cannot score it")
+    if first_start is None:
+        raise ScoreRefused(
+            "cannot verify this session started after the forecast; use --actual to attest it"
+        )
+    if first_start < issued:
+        raise ScoreRefused("that session started before the forecast was issued")
+    return session_span(rows)
+
+
+def _pinball(actual: float, predicted: float, q: float) -> float:
+    gap = actual - predicted
+    return max(q * gap, (q - 1) * gap)
+
+
+@dataclass(frozen=True)
+class Summary:
+    scored: int
+    attested: int
+    within: dict[str, float] | None
+    pinball: float | None
+    quotes: int
+    quote_closer: float | None
+    quote_ratio: float | None
+
+
+def summarize(ledger: Ledger) -> Summary:
+    pairs = [
+        (ledger.forecasts[key], score)
+        for key, score in latest_scores(ledger.scores).items()
+        if key in ledger.forecasts
+    ]
+    attested = sum(not score["verified"] for _, score in pairs)
+    within = pinball = None
+    if len(pairs) >= MIN_RATED:
+        within = {
+            key: sum(score["actual_s"] <= forecast[key] for forecast, score in pairs) / len(pairs)
+            for key, _ in QUANTILE_KEYS
+        }
+        pinball = sum(
+            sum(_pinball(score["actual_s"], forecast[key], q) for key, q in QUANTILE_KEYS)
+            for forecast, score in pairs
+        ) / len(pairs)
+    quoted = [(f, s) for f, s in pairs if isinstance(f.get("quoted_s"), int)]
+    closer = ratio = None
+    if len(quoted) >= MIN_RATED:
+        closer = sum(bool(s["quote_closer"]) for _, s in quoted) / len(quoted)
+        ratio = statistics.median(f["quoted_s"] / s["actual_s"] for f, s in quoted)
+    return Summary(len(pairs), attested, within, pinball, len(quoted), closer, ratio)

agentpace/ingest.py

@@ -0,0 +1,337 @@
+"""Turn `RawRun` records into normalized rows, one code path for every harness."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from bisect import bisect_right
+from collections import defaultdict
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from pathlib import Path
+
+from agentpace import classify, pseudonym, schema
+from agentpace.adapters.base import Adapter, ParseStats, RawRun, Source
+from agentpace.cache import RunCache
+from agentpace.schema import Row
+
+DEFAULT_IDLE_CAP_S = 900
+_EFFORTS = frozenset(schema.enum("effort"))
+
+_FAMILIES = (
+    re.compile(r"claude-(?:opus|sonnet|haiku|fable)-\d+(?:-\d{1,2})?(?!\d)"),
+    re.compile(r"claude-\d(?:-\d)?-(?:opus|sonnet|haiku)"),
+    re.compile(r"gpt-\d+(?:\.\d+)?(?:-[a-z]+)?"),
+    re.compile(r"gemini-\d(?:\.\d)?-[a-z]+(?:-lite)?"),
+    re.compile(r"(?<![a-z0-9])o\d(?:-[a-z]+)?(?![a-z0-9])"),
+)
+# Some providers, such as OpenRouter or Copilot, write a dotted Claude version,
+# `claude-sonnet-4.5`, which the families above would cut to `claude-sonnet-4`. Rewrite only
+# that shape to the dashed family, for every harness.
+_DOTTED_CLAUDE = re.compile(r"(claude-(?:opus|sonnet|haiku|fable)-\d+)\.(\d{1,2})(?!\d)")
+_DOTTED_CLAUDE_OLD = re.compile(r"(claude-\d)\.(\d)-")
+
+
+def _canonical_model(model: str) -> str:
+    return _DOTTED_CLAUDE_OLD.sub(r"\1-\2-", _DOTTED_CLAUDE.sub(r"\1-\2", model))
+
+
+def normalize_model(raw: str) -> str:
+    """Keep a public model family. ARNs and proxy names can leak account or customer names."""
+    lowered = _canonical_model(raw.lower())
+    for family in _FAMILIES:
+        match = family.search(lowered)
+        if match:
+            return match.group(0)
+    return "other"
+
+
+def iso_week(epoch: float) -> str:
+    year, week, _ = datetime.fromtimestamp(epoch, tz=timezone.utc).isocalendar()
+    return f"{year}-W{week:02d}"
+
+
+@dataclass
+class IngestReport:
+    files: int = 0
+    rows: int = 0
+    zero_duration: int = 0
+    still_running: int = 0
+    cached: int = 0
+    cache_rebuilt: bool = False
+    parse: ParseStats = field(default_factory=ParseStats)
+
+    def lines(self) -> list[str]:
+        parse = self.parse
+        lines = [
+            f"files seen:       {self.files}",
+            f"read from cache:  {self.cached}" + (" (cache rebuilt)" if self.cache_rebuilt else ""),
+            f"rows produced:    {self.rows}",
+            f"empty runs:       {parse.empty_runs}",
+            f"unreadable files: {parse.unreadable_files}",
+            f"unparsed lines:   {parse.unparsed_lines}",
+            f"zero-duration:    {self.zero_duration}",
+            f"still running:    {self.still_running}",
+        ]
+        if parse.skipped_files:
+            lines.append(f"skipped files:    {parse.skipped_files}")
+        if parse.skipped_runs:
+            lines.append(f"skipped runs:     {parse.skipped_runs}")
+        return lines
+
+
+class SessionClock:
+    """Maps real time onto a session's own clock, with idle gaps clipped."""
+
+    def __init__(self, runs: Sequence[RawRun], idle_cap_s: int) -> None:
+        merged: list[list[float]] = []
+        for start, end in sorted(span for run in runs for span in run.spans):
+            if merged and start <= merged[-1][1]:
+                merged[-1][1] = max(merged[-1][1], end)
+            else:
+                merged.append([start, end])
+        self._starts = [start for start, _ in merged]
+        self._ends = [end for _, end in merged]
+        self._elapsed = [0.0]
+        for i in range(1, len(merged)):
+            busy = self._ends[i - 1] - self._starts[i - 1]
+            gap = self._starts[i] - self._ends[i - 1]
+            self._elapsed.append(self._elapsed[-1] + busy + min(gap, idle_cap_s))
+
+    def at(self, time: float) -> int:
+        index = max(bisect_right(self._starts, time) - 1, 0)
+        return round(self._elapsed[index] + max(time - self._starts[index], 0.0))
+
+
+def peak_overlaps(runs: Sequence[RawRun]) -> dict[int, int]:
+    """Peak number of runs alive at once during each run, including itself."""
+    events = sorted(
+        (time, order, index)
+        for index, run in enumerate(runs)
+        for time, order in ((run.start, 0), (run.end, 1))
+    )
+    peaks = dict.fromkeys(range(len(runs)), 1)
+    live: set[int] = set()
+    for _, order, index in events:
+        if order == 1:
+            live.discard(index)
+            continue
+        live.add(index)
+        for member in live:
+            peaks[member] = max(peaks[member], len(live))
+    return peaks
+
+
+def load_labels(path: Path) -> dict[str, dict[str, str]]:
+    if not path.exists():
+        return {}
+    labels: dict[str, dict[str, str]] = json.loads(path.read_text(encoding="utf-8"))
+    return labels
+
+
+def apply_labels(row: Row, labels: Mapping[str, Mapping[str, str]]) -> None:
+    label = labels.get(run_ref(row))
+    if label:
+        row["task_kind"] = label.get("kind", row["task_kind"])
+        row["risk"] = label.get("risk", row["risk"])
+
+
+def run_ref(row: Row) -> str:
+    """A short handle for labeling one run."""
+    return f"{row['batch']}:{row['offset_s']}"
+
+
+def build_rows(
+    runs: Sequence[RawRun],
+    secret: bytes,
+    idle_cap_s: int = DEFAULT_IDLE_CAP_S,
+    kind_map: Mapping[str, str] | None = None,
+    labels: Mapping[str, Mapping[str, str]] | None = None,
+    now: float | None = None,
+) -> tuple[list[Row], int, int]:
+    """Return schema-valid rows, how many runs had zero duration and were dropped, and how many
+    were withheld because they may still be running.
+
+    A run that has not completed and was active within the idle cap may still be going. Storing
+    it would leave a partial row behind for good, because its duration is part of the key, so it
+    is withheld until a later ingest finds it settled. It still feeds the session clock and the
+    overlap count, so its siblings get the same offsets they will have once it finishes. A
+    completed sibling that starts in the same second is held back too, because tie-breaking
+    between the two can only be settled once both are final.
+    """
+    now = time.time() if now is None else now
+    sessions: dict[tuple[str, str], list[RawRun]] = defaultdict(list)
+    for run in runs:
+        sessions[(run.project, run.session)].append(run)
+    contributor = pseudonym.contributor(secret)
+    rows: list[Row] = []
+    dropped = withheld = 0
+    for (project, session), members in sessions.items():
+        clock = SessionClock(members, idle_cap_s)
+        peaks = peak_overlaps(members)
+        batch = pseudonym.batch(secret, session)
+        project_hash = pseudonym.project(secret, project)
+        taken: set[tuple[int, int]] = set()
+        order = sorted(range(len(members)), key=lambda i: (members[i].start, members[i].end))
+        base = {i: clock.at(members[i].start) for i in order}
+        running = {
+            i
+            for i in order
+            if members[i].outcome != "completed" and now - members[i].end < idle_cap_s
+        }
+        # A sibling that starts in the same second as a running run is held back with it, since
+        # the tie nudge below would give it a different key once the running one finishes.
+        blocked = {base[i] for i in running}
+        for index in order:
+            run = members[index]
+            if run.active_s < 1:
+                dropped += 1
+                continue
+            if index in running or base[index] in blocked:
+                withheld += 1
+                continue
+            # Agents launched together can tie on (start, duration) to the second. A one-second
+            # nudge keeps both runs apart under the duplicate key, deterministically.
+            offset = base[index]
+            while (offset, run.active_s) in taken:
+                offset += 1
+            taken.add((offset, run.active_s))
+            kind = classify.classify_kind(run.agent_type, kind_map)
+            row: Row = {
+                "harness": run.harness,
+                "model": normalize_model(run.model),
+                "task_kind": kind,
+                "risk": classify.classify_risk(run.agent_type, kind),
+                "size": classify.size_bucket(run.edit_calls),
+                "duration_s": run.active_s,
+                "tool_calls": run.tool_calls,
+                "retries": run.errors,
+                "outcome": run.outcome,
+                "parallel_agents": peaks[index],
+                "contributor": contributor,
+                "week": iso_week(run.start),
+                "batch": batch,
+                "project": project_hash,
+                "offset_s": offset,
+            }
+            if run.tokens is not None:
+                row["tokens"] = run.tokens
+            if run.effort in _EFFORTS:
+                row["effort"] = run.effort
+            if labels:
+                apply_labels(row, labels)
+            problems = schema.check_row(row)
+            if problems:
+                raise ValueError(f"adapter produced an invalid row: {problems}")
+            rows.append(row)
+    return rows, dropped, withheld
+
+
+def _stamp(path: str) -> list[int] | None:
+    try:
+        stamp = os.stat(path)
+    except OSError:
+        return None
+    return [stamp.st_size, stamp.st_mtime_ns]
+
+
+def _parse(
+    adapter: Adapter,
+    source: Source,
+    idle_cap_s: int,
+    report: IngestReport,
+    cache: RunCache | None,
+) -> list[RawRun]:
+    if cache is None:
+        return adapter.parse(source, idle_cap_s, report.parse)
+    try:
+        stamp = os.stat(source.path)
+    except OSError:
+        report.parse.unreadable_files += 1
+        return []
+    stamps = [[stamp.st_size, stamp.st_mtime_ns], *map(_stamp, source.companions)]
+    hit, runs = cache.lookup(source.path, stamps)
+    if hit:
+        report.cached += 1
+        if not runs:
+            report.parse.empty_runs += 1
+        return runs
+    unreadable = report.parse.unreadable_files
+    runs = adapter.parse(source, idle_cap_s, report.parse)
+    if report.parse.unreadable_files == unreadable:
+        # Normalize before storing, so no raw model name (an ARN, a proxy) sits on disk.
+        runs = [replace(run, model=normalize_model(run.model)) for run in runs]
+        cache.store(source.path, stamps, runs)
+    return runs
+
+
+def ingest(
+    adapter: Adapter,
+    path: Path,
+    secret: bytes,
+    idle_cap_s: int = DEFAULT_IDLE_CAP_S,
+    kind_map: Mapping[str, str] | None = None,
+    labels: Mapping[str, Mapping[str, str]] | None = None,
+    now: float | None = None,
+    cache: RunCache | None = None,
+) -> tuple[list[Row], IngestReport]:
+    """Parse every run under `path` into rows. With a cache, unchanged files are not re-read."""
+    report = IngestReport(cache_rebuilt=cache is not None and cache.rebuilt)
+    runs: list[RawRun] = []
+    seen: set[str] = set()
+    for source in adapter.discover(path):
+        report.files += 1
+        seen.add(source.path)
+        runs.extend(_parse(adapter, source, idle_cap_s, report, cache))
+    if cache is not None:
+        sessions = {(run.project, run.session) for run in runs}
+        runs += cache.vanished(sessions, seen)
+        cache.save()
+    rows, report.zero_duration, report.still_running = build_rows(
+        runs, secret, idle_cap_s, kind_map, labels, now
+    )
+    report.rows = len(rows)
+    return rows, report
+
+
+def merge_into(path: Path, rows: Sequence[Row]) -> int:
+    """Add rows to a store. Old rows survive, since harnesses delete their transcripts."""
+    existing = schema.read_rows(path) if path.exists() else []
+    merged = {schema.dedupe_key(row): row for row in [*existing, *rows]}
+    return schema.write_rows(path, (merged[key] for key in sorted(merged)))
+
+
+class StoreBusy(Exception):
+    """Another ingest holds the store."""
+
+
+@contextmanager
+def store_lock(store: Path, wait_s: float = 5.0, stale_s: float = 900.0) -> Iterator[None]:
+    """Hold `<store>.lock` while reading, merging and writing, so a hook and a manual ingest
+    never interleave. A lock older than `stale_s` is taken to be left by a crash. That is longer
+    than a cold ingest takes, so a live holder is never mistaken for a dead one."""
+    lock = store.with_name(store.name + ".lock")
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    deadline = time.monotonic() + wait_s
+    while True:
+        try:
+            os.close(os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY))
+            break
+        except (FileExistsError, PermissionError):
+            # Windows reports PermissionError while another holder's lock is being deleted.
+            with suppress(OSError):
+                if time.time() - lock.stat().st_mtime > stale_s:
+                    lock.unlink()
+                    continue
+            if time.monotonic() > deadline:
+                raise StoreBusy(str(lock)) from None
+            time.sleep(0.05)
+    try:
+        yield
+    finally:
+        with suppress(FileNotFoundError):
+            lock.unlink()

agentpace/paths.py

@@ -0,0 +1,62 @@
+"""Where agentpace finds its files.
+
+Installed wheels carry the schema and seed rows under `_bundled`. A source checkout reads the
+same files from the repo root, so there is never a second copy to drift.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_PACKAGE = Path(__file__).resolve().parent
+_REPO_ROOT = _PACKAGE.parent.parent
+
+
+def home() -> Path:
+    """Directory for the local secret, labels and ingested rows."""
+    override = os.environ.get("AGENTPACE_HOME")
+    return Path(override) if override else Path.home() / ".agentpace"
+
+
+def schema_file() -> Path:
+    bundled = _PACKAGE / "_bundled" / "run.schema.json"
+    return bundled if bundled.exists() else _REPO_ROOT / "schema" / "run.schema.json"
+
+
+def turn_schema_file() -> Path:
+    bundled = _PACKAGE / "_bundled" / "turn.schema.json"
+    return bundled if bundled.exists() else _REPO_ROOT / "schema" / "turn.schema.json"
+
+
+def seed_dir() -> Path:
+    bundled = _PACKAGE / "_bundled" / "runs"
+    return bundled if bundled.exists() else _REPO_ROOT / "data" / "runs"
+
+
+def example_plan() -> Path:
+    """The plan the README's Try it runs, shipped so it needs no clone."""
+    bundled = _PACKAGE / "_bundled" / "example-plan.json"
+    return bundled if bundled.exists() else _REPO_ROOT / "examples" / "plan.json"
+
+
+def local_runs() -> Path:
+    return home() / "runs.jsonl"
+
+
+def turns_file() -> Path:
+    """Waits on the human, from main sessions. Local only, never shared."""
+    return home() / "turns.jsonl"
+
+
+def forecasts_file() -> Path:
+    """Recorded forecasts and their scores. Local only, never shared."""
+    return home() / "forecasts.jsonl"
+
+
+def labels_file() -> Path:
+    return home() / "labels.json"
+
+
+def cache_file(adapter: str) -> Path:
+    return home() / f"cache-{adapter}.json"