Curriculum-aware STEM learning: visual-first, label-second coding from syllabus to student evidence.
Project description
Poetica
Write what you mean. Compile to what you need.
Poetica is a human-readable DSL that compiles to real code in six languages. The poem type selects the backend. The gate controls what's allowed.
seed message with "hello world"
emit message
That's a program. Compile it:
poetica compile hello.poem --type sonnet # → Python
poetica compile hello.poem --type haiku # → Rust
poetica compile hello.poem --type ballad # → JavaScript
poetica compile hello.poem --type ode # → Go
poetica compile hello.poem --type prose # → Bash
poetica compile hello.poem --type verse # → SQL
Why
Programming is gatekept by syntax. Students see if sensor_distance < 10: before they understand what a condition does. Poetica flips that: see the robot stop, describe what happened, then see the code.
For teachers: Bring your existing syllabus. Poetica maps objectives to computing concepts, domain-specific language, visual simulations, and evidence criteria. No naked syntax — every code token appears with its meaning.
For students: Write in the language of your subject. stop motor, not motor_speed = 0. See what happens in a visual world before you see Python. Learn what the code means before you memorize how it's spelled.
For coders: Write polyglot programs once. Think in operations, not syntax. seed, grow, emit, pack, lift, bloom — these map to the same intent in every language. The poem type is just a compiler flag.
Demo: Grade 5 Robotics
A complete vertical slice from teacher syllabus to student evidence:
bash demos/grade5_robotics/run_demo.sh
Student writes robotics language:
when sensor.distance < 10:
stop motor
emit "obstacle detected"
Poetica shows five layers (no naked syntax):
Original: stop motor ← what the student wrote
Canonical: seed motor_speed with 0 ← what Poetica compiled
Concept: actuator_control ← the robotics concept
Code: motor_speed = 0 ← the Python code
Visual: the motor stops spinning ← what you'd SEE
Evidence replaces a letter grade:
{"description": "student can explain input -> condition -> action", "met": null}
{"description": "student can modify the threshold", "met": null}
{"description": "student can debug a wrong comparison", "met": null}
See demos/grade5_robotics/PITCH.md for the full pitch.
Install
pip install poetica
Or from source:
cd packages/poetica
pip install -e .
Poem Types
| Poem Type | Target | Character |
|---|---|---|
| sonnet | Python | Flowing, expressive, readable |
| haiku | Rust | Minimal, precise, safe |
| ballad | JavaScript | Event-driven, flowing, async |
| ode | Go | Structured, concurrent, explicit |
| prose | Bash | Imperative, step-by-step, direct |
| verse | SQL | Declarative, set-based |
Grammar
name <identifier> — name the program
seed <thing> with <value> — create / initialize
grow <thing> with <source> — build / construct
emit <message> — output / print
emit "<label>" <message> — labeled output
pack <data> as <format> — serialize / bundle
lift <thing> to <dest> — deploy / upload
use <tool>(key: val, ...) — call external tool
when <condition>: — conditional
when <x> in <y>: — membership test
if <a> echoes <b> — equality check
flow <source> to <dest> — pipe / assign
bloom <value> — return
remember <key>: <value> — persist
learn pattern "<name>" — fit / recognize
for each <x> in <y>: <body> — iterate
Capability Levels (The Gate)
Every compilation goes through the gate. The gate checks each operation against the current level. If an operation exceeds the level, compilation fails. No bypass.
| Level | Name | Operations Unlocked |
|---|---|---|
| L1 | Pure | seed, emit, flow, bloom, remember |
| L2 | + Logic | if, when, for |
| L3 | + Transform | pack, grow, learn |
| L4 | + External | lift, use |
| L5 | Unrestricted | everything |
L1 is safe. A Level 1 program can create values and print them. It cannot build, transform, deploy, or call external tools. Give this to anyone.
# This works at L1:
poetica compile hello.poem --level 1
# This fails at L1 (grow needs L3):
poetica compile garden.poem --level 1
# Gate REJECT: op='grow': LEVEL-EXCEEDED
Python API
from poetica import compile_poem
# Simple
code = compile_poem("seed x with 42\nemit x", target="python")
print(code)
# With gate level
code = compile_poem(source, target="rust", level=3)
# All poem types
from poetica.emitters import list_targets
print(list_targets())
# {'sonnet': 'python', 'haiku': 'rust', 'ballad': 'javascript', ...}
CLI
# Compile to stdout
poetica compile program.poem --type sonnet
# Compile to file
poetica compile program.poem --type haiku -o program.rs
# Set capability level
poetica compile program.poem -t ballad --level 3
# Gate-check without compiling
poetica check program.poem --level 2
# List targets
poetica targets
# Pipe from stdin
echo "seed x with 42\nemit x" | poetica compile - --type prose
Receipt
Every compilation can produce a receipt — an audit trail of what was checked and what was generated.
poetica compile hello.poem --type sonnet --receipt 2>receipt.json
{
"schema": "poetica.receipt.v1",
"source_hash": "a1b2c3...",
"target": "sonnet",
"gate_level": 1,
"all_allowed": true,
"decisions": [
{"op": "seed", "verdict": "ALLOW", "reason": "OK", "level": 1},
{"op": "emit", "verdict": "ALLOW", "reason": "OK", "level": 1}
],
"output_hash": "d4e5f6..."
}
Education Stack
Beyond the compiler, Poetica includes a curriculum-aware education layer:
| Layer | What it does |
|---|---|
| Domain Packs | Subject-specific language (robotics, microbiology, finance) |
| Syllabus Import | Extract objectives from teacher syllabi into draft curriculum YAML |
| Curriculum Mapper | Map standards/objectives → concepts → ops → worlds → evidence |
| Alignment Map | Phrase-level source maps: source → concept → code |
| Lesson Format | 4-layer (or 5-layer with domain) "no naked syntax" output |
| Visual Worlds | Step-by-step simulations (robot_grid, garden, filesystem) |
| Evidence Portfolio | Observable criteria per concept, not letter grades |
# Import a syllabus
poetica syllabus inspect my_syllabus.txt
poetica syllabus draft my_syllabus.txt --domain robotics --output curriculum.yaml
# Use the curriculum
poetica curriculum inspect curriculum.yaml
poetica curriculum lesson curriculum.yaml input_condition_action --format lesson
# Align with domain provenance
poetica align program.poem --domain robotics --format lesson
# Visual simulation
poetica play program.poem --domain robotics --world robot_grid
Examples
See examples/ for complete programs:
hello.poem— Level 1, pure outputgarden.poem— Level 3, growth and transformationfizzbuzz.poem— Level 2, logic and iterationpipeline.poem— Level 4, external data pipelinedeploy.poem— Level 4, full deployment workflowsensor.poem— Level 2, robotics domainassay.poem— Level 4, microbiology domain
Same program, six languages
name greeter
seed message with "hello world"
emit message
bloom "done"
sonnet (Python):
def greeter():
message = "hello world"
print(message)
return "done"
haiku (Rust):
fn greeter() {
let message = "hello world";
println!("{}", message);
return "done";
}
ballad (JavaScript):
function greeter() {
const message = "hello world";
console.log(message);
return "done";
}
ode (Go):
func greeter() {
message := "hello world"
fmt.Println(message)
return "done"
}
prose (Bash):
greeter() {
message="hello world"
echo "message"
echo "done"
}
verse (SQL):
SET @message = 'hello world';
SELECT "message" AS output;
SELECT 'done' AS result;
License
Apache-2.0
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file poetica-0.1.0.tar.gz.
File metadata
- Download URL: poetica-0.1.0.tar.gz
- Upload date:
- Size: 59.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.10.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d4f431d88fee1091fa8421f44c0c7377b0797eabb7c238036869325753646b5c
|
|
| MD5 |
40c43926e4267ef86194786fcaf128cd
|
|
| BLAKE2b-256 |
b9ac8bf2e7cfc035dbf728bc214718db013b9466f2dbfe8ded40180b3551fdb8
|
File details
Details for the file poetica-0.1.0-py3-none-any.whl.
File metadata
- Download URL: poetica-0.1.0-py3-none-any.whl
- Upload date:
- Size: 53.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.10.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9f3d6f030bb6d7ac5a002ac8c76332189f499f1451666e6cabc7199fa7347459
|
|
| MD5 |
5e335bce94d9564e107da7f52f02efe7
|
|
| BLAKE2b-256 |
492ca3b528979f20e6d4f4e430424073dac29da6c3c8d32b32d9473f1661a7c1
|
