SPL — Structured Prompt Language

SPL is a declarative language for agentic AI workflows — SQL for LLMs.

Where SQL abstracts over databases, SPL abstracts over language models: the same .spl file runs on Ollama, Claude, OpenAI, Gemini, or a Momagrid compute grid without changing a single line of workflow code. Below is a condensed version of self_refine workflow

WORKFLOW self_refine
    INPUT:  @topic TEXT
    OUTPUT: @essay TEXT
DO
    GENERATE draft(@topic) INTO @essay
    CALL critique(@essay) INTO @feedback
    GENERATE refine(@essay, @feedback) INTO @essay
    COMMIT @essay
END

spl3 run cookbook/05_self_refine/self_refine.spl --adapter ollama --param topic="What is vibe coding?"

Quick Start

For a fresh-machine walkthrough covering the full verifier ladder (SymPy → SageMath → Lean 4 + mathlib), see docs/GUIDE/SETUP.md.

conda create -n spl123 python=3.11
conda activate spl123        # Python 3.11+

pip install -e ".[dev]"      # install from this repo

# Verify install
spl3 --help

# Run hello world (Ollama)
spl3 run cookbook/01_hello_world/hello.spl --adapter ollama

# Run self-refine with local models and input parameters explicitly specified
spl3 run cookbook/05_self_refine/self_refine.spl \
    --adapter ollama \
    --param task="Explain vibe coding" \
    --param writer_model="gemma3" \
    --param critic_model="llama3.2" \
    --param max_iterations=3 \
    --param log_dir="$HOME/.spl/logs/05_self_refine/output"

# Run all active recipes
python cookbook/run_all.py

# Run a specific subset
python cookbook/run_all.py --ids 01,05,13

# Run multimodal / SPL 3.0 recipes (tier 1 = Ollama only)
python cookbook/run_all.py --tier 1 --category multimodal

Why SPL

Most agentic frameworks require hundreds of lines of imperative Python to wire up prompts, manage context, handle errors, and switch LLM providers. SPL takes a different path: declare what you want, not how to get it.

Language Layers

SPL synthesizes three programming paradigms:

CLI Reference

spl3 run      <file.spl> [--adapter NAME] [--model MODEL] [--param KEY=VALUE ...]
spl3 validate <file.spl>
spl3 explain  <file.spl>

# Natural language → workflow pipeline
spl3 text2spl  "natural language description" [--mode prompt|workflow|auto] [-o FILE]
spl3 text2mmd  "description" [--adapter NAME] [-m MODEL] [-o FILE]   # → Mermaid diagram
spl3 mmd2spl   <file.mmd>   [--adapter NAME] [-m MODEL] [-o FILE]   # → SPL workflow

# Introspection
spl3 show --adapter                        # list all adapters
spl3 show --adapter <name> --model         # list models for an adapter
spl3 show --tool                           # list all 68 stdlib tools by category
spl3 show --tool <name>                    # show tool detail (usage, args, deps)

# Code intelligence
spl3 code-rag  seed <dir> --catalog <catalog.json>
spl3 code-rag  query "judge-retry loop"

# Neurosymbolic verifier ladder — SOLVE/ASSERT against a persistent kernel
spl3 run <file.spl> --kernel --kernel-name sagemath   # SymPy/SageMath/Lean backends

# Deterministic tool libraries (CREATE TOOL_API)
spl3 tool-api promote <file.spl> --name <lib_name>
spl3 tool-api list

# Compile a .spl logical view to a physical target (Go, TS, LangGraph, notebook, ...)
spl3 splc compile <file.spl> --target <name>

spl3 judge <file> --criteria <name>                    # LLM-as-judge against a rubric
spl3 vibe "description"                                # one-shot NL → code + README
spl3 workflow list                                      # durable workflow runs (persistence)

spl3 --hub http://localhost:8080 run <file.spl>       # Hub-backed registry
spl3 --hub http://localhost:8080 register <dir/>       # register workflows on Hub

Adapters

Four adapters form the mandatory baseline that every SPL runtime must support — they cover the full development lifecycle from local prototyping to production grid deployment:

Additional adapters available in the Python (spl3) runtime:

Porting checklist: Any new SPL runtime port must implement the four mandatory adapters before being considered feature-complete. echo is testing scaffolding only.

Codebase Layout

spl/              SPL 2.0 runtime (lexer, parser, executor, 15 adapters)
  lexer.py          tokenization
  parser.py         recursive-descent parser → AST
  ast_nodes.py      30+ dataclass node types
  executor.py       runtime engine
  analyzer.py       semantic validation
  optimizer.py      token budget allocation
  explain.py        ASCII plan rendering
  ir.py             JSON AST serialization
  text2spl.py       natural language → SPL compiler
  config.py         ~/.spl/config.yaml load/save (adapter, storage_dir, text2spl defaults)
  adapters/         LLM backend plugins
  stdlib.py         68 built-in tools (web_search, http_get, run_python, file I/O, string, JSON, …)
  storage/          SQLite memory + vector store (RAG)

spl3/             SPL 3.0 extension layer (inherits from spl/)
  executor.py       SPL3Executor(SPL2Executor) — CALL dispatch, type coercion
  parser.py         SPL3Parser(SPL2Parser) — IMPORT, SET, NONE, CALL PARALLEL, SOLVE/ASSERT
  composer.py       workflow-to-workflow CALL execution
  registry.py       LocalRegistry + FederatedRegistry
  hub_registry.py   REST-backed Hub registry
  event.py          WorkflowInvocationEvent (UUID, lifecycle, Hub serialization)
  status.py         COMMIT status → exception type mapping
  kernel.py         persistent IPython kernel (--kernel); SymPy/SageMath/Lean via --kernel-name
  lean_bridge.py    Lean 4 + mathlib proof elaboration/kernel-checking
  tool_api_registry.py CREATE TOOL_API — deterministic Python tool libraries (~/.spl/tool_apis/)
  judge/            LLM-as-judge: rubric scoring, aggregation, reporting
  persistence/      durable workflow state — SQLite / Postgres / DBOS backends
  cache/            content-addressed generation cache (Layer 2)
  rag/              recipe/code retrieval (Chroma-backed)
  codecs/           image / audio / video codec layer
  splc/             transpilers: Go, TypeScript, LangGraph, PocketFlow, python/<domain> (concept-book / textbook)
  text2spl/         SPL 3.0 text2spl (extends spl/text2spl.py)
  adapters/         SPL 3.0 adapters: multimodal, Liquid, Snap

cookbook/         74 recipes (SPL 2.0: 01–49, SPL 3.0 multimodal: 50–64, neurosymbolic verifier ladder: 65–87)
tests/            unified test suite (900+ tests)

Cookbook

Working examples are provided as 74 recipes spanning beginner to advanced:

python cookbook/run_all.py --list           # all 74 recipes
python cookbook/run_all.py --catalog        # full table with tier + category
python cookbook/run_all.py --check          # verify env vars + Ollama models

Momagrid — Decentralized Compute Grid

The momagrid adapter routes SPL inference tasks to a Momagrid Hub, which dispatches them across a LAN grid of GPU nodes.

export MOMAGRID_HUB_URL=http://192.168.1.10:9000

# Single recipe on the grid
spl3 run cookbook/05_self_refine/self_refine.spl --adapter momagrid -m llama3.2

# Full cookbook in parallel (fills the task queue so all nodes get work)
python cookbook/run_all.py --adapter momagrid --workers 5

SPL 3.0 extends Momagrid as a Compute OS: each CALL workflow_name() becomes a Hub-dispatched system call; CALL PARALLEL concurrently routes sub-workflows to different nodes.

Tests

pytest tests/test_registry.py       # single file
pytest -k test_status_mapping       # single test
pytest                              # full suite

Development Workflow

SPL.py is the stable public repo. New features are prototyped in SPL30 and graduate here when they have test coverage and a cookbook recipe.

Future major versions (spl4/, spl5/, ...) will be prototyped in SPL30 and added as new subpackages alongside spl/ and spl3/. The spl3 CLI command is permanent — it always points to the highest available runtime layer.

Version History

License

Apache-2.0