autoforge-trainer 1.0.2__py3-none-any.whl

autoforge/cli/models.py

@@ -0,0 +1,172 @@
+"""`autoforge model ...`, `autoforge serve` and `autoforge serve-mcp`."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import typer
+
+from autoforge.cli.output import JsonOpt, emit, errors_as_envelope, fail
+from autoforge.cli.runs import ActorOpt, _actor
+
+model_app = typer.Typer(help="Registered models: register, inspect, predict, export.", no_args_is_help=True)
+
+
+@model_app.command("register")
+def register(
+    run_id: str,
+    name: str = typer.Option(..., "--name", "-n", help="Model name (lowercase, digits, '-', '_')."),
+    description: str = typer.Option("", "--description", "-d"),
+    actor: str = ActorOpt,
+    as_json: bool = JsonOpt,
+) -> None:
+    """Turn a succeeded run into the next version of a model."""
+    from autoforge import api
+
+    with errors_as_envelope(as_json):
+        card = api.model_register(run_id, name, _actor(actor), description)
+    note = "" if card["servable"] else "\n(not servable: the recipe has no predictor)"
+    emit(as_json, card, f"Registered {card['name']}:v{card['version']} from {run_id}{note}")
+
+
+@model_app.command("list")
+def list_cmd(as_json: bool = JsonOpt) -> None:
+    """Registered models (latest version of each)."""
+    from autoforge import api
+
+    rows = api.model_list()
+    human = "\n".join(
+        f"{r['model']:<28} {r['task']:<24} " + ", ".join(f"{k}={v:.4g}" for k, v in r["metrics"].items())
+        for r in rows) or "(no models)"
+    emit(as_json, rows, human)
+
+
+@model_app.command("info")
+def info(model: str, as_json: bool = JsonOpt) -> None:
+    """Model card: features, labels, metrics, source run."""
+    from autoforge import api
+
+    with errors_as_envelope(as_json):
+        emit(as_json, api.model_info(model))
+
+
+@model_app.command("predict")
+def predict(
+    model: str,
+    rows_json: str = typer.Option(None, "--rows", help='JSON list of objects, e.g. \'[{"age": 30}]\''),
+    rows_file: Path = typer.Option(None, "--file", "-f", help="JSON file, or CSV with a header row."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Predict with a registered model."""
+    import csv
+
+    from autoforge import api
+
+    if rows_file:
+        if rows_file.suffix.lower() == ".csv":
+            with rows_file.open(newline="", encoding="utf-8") as f:
+                rows = [{k: v for k, v in r.items()} for r in csv.DictReader(f)]
+        else:
+            rows = json.loads(rows_file.read_text(encoding="utf-8"))
+    elif rows_json:
+        rows = json.loads(rows_json)
+    else:
+        fail(as_json, "BAD_REQUEST", "give --rows or --file")
+    with errors_as_envelope(as_json):
+        out = api.model_predict(model, rows)
+    emit(as_json, out)
+
+
+@model_app.command("export")
+def export(
+    model: str,
+    fmt: str = typer.Option("bundle", "--format", help="bundle (zip) or a format the model supports, e.g. onnx."),
+    out: Path = typer.Option(None, "--out", "-o"),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Export a model as a portable bundle or another format (e.g. ONNX)."""
+    from autoforge import api
+
+    with errors_as_envelope(as_json):
+        res = api.model_export(model, fmt, str(out) if out else None)
+    emit(as_json, res, f"Exported {res['model']} ({fmt}) → {res['path']}  sha256 {res['sha256'][:16]}…")
+
+
+@model_app.command("import")
+def import_cmd(bundle: Path, name: str = typer.Option(None, "--name"), actor: str = ActorOpt,
+               as_json: bool = JsonOpt) -> None:
+    """Import a bundle exported elsewhere as a new version."""
+    from autoforge.registry import models as reg
+
+    with errors_as_envelope(as_json):
+        card = reg.import_bundle(bundle, name, _actor(actor))
+    emit(as_json, card.model_dump(mode="json"), f"Imported {card.ref}")
+
+
+@model_app.command("remove")
+def remove(model: str, as_json: bool = JsonOpt) -> None:
+    """Delete a model version (name:vN) or all versions (name)."""
+    from autoforge.registry import models as reg
+
+    with errors_as_envelope(as_json):
+        gone = reg.remove(model)
+    emit(as_json, gone, "Removed " + ", ".join(gone))
+
+
+def serve(
+    model: list[str] = typer.Option(None, "--model", "-m", help="Only serve these model names (repeatable)."),
+    host: str = typer.Option("127.0.0.1", "--host", help="Use 0.0.0.0 to accept connections from other machines."),
+    port: int = typer.Option(8000, "--port", "-p"),
+    api_key_env: str = typer.Option(None, "--api-key-env", help="Env var holding an API key clients must send."),
+) -> None:
+    """Serve registered models over HTTP (REST)."""
+    import uvicorn
+
+    from autoforge.serve.rest import create_app
+
+    key = None
+    if api_key_env:
+        key = os.environ.get(api_key_env)
+        if not key:
+            fail(False, "BAD_REQUEST", f"{api_key_env} is not set")
+    if host not in ("127.0.0.1", "localhost") and not key:
+        typer.echo(typer.style("warning: serving on a network interface without an API key", fg="yellow"), err=True)
+    typer.echo(f"Serving {'all models' if not model else ', '.join(model)} on http://{host}:{port}  (docs: docs/DEPLOY.md)")
+    uvicorn.run(create_app(model or None, key), host=host, port=port, log_level="info")
+
+
+def serve_mcp(
+    model: list[str] = typer.Option(None, "--model", "-m", help="Only expose these model names (repeatable)."),
+) -> None:
+    """Expose registered models as MCP tools (predict_<name>) over stdio — prediction only, no training."""
+    from autoforge.serve.model_mcp import main
+
+    main(model or None)
+
+
+def gui(
+    port: int = typer.Option(8800, "--port", "-p"),
+    host: str = typer.Option("127.0.0.1", "--host",
+                             help="Bind address. Use 0.0.0.0 only inside Docker with -p 127.0.0.1:8800:8800."),
+    open_browser: bool = typer.Option(True, "--open/--no-open", help="Open the browser automatically."),
+) -> None:
+    """Open the web interface (local only: 127.0.0.1, protected by a one-time token)."""
+    import secrets
+    import threading
+    import webbrowser
+
+    import uvicorn
+
+    from autoforge.gui.app import create_app
+
+    token = secrets.token_urlsafe(24)
+    url = f"http://127.0.0.1:{port}/"
+    typer.echo(f"AutoForge GUI: {url}  (Ctrl+C to stop)")
+    if host not in ("127.0.0.1", "localhost"):
+        typer.echo(typer.style(f"warning: binding {host}; the GUI still only answers requests addressed to "
+                               "localhost/127.0.0.1, so publish the port only on 127.0.0.1", fg="yellow"), err=True)
+    if open_browser:
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+    uvicorn.run(create_app(token), host=host, port=port, log_level="warning")

autoforge/cli/output.py

@@ -0,0 +1,40 @@
+"""Shared output helpers: every command emits the Envelope shape with --json."""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+import typer
+
+from autoforge.errors import AutoForgeError
+from autoforge.schemas.core import Envelope, ErrorInfo
+
+JsonOpt = typer.Option(False, "--json", help="Machine-readable JSON output.")
+
+
+def emit(as_json: bool, data: Any = None, human: str | None = None) -> None:
+    if as_json:
+        typer.echo(Envelope(ok=True, data=data).model_dump_json(indent=2))
+    else:
+        typer.echo(human if human is not None else json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def fail(as_json: bool, code: str, message: str, hint: str | None = None, details: Any = None) -> None:
+    if as_json:
+        err = ErrorInfo(code=code, message=message, hint=hint)
+        env = Envelope(ok=False, error=err, data=details)
+        typer.echo(env.model_dump_json(indent=2))
+    else:
+        typer.echo(f"Error [{code}]: {message}" + (f"\nHint: {hint}" if hint else ""), err=True)
+    raise typer.Exit(1)
+
+
+@contextmanager
+def errors_as_envelope(as_json: bool) -> Iterator[None]:
+    """Turn any AutoForgeError into an error envelope carrying its code and details."""
+    try:
+        yield
+    except AutoForgeError as e:
+        fail(as_json, e.code, str(e), e.hint, e.details)

autoforge/cli/packs.py

@@ -0,0 +1,185 @@
+"""`autoforge pack ...` and `autoforge index ...` commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from autoforge.cli.output import JsonOpt, emit, errors_as_envelope, fail
+from autoforge.packs import installer
+from autoforge.packs.index import PackIndex, dump_index, entry_from_pack, load_index, parse_index, search
+from autoforge.packs.manifest import collect_problems, load_pack
+
+pack_app = typer.Typer(help="Install, inspect and search method packs.", no_args_is_help=True)
+index_app = typer.Typer(help="Maintain a pack index (index.json).", no_args_is_help=True)
+
+
+@pack_app.command("validate")
+def validate(path: Path, as_json: bool = JsonOpt) -> None:
+    """Check a pack directory without executing any of its code."""
+    pack, problems = collect_problems(path)
+    if pack is None:
+        fail(as_json, "PACK_INVALID", f"{len(problems)} problem(s)", None, {"problems": problems})
+    emit(as_json, {"name": pack.manifest.name, "version": pack.manifest.version,
+                   "recipes": [r.id for r in pack.recipes]},
+         f"OK: {pack.manifest.name} {pack.manifest.version} ({len(pack.recipes)} recipes)")
+
+
+@pack_app.command("install")
+def install(
+    source: str = typer.Argument(help="index name, ./local/path, or github:owner/repo[/subdir][@ref]"),
+    force: bool = typer.Option(False, "--force", help="Reinstall if already installed."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Install a pack and pin its commit in the lock file."""
+    with errors_as_envelope(as_json):
+        rec = installer.install(source, force=force)
+    emit(as_json, rec.model_dump(), f"Installed {rec.name} {rec.version} from {rec.source}")
+
+
+@pack_app.command("remove")
+def remove(name: str, as_json: bool = JsonOpt) -> None:
+    """Uninstall a pack."""
+    with errors_as_envelope(as_json):
+        rec = installer.remove(name)
+    emit(as_json, rec.model_dump(), f"Removed {rec.name}")
+
+
+@pack_app.command("list")
+def list_installed(as_json: bool = JsonOpt) -> None:
+    """List installed packs."""
+    lock = installer.read_lock()
+    rows = [r.model_dump() for r in lock.values()]
+    human = "\n".join(f"{r.name:<28} {r.version:<10} {r.source}" for r in lock.values()) or "(no packs installed)"
+    emit(as_json, rows, human)
+
+
+@pack_app.command("info")
+def info(
+    name: str,
+    knowledge: bool = typer.Option(True, "--knowledge/--no-knowledge", help="Include KNOWLEDGE.md text."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Show an installed pack's manifest, recipes, missing deps and KNOWLEDGE.md (for AI reading)."""
+    with errors_as_envelope(as_json):
+        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()
+    emit(as_json, data)
+
+
+@pack_app.command("search")
+def search_cmd(
+    query: str = typer.Argument(None, help="Free-text keywords."),
+    task: str = typer.Option(None, "--task", help="Exact task type, e.g. tabular-classification."),
+    fit: bool = typer.Option(False, "--fit", help="Only recipes this machine's hardware can run."),
+    offline: bool = typer.Option(False, "--offline", help="Use the cached index only."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Search the pack index."""
+    hw = None
+    if fit:
+        from autoforge.hardware.detect import detect_hardware
+
+        hw = detect_hardware()
+    with errors_as_envelope(as_json):
+        index, notes = load_index(refresh=not offline)
+    hits = search(index, task=task, query=query, hardware=hw)
+    lock = installer.read_lock()
+    rows = [
+        h.model_dump(mode="json") | {"installed": h.entry.name in lock, "install_with": h.entry.name}
+        for h in hits
+    ]
+    human = "\n".join(
+        f"{h.entry.name:<28} {h.entry.version:<8} {', '.join(h.runnable_recipes):<30} {h.entry.summary}"
+        for h in hits
+    ) or "(no matches)"
+    if as_json:
+        emit(True, {"hits": rows, "notes": notes})
+    else:
+        emit(False, human="\n".join([*(f"note: {n}" for n in notes), human]))
+
+
+@index_app.command("entry")
+def index_entry(
+    path: Path,
+    source: str = typer.Option(..., help="github:owner/repo[/subdir] where the pack lives"),
+    commit: str = typer.Option(..., help="40-char commit SHA to pin"),
+    tag: list[str] = typer.Option([], "--tag", help="Search tag; repeatable."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Print the index.json entry for a local pack checkout."""
+    with errors_as_envelope(as_json):
+        pack = load_pack(path)
+    entry = entry_from_pack(pack, source, commit, tag)
+    emit(as_json, entry.model_dump(mode="json"))
+
+
+@index_app.command("add")
+def index_add(
+    index_file: Path,
+    path: Path,
+    source: str = typer.Option(...),
+    commit: str = typer.Option(...),
+    tag: list[str] = typer.Option([], "--tag"),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Add or replace a pack's entry in an index.json file."""
+    with errors_as_envelope(as_json):
+        pack = load_pack(path)
+        index = parse_index(index_file.read_text(encoding="utf-8")) if index_file.exists() else PackIndex()
+    entry = entry_from_pack(pack, source, commit, tag)
+    index.packs = sorted([p for p in index.packs if p.name != entry.name] + [entry], key=lambda p: p.name)
+    index_file.write_text(dump_index(index), encoding="utf-8")
+    emit(as_json, entry.model_dump(mode="json"), f"Wrote {entry.name} {entry.version} to {index_file}")
+
+
+@index_app.command("validate")
+def index_validate(index_file: Path, as_json: bool = JsonOpt) -> None:
+    """Validate an index.json file (structure, SHAs, duplicate names)."""
+    with errors_as_envelope(as_json):
+        index = parse_index(index_file.read_text(encoding="utf-8"))
+    emit(as_json, {"packs": len(index.packs)}, f"OK: {len(index.packs)} pack(s)")
+
+
+@pack_app.command("new")
+def new(
+    name: str,
+    task: str = typer.Option(..., "--task", help="Task type, e.g. text-classification."),
+    dest: Path = typer.Option(Path("."), "--dest", help="Parent directory."),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Create a valid pack skeleton (pack.yaml, KNOWLEDGE.md, recipe, trainer, smoke test)."""
+    from autoforge.packs.authoring import scaffold
+
+    with errors_as_envelope(as_json):
+        res = scaffold(name, task, dest)
+    emit(as_json, res, f"Created {res['path']}\nNext: edit trainers/train.py and KNOWLEDGE.md, then "
+                       f"`autoforge pack test {res['path']}`")
+
+
+@pack_app.command("test")
+def test(
+    target: str = typer.Argument(help="Installed pack name or a pack directory."),
+    timeout: float = typer.Option(600, "--timeout"),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Run a pack's smoke tests (tests/) with pytest."""
+    from autoforge.packs.authoring import test_pack
+
+    path = target
+    if not Path(target).is_dir():
+        with errors_as_envelope(as_json):
+            path = installer.get_installed(target)[0].path
+    with errors_as_envelope(as_json):
+        res = test_pack(path, timeout)
+    if not res["ok"]:
+        fail(as_json, "PACK_TEST_FAILED", res["summary"] or "tests failed", "read output_tail", res)
+    emit(as_json, res, f"OK: {res['summary']} ({res['seconds']} s)")

autoforge/cli/quickstart.py

@@ -0,0 +1,61 @@
+"""`autoforge quickstart`: the whole loop in one command, on bundled example data."""
+
+from __future__ import annotations
+
+import time
+from importlib import resources
+
+import typer
+
+from autoforge.cli.output import JsonOpt, emit, errors_as_envelope
+
+
+def quickstart(
+    recipe: str = typer.Option("random_forest", "--recipe", help="logistic_regression or random_forest"),
+    as_json: bool = JsonOpt,
+) -> None:
+    """Hardware check → install a pack → train → register → predict, on a bundled churn dataset (~1 min)."""
+    from autoforge import api
+    from autoforge.errors import AutoForgeError
+    from autoforge.packs import installer
+    from autoforge.schemas.core import BrainKind
+
+    start = time.monotonic()
+    log = (lambda *a: None) if as_json else typer.echo
+    data = str(resources.files("autoforge.examples") / "churn.csv")
+    with errors_as_envelope(as_json):
+        hw = api.hardware()
+        log(f"1/5 hardware: {hw['cpu']['model']}, device {hw['best_device']}")
+        if "tabular-classic" not in installer.read_lock():
+            try:
+                rec = api.pack_install("tabular-classic")
+            except AutoForgeError:  # offline or index unreachable: fall back to the GitHub source
+                rec = api.pack_install("github:Honguan/autoforge/packs/tabular-classic@main")
+            log(f"2/5 installed pack tabular-classic {rec['version']}")
+        else:
+            log("2/5 pack tabular-classic already installed")
+        plan = {"task": {"task_type": "tabular-classification", "input_modality": "tabular", "output_modality": "label",
+                         "target": "churned", "metric": "f1_macro"},
+                "data_path": data, "pack": "tabular-classic", "recipe": recipe,
+                "hyperparameters": {"class_weight": "balanced"}}
+        run = api.run_start(plan, "human", BrainKind.human)
+        log(f"3/5 training {run['run_id']} …")
+        view = api.run_wait(run["run_id"], 120)
+        if view["status"] != "succeeded":
+            raise AutoForgeError(f"training {view['status']}: {view.get('error')}",
+                                 hint=f"autoforge run logs {run['run_id']}")
+        log("    " + ", ".join(f"{k}={v:.3f}" for k, v in view["metrics"].items()))
+        card = api.model_register(run["run_id"], "quickstart-churn", "human", "Quickstart churn model")
+        log(f"4/5 registered model {card['name']}:v{card['version']}")
+        rows = [{"tenure_months": 2, "monthly_fee": 110, "contract": "month-to-month", "support_calls": 5},
+                {"tenure_months": 60, "monthly_fee": 25, "contract": "two-year", "support_calls": 0}]
+        pred = api.model_predict(card["name"], rows)
+        for r, p in zip(rows, pred["predictions"]):
+            log(f"5/5 predict {r} → churn={p['prediction']} (p={p['probabilities'].get('1', 0):.2f})")
+    seconds = round(time.monotonic() - start, 1)
+    emit(as_json, {"seconds": seconds, "run_id": run["run_id"], "model": f"{card['name']}:v{card['version']}",
+                   "metrics": view["metrics"], "predictions": pred["predictions"]},
+         f"\nDone in {seconds} s. Next:\n"
+         f"  autoforge gui                      # web interface\n"
+         f"  autoforge serve                    # REST API for the model\n"
+         f"  claude mcp add autoforge -- autoforge mcp   # let Claude drive AutoForge")