# SparkLang agent contract

version `0.8.0` · sha `e91e80b64230` · verified `2026-09-04`

## install

`pip install sparklang`

binary: https://sparklang.dev/downloads.html

## dry-run

`spark --dry-run examples/train_eval.spark`

## verbs

| verb | grammar |
| --- | --- |
| `model train` | `model train dataset "PATH" base "ID" out "DIR" backend "http" method "METHOD" -> job` |
| `model status` | `model status "JOB_ID" -> status` |
| `model inspect` | `model inspect PATH -> summary (CLI: spark-modelscope)` |
| `model diff` | `model diff A B -> delta (adapter heatmap)` |
| `model probe` | `model probe base symbols "DIR" -> p (AUROC < 0.85 = unusable)` |
| `model decompile` | `model decompile contrast→vector — EXPERIMENTAL until probe AUROC ≥ 0.85` |
| `model patch` | `model patch vector|rome|memit + scale 0.4–1.2 — EXPERIMENTAL until probe AUROC ≥ 0.85` |
| `model eval` | `model eval ARTIFACT suite "PATH" -> e` |
| `model stage` | `model stage ARTIFACT marker "ID" -> staged (serving_loaded: false always)` |
| `expect contains` | `expect contains NAME fixture "PATH"` |
| `expect gte` | `expect gte NAME $.path N` |
| `expect lte` | `expect lte NAME $.path N` |
| `expect eq` | `expect eq NAME $.path V` |
| `expect histogram_min` | `expect histogram_min NAME CLASS N` |
| `expect score` | `expect score NAME $.path using "URL" >= N` |
| `http get` | `http get "URL" fixture "PATH" timeout N -> resp` |
| `http post` | `http post "URL" body "{…}" fixture "PATH" timeout N -> resp` |

## trainer

| method | path |
| --- | --- |
| POST | `{SPARK_TRAIN_URL}/jobs` |
| GET | `{SPARK_TRAIN_URL}/jobs/{id}` |

```json
{
  "schema_version": 1,
  "required": [
    "schema_version",
    "method",
    "artifact_path",
    "base",
    "dataset_sha256",
    "rows",
    "metrics"
  ],
  "poll": {
    "job_id": "string",
    "state": "succeeded|failed|running|accepted",
    "artifacts": "object",
    "method": "string"
  }
}
```

## exit

| code | meaning |
| --- | --- |
| 0 | success / expect pass |
| 1 | expect fail or language fail |
| 2 | usage / unknown method / missing program |
| 4 | credential unavailable or CAP miss |

## governance

| flag | meaning |
| --- | --- |
| `--require-token` | SPARK_REQUIRE_TOKEN=1 — live submit needs token |
| `--ledger PATH` | SPARK_LEDGER — append live submits as JSONL |
| `--allowlist` | SPARK_TRAIN_UNIT_ALLOWLIST — optional local-yield |

## what-is-real

| verb | reality | since |
| --- | --- | --- |
| `model train` | real | 0.6.0 |
| `model status` | real | 0.6.0 |
| `model inspect` | real | 0.8.0 |
| `model diff` | real | 0.8.0 |
| `model probe` | real | 0.8.0 |
| `model decompile` | experimental | 0.8.0 |
| `model patch` | experimental | 0.8.0 |
| `model eval` | real | 0.8.0 |
| `model stage` | real | 0.8.0 |
| `expect contains` | real | 0.6.0 |
| `expect gte` | real | 0.7.0 |
| `expect lte` | real | 0.7.0 |
| `expect eq` | real | 0.7.0 |
| `expect histogram_min` | real | 0.7.0 |
| `expect score` | real | 0.7.0 |
| `http get` | real | 0.6.0 |
| `http post` | real | 0.6.0 |
| `spark_distill_cpu` | real | 0.6.0 |
| `spark_pref_pack` | real | 0.6.0 |
| `spark_playbook_fit` | real | 0.6.0 |
| `spark_faq_index` | real | 0.6.0 |
| `lora_bf16` | real | 0.7.0 |
| `hf://` | real | 0.7.0 |
| `GitHub Action dry-run` | real | 0.7.0 |

[llms.txt](https://sparklang.dev/llms.txt) · [grammar.ebnf](https://sparklang.dev/grammar.ebnf) · [openapi.json](https://sparklang.dev/openapi.json) · [SKILL.md](https://sparklang.dev/SKILL.md)