ai-kit-python 1.4.2__py3-none-any.whl

aikit/scripts/memory_import.py

@@ -0,0 +1,177 @@
+"""Normalize selected text dialogue branches without network access or tool replay."""
+from __future__ import annotations
+
+import hashlib
+import math
+from pathlib import Path
+import re
+
+import memory_store as store
+
+ROLES = {"user", "assistant", "system", "developer", "tool", "function", "unknown"}
+MAX_MESSAGES = 4000
+
+
+def text(value: object, label: str, *, maximum: int = 1024 * 1024) -> str:
+    if not isinstance(value, str) or len(value) > maximum or "\x00" in value:
+        raise ValueError("Invalid " + label)
+    return value
+
+
+def content(value: object) -> tuple[str, int]:
+    if isinstance(value, str):
+        return text(value, "message text"), 0
+    if value is None:
+        return "", 1
+    if not isinstance(value, list):
+        raise ValueError("Expected text or a list of content blocks")
+    parts, omitted = [], 0
+    for part in value:
+        if isinstance(part, str):
+            parts.append(text(part, "text part"))
+        elif isinstance(part, dict):
+            if part.get("type") in {"text", "input_text", "output_text"}:
+                parts.append(text(part.get("text"), "text block"))
+            else:
+                omitted += 1
+        else:
+            raise ValueError("Invalid content part")
+    return text("\n".join(parts), "combined message"), omitted
+
+
+def normalize(rows: list[dict], *, source_format: str, raw: bytes,
+              selection: dict | None = None, omitted: int = 0) -> dict:
+    if not rows or len(rows) > MAX_MESSAGES:
+        raise ValueError("Dialogue must contain 1-4000 messages")
+    messages = []
+    for number, row in enumerate(rows, 1):
+        role = row.get("role")
+        if not isinstance(role, str) or role not in ROLES:
+            raise ValueError("Unknown message role")
+        body, dropped = content(row.get("content"))
+        omitted += dropped + int(bool(row.get("tool_calls")))
+        timestamp = row.get("timestamp")
+        if timestamp is not None and (type(timestamp) not in {str, int, float} or
+                                      (type(timestamp) in {int, float} and not math.isfinite(timestamp))):
+            raise ValueError("Invalid message timestamp")
+        original_id = row.get("id")
+        if original_id is not None:
+            text(original_id, "original message identifier", maximum=256)
+        messages.append({"id": f"m{number:04d}", "role": role, "text": body,
+                         "original_id": original_id, "timestamp": timestamp})
+    if not any(m["text"].strip() for m in messages):
+        raise ValueError("Dialogue has no usable text")
+    return {"schema": 1, "kind": "aikit-dialogue", "format": source_format,
+            "source_sha256": hashlib.sha256(raw).hexdigest(), "selection": selection or {},
+            "omitted_nontext": omitted, "messages": messages}
+
+
+def chatgpt(value: object, conversation_id: str | None, branch: str | None) -> tuple[list[dict], dict]:
+    conversations = value if isinstance(value, list) else [value]
+    if not conversations or any(not isinstance(c, dict) for c in conversations):
+        raise ValueError("Expected ChatGPT conversation object(s)")
+    if conversation_id is not None:
+        conversations = [c for c in conversations if c.get("id", c.get("conversation_id")) == conversation_id]
+    if len(conversations) != 1:
+        raise ValueError("Select exactly one conversation with --conversation-id")
+    conversation = conversations[0]
+    mapping = conversation.get("mapping")
+    if not isinstance(mapping, dict) or not mapping or len(mapping) > 20000:
+        raise ValueError("Expected a bounded ChatGPT mapping")
+    if any(not isinstance(key, str) or not isinstance(node, dict) for key, node in mapping.items()):
+        raise ValueError("Invalid ChatGPT mapping nodes")
+    leaf = branch if branch is not None else conversation.get("current_node")
+    if leaf is None:
+        parents = {n.get("parent") for n in mapping.values() if isinstance(n.get("parent"), str)}
+        leaves = set(mapping) - parents
+        if len(leaves) != 1:
+            raise ValueError("Ambiguous ChatGPT branch; pass --branch")
+        leaf = next(iter(leaves))
+    if not isinstance(leaf, str) or leaf not in mapping:
+        raise ValueError("Selected ChatGPT branch is missing")
+    visited, nodes = set(), []
+    node_id = leaf
+    while node_id is not None:
+        if not isinstance(node_id, str) or node_id not in mapping or node_id in visited:
+            raise ValueError("Broken or cyclic ChatGPT parent chain")
+        visited.add(node_id)
+        node = mapping[node_id]
+        if "parent" not in node:
+            raise ValueError("Missing ChatGPT parent field")
+        nodes.append((node_id, node))
+        node_id = node.get("parent")
+    rows = []
+    for node_id, node in reversed(nodes):
+        message = node.get("message")
+        if message is None:
+            continue
+        if not isinstance(message, dict) or not isinstance(message.get("author"), dict):
+            raise ValueError("Invalid ChatGPT message")
+        payload = message.get("content")
+        if not isinstance(payload, dict):
+            raise ValueError("Invalid ChatGPT content object")
+        if "parts" in payload:
+            body = payload["parts"]
+        elif isinstance(payload.get("text"), str):
+            body = payload["text"]
+        else:
+            body = None  # Nontext-only messages stay visible as an omission.
+        rows.append({"id": node_id, "role": message["author"].get("role"), "content": body,
+                     "timestamp": message.get("create_time")})
+    selected_id = conversation.get("id", conversation.get("conversation_id"))
+    if selected_id is not None:
+        text(selected_id, "conversation identifier", maximum=256)
+    return rows, {"conversation_id": selected_id, "branch": leaf}
+
+
+def transcript(value: str) -> list[dict]:
+    """Recognize explicit role headers outside code fences; preserve unlabeled text."""
+    rows, lines, role, fence = [], [], "unknown", None
+    header = re.compile(r"^(?:#{1,6}\s+)?(user|assistant|system|developer|tool|human|chatgpt|\u043f\u043e\u043b\u044c\u0437\u043e\u0432\u0430\u0442\u0435\u043b\u044c|\u0430\u0441\u0441\u0438\u0441\u0442\u0435\u043d\u0442):\s*(.*)$", re.I)
+    for line in value.splitlines(keepends=True):
+        match = header.fullmatch(line.rstrip("\r\n")) if fence is None else None
+        if match:
+            if lines:
+                rows.append({"role": role, "content": "".join(lines)})
+            label = match[1].casefold()
+            role = {"human": "user", "chatgpt": "assistant", "\u043f\u043e\u043b\u044c\u0437\u043e\u0432\u0430\u0442\u0435\u043b\u044c": "user",
+                    "\u0430\u0441\u0441\u0438\u0441\u0442\u0435\u043d\u0442": "assistant"}.get(label, label)
+            lines = [match[2] + ("\n" if line.endswith("\n") else "")] if match[2] else []
+            marker = re.match(r"^\s*(`{3,}|~{3,})", match[2])
+            if marker:
+                fence = marker[1]
+        else:
+            lines.append(line)
+            marker = re.match(r"^\s*(`{3,}|~{3,})", line)
+            if marker:
+                token = marker[1]
+                if fence is None:
+                    fence = token
+                elif token[0] == fence[0] and len(token) >= len(fence):
+                    fence = None
+    if lines:
+        rows.append({"role": role, "content": "".join(lines)})
+    return rows
+
+
+def load(path: Path, *, source_format: str = "auto", conversation_id: str | None = None,
+         branch: str | None = None) -> dict:
+    raw = store.read_bytes(path)
+    if source_format == "auto":
+        source_format = "json" if path.suffix.casefold() == ".json" else "text"
+    if source_format == "text":
+        if conversation_id is not None or branch is not None:
+            raise ValueError("Conversation/branch selection requires ChatGPT JSON")
+        return normalize(transcript(raw.decode("utf-8-sig")), source_format="text", raw=raw)
+    value = store.decode(raw)
+    is_mapping = isinstance(value, dict) and "mapping" in value
+    is_collection = isinstance(value, list) and any(isinstance(c, dict) and "mapping" in c for c in value)
+    if source_format == "chatgpt" or (source_format == "json" and (is_mapping or is_collection)):
+        rows, selection = chatgpt(value, conversation_id, branch)
+        return normalize(rows, source_format="chatgpt", raw=raw, selection=selection)
+    if conversation_id is not None or branch is not None:
+        raise ValueError("Conversation/branch selection requires ChatGPT JSON")
+    rows = value.get("messages") if isinstance(value, dict) else value
+    if not isinstance(rows, list) or any(not isinstance(m, dict) for m in rows):
+        raise ValueError("Expected a messages array or an object containing messages")
+    return normalize(rows, source_format="messages", raw=raw)

aikit/scripts/memory_store.py

@@ -0,0 +1,125 @@
+"""Bounded local I/O and immutable artifacts for dialogue memory."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import stat
+
+import install
+
+LIMIT = 16 * 1024 * 1024
+MARKER = {"schema": 1, "kind": "aikit-memory-workspace"}
+
+
+def encode(value: object) -> bytes:
+    return (json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False) + "\n").encode("utf-8")
+
+
+def digest(value: object) -> str:
+    return hashlib.sha256(encode(value)).hexdigest()
+
+
+def guarded(path: Path) -> Path:
+    path = path.absolute()
+    for parent in (path, *path.parents):
+        if install.is_link(parent):
+            raise ValueError("Linked paths and junctions are not supported")
+        if parent != path and parent.exists() and not parent.is_dir():
+            raise ValueError("Path parent is not a directory")
+    return path.resolve()
+
+
+def read_bytes(path: Path, *, limit: int = LIMIT) -> bytes:
+    path = guarded(path)
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    with os.fdopen(os.open(path, flags), "rb") as stream:
+        info = os.fstat(stream.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size > limit:
+            raise ValueError("Expected a bounded regular file")
+        data = stream.read(limit + 1)
+    if len(data) > limit:
+        raise ValueError("Input exceeds the byte limit")
+    return data
+
+
+def decode(data: bytes) -> object:
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise ValueError("Duplicate JSON keys are not supported")
+            result[key] = value
+        return result
+
+    def constant(_):
+        raise ValueError("Nonfinite JSON numbers are not supported")
+
+    return json.loads(data.decode("utf-8-sig"), object_pairs_hook=pairs, parse_constant=constant)
+
+
+def read_json(path: Path) -> object:
+    return decode(read_bytes(path))
+
+
+def root(path: Path, *, existing: bool = True) -> Path:
+    path = guarded(path)
+    if path.exists() and not path.is_dir():
+        raise ValueError("Workspace must be a directory")
+    marker = install.safe_path(path, "workspace.json")
+    if marker.exists():
+        value = read_json(marker)
+        if not isinstance(value, dict) or type(value.get("schema")) is not int or value != MARKER:
+            raise ValueError("Unknown workspace marker")
+    elif existing or (path.exists() and any(path.iterdir())):
+        raise ValueError("Use a new/empty directory or an AI-KIT memory workspace")
+    return path
+
+
+def artifact(workspace: Path, relative: str) -> object:
+    return read_json(install.safe_path(root(workspace), relative))
+
+
+def write(workspace: Path, files: dict[str, bytes], *, apply: bool) -> list[str]:
+    """Preview first; exclusively create files, preserve existing bytes, allow identical reruns."""
+    workspace = root(workspace, existing=False)
+    if "workspace.json" in files:
+        raise ValueError("Workspace marker is managed internally")
+    files = {"workspace.json": encode(MARKER), **files}
+    writes = []
+    for relative, data in files.items():
+        if len(data) > LIMIT:
+            raise ValueError("Artifact exceeds the byte limit")
+        target = install.safe_path(workspace, relative)
+        if target.exists():
+            if target.stat().st_nlink != 1 or read_bytes(target) != data:
+                raise ValueError("Existing artifact differs or is hard-linked; use a new name/workspace")
+        else:
+            writes.append(relative)
+    if not apply:
+        return writes
+    for relative in writes:
+        target = install.safe_path(guarded(workspace), relative)
+        missing = []
+        parent = target.parent
+        while not parent.exists():
+            missing.append(parent)
+            parent = parent.parent
+        for parent in reversed(missing):
+            guarded(parent)
+            parent.mkdir(mode=0o700, exist_ok=True)
+        # O_EXCL refuses a file/link created after planning, rather than replacing it.
+        descriptor = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        identity = os.fstat(descriptor)
+        try:
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(files[relative])
+                stream.flush()
+                os.fsync(stream.fileno())
+        except BaseException:
+            current = target.lstat()
+            if (current.st_dev, current.st_ino) == (identity.st_dev, identity.st_ino):
+                target.unlink()
+            raise
+    return writes

aikit/scripts/metrics.py

@@ -0,0 +1,351 @@
+"""Opt-in local task measurements. No prompts, credentials, API calls, or automatic pricing."""
+from __future__ import annotations
+
+import argparse
+from collections import defaultdict
+from decimal import Decimal, InvalidOperation
+import json
+import math
+import os
+from pathlib import Path
+import re
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import install
+
+JOURNAL = "ai-kit/.metrics/tasks.jsonl"
+LOCK = "ai-kit/.metrics/write.lock"
+IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}\Z")
+TOKEN_FIELDS = ("input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens")
+ATTEMPT_DISPOSITIONS = ("succeeded", "failed", "inconclusive")
+STACKS = ("LARAVEL", "FILAMENT", "GO", "MOODLE", "PYTHON", "RUST", "DOTNET", "JAVA", "INFRA", "unknown")
+
+
+def _fields(value: object, allowed: set[str], label: str) -> dict:
+    if not isinstance(value, dict) or set(value) - allowed:
+        raise ValueError(f"Invalid {label} object or unknown fields")
+    return value
+
+
+def _identifier(value: object, label: str) -> str:
+    if not isinstance(value, str) or not IDENTIFIER.fullmatch(value):
+        raise ValueError(f"Invalid {label}; use an opaque identifier, not task text")
+    return value
+
+
+def validate_record(value: object) -> dict:
+    record = _fields(value, {"schema", "task_id", "experiment", "arm", "kit_version", "outcome",
+                             "checks", "rework", "escalations", "attempts", "metadata"}, "task record")
+    if type(record.get("schema")) is not int or record["schema"] not in {1, 2, 3}:
+        raise ValueError("Expected measurement schema 1, 2 or 3")
+    if record["schema"] < 3 and "metadata" in record:
+        raise ValueError("Metadata requires schema 3")
+    if record["schema"] == 3:
+        metadata = _fields(record.get("metadata"), {"stack", "task_class", "level", "revision",
+                                                   "repetition", "review", "capabilities", "case_id"}, "metadata")
+        if set(metadata) != {"stack", "task_class", "level", "revision", "repetition", "review", "capabilities", "case_id"}:
+            raise ValueError("Schema 3 requires complete metadata, with null for unknown revision/level")
+        if not isinstance(metadata["stack"], str) or metadata["stack"] not in STACKS:
+            raise ValueError("Unknown measurement stack")
+        _identifier(metadata["task_class"], "task_class")
+        _identifier(metadata["case_id"], "case_id")
+        if metadata["level"] is not None and (type(metadata["level"]) is not int or not 0 <= metadata["level"] <= 6):
+            raise ValueError("Metadata level must be 0-6 or null")
+        if metadata["revision"] is not None and (not isinstance(metadata["revision"], str) or
+                                                not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", metadata["revision"])):
+            raise ValueError("Revision must be a full Git object ID or null")
+        if type(metadata["repetition"]) is not int or metadata["repetition"] < 1:
+            raise ValueError("Repetition must be a positive integer")
+        if not isinstance(metadata["review"], str) or metadata["review"] not in {"manual", "independent", "pending"}:
+            raise ValueError("Review must be manual, independent or pending")
+        if metadata["review"] == "pending" and record.get("outcome") != "incomplete":
+            raise ValueError("Pending semantic review requires an incomplete outcome")
+        if not isinstance(metadata["capabilities"], list):
+            raise ValueError("Capabilities must be a list")
+        for capability in metadata["capabilities"]:
+            _identifier(capability, "capability")
+    for field in ("task_id", "experiment", "arm", "kit_version"):
+        _identifier(record.get(field), field)
+    if not isinstance(record.get("outcome"), str) or record["outcome"] not in {"correct", "incorrect", "incomplete"}:
+        raise ValueError("Outcome must be correct, incorrect, or incomplete after review")
+    if not isinstance(record.get("checks"), str) or record["checks"] not in {"passed", "failed", "not-run"}:
+        raise ValueError("Checks must be passed, failed, or not-run")
+    if record["outcome"] == "correct" and record["checks"] == "failed":
+        raise ValueError("A correct result cannot have failed required checks")
+    for field in ("rework", "escalations"):
+        if record["schema"] == 3 and field in record and record[field] is None:
+            continue
+        if type(record.get(field)) is not int or record[field] < 0:
+            raise ValueError(f"{field} must be a nonnegative integer")
+    attempts = record.get("attempts")
+    if not isinstance(attempts, list) or not attempts:
+        raise ValueError("Include all attempts, including failures and recovery")
+    for attempt in attempts:
+        allowed = {"provider", "model", "effort", "duration_seconds", "cost", *TOKEN_FIELDS}
+        if record["schema"] >= 2:
+            allowed.add("disposition")
+        _fields(attempt, allowed,
+                "attempt")
+        for field in ("provider", "model", "effort"):
+            if attempt.get(field) is not None:
+                _identifier(attempt[field], field)
+        duration = attempt.get("duration_seconds")
+        if duration is not None and (type(duration) not in {int, float} or
+                                     duration < 0 or duration > sys.float_info.max or
+                                     not math.isfinite(duration)):
+            raise ValueError("duration_seconds must be finite and nonnegative, or null")
+        for field in TOKEN_FIELDS:
+            number = attempt.get(field)
+            if number is not None and (type(number) is not int or number < 0):
+                raise ValueError(f"{field} must be a nonnegative integer or null")
+        for subset, total in (("cached_input_tokens", "input_tokens"),
+                              ("reasoning_tokens", "output_tokens")):
+            if (attempt.get(subset) is not None and attempt.get(total) is not None and
+                    attempt[subset] > attempt[total]):
+                raise ValueError(f"{subset} cannot exceed {total}")
+        cost = attempt.get("cost")
+        if cost is not None:
+            _fields(cost, {"amount", "currency", "source"}, "cost")
+            amount = cost.get("amount")
+            if not isinstance(amount, str) or not re.fullmatch(r"\d{1,16}(?:\.\d{1,12})?", amount):
+                raise ValueError("Cost amount must be a nonnegative decimal string")
+            try:
+                Decimal(amount)
+            except InvalidOperation as exc:
+                raise ValueError("Invalid decimal amount") from exc
+            if not isinstance(cost.get("currency"), str) or not re.fullmatch(r"[A-Z]{3}", cost["currency"]):
+                raise ValueError("Cost currency must be a three-letter uppercase code")
+            if not isinstance(cost.get("source"), str) or cost["source"] not in {"billing", "provider-usage", "estimate"}:
+                raise ValueError("Cost source must be billing, provider-usage, or estimate")
+        if record["schema"] >= 2 and attempt.get("disposition") not in ATTEMPT_DISPOSITIONS:
+            raise ValueError("Schema 2 attempts need disposition: succeeded, failed, or inconclusive")
+    # Normalize JSON values without carrying caller-owned mutable objects into a write plan.
+    return json.loads(json.dumps(record, allow_nan=False))
+
+
+def _target(project: Path) -> Path:
+    project = project.absolute()
+    if install.is_link(project):
+        raise ValueError("Refusing a linked project root")
+    project = project.resolve()
+    if not project.is_dir():
+        raise ValueError("Project must be an existing directory")
+    return project
+
+
+def read_records(project: Path) -> list[dict]:
+    path = install.safe_path(_target(project), JOURNAL)
+    if not path.exists():
+        return []
+    records, identities = [], set()
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        try:
+            record = validate_record(json.loads(line))
+            identity = (record["experiment"], record["arm"], record["task_id"])
+            if identity in identities:
+                raise ValueError("Duplicate task identity")
+            identities.add(identity)
+            records.append(record)
+        except ValueError as exc:
+            raise ValueError(f"Invalid journal line {number}: {exc}") from exc
+    return records
+
+
+def record_task(project: Path, record: dict, *, apply: bool = False) -> dict:
+    project = _target(project)
+    record = validate_record(record)
+    path = install.safe_path(project, JOURNAL)
+    lock = install.safe_path(project, LOCK)
+
+    def check_duplicate(records: list[dict]) -> None:
+        if any(all(existing[key] == record[key] for key in ("experiment", "arm", "task_id"))
+               for existing in records):
+            raise ValueError("Task already recorded for this experiment/arm; journal left unchanged")
+
+    check_duplicate(read_records(project))
+    if apply:
+        lock.parent.mkdir(parents=True, exist_ok=True)
+        # Exclusive lock protects cooperating writers. Never remove another writer's lock.
+        descriptor = os.open(install.safe_path(project, LOCK), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        try:
+            os.close(descriptor)
+            records = read_records(project)
+            check_duplicate(records)
+            data = "".join(json.dumps(item, ensure_ascii=True, allow_nan=False) + "\n"
+                           for item in [*records, record]).encode("utf-8")
+            install.atomic_write(install.safe_path(project, JOURNAL), data)
+        finally:
+            install.safe_path(project, LOCK).unlink()
+    return {"preview": not apply, "journal": str(path), "task_id": record["task_id"],
+            "attempts": len(record["attempts"])}
+
+
+def summarize(records: list[dict]) -> dict:
+    groups: dict[tuple[str, str], list[dict]] = defaultdict(list)
+    for record in records:
+        record = validate_record(record)
+        groups[(record["experiment"], record["arm"])].append(record)
+    results = []
+    for (experiment, arm), tasks in sorted(groups.items()):
+        attempts = [attempt for task in tasks for attempt in task["attempts"]]
+        correct = sum(task["outcome"] == "correct" for task in tasks)
+        costs: dict[str, Decimal] = defaultdict(Decimal)
+        known_costs = 0
+        estimated = 0
+        for attempt in attempts:
+            cost = attempt.get("cost")
+            if cost is not None:
+                costs[cost["currency"]] += Decimal(cost["amount"])
+                known_costs += 1
+                estimated += cost["source"] == "estimate"
+        complete = known_costs == len(attempts) and len(costs) == 1 and not estimated
+        total = next(iter(costs.values())) if complete else None
+        durations = [attempt["duration_seconds"] for attempt in attempts
+                     if attempt.get("duration_seconds") is not None]
+        results.append({"experiment": experiment, "arm": arm, "tasks": len(tasks), "correct": correct,
+                        "success_rate": correct / len(tasks), "attempts": len(attempts),
+                        "rework": sum(task["rework"] for task in tasks) if all(task["rework"] is not None for task in tasks) else None,
+                        "escalations": sum(task["escalations"] for task in tasks) if all(task["escalations"] is not None for task in tasks) else None,
+                        "intervention_coverage": {field: {"known": sum(task[field] is not None for task in tasks),
+                                                          "total": len(tasks)} for field in ("rework", "escalations")},
+                        "checks_not_run": sum(task["checks"] == "not-run" for task in tasks),
+                        "known_cost_by_currency": {key: str(value) for key, value in sorted(costs.items())},
+                        "cost_coverage": {"known": known_costs, "total": len(attempts), "estimated": estimated},
+                        "cost_per_correct_result": str(total / correct) if complete and correct else None,
+                        "duration_seconds": sum(durations) if len(durations) == len(attempts) else None,
+                        "duration_coverage": {"known": len(durations), "total": len(attempts)},
+                        "tokens": {field: {"known_total": sum(a.get(field) or 0 for a in attempts),
+                                           "known_attempts": sum(a.get(field) is not None for a in attempts),
+                                           "total_attempts": len(attempts)} for field in TOKEN_FIELDS}})
+    return {"groups": results,
+            "note": "Descriptive totals only; include all failed/recovery attempts. Unknown values remain "
+                    "unknown. Compare matched tasks and reviewed correctness before claiming savings."}
+
+
+def analyze(records: list[dict]) -> dict:
+    """Aggregate reviewed tasks per provider to inform routing without writing anything."""
+    providers: dict[str, dict] = {}
+    for record in records:
+        record = validate_record(record)
+        correct = record["outcome"] == "correct"
+        for attempt in record["attempts"]:
+            provider = attempt.get("provider")
+            if provider is None:
+                continue
+            entry = providers.setdefault(provider, {"tasks": set(), "correct_tasks": set(),
+                                                    "attempts": 0, "cost": defaultdict(Decimal),
+                                                    "cost_attempts": 0, "models": set(), "efforts": set(),
+                                                    "dispositions": defaultdict(int), "known_dispositions": 0,
+                                                    "estimated": 0})
+            entry["attempts"] += 1
+            identity = (record["experiment"], record["arm"], record["task_id"])
+            entry["tasks"].add(identity)
+            if correct:
+                entry["correct_tasks"].add(identity)
+            if attempt.get("model") is not None:
+                entry["models"].add(attempt["model"])
+            if attempt.get("effort") is not None:
+                entry["efforts"].add(attempt["effort"])
+            cost = attempt.get("cost")
+            if cost is not None:
+                entry["cost"][cost["currency"]] += Decimal(cost["amount"])
+                entry["cost_attempts"] += 1
+                entry["estimated"] += cost["source"] == "estimate"
+            disposition = attempt.get("disposition")
+            if disposition is not None:
+                entry["dispositions"][disposition] += 1
+                entry["known_dispositions"] += 1
+    results = []
+    for name in sorted(providers):
+        entry = providers[name]
+        tasks = len(entry["tasks"])
+        correct = len(entry["correct_tasks"])
+        complete = (entry["cost_attempts"] == entry["attempts"] and len(entry["cost"]) == 1
+                    and not entry["estimated"])
+        total = next(iter(entry["cost"].values())) if complete else None
+        decisive = entry["dispositions"]["succeeded"] + entry["dispositions"]["failed"]
+        results.append({"provider": name, "attempts": entry["attempts"], "tasks": tasks,
+                        "correct_tasks": correct, "success_rate": correct / tasks if tasks else None,
+                        "known_cost_by_currency": {key: str(value) for key, value in sorted(entry["cost"].items())},
+                        "cost_coverage": {"known": entry["cost_attempts"], "total": entry["attempts"],
+                                          "estimated": entry["estimated"]},
+                        "cost_per_correct": str(total / correct) if complete and correct else None,
+                        "attempt_dispositions": {key: entry["dispositions"][key] for key in ATTEMPT_DISPOSITIONS},
+                        "attempt_disposition_coverage": {"known": entry["known_dispositions"],
+                                                         "total": entry["attempts"]},
+                        "attempt_success_rate": (entry["dispositions"]["succeeded"] / decisive
+                                                 if decisive else None),
+                        "models": sorted(entry["models"]), "efforts": sorted(entry["efforts"])})
+    return {"providers": results,
+            "note": "Descriptive per-provider totals from reviewed records; a task identity is experiment, arm, "
+                    "and task_id, and each provider used in its attempts receives that attribution. Schema 2 "
+                    "attempt dispositions describe execution, not causation. Compare matched tasks and reviewed "
+                    "correctness before changing selection.json."}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    record_parser = sub.add_parser("record", help="Preview or record one reviewed task and all its attempts")
+    record_parser.add_argument("project", type=Path)
+    record_parser.add_argument("--from-json", type=Path, required=True)
+    record_parser.add_argument("--apply", action="store_true")
+    summary_parser = sub.add_parser("summary", help="Summarize the local journal without writing")
+    summary_parser.add_argument("project", type=Path)
+    analyze_parser = sub.add_parser("analyze", help="Aggregate per provider to inform routing, without writing")
+    analyze_parser.add_argument("project", type=Path)
+    compare_parser = sub.add_parser("compare", help="Compare matched reviewed trials with actual costs")
+    compare_parser.add_argument("project", type=Path)
+    compare_parser.add_argument("--experiment", required=True)
+    compare_parser.add_argument("--baseline", default="baseline")
+    compare_parser.add_argument("--candidate", default="kit-fixed")
+    stacks_parser = sub.add_parser("stacks", help="Summarize by declared technology stack")
+    stacks_parser.add_argument("project", type=Path)
+    propose_parser = sub.add_parser("propose", help="Preview or save evidence; never apply routing changes")
+    propose_parser.add_argument("project", type=Path)
+    propose_parser.add_argument("--stack", choices=STACKS, required=True)
+    propose_parser.add_argument("--task-class", required=True)
+    propose_parser.add_argument("--level", type=int, required=True)
+    propose_parser.add_argument("--capability", action="append", default=[])
+    propose_parser.add_argument("--minimum", type=int, default=20)
+    propose_parser.add_argument("--quality-floor", type=float, default=0.8)
+    propose_parser.add_argument("--apply", action="store_true")
+    restore_parser = sub.add_parser("restore", help="Explicitly restore a proposal's prior selection with backup")
+    restore_parser.add_argument("project", type=Path)
+    restore_parser.add_argument("--proposal", required=True)
+    restore_parser.add_argument("--apply", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "record":
+            record = json.loads(args.from_json.read_text(encoding="utf-8"))
+            result = record_task(args.project, record, apply=args.apply)
+        elif args.command == "analyze":
+            result = analyze(read_records(args.project))
+        elif args.command in {"compare", "stacks", "propose", "restore"}:
+            import learning
+            if args.command == "compare":
+                result = learning.compare(read_records(args.project), args.experiment, args.baseline, args.candidate)
+            elif args.command == "stacks":
+                result = learning.by_stack(read_records(args.project))
+            elif args.command == "restore":
+                result = learning.restore_selection(args.project, args.proposal, apply=args.apply)
+            else:
+                proposal = {"stack": args.stack, "task_class": args.task_class, "level": args.level,
+                            "capabilities": args.capability, "minimum": args.minimum,
+                            "quality_floor": args.quality_floor,
+                            "candidates": learning.candidates(read_records(args.project), stack=args.stack,
+                                task_class=args.task_class, level=args.level, capabilities=args.capability,
+                                minimum=args.minimum, quality_floor=args.quality_floor)}
+                result = learning.save_proposal(args.project, proposal, apply=args.apply)
+        else:
+            result = summarize(read_records(args.project))
+        print(json.dumps(result, indent=2, allow_nan=False))
+        return 0
+    except (OSError, ValueError) as exc:
+        print(f"Measurement refused: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())