Personal AI, On Personal Devices
Python
feat(mining): inspect Pearl model artifacts before launch
Avanika Narayandaaa5577f0c5
diff --git a/docs/development/pearl-model-enablement.md b/docs/development/pearl-model-enablement.mdindex 9b54a200..b21ff95d 100644--- a/docs/development/pearl-model-enablement.md+++ b/docs/development/pearl-model-enablement.md@@ -56,6 +56,8 @@ The Qwen and Gemma targets remain planned:- Publish under the planned `pearl-ai/*-pearl` id or a staging namespace.3. Validate the Pearl vLLM plugin path.+ - Run `jarvis mine inspect-model --model <pearl-model-id>+ --allow-planned` before starting the miner.- Model loads in Pearl's `vllm-miner` container.- vLLM registers Pearl's quantization plugin.- Mining layers use int7 NoisyGEMM.@@ -91,6 +93,7 @@ validation exist.A model is `validated` only when all of these pass on real hardware:+- `jarvis mine inspect-model --model <pearl-model-id> --allow-planned`- `jarvis mine init --model <pearl-model-id>`- `jarvis mine start`- `curl http://127.0.0.1:8000/v1/models`diff --git a/docs/user-guide/mining.md b/docs/user-guide/mining.mdindex f6bbfea0..c9b67fd4 100644--- a/docs/user-guide/mining.md+++ b/docs/user-guide/mining.md@@ -54,6 +54,7 @@ Docker instead of exposing every GPU on the machine.## Commands- `jarvis mine models` lists Pearl model support status.+- `jarvis mine inspect-model` checks a Pearl model artifact before GPU launch.- `jarvis mine doctor` prints hardware, Docker, Pearl node, wallet, provider,and session checks.- `jarvis mine init` writes the local mining config and resolves the image.@@ -97,6 +98,10 @@ need to be published and validated.When validating a newly converted Pearl model on a mining host, run:```bash+jarvis mine inspect-model \+ --model pearl-ai/Qwen3.5-9B-pearl \+ --allow-planned+jarvis mine validate-model \--model pearl-ai/Qwen3.5-9B-pearl \--allow-planned \diff --git a/src/openjarvis/cli/mine_cmd.py b/src/openjarvis/cli/mine_cmd.pyindex 38598296..f5e1c53a 100644--- a/src/openjarvis/cli/mine_cmd.py+++ b/src/openjarvis/cli/mine_cmd.py@@ -7,6 +7,8 @@ import jsonimport osimport signalimport time+import urllib.error+import urllib.parseimport urllib.requestfrom pathlib import Pathfrom typing import Any@@ -113,6 +115,21 @@ def _post_json(url: str, payload: dict[str, Any], *, timeout: float) -> dict[strreturn json.loads(resp.read().decode())+def _hf_json(+ path: str,+ *,+ token: str = "",+ timeout: float = 10.0,+) -> dict[str, Any] | list[dict[str, Any]]:+ """Fetch JSON from the Hugging Face API with an optional token."""++ request = urllib.request.Request(f"https://huggingface.co{path}")+ if token:+ request.add_header("authorization", f"Bearer {token}")+ with urllib.request.urlopen(request, timeout=timeout) as resp:+ return json.loads(resp.read().decode())++def _extract_model_ids(models_payload: dict[str, Any]) -> set[str]:data = models_payload.get("data", [])ids: set[str] = set()@@ -125,6 +142,51 @@ def _extract_model_ids(models_payload: dict[str, Any]) -> set[str]:return ids+def _hf_model_path(model_id: str, suffix: str) -> str:+ encoded = urllib.parse.quote(model_id, safe="/")+ return f"/api/models/{encoded}{suffix}"+++def _artifact_file_paths(tree_payload: Any) -> set[str]:+ paths: set[str] = set()+ if isinstance(tree_payload, list):+ for item in tree_payload:+ if isinstance(item, dict) and isinstance(item.get("path"), str):+ paths.add(item["path"])+ return paths+++def _artifact_has_weights(paths: set[str]) -> bool:+ return any(+ path.endswith(".safetensors") or path.endswith(".bin") or path.endswith(".gguf")+ for path in paths+ )+++def _artifact_quant_method(model_payload: Any) -> str:+ if not isinstance(model_payload, dict):+ return ""+ config = model_payload.get("config")+ if not isinstance(config, dict):+ return ""+ quant_config = config.get("quantization_config")+ if not isinstance(quant_config, dict):+ return ""+ return str(quant_config.get("quant_method") or "")+++def _artifact_architectures(model_payload: Any) -> list[str]:+ if not isinstance(model_payload, dict):+ return []+ config = model_payload.get("config")+ if not isinstance(config, dict):+ return []+ architectures = config.get("architectures")+ if not isinstance(architectures, list):+ return []+ return [str(item) for item in architectures if isinstance(item, str)]++def _pid_alive(pid: int | None) -> bool:if not pid:return False@@ -705,6 +767,147 @@ def validate_model(click.echo("Validation checks passed.")[email protected]("inspect-model")[email protected]("--model", default=DEFAULT_PEARL_MODEL, help="Pearl model id to inspect.")+ "--allow-planned",+ is_flag=True,+ default=False,+ help="Inspect planned models even though they are not enabled for mining yet.",+)+ "--hf-token-env",+ default="HF_TOKEN",+ show_default=True,+ help="Environment variable containing a Hugging Face token.",+)+ "--output",+ type=click.Path(dir_okay=False, path_type=Path),+ default=None,+ help="Write a JSON artifact inspection report.",+)[email protected]("--timeout", default=10.0, show_default=True, type=float)+def inspect_model(+ model: str,+ allow_planned: bool,+ hf_token_env: str,+ output: Path | None,+ timeout: float,+) -> None:+ """Inspect a Pearl model artifact before spending GPU time."""++ click.echo("Pearl Model Artifact Inspection")+ click.echo(f"model: {model}")+ results: list[bool] = []+ records: list[dict[str, Any]] = []++ def record(name: str, ok: bool, info: str) -> None:+ records.append({"name": name, "ok": ok, "info": info})+ _validation_row(results, name, ok, info)++ spec = get_pearl_model_spec(model)+ if spec is None:+ planned = pearl_variant_for_base_model(model)+ info = f"raw model; planned Pearl variant {planned}" if planned else "unknown"+ record("Model registry", False, info)+ elif spec.is_validated:+ record("Model registry", True, f"validated: {spec.model_id}")+ else:+ record("Model registry", allow_planned, f"{spec.status}: {spec.model_id}")++ token = os.environ.get(hf_token_env, "")+ model_payload: Any = None+ paths: set[str] = set()+ try:+ model_payload = _hf_json(+ _hf_model_path(model, ""),+ token=token,+ timeout=timeout,+ )+ record("HF model", True, "accessible")+ except urllib.error.HTTPError as exc:+ info = f"HTTP {exc.code}"+ if exc.code in {401, 403} and not token:+ info += f"; set ${hf_token_env} for gated/private models"+ record("HF model", False, info)+ except Exception as exc: # noqa: BLE001+ record("HF model", False, str(exc).splitlines()[0])++ if model_payload is not None:+ quant_method = _artifact_quant_method(model_payload)+ record(+ "Pearl quantization",+ quant_method == "pearl",+ quant_method or "missing quantization_config.quant_method",+ )++ try:+ tree_payload = _hf_json(+ _hf_model_path(model, "/tree/main?recursive=false"),+ token=token,+ timeout=timeout,+ )+ paths = _artifact_file_paths(tree_payload)+ record("HF file list", bool(paths), f"{len(paths)} files")+ except Exception as exc: # noqa: BLE001+ record("HF file list", False, str(exc).splitlines()[0])++ if paths:+ has_config = "config.json" in paths+ record(+ "config.json",+ has_config,+ "present" if has_config else "missing",+ )+ tokenizer_ok = bool({"tokenizer.json", "tokenizer_config.json"} & paths)+ record(+ "Tokenizer metadata",+ tokenizer_ok,+ "present"+ if tokenizer_ok+ else "missing tokenizer.json/tokenizer_config.json",+ )+ has_weights = _artifact_has_weights(paths)+ record(+ "Weights",+ has_weights,+ "present" if has_weights else "missing",+ )++ architectures = _artifact_architectures(model_payload)+ is_gemma4 = any("Gemma4" in arch for arch in architectures)+ if is_gemma4:+ missing = [+ name+ for name in ("processor_config.json", "preprocessor_config.json")+ if name not in paths+ ]+ record(+ "Gemma4 processor metadata",+ not missing,+ "present" if not missing else "missing " + ", ".join(missing),+ )++ passed = bool(results) and all(results)+ if output is not None:+ output.parent.mkdir(parents=True, exist_ok=True)+ artifact = {+ "schema_version": 1,+ "model": model,+ "status": "passed" if passed else "failed",+ "allow_planned": allow_planned,+ "hf_token_env": hf_token_env,+ "checks": records,+ }+ output.write_text(json.dumps(artifact, indent=2, sort_keys=True) + "\n")+ click.echo(f"Inspection artifact written to {output}")++ if not passed:+ raise click.ClickException("Pearl model artifact inspection failed.")+ click.echo("Artifact inspection passed.")++@mine.command()@click.option("--vllm-endpoint", required=True)@click.option("--gateway-url", required=True)diff --git a/tests/cli/test_mine_cmd.py b/tests/cli/test_mine_cmd.pyindex 4bac1431..5f7c56d9 100644--- a/tests/cli/test_mine_cmd.py+++ b/tests/cli/test_mine_cmd.py@@ -33,6 +33,62 @@ def test_mine_models_lists_validated_and_planned_models() -> None:assert "planned" in result.output+def test_mine_inspect_model_validated_artifact_passes(monkeypatch) -> None:+ model = "pearl-ai/Llama-3.3-70B-Instruct-pearl"++ def fake_hf_json(path: str, *, token: str = "", timeout: float = 10.0):+ if path.endswith("/tree/main?recursive=false"):+ return [+ {"path": "config.json"},+ {"path": "tokenizer.json"},+ {"path": "model.safetensors"},+ ]+ return {+ "config": {+ "architectures": ["LlamaForCausalLM"],+ "quantization_config": {"quant_method": "pearl"},+ }+ }++ monkeypatch.setattr("openjarvis.cli.mine_cmd._hf_json", fake_hf_json)++ result = CliRunner().invoke(cli, ["mine", "inspect-model", "--model", model])++ assert result.exit_code == 0+ assert "Artifact inspection passed" in result.output+ assert "Pearl quantization" in result.output+++def test_mine_inspect_model_gemma4_requires_processor_metadata(monkeypatch) -> None:+ model = "pearl-ai/Gemma-4-31B-it-pearl"++ def fake_hf_json(path: str, *, token: str = "", timeout: float = 10.0):+ if path.endswith("/tree/main?recursive=false"):+ return [+ {"path": "config.json"},+ {"path": "processor_config.json"},+ {"path": "tokenizer.json"},+ {"path": "model.safetensors"},+ ]+ return {+ "config": {+ "architectures": ["Gemma4ForConditionalGeneration"],+ "quantization_config": {"quant_method": "pearl"},+ }+ }++ monkeypatch.setattr("openjarvis.cli.mine_cmd._hf_json", fake_hf_json)++ result = CliRunner().invoke(+ cli,+ ["mine", "inspect-model", "--model", model, "--allow-planned"],+ )++ assert result.exit_code != 0+ assert "Gemma4 processor metadata" in result.output+ assert "missing preprocessor_config.json" in result.output++def test_mine_init_writes_mining_config(tmp_path: Path) -> None:config_path = tmp_path / "config.toml"