blitz-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{blitz_cli-0.3.0 → blitz_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blitz-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Developer CLI for Blitz: pull a workflow's training data + base-model recommendation and scaffold a runnable QLoRA training container.
 License: MIT
 License-File: LICENSE
@@ -10,9 +10,8 @@ Description-Content-Type: text/markdown
 # blitz-cli
 
 Developer CLI for [Blitz](https://github.com/sparepartslabs/blitz-sdk-py). Pull a
-workflow's captured traces as a fine-tuning dataset + the recommended open base
-model, and scaffold a self-contained, runnable QLoRA training container — then
-close the loop by grading the trained student against the held-out eval set.
+workflow's captured traces as a fine-tuning dataset, and scaffold a
+self-contained, runnable QLoRA training container.
 
 ```bash
 pip install blitz-cli
@@ -21,16 +20,12 @@ export BLITZ_API_KEY=blz_...   # a read-scoped project key (mint one in the dash
 blitz scaffold -p proj_abc -w mechanic-assistant -o ./train
 
 cd train
-make build && make train && make eval
+make build && make train
 ```
 
-`blitz scaffold` writes `./train` with `data/dataset.jsonl`, `data/evalset.jsonl`,
-`config.json` (derived from the base-model recommendation), and a `Dockerfile` +
-`train.py` + `eval.py` + `Makefile`. Bring your own NVIDIA GPU.
+`blitz scaffold` writes `./train` with `data/dataset.jsonl` and a `Dockerfile` +
+`train.py` + `Makefile`. Bring your own NVIDIA GPU.
 
 This package is intentionally dependency-free (stdlib + the Blitz HTTP API). The
 heavy ML stack (torch / transformers / trl / peft) is pinned only in the
 *generated* project's `requirements.txt`, installed inside the training image.
-
-The complementary tracing SDK (`pip install blitz-sdk`, `import blitz`) lives in
-[`../blitz-sdk`](../blitz-sdk).

blitz_cli-0.4.0/README.md

@@ -0,0 +1,22 @@
+# blitz-cli
+
+Developer CLI for [Blitz](https://github.com/sparepartslabs/blitz-sdk-py). Pull a
+workflow's captured traces as a fine-tuning dataset, and scaffold a
+self-contained, runnable QLoRA training container.
+
+```bash
+pip install blitz-cli
+
+export BLITZ_API_KEY=blz_...   # a read-scoped project key (mint one in the dashboard)
+blitz scaffold -p proj_abc -w mechanic-assistant -o ./train
+
+cd train
+make build && make train
+```
+
+`blitz scaffold` writes `./train` with `data/dataset.jsonl` and a `Dockerfile` +
+`train.py` + `Makefile`. Bring your own NVIDIA GPU.
+
+This package is intentionally dependency-free (stdlib + the Blitz HTTP API). The
+heavy ML stack (torch / transformers / trl / peft) is pinned only in the
+*generated* project's `requirements.txt`, installed inside the training image.

{blitz_cli-0.3.0 → blitz_cli-0.4.0}/blitz_cli/__init__.py

@@ -12,15 +12,16 @@ Commands:
 - ``blitz verify [--wait]`` — confirm sample traces have landed in Blitz,
   authenticated by the ingest key (``BLITZ_API_KEY``).
 
-- ``blitz skill install`` — drop the ``onboard-to-blitz`` Claude Code skill into
-  the repo's ``.claude/skills`` so Claude can run the onboarding playbook.
+- ``blitz skill install`` — drop the Blitz Claude Code skills (``onboard-to-blitz``,
+  ``configure-training``) into the repo's ``.claude/skills`` so Claude can run the
+  onboarding and training playbooks.
 
 - ``blitz scaffold -p <project> -w <workflow> -o ./train`` — download a
-  workflow's SFT dataset, held-out eval set, and base-model recommendation, then
-  emit a self-contained, runnable training project (Dockerfile + train.py +
-  eval.py). Authenticates with a read-scoped Blitz API key (``BLITZ_API_KEY``).
+  workflow's SFT dataset, then emit a self-contained, runnable training project
+  (Dockerfile + train.py). Authenticates with a read-scoped Blitz API key
+  (``BLITZ_API_KEY``).
 """
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{blitz_cli-0.3.0 → blitz_cli-0.4.0}/blitz_cli/_client.py

@@ -92,30 +92,34 @@ class BlitzClient:
                 if line:
                     yield json.loads(line)
 
-    def _post_json(self, path: str, body: dict) -> dict:
+    def _send_json(self, path: str, body: dict, method: str) -> dict:
         data = json.dumps(body).encode("utf-8")
         req = urllib.request.Request(
             self._url(path),
             data=data,
-            method="POST",
+            method=method,
             headers={**self._headers, "content-type": "application/json"},
         )
         with self._open(req) as resp:
             return json.loads(resp.read().decode("utf-8"))
 
-    # -- public API (one method per endpoint the CLI / eval loop needs) -----
+    def _post_json(self, path: str, body: dict) -> dict:
+        return self._send_json(path, body, "POST")
+
+    def _put_json(self, path: str, body: dict) -> dict:
+        return self._send_json(path, body, "PUT")
+
+    # -- public API (one method per endpoint the CLI needs) -----------------
 
     def _p(self, suffix: str) -> str:
         return f"/blitz/projects/{self._project}{suffix}"
 
-    def recommended_base(self, workflow: str) -> dict:
-        return self._get_json(self._p("/recommended-base"), {"workflow": workflow})
+    def get_training_config(self, workflow: str) -> dict:
+        return self._get_json(self._p("/training-config"), {"workflow": workflow})
 
-    def recommended_tools(self, workflow: str) -> dict:
-        return self._get_json(self._p("/recommended-tools"), {"workflow": workflow})
-
-    def eval_summary(self, workflow: str) -> dict:
-        return self._get_json(self._p("/eval-set/summary"), {"workflow": workflow})
+    def set_training_config(self, config: dict) -> dict:
+        # config is the full flat config (includes `workflow`); the server keys on it.
+        return self._put_json(self._p("/training-config"), config)
 
     def download_dataset(
         self, workflow: Optional[str] = None, include_synthetic: bool = True
@@ -125,24 +129,8 @@ class BlitzClient:
             {"workflow": workflow, "include_synthetic": include_synthetic},
         )
 
-    def download_eval_set(self, workflow: Optional[str] = None) -> Iterator[dict]:
-        return self._get_ndjson(self._p("/eval-dataset"), {"workflow": workflow})
-
-    def submit_eval(
-        self, workflow: str, predictions: list, grader: str = "auto"
-    ) -> dict:
-        return self._post_json(
-            self._p("/eval"),
-            {
-                "workflow": workflow,
-                "candidate": "supplied",
-                "grader": grader,
-                "predictions": predictions,
-            },
-        )
-
-    def get_eval_run(self, run_id: str) -> dict:
-        return self._get_json(self._p(f"/eval/runs/{run_id}"))
+    def training_readiness(self, workflow: str) -> dict:
+        return self._get_json(self._p("/training-readiness"), {"workflow": workflow})
 
     def ingest_status(self, workflow: Optional[str] = None) -> dict:
         """Trace summary for `blitz verify`, authed by the ingest key. This is

blitz_cli-0.4.0/blitz_cli/_scaffold.py

@@ -0,0 +1,103 @@
+"""Render a runnable QLoRA training project + derive a training config.
+
+Templates live in ``blitz_cli/templates`` and ship as package data. ``train.py``
+and ``requirements.txt`` are copied verbatim (they read ``config.json`` at
+runtime, so they need no substitution and stay valid Python regardless of the
+chosen base model); ``Dockerfile``/``Makefile``/``README`` get ``$var`` substitution
+via string.Template (avoids the brace-escaping pain of str.format on code).
+
+The config itself is no longer written into the project at scaffold time. The
+onboarding skill assembles it (via ``build_config``) and pushes it to Blitz with
+``blitz config set``; the training container fetches it at run start and writes its
+own ``config.json``. ``build_config`` stays here as the shared deriver that turns a
+base-model choice into a full config with sensible, size-scaled hyperparameters.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from string import Template
+
+
+def clamp_seq_len(raw: int) -> int:
+    """Clamp a raw sequence length (p95_input + max_output) to the trainer's
+    supported range. Defaults to 2048 when nothing usable is supplied."""
+    return max(1024, min(8192, int(raw or 0) or 2048))
+
+
+def build_config(
+    workflow: str,
+    base_model_hf: str,
+    params_b: float = 7.0,
+    license: str = "",
+    seq_len: int = 2048,
+) -> dict:
+    """Derive a full QLoRA training config from a base-model choice.
+
+    Hyperparameters scale with model size to keep a single 24GB-class card viable
+    (effective batch ~16-32). ``seq_len`` is clamped to the trainer's range.
+    """
+    params_b = float(params_b or 7)
+
+    if params_b <= 3:
+        lora_r, batch, accum, lr = 16, 4, 4, 2e-4
+    elif params_b <= 9:
+        lora_r, batch, accum, lr = 16, 2, 8, 2e-4
+    else:  # 14B and up
+        lora_r, batch, accum, lr = 32, 1, 16, 1e-4
+
+    return {
+        "workflow": workflow,
+        "base_model_hf": base_model_hf,
+        "params_b": params_b,
+        "license": license or "",
+        "seq_len": clamp_seq_len(seq_len),
+        "lora_r": lora_r,
+        "lora_alpha": lora_r * 2,
+        "lora_dropout": 0.05,
+        "epochs": 3,
+        "lr": lr,
+        "per_device_batch_size": batch,
+        "grad_accum": accum,
+    }
+
+
+def _template(name: str) -> str:
+    return resources.files("blitz_cli.templates").joinpath(name).read_text(
+        encoding="utf-8"
+    )
+
+
+def _write(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8")
+
+
+def render(out_dir: Path, project: str, workflow: str, endpoint: str) -> None:
+    """Write the training project skeleton into out_dir.
+
+    No config.json is written: the container fetches the config from Blitz at run
+    start (see the templates). Only project/workflow/endpoint are substituted, all
+    into the Dockerfile/Makefile/README wiring.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Verbatim (read config.json at runtime) — keep as real source files.
+    for name in ("train.py", "requirements.txt", "dockerignore"):
+        dest = ".dockerignore" if name == "dockerignore" else name
+        _write(out_dir / dest, _template(name + ".tmpl"))
+
+    subs = {"project": project, "workflow": workflow, "endpoint": endpoint}
+    for name in ("Dockerfile", "Makefile", "README.md"):
+        _write(out_dir / name, Template(_template(name + ".tmpl")).safe_substitute(subs))
+
+
+def gated_license_warning(license: str) -> str | None:
+    """A warning string if a base model's license needs HF acceptance, else None."""
+    lic = (license or "").lower()
+    if lic.startswith("llama") or lic.startswith("gemma"):
+        return (
+            f"This base model is gated ({lic}). Accept its license on Hugging Face "
+            "and pass HF_TOKEN into the container (see README) before training."
+        )
+    return None

blitz_cli-0.4.0/blitz_cli/_skill.py

@@ -0,0 +1,59 @@
+"""`blitz skill install` — drop the Blitz Claude Code skills into a repo.
+
+Each skill ships as package data under its own ``blitz_cli/skills/<name>`` dir
+and is copied verbatim into a repo's ``.claude/skills`` so Claude Code can run
+it in that repo.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+SkillResult = tuple[str, Path, list[str], list[str]]
+
+
+def list_skill_names() -> list[str]:
+    """Every skill packaged with this CLI, e.g. ["onboard-to-blitz", "configure-training"]."""
+    root = resources.files("blitz_cli.skills")
+    return sorted(
+        entry.name
+        for entry in root.iterdir()
+        if entry.is_dir() and entry.joinpath("SKILL.md").is_file()
+    )
+
+
+def _iter_skill_files(name: str):
+    """Yield (filename, text) for every file in the packaged skill ``name``."""
+    root = resources.files("blitz_cli.skills").joinpath(name)
+    for entry in root.iterdir():
+        if entry.is_file():
+            yield entry.name, entry.read_text(encoding="utf-8")
+
+
+def _install_one(dest_dir: Path, name: str, force: bool) -> SkillResult:
+    skill_dir = dest_dir / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    written: list[str] = []
+    skipped: list[str] = []
+    for filename, text in _iter_skill_files(name):
+        target = skill_dir / filename
+        if target.exists() and not force:
+            skipped.append(filename)
+            continue
+        target.write_text(text, encoding="utf-8")
+        written.append(filename)
+    return name, skill_dir, written, skipped
+
+
+def install(
+    dest_dir: Path, force: bool = False, names: list[str] | None = None
+) -> list[SkillResult]:
+    """Copy one or more packaged skills into ``dest_dir/<name>``.
+
+    Defaults to every packaged skill. Returns one ``(name, skill_dir, written,
+    skipped)`` tuple per skill — files newly written and files left untouched
+    because they already existed and ``force`` was False.
+    """
+    targets = names if names is not None else list_skill_names()
+    return [_install_one(dest_dir, name, force) for name in targets]

{blitz_cli-0.3.0 → blitz_cli-0.4.0}/blitz_cli/cli.py

@@ -30,50 +30,103 @@ def _cmd_scaffold(args: argparse.Namespace) -> int:
     out = Path(args.out)
     data_dir = out / "data"
 
-    try:
-        rec = client.recommended_base(args.workflow)
-    except BlitzAPIError as exc:
-        _eprint(f"error: {exc}")
-        return 1
-
-    model = rec["recommendation"]
-    print(f"Recommended base: {model['name']} ({model['hf']}) — {model.get('why', '')}")
-    warning = _scaffold.gated_license_warning(rec)
-    if warning:
-        _eprint(f"warning: {warning}")
-
     data_dir.mkdir(parents=True, exist_ok=True)
     try:
         n_train = _stream_to_file(
             client.download_dataset(args.workflow, args.include_synthetic),
             data_dir / "dataset.jsonl",
         )
-        n_eval = _stream_to_file(
-            client.download_eval_set(args.workflow), data_dir / "evalset.jsonl"
-        )
     except BlitzAPIError as exc:
         _eprint(f"error: {exc}")
         return 1
 
     print(f"Pulled {n_train} training examples → {data_dir / 'dataset.jsonl'}")
-    print(f"Pulled {n_eval} eval examples → {data_dir / 'evalset.jsonl'}")
     if n_train == 0:
         _eprint("error: no training examples for this workflow — nothing to train on.")
         return 1
-    if n_eval == 0:
-        _eprint("warning: held-out eval set is empty — `make eval` will be skipped.")
 
-    config = _scaffold.render(out, rec, args.project, args.workflow, args.endpoint)
+    _scaffold.render(out, args.project, args.workflow, args.endpoint)
     print(f"Scaffolded training project → {out}/")
     print(
         "\nNext:\n"
+        f"  blitz config set -p {args.project} -w {args.workflow} \\\n"
+        "      --base <hf-model-id> --params-b <N> --seq-len <N>   # push the training config\n"
         f"  cd {out}\n"
-        "  export BLITZ_API_KEY=<your read key>   # used by `make eval` to post results\n"
+        "  export BLITZ_API_KEY=<your read key>   # container fetches config + posts results\n"
         "  make build\n"
         "  make train\n"
-        "  make eval\n"
-        f"\n(base={config['base_model_hf']} seq_len={config['seq_len']} "
-        f"lora_r={config['lora_r']} epochs={config['epochs']})"
+        "\n(the container fetches config.json from Blitz at run start — set it first "
+        "with `blitz config set`)"
+    )
+    return 0
+
+
+def _cmd_config(args: argparse.Namespace) -> int:
+    api_key = args.api_key or os.environ.get("BLITZ_API_KEY")
+    if not api_key:
+        _eprint("error: no API key. Pass --api-key or set BLITZ_API_KEY (a read-scoped key).")
+        return 2
+    client = BlitzClient(endpoint=args.endpoint, api_key=api_key, project=args.project)
+
+    if args.config_cmd == "get":
+        try:
+            row = client.get_training_config(args.workflow)
+        except BlitzAPIError as exc:
+            _eprint(f"error: {exc}")
+            return 1
+        print(json.dumps(row["config"], indent=2))
+        return 0
+
+    # config_cmd == "set": build the config from --from, or derive from flags.
+    if args.from_file:
+        try:
+            config = json.loads(Path(args.from_file).read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            _eprint(f"error: could not read config from {args.from_file}: {exc}")
+            return 2
+        config.setdefault("workflow", args.workflow)
+        if config.get("workflow") != args.workflow:
+            _eprint(
+                f"error: --workflow {args.workflow!r} does not match config "
+                f"workflow {config.get('workflow')!r}."
+            )
+            return 2
+        if not config.get("base_model_hf"):
+            _eprint("error: config is missing base_model_hf.")
+            return 2
+    else:
+        if not args.base:
+            _eprint("error: pass --from <config.json>, or --base <hf-model-id> to derive a config.")
+            return 2
+        config = _scaffold.build_config(
+            workflow=args.workflow,
+            base_model_hf=args.base,
+            params_b=args.params_b if args.params_b is not None else 7.0,
+            license=args.license or "",
+            seq_len=args.seq_len if args.seq_len is not None else 2048,
+        )
+        # Optional per-flag hyperparameter overrides on top of the size-scaled defaults.
+        for key in ("epochs", "lr", "lora_r", "lora_alpha", "lora_dropout",
+                    "per_device_batch_size", "grad_accum"):
+            val = getattr(args, key, None)
+            if val is not None:
+                config[key] = val
+
+    warning = _scaffold.gated_license_warning(config.get("license", ""))
+    if warning:
+        _eprint(f"warning: {warning}")
+
+    try:
+        row = client.set_training_config(config)
+    except BlitzAPIError as exc:
+        _eprint(f"error: {exc}")
+        return 1
+    stored = row["config"]
+    print(f"Pushed training config for {args.workflow} → project {args.project}")
+    print(
+        f"(base={stored['base_model_hf']} seq_len={stored['seq_len']} "
+        f"lora_r={stored['lora_r']} epochs={stored['epochs']} "
+        f"batch={stored['per_device_batch_size']} accum={stored['grad_accum']})"
     )
     return 0
 
@@ -230,17 +283,19 @@ def _cmd_skill(args: argparse.Namespace) -> int:
     from blitz_cli import _skill
 
     if getattr(args, "skill_cmd", None) != "install":
-        _eprint("usage: blitz skill install [--dir .claude/skills] [--force]")
+        _eprint("usage: blitz skill install [--dir .claude/skills] [--name NAME] [--force]")
         return 2
-    skill_dir, written, skipped = _skill.install(Path(args.dir), force=args.force)
-    if written:
-        print(f"Installed onboard-to-blitz skill -> {skill_dir}/ ({', '.join(written)})")
-    else:
-        print(
-            f"Skill already present at {skill_dir}/ "
-            f"({', '.join(skipped)}); use --force to overwrite."
-        )
-    print("Open Claude Code in this repo and run the onboard-to-blitz skill.")
+    names = [args.name] if getattr(args, "name", None) else None
+    results = _skill.install(Path(args.dir), force=args.force, names=names)
+    for name, skill_dir, written, skipped in results:
+        if written:
+            print(f"Installed {name} skill -> {skill_dir}/ ({', '.join(written)})")
+        else:
+            print(
+                f"Skill {name} already present at {skill_dir}/ "
+                f"({', '.join(skipped)}); use --force to overwrite."
+            )
+    print("Open Claude Code in this repo and run the installed skill(s).")
     return 0
 
 
@@ -261,7 +316,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     sc = sub.add_parser(
         "scaffold",
-        help="Pull a workflow's dataset + recommendation and emit a QLoRA training project.",
+        help="Pull a workflow's dataset + emit a QLoRA training project skeleton.",
     )
     sc.add_argument("-p", "--project", required=True, help="Blitz project id")
     sc.add_argument("-w", "--workflow", required=True, help="Workflow (root span) name")
@@ -283,6 +338,50 @@ def build_parser() -> argparse.ArgumentParser:
     )
     sc.set_defaults(func=_cmd_scaffold)
 
+    cfg = sub.add_parser(
+        "config",
+        help="Push or read a workflow's training config (the container fetches it at run).",
+    )
+    cfg.add_argument("-p", "--project", required=True, help="Blitz project id")
+    cfg.add_argument("-w", "--workflow", required=True, help="Workflow (root span) name")
+    cfg.add_argument(
+        "--endpoint",
+        default=os.environ.get("BLITZ_ENDPOINT", _DEFAULT_ENDPOINT),
+        help="Blitz API base URL (env BLITZ_ENDPOINT)",
+    )
+    cfg.add_argument(
+        "--api-key", default=None, help="Read-scoped API key (env BLITZ_API_KEY)"
+    )
+    cfg_sub = cfg.add_subparsers(dest="config_cmd", required=True)
+
+    cfg_get = cfg_sub.add_parser("get", help="Print the stored training config as JSON.")
+    cfg_get.set_defaults(func=_cmd_config)
+
+    cfg_set = cfg_sub.add_parser(
+        "set",
+        help="Push a training config: --from <file>, or --base/--params-b/--seq-len to derive.",
+    )
+    cfg_set.add_argument(
+        "--from", dest="from_file", default=None,
+        help="Path to a full config.json to push verbatim.",
+    )
+    cfg_set.add_argument("--base", default=None, help="Base model HF id (derive mode)")
+    cfg_set.add_argument("--params-b", dest="params_b", type=float, default=None,
+                         help="Base model size in billions (drives hyperparameter defaults)")
+    cfg_set.add_argument("--license", default=None, help="Base model license (derive mode)")
+    cfg_set.add_argument("--seq-len", dest="seq_len", type=int, default=None,
+                         help="Training sequence length (clamped 1024-8192)")
+    cfg_set.add_argument("--epochs", type=int, default=None, help="Override epochs")
+    cfg_set.add_argument("--lr", type=float, default=None, help="Override learning rate")
+    cfg_set.add_argument("--lora-r", dest="lora_r", type=int, default=None, help="Override LoRA rank")
+    cfg_set.add_argument("--lora-alpha", dest="lora_alpha", type=int, default=None, help="Override LoRA alpha")
+    cfg_set.add_argument("--lora-dropout", dest="lora_dropout", type=float, default=None, help="Override LoRA dropout")
+    cfg_set.add_argument("--batch-size", dest="per_device_batch_size", type=int, default=None,
+                         help="Override per-device batch size")
+    cfg_set.add_argument("--grad-accum", dest="grad_accum", type=int, default=None,
+                         help="Override gradient accumulation steps")
+    cfg_set.set_defaults(func=_cmd_config)
+
     scn = sub.add_parser(
         "scan",
         help="Statically scan a codebase for AI/LLM calls and report Blitz "
@@ -353,17 +452,22 @@ def build_parser() -> argparse.ArgumentParser:
     ver.set_defaults(func=_cmd_verify)
 
     skl = sub.add_parser(
-        "skill", help="Install the Blitz Claude Code onboarding skill into this repo."
+        "skill", help="Install the Blitz Claude Code skills into this repo."
     )
     skl_sub = skl.add_subparsers(dest="skill_cmd", required=True)
     skl_install = skl_sub.add_parser(
-        "install", help="Copy the onboard-to-blitz skill into .claude/skills/."
+        "install", help="Copy the Blitz skills into .claude/skills/ (default: all of them)."
     )
     skl_install.add_argument(
         "--dir",
         default=".claude/skills",
         help="Skills directory to install into (default .claude/skills)",
     )
+    skl_install.add_argument(
+        "--name",
+        default=None,
+        help="Install only this skill (default: install every packaged skill)",
+    )
     skl_install.add_argument(
         "--force", action="store_true", help="Overwrite an existing skill copy"
     )