Spark

For AI models, retrieval, coding, and voice/phone

AI workflows you can read, test, and ship

Spark puts model analyze/compare/improve, gateway-routed ask, retrieval targets (RAG/embed on the roadmap), IDE playbooks, and voice/phone bots — listen, speak, classify-in-call, PSTN dial (gated) — in one reviewable .spark file. Dry-run without keys; go live when you are ready.

Download Spark Playground Getting started

What you can do

Model analyze → build

First-class model analyze, compare, improve, and build — blueprint markdown, not scattered training scripts. 

model compare ["fast", "code", "best"]
  on suite "examples/eval_suite.json" -> pick
model build blueprint into "out/model.md"

Gateway aliases + dry-run

Route live ask through Bifrost (fast, code, best). Offline fixtures with --dry-run — no API key for CI. 

use auto
ask "Summarize: {doc}" -> text
./spark --dry-run my_task.spark

Voice & phone bots

First-class listen, speak, and voice { … } loops — STT/TTS, classify-in-call, optional PSTN (off by default). 

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

Spark has built-in steps to analyze models, compare them on your examples, suggest improvements, and write a blueprint file you review before any live training.

  1. 1 Analyze Read metrics for one model or your whole catalog
  2. 2 Compare Run fast, code, and best on your eval suite
  3. 3 Improve Pick quality, speed, cost, or local preference
  4. 4 Build Write a blueprint markdown file — not weights 
# tune-model.spark — copy, save, run
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 — you review it before any live training. ./spark --dry-run uses fixtures (no keys, no network). Live calls use ./spark --live with AI_GATEWAY_URL (Bifrost default); gateway keys are optional. Open the model wizard or language reference.

Voice & phone workflows

Build receptionist-style bots, IVR flows, and outbound dial scripts in the same language as your model and coding workflows — dry-run with stub audio, go live with --live and optional --pstn-live when gates are on. 

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

First-class network, engine fetch, and browser / MITM ops in .spark — dry-run fixtures by default; opt in with --allow-net or --allow-net-capture when you need live HTTP or packet 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

Spark IDE + AI coding

Verified ide ops (new, open, save, run, buffer, ask, show) plus playbooks and review / builder — readable diffs, dry-run tests, optional live gateway 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++.

Build a Model

Wizard for analyze → compare → improve → build — modify an existing model or create a new blueprint from scratch.

Open wizard →

Hello world

# Dry-run — no network, no API key
./spark --dry-run examples/hello.spark

# Live — Bifrost gateway (optional key)
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.