Spark

For CLI tools, automations, and voice bots

AI workflows you can read, test, and ship

Python plus the OpenAI SDK works until you need readable diffs, tests that run without keys, and one file you can ship. Spark puts ask, classify, and extract in plain .spark source—not scattered API calls or framework wrappers.

Download Spark Playground Getting started

What you can do

Ask questions in code

Call the AI from a .spark file instead of wiring HTTP calls in Python. 

ask "Summarize this" -> text
print text

Test without API money

Run ./spark --dry-run to get fake answers — no API key needed for local dev or CI. 

./spark --dry-run examples/hello.spark

Try two models side by side

Spark runs your test prompts on a cheap model and a smart model, then prints which one scored higher — save the winner to spark.toml or a blueprint file you can check into git. 

# compare-models.spark
model compare ["fast", "best"]
  on suite "examples/eval_suite.json" -> pick
print pick

Run steps in order

Put each step on its own line — step two runs after step one finishes, with no separate Python script. 

ask "What is Spark?" -> answer
print answer

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 API key). Live calls need OPENAI_API_KEY and ./spark --live. Open the model wizard or try it in the browser.

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 — set OPENAI_API_KEY first
export OPENAI_API_KEY=your_key
./spark --live examples/ask_live.spark

Sample program: use code then ask "…" -> text. See full programming guide and language reference.