SparkLang — the Spark programming language
A language and runtime for readable AI workflows
Write programs in plain .spark files —
dry-run fixtures, compile/BC, playbooks, and the Spark IDE are the
core story. Model analyze/compare/improve/build is blueprint and eval
sugar (not weight training). Optional language ops cover network,
web/browser, and voice/PSTN (gated). Live
ask against an OpenAI-compatible
gateway is optional when you pass --live
— Spark is not a Bifrost plugin.
What you can do
Model analyze → build
First-class model analyze,
compare,
improve, and
build — blueprint / eval sugar
(plan + config markdown), not weight training.
model compare ["fast", "code", "best"]
on suite "examples/eval_suite.json" -> pick
model build blueprint into "out/model.md"
Dry-run first · optional live ask
Default --dry-run uses offline
fixtures — no keys, no network. Live
ask is opt-in
(./spark --live + any
OpenAI-compatible AI_GATEWAY_URL).
Alias names like fast /
code /
best are language conventions —
not a required Bifrost install.
use auto
ask "Summarize: {doc}" -> text
./spark --dry-run my_task.spark
Voice & phone (optional)
Optional language ops: listen,
speak, and
voice { … } — STT/TTS,
classify-in-call, PSTN dial (off by default / gated).
voice {
listen -> user
classify Intent { support, sales } from user -> intent
ask "Reply as {intent}: {user}" -> reply
speak reply
}
AI coding playbooks
Copy playbooks from lib/playbooks.spark
— fix tests, refactor, review paths — with
use auto picking fast vs code.
include "lib/ai.spark"
ask "Fix this test failure: {msg}" -> fix
Retrieval stack [roadmap]
Integration targets: rag-gateway retrieve, gateway
embed, TEI embeddings, CRAG grade.
Documented honestly — not wired as language ops yet.
# today: model + ask + voice + classify
# roadmap: retrieve / embed via gateway
Create & tune models
Built-in steps analyze catalog entries, compare them on your eval
suite, suggest improvements, and write a blueprint markdown
file you review — sugar for planning, not weight training.
-
1
Analyze
Read metrics for one model or your whole catalog
-
2
Compare
Run fast, code, and best on your eval suite
-
3
Improve
Pick quality, speed, cost, or local preference
-
4
Build
Write a blueprint markdown file — not weights
model code
model analyze "fast" -> report
model compare ["fast", "code", "best"]
on suite "examples/eval_suite.json" -> comparison
model improve from report prefer quality -> blueprint
model build blueprint into "out/my-model.md"
model build writes a plan and config
file only — never starts training jobs.
./spark --dry-run uses fixtures (no
keys, no network). Optional live
ask uses
./spark --live with any
OpenAI-compatible AI_GATEWAY_URL.
Open the model wizard or
language reference.
Voice & phone workflows
Optional capability: receptionist-style bots, IVR flows, and outbound
dial scripts in the same language — dry-run with stub audio; live
speech and --pstn-live stay gated.
voice {
listen -> user
classify Intent { support, sales, billing } from user -> intent
ask "Reply helpfully to: {user}" -> reply
speak reply -> "out/turn.wav"
}
# PSTN off by default — placeholders only until you enable gates
voice pstn status -> st
voice pstn dial "+15555550100" -> call
See AI in 5 Minutes — voice,
Playground voice tab, and
language reference (listen/speak/pstn).
Native network & web
Optional capability: network,
engine fetch, and
browser / MITM ops — dry-run fixtures
by default; opt in with --allow-net or
--allow-net-capture for live HTTP or
capture.
network capture probe -> info
network open "examples/fixtures/sample.pcap" -> pcap
network analyze pcap -> traffic_report
engine fetch "file://examples/fixtures/engine/sample.html"
browser run "examples/browser_main.spark"
Not a Python stub driver — asm dispatch today. First-class
http get / http post
are [roadmap]; use engine fetch
for HTTP now.
Network + web guide ·
Language reference ·
Browser / MITM
Core vs optional
SparkLang is the language and runtime. Gateways, voice, and capture
are capabilities you turn on — not the product identity.
Core
Language + dry-run fixtures + playbooks + Spark IDE language ops
(ide new|open|save|run|buffer|ask|show).
Optional
Live gateway ask
(--live; voice/PSTN (gated);
browser/MITM; network capture.
Spark IDE + AI coding
Core surface: verified ide ops plus
playbooks and review /
builder — readable diffs and dry-run
tests. Live gateway is optional when you are ready.
include "lib/ai.spark"
ide new "out/ide/task.spark"
ide ask "Explain this buffer" -> reply
./spark --dry-run examples/ide_ask_show.spark
Terminal-first IDE today — not Electron product chrome.
IDE status ·
AI models guide ·
Programming guide
Learn Spark
Follow the tutorial path — same structure as official language docs for
Java or C++.
Install the runtime, run your first dry-run, and set up live ask.
Start here →
Hello world with use,
ask, and
print.
Write hello.spark →
Classify, extract, pipeline, voice, and model workflow — the
primitives for AI programs in one file.
Quick tour →
Wizard for analyze → compare → improve → build — modify an
existing model or create a new blueprint from scratch.
Open wizard →
Hello world
./spark --dry-run examples/hello.spark
export AI_GATEWAY_URL=http://127.0.0.1:4000
./spark --live examples/ask_live.spark
Sample program:
use code then
ask "…" -> text. See
full programming guide and
language reference.