The Spectra Booklet

Spectra is the little language inside AI Glassbox. You write a few near-English lines, press Run, and watch a real machine-learning model load data, learn, and explain itself. This booklet walks you through it one short chapter at a time. Spectra is a bigger language than a first reader expects, so we build it up slowly — each chapter adds one new idea and a snippet you can run as-is.

How to read it: open the Studio in another tab. As you reach each snippet, type or paste a single line at a time (paste is limited to one short line on purpose), press Run, and watch what happens. Nothing here uploads or leaves your browser. A separate, longer curriculum goes deeper into the why; this booklet is the hands-on tour of the language.

Chapters

1. Hello, Spectra
2. Values and names
3. Load data — and look first
4. Tidy and split
5. Your first model: a classifier
6. Predicting numbers: regression
7. Finding groups with no answers
8. The algorithm catalog
9. A brain made of layers
10. Asking questions: if and repeat
11. Building blocks: modules and app
12. Reading the results
13. Safe by design
14. Where to go next

1 · Hello, Spectra

Every language starts with printing something. In Spectra that verb is say. It prints its values with spaces between them, like print in Python.

say "Hello!", 2 + 2, "is four."

Press Run and the Output panel shows Hello! 4 is four. — Spectra did the math for you. A line that starts with # is a comment: a note for humans that Spectra ignores.

2 · Values and names

Spectra has a few kinds of values: numbers (42, 3.5), text in double quotes ("animals"), true/false, a percent like 20% (which just means 0.2), and a list like ["weight", "height"]. You give a value a name with =, then use the name later.

price   = 5
sold    = 12
takings = price * sold
say "I made", takings, "dollars."

A name has to be made before it is used. Some steps hand back more than one value — you can catch them with commas: train, test = split data, hold_out: 20%.

3 · Load data — and look first

Data only ever enters a program one way: load a built-in, made-up dataset. There is no way to upload or paste in a table — that is on purpose (see chapter 13). Once it is loaded, the very first habit of every data scientist is to look at it with describe_data.

data = load "animals"
describe_data data

You will see how many rows there are, the columns, and the range of each one. Try other datasets too: "lemonade_stand", "fruits", "students", "houses", "flowers", "cars", "weather_town", "sayings". You can also draw one column’s shape with plot_distribution data, x: "weight".

4 · Tidy and split

Real data is messy. clean_data tidies it and tells you exactly what it changed. Then comes the single most important trick in machine learning: hold some data back. If you test a model on the same rows it studied, of course it looks smart. split hides a slice so you can test honestly later.

data = load "animals"
clean = clean_data data
train, test = split clean, hold_out: 20%   # keep 20% hidden

Now train is for learning and test is for the honest grade.

5 · Your first model: a classifier

A classifier sorts things into known kinds. You make one, train it on the train set (telling it what to predict and which clues to use), check it on the hidden test set, then ask it about something brand new.

data = load "animals"
clean = clean_data data
train, test = split clean, hold_out: 20%

model = make_model "classifier"
train_model model, on: train, predict: "kind", using: ["weight", "height", "legs"]

check model, with: test
say "My guesser is", accuracy(model), "right."

guess = predict model, weight: 12, height: 30, legs: 4
say "I think this is a", guess

That is a complete, honest pipeline in a dozen lines — every line a step a professional would recognize. check draws a confusion matrix: rows are the real answer, columns the guess, the diagonal is right.

6 · Predicting numbers: regression

When the answer is a number instead of a kind, you want a regressor. It fits a line through the dots so you can predict a value you have never seen.

data = load "lemonade_stand"
model = make_model "regressor"
train_model model, on: data, predict: "cups", using: ["temperature"]

say "On a 30 degree day, about", predict(model, temperature: 30), "cups."
plot_data data, x: "temperature", y: "cups", line: model

The line: part draws the fitted line right over the data. The line-of-best-fit simulation lets you feel why one line is “best.”

7 · Finding groups with no answers

Sometimes nobody tells you the answers and you want the computer to find natural groups by itself. That is unsupervised learning. A clusterer takes no predict: — just the clues and how many groups: to look for.

data = load "fruits"
groups = make_model "clusterer"
train_model groups, on: data, using: ["color_score", "size", "sweetness"], groups: 4
show_model groups

The glassbox view shows each group’s “typical member.” The k-means simulation shows the groups forming step by step.

8 · The algorithm catalog

You pick an algorithm by name in make_model "…". The names are a catalog that keeps growing, so new ideas can arrive without changing the language. Each one comes with its own glassbox view.

Two of these have their own verbs. A "recommender" uses recommend, and a "markov" or "transformer" uses generate:

data = load "sayings"
babbler = make_model "markov"
train_model babbler, on: data, using: "text"   # learns from one text column
generate babbler, count: 4                      # makes up 4 new lines

9 · A brain made of layers

A neural network is layers of little math “neurons.” You build one in a make_network … end block, train it for some rounds: at a speed: (the learning rate), and watch the loss fall.

data = load "fruits"

net = make_network
  layer input  from data
  layer hidden size 16 kind relu
  layer output size 4  kind softmax
end

train_network net, on: data, rounds: 30, speed: 0.1
plot_training net
show_network net

If the curve does not fall, the speed may be wrong — the gradient-descent simulation shows exactly why too-slow crawls and too-fast overshoots.

10 · Asking questions: if and repeat

Spectra can make decisions and do things more than once. Blocks end with end.

if accuracy(model) >= 90%
  say "Great guesser!"
else
  say "Let's train more."
end

repeat 3
  say "again"
end

Repeat counts are capped so a program can never freeze a school laptop.

11 · Building blocks: modules and app

As a project grows, you package each stage as a module (a reusable building block) and wire them together in an app block — the dashboard and starting point. Modules can be defined in any order; Spectra finds them. Each keeps its own private variables.

module prepare(raw)
  clean = clean_data raw
  train, test = split clean, hold_out: 20%
  return train, test
end

module build_guesser(train)
  model = make_model "tree"
  train_model model, on: train, predict: "kind", using: ["weight", "height", "legs"]
  return model
end

app
  data        = load "animals"
  train, test = prepare(data)
  guesser     = build_guesser(train)
  check guesser, with: test
  show_model guesser
end

Beginners do not need an app: with none, the program just runs top to bottom. Modules are the “growing-up” structure once a project has more than one stage.

12 · Reading the results

Training is only half the job — the other half is reading what came back. After a check you can pull a single number, see which clues mattered, or line models up against each other.

check model, with: test
say "Right:", accuracy(model)      # for a classifier
say "Off by:", error(model)        # for a regressor
importance model                    # which clue mattered most (a bar each)
# train a second model the same way, then:
compare model, model2               # a scoreboard; stars the best

The big idea: a model is not magic, it is a set of numbers you are allowed to inspect. Every show_model opens that glass box.

13 · Safe by design

Much of Spectra’s safety is not a setting — it is what was deliberately left out. There is no network command, so your code cannot reach the internet. There is no way to upload or type in a dataset; data only comes from built-in synthetic sources. Randomness is seeded, so a saved project reproduces exactly and a teacher sees the same result as a student. Nothing you make here ever leaves your browser. The About & Safety page tells the whole story.

14 · Where to go next

• Open the Studio and load an example from the menu — each one is fully commented with its goal and how to read the result.
• Play the Simulations to feel an idea before you code it.
• Browse the Gallery to see what other learners built, then build and deploy your own.

That is the whole language. It is small on purpose — small enough to hold in your head, real enough to do honest machine learning. Happy building.