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

blitz_cli-0.4.0/.github/workflows/homebrew.yml

@@ -0,0 +1,54 @@
+name: Update Homebrew tap
+
+# On every release tag, point the sparepartslabs/homebrew-tap formula at the new
+# PyPI sdist. Runs alongside publish.yml (same v* trigger) and waits for the
+# sdist to appear on PyPI before reading its canonical URL + sha256.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve version
+        id: v
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Fetch sdist url + sha256 from PyPI (wait for publish)
+        id: pypi
+        run: |
+          VERSION="${{ steps.v.outputs.version }}"
+          for i in $(seq 1 30); do
+            JSON=$(curl -fsSL "https://pypi.org/pypi/blitz-cli/${VERSION}/json" || true)
+            URL=$(printf '%s' "$JSON" | jq -r '.urls[]? | select(.packagetype=="sdist") | .url')
+            SHA=$(printf '%s' "$JSON" | jq -r '.urls[]? | select(.packagetype=="sdist") | .digests.sha256')
+            if [ -n "$URL" ] && [ "$URL" != "null" ]; then break; fi
+            echo "sdist for ${VERSION} not on PyPI yet, retrying ($i)..."
+            sleep 10
+          done
+          if [ -z "$URL" ] || [ "$URL" = "null" ]; then
+            echo "::error::blitz-cli ${VERSION} sdist not found on PyPI"; exit 1
+          fi
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout tap
+        uses: actions/checkout@v4
+        with:
+          repository: sparepartslabs/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+
+      - name: Update formula
+        run: |
+          F=Formula/blitz-cli.rb
+          sed -i -E "s#^  url \".*\"#  url \"${{ steps.pypi.outputs.url }}\"#" "$F"
+          sed -i -E "s#^  sha256 \".*\"#  sha256 \"${{ steps.pypi.outputs.sha }}\"#" "$F"
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet; then
+            echo "formula already up to date"; exit 0
+          fi
+          git commit -am "blitz-cli ${{ steps.v.outputs.version }}"
+          git push

blitz_cli-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spare Parts Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: blitz-cli
-Version: 0.1.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
 Requires-Python: >=3.9
 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
@@ -19,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.4.0/blitz_cli/__init__.py

@@ -0,0 +1,27 @@
+"""blitz-cli — onboard a codebase to Blitz and scaffold a QLoRA trainer.
+
+Commands:
+
+- ``blitz init -p <project>`` — write a repo-local ``.env`` (BLITZ_PROJECT /
+  BLITZ_ENDPOINT) and validate your ingest key.
+
+- ``blitz scan [path]`` — statically walk a codebase and report each AI/LLM
+  call's Blitz instrumentation posture (unsupported provider / no blitz.init() /
+  traced-but-unnamed / instrumented), with copy-paste fixes. Offline, no API key.
+
+- ``blitz verify [--wait]`` — confirm sample traces have landed in Blitz,
+  authenticated by the ingest key (``BLITZ_API_KEY``).
+
+- ``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, 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.4.0"

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

@@ -26,8 +26,9 @@ class BlitzAPIError(RuntimeError):
 def _hint(status: int, detail: str) -> str:
     if status in (401, 403):
         return (
-            f"{detail} (HTTP {status}). Check BLITZ_API_KEY — it must be a "
-            "read-scoped key for this project (create one in the dashboard)."
+            f"{detail} (HTTP {status}). Check BLITZ_API_KEY — it must be a valid "
+            "key for this project (an ingest key for tracing/verify, a read key "
+            "for training data). Create one in the dashboard."
         )
     if status == 404:
         return (
@@ -71,6 +72,12 @@ class BlitzClient:
             except Exception:  # noqa: BLE001
                 pass
             raise BlitzAPIError(exc.code, _hint(exc.code, str(detail))) from None
+        except urllib.error.URLError as exc:
+            raise BlitzAPIError(
+                0,
+                f"could not reach the Blitz API at {self._base} ({exc.reason}). "
+                "Check BLITZ_ENDPOINT and your network.",
+            ) from None
 
     def _get_json(self, path: str, query: Optional[dict] = None) -> dict:
         req = urllib.request.Request(self._url(path, query), headers=self._headers)
@@ -85,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 recommended_tools(self, workflow: str) -> dict:
-        return self._get_json(self._p("/recommended-tools"), {"workflow": workflow})
+    def get_training_config(self, workflow: str) -> dict:
+        return self._get_json(self._p("/training-config"), {"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
@@ -118,21 +129,11 @@ 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 training_readiness(self, workflow: str) -> dict:
+        return self._get_json(self._p("/training-readiness"), {"workflow": workflow})
 
-    def get_eval_run(self, run_id: str) -> dict:
-        return self._get_json(self._p(f"/eval/runs/{run_id}"))
+    def ingest_status(self, workflow: Optional[str] = None) -> dict:
+        """Trace summary for `blitz verify`, authed by the ingest key. This is
+        the one read the ingest scope can do (path is not project-scoped; the
+        key resolves the project server-side)."""
+        return self._get_json("/blitz/v1/ingest-status", {"workflow": workflow})

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/_scan/__init__.py

@@ -0,0 +1,65 @@
+"""Codebase scan: find AI/LLM calls and report their Blitz instrumentation
+posture. Public surface: ``scan_path``, ``render_report``, ``dumps_json``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Set
+
+from ._classify import classify
+from ._js import scan_js
+from ._models import ProjectSignals, ScanResult, Tier
+from ._python import scan_python
+from ._report import dumps_json, render_report
+from ._walk import iter_source_files
+
+__all__ = ["scan_path", "render_report", "dumps_json", "ScanResult", "Tier"]
+
+
+def scan_path(root: Path, langs: Optional[Set[str]] = None) -> ScanResult:
+    """Walk ``root``, detect LLM calls in each file, then classify every site
+    against tree-wide signals (whether the project calls ``blitz.init()``)."""
+    langs = langs or {"python", "js"}
+    root = root.resolve()
+    base = root if root.is_dir() else root.parent
+
+    result = ScanResult(root=str(root))
+    signals = ProjectSignals()
+
+    for path, lang in iter_source_files(root, langs):
+        try:
+            source = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        rel = _relpath(path, base)
+        try:
+            scan = scan_python(path, source, rel) if lang == "python" else scan_js(
+                path, source, rel
+            )
+        except SyntaxError:
+            result.skipped.append(rel)
+            continue
+        signals.files_scanned += 1
+        if scan.has_init:
+            if lang == "python":
+                signals.has_python_init = True
+            else:
+                signals.has_js_init = True
+        result.sites.extend(scan.sites)
+
+    # Classification needs the tree-wide init signal, so it runs after the walk.
+    result.signals = signals
+    for site in result.sites:
+        classify(site, signals)
+
+    # Stable ordering: worst tier first, then path/line.
+    order = {Tier.UNSUPPORTED: 0, Tier.NO_INIT: 1, Tier.UNNAMED: 2, Tier.INSTRUMENTED: 3}
+    result.sites.sort(key=lambda s: (order.get(s.tier, 9), s.path, s.line))
+    return result
+
+
+def _relpath(path: Path, base: Path) -> str:
+    try:
+        return path.resolve().relative_to(base).as_posix()
+    except ValueError:
+        return path.as_posix()

blitz_cli-0.4.0/blitz_cli/_scan/_classify.py

@@ -0,0 +1,28 @@
+"""The 4-tier decision tree. Pure and language-agnostic: both detectors funnel
+their ``CallSite`` drafts through here once project-wide signals are known."""
+
+from __future__ import annotations
+
+from ._models import CallSite, Confidence, ProjectSignals, Provider, SUPPORTED, Tier
+
+
+def classify(site: CallSite, signals: ProjectSignals) -> None:
+    """Set ``site.tier`` (and adjust confidence) in place."""
+    if site.in_untraced:
+        # Intentional suppression (blitz-platform meta-calls). Not a miss; we
+        # still label it INSTRUMENTED-equivalent so it drops out of misses().
+        site.tier = Tier.INSTRUMENTED
+        return
+
+    if site.provider not in SUPPORTED:
+        site.tier = Tier.UNSUPPORTED
+    elif not signals.has_init(site.lang):
+        site.tier = Tier.NO_INIT
+    elif not site.in_named_workflow:
+        site.tier = Tier.UNNAMED
+        # A decorated caller further up the stack may already be tracing this
+        # helper at runtime — we can't see that lexically, so soften confidence.
+        if site.confidence is Confidence.HIGH:
+            site.confidence = Confidence.MEDIUM
+    else:
+        site.tier = Tier.INSTRUMENTED

blitz_cli-0.4.0/blitz_cli/_scan/_js.py

@@ -0,0 +1,98 @@
+"""JS/TS detector — honest regex heuristic.
+
+There's no stdlib JS parser and blitz-cli must stay dependency-free, so this is
+line-oriented ``re`` matching, not real parsing. Consequences, stated loudly:
+no scope resolution, no reliable client-var/decorator tracking, and — because a
+JS Blitz SDK's ``init`` can't be verified here — supported-provider JS calls are
+reported as NO_INIT at LOW confidence rather than pretending they're traced.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import List, Optional
+
+from ._models import CallSite, Confidence, FileScan, Provider
+
+# import specifier substring -> provider (used to know what a file touches)
+_IMPORT_PROVIDER = [
+    ("@anthropic-ai/sdk", Provider.ANTHROPIC),
+    ("@google/generative-ai", Provider.GEMINI),
+    ("@google/genai", Provider.GEMINI),
+    ("openai", Provider.OPENAI),
+    ("@langchain", Provider.LANGCHAIN),
+    ("langchain", Provider.LANGCHAIN),
+    ("litellm", Provider.LITELLM),
+    ("cohere-ai", Provider.COHERE),
+    ("@mistralai", Provider.MISTRAL),
+    ("@aws-sdk/client-bedrock", Provider.BEDROCK),
+    ("ollama", Provider.OLLAMA),
+    ("groq-sdk", Provider.GROQ),
+]
+
+# call-chain regex -> provider it identifies
+_CALL_PATTERNS = [
+    (re.compile(r"\.messages\.create\s*\("), Provider.ANTHROPIC),
+    (re.compile(r"\.messages\.stream\s*\("), Provider.ANTHROPIC),
+    (re.compile(r"\.chat\.completions\.create\s*\("), Provider.OPENAI),
+    (re.compile(r"\.responses\.create\s*\("), Provider.OPENAI),
+    (re.compile(r"\.generateContent\s*\("), Provider.GEMINI),
+    (re.compile(r"\.generateContentStream\s*\("), Provider.GEMINI),
+]
+
+_INIT_RE = re.compile(r"blitz\.init\s*\(")
+_WORKFLOW_RE = re.compile(r"blitz\.workflow\s*\(")
+
+
+def scan_js(path: Path, source: str, rel_path: str) -> FileScan:
+    lines = source.splitlines()
+    imported: List[Provider] = []
+    has_init = False
+    for ln in lines:
+        if _INIT_RE.search(ln):
+            has_init = True
+        for spec, prov in _IMPORT_PROVIDER:
+            if ("import" in ln or "require" in ln) and spec in ln and prov not in imported:
+                imported.append(prov)
+
+    sites: List[CallSite] = []
+    for i, ln in enumerate(lines, start=1):
+        for pat, prov in _CALL_PATTERNS:
+            m = pat.search(ln)
+            if not m:
+                continue
+            # Prefer a provider actually imported in this file; a bare
+            # `.responses.create` in a groq/azure file still reads as its shape.
+            provider = prov
+            sites.append(
+                CallSite(
+                    path=rel_path,
+                    line=i,
+                    provider=provider,
+                    lang="js",
+                    call_expr=m.group(0).rstrip("(").strip(),
+                    enclosing_func=_nearest_func(lines, i - 1),
+                    in_named_workflow=bool(_WORKFLOW_RE.search(ln)),
+                    in_untraced=False,
+                    confidence=Confidence.LOW,
+                )
+            )
+    return FileScan(sites=sites, has_init=has_init)
+
+
+_FUNC_RES = [
+    re.compile(r"function\s+([A-Za-z0-9_$]+)"),
+    re.compile(r"(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*(?:async\s*)?\("),
+    re.compile(r"([A-Za-z0-9_$]+)\s*\([^)]*\)\s*\{"),
+]
+
+
+def _nearest_func(lines: List[str], idx: int) -> Optional[str]:
+    """Best-effort: the nearest preceding function-ish declaration name."""
+    for j in range(idx, max(-1, idx - 60), -1):
+        for rx in _FUNC_RES:
+            m = rx.search(lines[j])
+            if m:
+                return m.group(1)
+    return None