# SparkLang agent contract
version: 0.8.0
sha: e91e80b64230
verified: 2026-09-04
site: https://sparklang.dev
source: https://github.com/Michael20251/sparklang

## links
https://sparklang.dev/llms.txt
https://sparklang.dev/agent.md
https://sparklang.dev/grammar.ebnf
https://sparklang.dev/openapi.json
https://sparklang.dev/SKILL.md
https://sparklang.dev/examples/dry_run.spark

## install
pip install sparklang
binary	https://sparklang.dev/downloads.html

## dry-run
spark --dry-run examples/train_eval.spark
spark --dry-run examples/dry_run.spark

## verbs
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
spark_distill_cpu	Trainer method — reply-class student → weights.pt
spark_pref_pack	Trainer method — preference pairs + ranker
spark_playbook_fit	Trainer method — intent→playbook router
spark_faq_index	Trainer method — FAQ dual-encoder
lora_bf16	Trainer method — Unsloth/PEFT LoRA (GPU) or fixture
hf://	hf://org/name on dataset/base/out (hf_resolve.py)
GitHub Action dry-run	uses: Michael20251/sparklang/.github/actions/dry-run

## trainer
POST {SPARK_TRAIN_URL}/jobs
GET {SPARK_TRAIN_URL}/jobs/{id}
POST_BODY {"dataset":"examples/fixtures/train/dataset.jsonl","base":"fixture-base","out":"out/train/job-dry-001","backend":"http","method":"spark_distill_cpu"}
STATUS_SCHEMA {"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
0	success / expect pass
1	expect fail or language fail
2	usage / unknown method / missing program
4	credential unavailable or CAP miss

## governance
--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

## inline.spark
model code
model train dataset "examples/fixtures/train/dataset.jsonl" base "fixture-base" out "out/train/job-dry-001" backend "http" method "spark_distill_cpu" -> job
model status "job-dry-001" -> status
expect contains job fixture "examples/fixtures/train/want_accepted.txt"
expect contains status fixture "examples/fixtures/train/want_succeeded.txt"

## mock-trainer
SPARK_TRAIN_URL=http://127.0.0.1:8099/v1
curl -sS -X POST $SPARK_TRAIN_URL/jobs -H 'Content-Type: application/json' -d '{"dataset":"examples/fixtures/train/dataset.jsonl","base":"fixture-base","out":"out/train/job-dry-001","backend":"http","method":"spark_distill_cpu"}'
curl -sS $SPARK_TRAIN_URL/jobs/JOB_ID