autoforge-trainer 1.0.2__py3-none-any.whl

autoforge/api.py

@@ -0,0 +1,330 @@
+"""Core API shared by the MCP server (and later REST / GUI).
+
+Functions return JSON-serializable data and raise AutoForgeError subclasses;
+transports wrap them in the Envelope shape. `actor` says who acts (for the
+audit log); `brain` decides what data the caller may see (privacy guard).
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Any
+
+from autoforge import config
+from autoforge.data import registry
+from autoforge.data.profile import profile
+from autoforge.engine import runner
+from autoforge.engine.store import RunStore, list_runs
+from autoforge.engine.validate import check_plan, parse_plan
+from autoforge.errors import AutoForgeError
+from autoforge.hardware.detect import detect_hardware
+from autoforge.packs import installer
+from autoforge.packs.index import load_index, search
+from autoforge.policy.privacy import require_access
+from autoforge.schemas.core import BrainKind
+
+TRAINER_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}\.py$")
+
+
+class BadRequest(AutoForgeError):
+    code = "BAD_REQUEST"
+
+
+# ---------- hardware / schema ----------
+
+
+def hardware() -> dict:
+    hw = detect_hardware()
+    return hw.model_dump() | {"best_device": hw.best_device}
+
+
+# ---------- packs ----------
+
+
+def pack_search(query: str | None = None, task: str | None = None, fit: bool = True) -> dict:
+    hw = detect_hardware() if fit else None
+    index, notes = load_index()
+    lock = installer.read_lock()
+    hits = [
+        h.model_dump(mode="json") | {"installed": h.entry.name in lock}
+        for h in search(index, task=task, query=query, hardware=hw)
+    ]
+    return {"hits": hits, "notes": notes}
+
+
+def pack_install(source: str, force: bool = False) -> dict:
+    return installer.install(source, force=force).model_dump()
+
+
+def pack_info(name: str, knowledge: bool = True) -> dict:
+    rec, pack = installer.get_installed(name)
+    data = {
+        "installed": rec.model_dump(),
+        "manifest": pack.manifest.model_dump(),
+        "recipes": [r.model_dump() for r in pack.recipes],
+        "missing_dependencies": installer.missing_dependencies(pack),
+    }
+    if knowledge:
+        data["knowledge"] = pack.knowledge()
+    return data
+
+
+def pack_list() -> list[dict]:
+    return [r.model_dump() for r in installer.read_lock().values()]
+
+
+# ---------- data ----------
+
+
+def data_profile(path: str, brain: BrainKind) -> dict:
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise BadRequest(f"path not found: {path}")
+    sens = registry.sensitivity_of(p)
+    access = require_access(brain, sens, str(p.resolve()))
+    return profile(p, access) | {"sensitivity": sens.value}
+
+
+# ---------- trainers written by AI ----------
+
+
+def trainers_dir() -> Path:
+    return config.home() / "workspace" / "trainers"
+
+
+def trainer_write(filename: str, source: str) -> dict:
+    """Save AI-written trainer code to the workspace and report its top-level functions."""
+    if not TRAINER_NAME_RE.fullmatch(filename):
+        raise BadRequest("filename must look like 'my_trainer.py' (letters, digits, '_')")
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        raise BadRequest(f"syntax error: {e}", hint="Fix the code and write it again.")
+    path = trainers_dir() / filename
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(source, encoding="utf-8")
+    funcs = [n.name for n in tree.body if isinstance(n, ast.FunctionDef)]
+    return {
+        "path": str(path),
+        "functions": funcs,
+        "use_in_plan": f"custom_code_path: {path}:{'train' if 'train' in funcs else (funcs[0] if funcs else 'train')}",
+    }
+
+
+# ---------- plans / runs ----------
+
+
+def _plan(plan: dict[str, Any], base: Path | None):
+    return parse_plan(plan, base or Path.cwd())
+
+
+def plan_validate(plan: dict[str, Any], actor: str, brain: BrainKind, base: Path | None = None) -> dict:
+    p = _plan(plan, base)
+    runner.require_data_access(p, actor, brain)
+    return check_plan(p).model_dump() | {"resolved_data_path": p.data_path}
+
+
+def run_start(plan: dict[str, Any], actor: str, brain: BrainKind, base: Path | None = None) -> dict:
+    store = runner.create_run(_plan(plan, base), actor, brain=brain)
+    runner.start(store, actor)
+    return runner.status(store).model_dump(mode="json")
+
+
+def run_status(run_id: str) -> dict:
+    return runner.status(RunStore.open(run_id)).model_dump(mode="json")
+
+
+def run_wait(run_id: str, timeout_seconds: float = 30) -> dict:
+    timeout = max(0.0, min(timeout_seconds, 120.0))
+    return runner.wait(RunStore.open(run_id), timeout).model_dump(mode="json")
+
+
+def run_list(limit: int = 20) -> list[dict]:
+    return [runner.status(s).model_dump(mode="json") for s in list_runs()[:limit]]
+
+
+def run_metrics(run_id: str, last: int = 5) -> dict:
+    return runner.metrics_summary(RunStore.open(run_id), last)
+
+
+def run_logs(run_id: str, tail: int = 50) -> dict:
+    return {"lines": RunStore.open(run_id).logs_tail(max(1, min(tail, 500)))}
+
+
+def run_audit(run_id: str) -> list[dict]:
+    return RunStore.open(run_id).audit_log()
+
+
+def run_pause(run_id: str, actor: str) -> dict:
+    return runner.pause(RunStore.open(run_id), actor).model_dump(mode="json")
+
+
+def run_resume(run_id: str, actor: str) -> dict:
+    return runner.resume(RunStore.open(run_id), actor).model_dump(mode="json")
+
+
+def run_stop(run_id: str, actor: str, grace_seconds: float = 10.0) -> dict:
+    return runner.stop(RunStore.open(run_id), actor, grace_seconds).model_dump(mode="json")
+
+
+def run_retry(run_id: str, actor: str, brain: BrainKind) -> dict:
+    store = runner.retry(RunStore.open(run_id), actor, brain=brain)
+    runner.start(store, actor)
+    return runner.status(store).model_dump(mode="json")
+
+
+# ---------- P5: diagnosis, live adjustment, comparison, hyperparameter search ----------
+
+
+def run_diagnose(run_id: str) -> dict:
+    from autoforge.engine.diagnose import diagnose
+
+    return diagnose(RunStore.open(run_id))
+
+
+def run_adjust(run_id: str, actor: str, changes: dict[str, Any]) -> dict:
+    return runner.adjust(RunStore.open(run_id), actor, changes)
+
+
+def run_compare(run_ids: list[str], metric: str | None = None) -> dict:
+    if not run_ids:
+        raise BadRequest("give at least one run_id")
+    return runner.compare(run_ids, metric)
+
+
+def hpo_start(
+    plan: dict[str, Any], metric: str, n_trials: int, actor: str, brain: BrainKind,
+    direction: str | None = None, search_space: dict[str, Any] | None = None,
+    timeout_minutes: float | None = None, base: Path | None = None,
+) -> dict:
+    from autoforge.engine import hpo
+
+    if direction not in (None, "maximize", "minimize"):
+        raise BadRequest("direction must be 'maximize' or 'minimize'")
+    store = hpo.create_study(_plan(plan, base), metric, n_trials, actor, brain, direction, search_space, timeout_minutes)
+    hpo.start_study(store)
+    return hpo.status(store).model_dump(mode="json")
+
+
+def hpo_status(study_id: str) -> dict:
+    from autoforge.engine import hpo
+
+    return hpo.status(hpo.StudyStore.open(study_id)).model_dump(mode="json")
+
+
+def hpo_wait(study_id: str, timeout_seconds: float = 60) -> dict:
+    from autoforge.engine import hpo
+
+    return hpo.wait(hpo.StudyStore.open(study_id), max(0.0, min(timeout_seconds, 120.0))).model_dump(mode="json")
+
+
+def hpo_stop(study_id: str, actor: str) -> dict:
+    from autoforge.engine import hpo
+
+    return hpo.stop(hpo.StudyStore.open(study_id), actor).model_dump(mode="json")
+
+
+def hpo_list(limit: int = 20) -> list[dict]:
+    from autoforge.engine import hpo
+
+    out = []
+    for s in hpo.list_studies()[:limit]:
+        v = hpo.status(s).model_dump(mode="json")
+        v.pop("trials", None)
+        out.append(v)
+    return out
+
+
+# ---------- P6: model registry and serving ----------
+
+
+def model_register(run_id: str, name: str, actor: str, description: str = "") -> dict:
+    from autoforge.registry import models as reg
+
+    return reg.register(run_id, name, actor, description).model_dump(mode="json")
+
+
+def model_list() -> list[dict]:
+    from autoforge.registry import models as reg
+
+    return [{"model": c.ref, "task": c.task.task_type, "target": c.task.target, "metrics": c.metrics,
+             "servable": c.servable, "run_id": c.run_id, "versions": reg.versions(c.name)} for c in reg.list_models()]
+
+
+def model_info(ref: str) -> dict:
+    from autoforge.registry import models as reg
+
+    card = reg.get_card(ref)
+    return card.model_dump(mode="json") | {"versions": reg.versions(card.name),
+                                           "export_formats": ["bundle", *card.exporters]}
+
+
+def model_predict(ref: str, rows: list[dict[str, Any]]) -> dict:
+    from autoforge.registry import models as reg
+
+    return reg.predict(ref, rows)
+
+
+def model_export(ref: str, fmt: str, out: str | None = None) -> dict:
+    from autoforge.registry import models as reg
+
+    card = reg.get_card(ref)
+    suffix = {"bundle": "zip"}.get(fmt, fmt)
+    path = Path(out) if out else config.home() / "exports" / f"{card.name}-v{card.version}.{suffix}"
+    return reg.export(ref, fmt, path)
+
+
+# ---------- P7: pack authoring ----------
+
+
+def pack_create(name: str, files: dict[str, str], overwrite: bool = False) -> dict:
+    from autoforge.packs.authoring import create_from_files
+
+    return create_from_files(name, files, overwrite)
+
+
+def pack_test(target: str) -> dict:
+    from autoforge.packs.authoring import test_pack
+
+    path = target if Path(target).is_dir() else installer.get_installed(target)[0].path
+    return test_pack(path)
+
+
+# ---------- P8: helpers for the GUI ----------
+
+
+def run_series(run_id: str, max_points: int = 500) -> dict[str, list[list[float]]]:
+    """Per-step metric curves {name: [[step, value], ...]} for charts. Final metrics (logged without a
+    step) are not curves and are left out; so are series with a single point."""
+    series: dict[str, list[list[float]]] = {}
+    for e in RunStore.open(run_id).events():
+        if e.get("type") == "metric" and e.get("step") is not None:
+            series.setdefault(e["name"], []).append([e["step"], e["value"]])
+    series = {k: v for k, v in series.items() if len(v) >= 2}
+    for name, pts in series.items():
+        if len(pts) > max_points:  # keep the shape, drop points evenly; always keep the last
+            stride = len(pts) / max_points
+            series[name] = [pts[int(k * stride)] for k in range(max_points - 1)] + [pts[-1]]
+    return series
+
+
+def task_catalog() -> list[dict]:
+    """Task types available from installed packs and the index, with the packs offering each."""
+    tasks: dict[str, set[str]] = {}
+    for rec in installer.read_lock().values():
+        try:
+            _, pack = installer.get_installed(rec.name)
+        except AutoForgeError:
+            continue
+        for t in pack.manifest.tasks:
+            tasks.setdefault(t, set()).add(pack.manifest.name)
+    try:
+        index, _ = load_index()
+        for e in index.packs:
+            for t in e.tasks:
+                tasks.setdefault(t, set()).add(e.name)
+    except AutoForgeError:
+        pass
+    return [{"task": t, "packs": sorted(p)} for t, p in sorted(tasks.items())]

autoforge/cli/agent.py

@@ -0,0 +1,102 @@
+"""`autoforge train "<goal>"`: the built-in agent plans and trains from one sentence."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+import typer
+
+from autoforge.agents.loop import AgentEvent, run_agent
+from autoforge.agents.providers import ToolCall, make_provider, parse_brain
+from autoforge.cli.output import emit, errors_as_envelope, fail
+
+_SHORT = {"hardware_profile", "pack_list", "run_status", "run_wait", "run_metrics", "run_list"}
+
+
+def _describe_plan(call: ToolCall) -> str:
+    if call.name == "run_retry":
+        return f"retry run {call.arguments.get('run_id')}"
+    if call.name == "hpo_start":
+        a = call.arguments
+        head = (f"  hyperparameter search: {a.get('n_trials', 10)} trials, optimise {a.get('metric')}"
+                f" ({a.get('direction') or 'auto direction'})\n")
+        return head + _describe_plan(ToolCall(call.id, "run_start", {"plan": a.get("plan")}))
+    plan = call.arguments.get("plan") or {}
+    task = plan.get("task") or {}
+    method = (f"{plan.get('pack')} / {plan.get('recipe')}" if plan.get("pack")
+              else f"custom code {plan.get('custom_code_path')}")
+    lines = [
+        f"  task:            {task.get('task_type')} (target: {task.get('target')}, metric: {task.get('metric')})",
+        f"  data:            {plan.get('data_path')}",
+        f"  method:          {method}",
+        f"  device:          {plan.get('device', 'auto')}",
+        f"  hyperparameters: {json.dumps(plan.get('hyperparameters') or {}, ensure_ascii=False)}",
+    ]
+    return "\n".join(lines)
+
+
+async def _ask(call: ToolCall) -> tuple[bool, str]:
+    typer.echo("\n" + typer.style("The agent wants to start training:", bold=True))
+    typer.echo(_describe_plan(call))
+    answer = typer.prompt("Start? [y = yes / n = no / or type feedback for the agent]", default="n").strip()
+    if answer.lower() in ("y", "yes"):
+        return True, ""
+    return False, "" if answer.lower() in ("n", "no") else answer
+
+
+def _printer(event: AgentEvent) -> None:
+    d = event.data
+    if event.kind == "text":
+        typer.echo("\n" + d["text"])
+    elif event.kind == "tool_call":
+        args = "" if event.data["name"] in _SHORT else json.dumps(d["arguments"], ensure_ascii=False)[:160]
+        typer.echo(typer.style(f"  → {d['name']} {args}", dim=True))
+    elif event.kind == "tool_result" and not d["ok"]:
+        typer.echo(typer.style(f"    ✗ {d['name']}: {d['error']}", fg="yellow"))
+    elif event.kind == "info":
+        typer.echo(typer.style(d["message"], fg="yellow"))
+
+
+def train(
+    goal: str = typer.Argument(help="What you want, in plain words. e.g. 'predict churned from this CSV'"),
+    data: Path = typer.Option(None, "--data", "-d", help="Dataset file or directory."),
+    brain: str = typer.Option(
+        None, "--brain", "-b",
+        help="provider:model. anthropic:claude-opus-5-5 (default), openai:<model>, ollama:<model>, local:<model>. "
+             "Default from $AUTOFORGE_BRAIN.",
+    ),
+    base_url: str = typer.Option(None, "--base-url", help="OpenAI-compatible endpoint for openai:/local:/ollama:."),
+    api_key_env: str = typer.Option(None, "--api-key-env", help="Env var holding the API key for openai: (default OPENAI_API_KEY)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not ask before starting training."),
+    max_steps: int = typer.Option(40, "--max-steps", help="Maximum model turns."),
+    as_json: bool = typer.Option(False, "--json", help="Machine-readable result (requires --yes)."),
+) -> None:
+    """Let an AI analyse your data and hardware, choose a method, train and report — from one sentence."""
+    if as_json and not yes:
+        fail(True, "BAD_REQUEST", "--json needs --yes (no interactive approval possible)")
+    with errors_as_envelope(as_json):
+        spec = parse_brain(brain, base_url, api_key_env)
+        provider = make_provider(spec)
+    if not as_json:
+        where = "local model" if spec.is_local else "cloud model"
+        typer.echo(typer.style(f"Brain: {spec.provider}:{spec.model} ({where}) — actor {spec.actor}", dim=True))
+    with errors_as_envelope(as_json):
+        result = asyncio.run(run_agent(
+            goal,
+            provider,
+            actor=spec.actor,
+            brain=spec.brain_kind,
+            approve=None if yes else _ask,
+            on_event=None if as_json else _printer,
+            max_steps=max_steps,
+            data_path=str(data) if data else None,
+        ))
+    data_out = {"stop": result.stop, "steps": result.steps, "runs": result.runs,
+                "final_text": result.final_text, "transcript": result.transcript}
+    human = (f"\n— {result.stop} after {result.steps} step(s); runs: {', '.join(result.runs) or 'none'}"
+             f"\n  transcript: {result.transcript}")
+    emit(as_json, data_out, human)
+    if result.stop not in ("end",):
+        raise typer.Exit(1)

autoforge/cli/data.py

@@ -0,0 +1,42 @@
+"""`autoforge data ...`: mark dataset sensitivity (humans only) and profile data."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from autoforge.cli.output import JsonOpt, emit, errors_as_envelope
+from autoforge.data import registry
+
+data_app = typer.Typer(help="Dataset sensitivity and profiling.", no_args_is_help=True)
+
+
+@data_app.command("mark")
+def mark(
+    path: Path,
+    sensitivity: registry.Sensitivity = typer.Option(..., "--sensitivity", "-s",
+                                                     help="public / internal / sensitive"),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Mark a file or directory. Sensitive data can only be used by a human or a local-model AI."""
+    key = registry.mark(path, sensitivity)
+    emit(as_json, {"path": key, "sensitivity": sensitivity.value}, f"{key}: {sensitivity.value}")
+
+
+@data_app.command("list")
+def list_marks(as_json: bool = JsonOpt) -> None:
+    """All marked paths (unmarked data is 'internal')."""
+    marks = registry.all_marks()
+    emit(as_json, marks, "\n".join(f"{v:<10} {k}" for k, v in marks.items()) or "(nothing marked; default: internal)")
+
+
+@data_app.command("profile")
+def profile(path: Path, as_json: bool = JsonOpt) -> None:
+    """Profile a dataset (as a human: full access, including sample rows)."""
+    from autoforge import api
+    from autoforge.schemas.core import BrainKind
+
+    with errors_as_envelope(as_json):
+        data = api.data_profile(str(path), BrainKind.human)
+    emit(as_json, data)

autoforge/cli/hpo.py

@@ -0,0 +1,98 @@
+"""`autoforge hpo ...`: hyperparameter search."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import typer
+import yaml
+
+from autoforge.cli.output import JsonOpt, emit, errors_as_envelope
+from autoforge.cli.runs import ActorOpt, _actor
+
+hpo_app = typer.Typer(help="Hyperparameter search (each trial is a normal run).", no_args_is_help=True)
+
+
+def _line(v: dict) -> str:
+    best = "-" if v["best_value"] is None else f"{v['best_value']:.4g}"
+    base = "-" if v["baseline_value"] is None else f"{v['baseline_value']:.4g}"
+    imp = "" if v["improvement"] is None else f" ({v['improvement']:+.4g} vs baseline)"
+    return (f"{v['study_id']:<34} {v['status']:<10} {v['completed']}/{v['n_trials']} trials, "
+            f"{v['metric']} best={best} baseline={base}{imp}")
+
+
+@hpo_app.command("start")
+def start(
+    plan_file: Path,
+    metric: str = typer.Option(..., "--metric", "-m", help="Run metric to optimise, e.g. f1_macro or rmse."),
+    trials: int = typer.Option(20, "--trials", "-n"),
+    direction: str = typer.Option(None, "--direction", help="maximize / minimize (default: inferred from the metric)."),
+    space_file: Path = typer.Option(None, "--space", help="YAML search space (default: the recipe's search_space)."),
+    timeout_min: float = typer.Option(None, "--timeout-min", help="Stop starting new trials after N minutes."),
+    wait: bool = typer.Option(False, "--wait", help="Block and print each finished trial."),
+    actor: str = ActorOpt,
+    as_json: bool = JsonOpt,
+) -> None:
+    """Start a search. Trial 0 is the plan's own hyperparameters, the baseline."""
+    from autoforge import api
+    from autoforge.policy.privacy import brain_from_actor
+
+    space = yaml.safe_load(space_file.read_text(encoding="utf-8")) if space_file else None
+    who = _actor(actor)
+    with errors_as_envelope(as_json):
+        plan = yaml.safe_load(plan_file.read_text(encoding="utf-8"))
+        view = api.hpo_start(plan, metric, trials, who, brain_from_actor(who), direction, space, timeout_min,
+                             base=plan_file.resolve().parent)
+    sid = view["study_id"]
+    if not wait:
+        emit(as_json, view, f"Started {sid}\nPoll with: autoforge hpo status {sid}")
+        return
+    if not as_json:
+        typer.echo(f"Started {sid}")
+    seen = 0
+    while True:
+        view = api.hpo_status(sid)
+        if not as_json:
+            for t in view["trials"][seen:]:
+                tag = " (baseline)" if t.get("baseline") else ""
+                res = f"{metric}={t['value']:.4g}" if "value" in t else f"failed: {t.get('error')}"
+                typer.echo(f"  trial {t['number']}{tag}: {res}  {t['params']}")
+        seen = len(view["trials"])
+        if view["status"] not in ("pending", "running"):
+            break
+        time.sleep(1)
+    emit(as_json, view, _line(view) + (f"\nbest params: {view['best_params']}  run: {view['best_run_id']}"
+                                       if view["best_params"] is not None else ""))
+
+
+@hpo_app.command("status")
+def status(study_id: str, as_json: bool = JsonOpt) -> None:
+    """Progress, best result and every trial."""
+    from autoforge import api
+
+    with errors_as_envelope(as_json):
+        v = api.hpo_status(study_id)
+    lines = [_line(v)] + [
+        f"  trial {t['number']}{' (baseline)' if t.get('baseline') else ''}: "
+        f"{t.get('value', 'failed')}  {t['params']}" for t in v["trials"]]
+    emit(as_json, v, "\n".join(lines))
+
+
+@hpo_app.command("list")
+def list_cmd(as_json: bool = JsonOpt) -> None:
+    """Recent searches."""
+    from autoforge import api
+
+    rows = api.hpo_list()
+    emit(as_json, rows, "\n".join(map(_line, rows)) or "(no searches)")
+
+
+@hpo_app.command("stop")
+def stop(study_id: str, actor: str = ActorOpt, as_json: bool = JsonOpt) -> None:
+    """Stop a search and its current trial; finished trials are kept."""
+    from autoforge import api
+
+    with errors_as_envelope(as_json):
+        v = api.hpo_stop(study_id, _actor(actor))
+    emit(as_json, v, _line(v))

autoforge/cli/main.py

@@ -0,0 +1,112 @@
+"""AutoForge CLI. Every command supports --json and emits the Envelope shape,
+so AI agents can call it as reliably as the MCP server."""
+
+from __future__ import annotations
+
+import typer
+
+from autoforge import __version__
+from autoforge.cli.output import JsonOpt, emit, fail
+from autoforge.cli.packs import index_app, pack_app
+from autoforge.cli.agent import train
+from autoforge.cli.data import data_app
+from autoforge.cli.hpo import hpo_app
+from autoforge.cli.models import gui, model_app, serve, serve_mcp
+from autoforge.cli.quickstart import quickstart
+from autoforge.cli.runs import plan_app, run_app
+from autoforge.hardware.detect import detect_hardware
+from autoforge.engine.runner import RunView
+from autoforge.registry.models import ModelCard
+from autoforge.packs.index import IndexEntry, PackIndex
+from autoforge.packs.manifest import PackManifest, RecipeSpec
+from autoforge.schemas.core import SCHEMAS
+
+app = typer.Typer(help="AutoForge: AI that trains AI.", no_args_is_help=True)
+app.add_typer(pack_app, name="pack")
+app.add_typer(index_app, name="index")
+app.add_typer(plan_app, name="plan")
+app.add_typer(run_app, name="run")
+app.add_typer(data_app, name="data")
+app.add_typer(hpo_app, name="hpo")
+app.add_typer(model_app, name="model")
+app.command()(serve)
+app.command("serve-mcp")(serve_mcp)
+app.command()(train)
+app.command()(gui)
+app.command()(quickstart)
+
+ALL_SCHEMAS = SCHEMAS | {
+    "PackManifest": PackManifest,
+    "RecipeSpec": RecipeSpec,
+    "PackIndex": PackIndex,
+    "IndexEntry": IndexEntry,
+    "RunView": RunView,
+    "ModelCard": ModelCard,
+}
+
+
+@app.command()
+def version(as_json: bool = JsonOpt) -> None:
+    """Show the AutoForge version."""
+    emit(as_json, {"version": __version__}, f"autoforge {__version__}")
+
+
+@app.command()
+def doctor(as_json: bool = JsonOpt) -> None:
+    """Detect CPU / RAM / NVIDIA GPU / CUDA and report the training device."""
+    hw = detect_hardware()
+    data = hw.model_dump() | {"best_device": hw.best_device}
+    if as_json:
+        emit(True, data)
+        return
+    lines = [
+        f"OS:      {hw.os} (Python {hw.python_version})",
+        f"CPU:     {hw.cpu.model} ({hw.cpu.physical_cores}C/{hw.cpu.logical_cores}T)",
+        f"RAM:     {hw.ram_available_gb} / {hw.ram_total_gb} GB available",
+        f"Disk:    {hw.disk_free_gb} GB free",
+    ]
+    if hw.gpus:
+        for g in hw.gpus:
+            lines.append(
+                f"GPU {g.index}:   {g.name}, {g.vram_total_gb} GB VRAM, "
+                f"CC {g.compute_capability}, driver {g.driver_version}"
+            )
+        lines.append(f"CUDA:    {hw.cuda_version}")
+    else:
+        lines.append("GPU:     none (NVIDIA)")
+    lines.append(f"Torch:   {hw.torch_version or 'not installed'} (CUDA usable: {hw.torch_cuda_available})")
+    lines.append(f"Device:  {hw.best_device}")
+    for n in hw.detection_notes:
+        lines.append(f"  note: {n}")
+    emit(False, human="\n".join(lines))
+
+
+@app.command()
+def mcp(
+    actor: str = typer.Option(
+        "ai:mcp", "--actor",
+        help="Recorded in audit logs. Use 'ai:local:<model>' only if the MCP client is driven by a local model.",
+    ),
+) -> None:
+    """Run the MCP server over stdio (for Claude Desktop, Claude Code and other MCP clients)."""
+    from autoforge.serve.mcp_server import main as serve
+
+    serve(actor)
+
+
+@app.command()
+def schema(
+    name: str = typer.Argument(None, help="Schema name; omit to list all."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Print the JSON Schema of a core data structure."""
+    if name is None:
+        emit(as_json, sorted(ALL_SCHEMAS), "\n".join(sorted(ALL_SCHEMAS)))
+        return
+    if name not in ALL_SCHEMAS:
+        fail(as_json, "UNKNOWN_SCHEMA", f"No schema named '{name}'", f"Choose from: {', '.join(sorted(ALL_SCHEMAS))}")
+    emit(as_json, ALL_SCHEMAS[name].model_json_schema())
+
+
+if __name__ == "__main__":
+    app()