# Oracle7 Workbench

A local page for your copy of Oracle7. It shows the model as a diagram, lights the path each answer takes, and lets you
add to the model: readers of your computer, servers, files and MCP tools, and specialists you write and examine yourself.

```bash
python oracle7.py --workbench          # opens http://127.0.0.1:8177/ in your browser
python oracle7.py --workbench 8200     # another port
```

It runs on the same CPU-only install as the model. The server listens on 127.0.0.1 only and sends nothing anywhere,
except to services you connect yourself (an SSH server, an MCP server, a sensor, ElevenLabs) and the optional Solana check. Type `/help` or ask
"what can you do?" in the chat for a guide to every feature and command.

## From a terminal

Everything that makes sense in a terminal works there too, with the same code, so a terminal answer is the page's answer:

```bash
python oracle7.py ask "Who directed Jaws?"            # the answer, its status and the path it took
python oracle7.py ask "..." --json                     # machine-readable
python oracle7.py chat                                 # a conversation; /path, /new, /help, /quit
python oracle7.py specialists moons                    # find specialists, with held-out scores
python oracle7.py card astronomy-v3                    # one specialist's card
python oracle7.py verify --chain                       # this install against RELEASE_HASHES.json and the Solana anchor
python oracle7.py example && python oracle7.py exam habitable-zone dev
python oracle7.py new beekeeping hive bees honey       # scaffold your own specialist
python oracle7.py build "q1" "q2" "q3"                # build a specialist from example questions (the swarm)
python oracle7.py compose --file examples.txt          # compose one from worked examples (the code composer)
python oracle7.py memory                               # your group's shared specialist memory (export / import)
python oracle7.py sensor-ideal garden-node "soil moisture" 25 35   # the ideal band the baseline reader measures against
python oracle7.py scan                                 # read this computer
python oracle7.py sensor-test http http://192.168.1.40/data
python oracle7.py sensors                              # read every connected sensor once
python oracle7.py history                              # saved conversations
python oracle7.py registry habitable-zone               # its on-chain registration and attestations
python oracle7.py help                                 # all of it
```

## The layout

The layout has three panes, plus a Conversations panel you can open and collapse:

- **Far left (the button at the top): Conversations.** Every conversation is kept on this computer. Open one and carry on:
  the core picks up its context, so "when was he born?" still means the person you were talking about. You can rename,
  search or delete conversations, or switch keeping off. "Make specialist" turns a conversation into a temporary specialist
  (7 days unless you choose) that answers "what did we say earlier about…?" by quoting the earlier answer with its date
  and route. The Workbench also answers "what did I ask first?" and "what did you just say?" from the conversation itself.
- **Left: the conversation.** The diagram of the whole model sits above it. Each answer lights the stages and modules it
  passed through. When Oracle7 declines, the answer says why.
- **Top right: the workspace,** in tabs: Start, Specialists, Sensors, Systems, Build, Gaps, Code, Film, Share.
- **Bottom right: the live log** of every turn, route, exam and change.

## Start: point it at something of yours

| | What it reads | Ask it |
|---|---|---|
| **Scan this computer** | system, CPU, memory, disks, uptime, the processes using the most memory (figures and process names only, never your files) | "How much disk space is free on my computer?" |
| **Connect a server** | over SSH with your own key, a fixed list of read-only commands: hostname, uptime, load, memory, disks, top processes, failed services | "How much memory is web server using?" |
| **Add files** | tables (.csv, .tsv) and text (.txt, .md), copied into the reader's own folder | "What is the price of honey?" · "What do my notes say about the boiler?" |
| **Connect an MCP server** | the tools of any MCP server, by command (stdio) or URL | "Count the words in 'the quick brown fox'" |
| **Connect a sensor** | an HTTP device or hub (JSON or Prometheus metrics), an MQTT topic, a USB/serial device, a log file, or a simulated garden node | "What is the soil moisture on garden node?" · "Show my sensor readings" |

Each becomes a reader whose answers name exactly where the value came from:
- the system call;
- the command;
- the file with its row and column, or line;
- the tool with the arguments it was sent.

Before a reader joins your model it passes an automatic check:
- it reads its own source back correctly;
- it declines general questions;
- it takes at most 9 of the 924 published general questions;
- it leaves identity questions alone;
- it answers within its time budget.

**MCP specialists adapt.** A tool specialist routes each question to the tool whose name, description and learned words
match it. It fills the tool's arguments from the question, or says which argument is missing. Mark its answers right or
wrong:
- A right mark teaches the tool the question's words.
- A wrong mark counts against the tool. After three wrongs, if wrongs outnumber rights, the tool is no longer used.

Every mark re-runs the check. Bad lessons therefore take the specialist out of your model rather than widen what it
answers.

## Sensors

Connect a sensor from Start or the Sensors tab:
- **Test** reads it once and lists the numbers it found, with a guess at what each measures: temperature, humidity, soil
  moisture, pressure, CO2, light, PM2.5, voltage, battery, wind, rain, power, energy, water level, or a name you give.
- **Add** polls it in the background (every 30 s unless you choose) and keeps 24 hours of readings in
  `workbench/local/sensors/`.

The Sensors tab shows each sensor's newest values with a 24-hour line.

Every answer gives:
- the value and its unit;
- how old the reading is, and says so if the sensor seems offline;
- whether it was measured or simulated;
- its source, down to the field;
- min, max and mean for the day, and the last hour's trend, when you ask for them.

A value outside the physical range of its quantity (412 °C for air, 140% humidity) is rejected. The answer says which
reading was rejected and why, and uses the last valid one.

| Connection | Address | Notes |
|---|---|---|
| HTTP | `http://192.168.1.40/data` | JSON (any nesting) or Prometheus text metrics; ESP32, Shelly, Tasmota, Home Assistant, weather stations |
| MQTT | `broker:1883/garden/node1` | read-only subscribe, MQTT 3.1.1; JSON or a plain number per message |
| USB / serial | `COM3@9600` or `/dev/ttyUSB0@9600` | lines like `temp=21.4 hum=40`, `21.4,40` or JSON; needs `pip install pyserial` on Windows and macOS |
| Log file | `C:\logs\garden.csv` | the newest line of a CSV (with header), JSON-lines or key=value log |
| Simulated | none | a made-up garden node for trying it; every answer says SIMULATED |

### Is it normal? The baseline reader (4.2)

Readings are also kept as 15-minute medians for 30 days. Import past readings with
`python oracle7.py sensor-history <id> <file.csv>`: a time column, plus one column per quantity.

Set the ideal band for a quantity with `sensor-ideal <id> <quantity> <low> <high>`. Then ask "Is the soil moisture on
garden node normal?" or "Is anything odd with the water level on river gauge?". The answer gives three things:

- **The ideal band.** How far the newest reading is from it, if one is set.
- **Its own normal.** How far the reading is from the channel's normal, which is learned from its history. Every test
  uses the channel's own typical change at that test's time scale (a local residual, an 8-hour change, a 48-hour change),
  so a tidal river or a daily temperature cycle is normal rather than an alarm.
- **Fluctuations in the last 3 days.** Each named: a **spike**; a **step** (the level jumps and holds); a **drift**
  (the level walks away slowly); **stuck** (the same value for longer than the history ever held still); a **dropout**
  (readings missing for hours); an **oscillation** (swinging back and forth around the level).

**Suspect the sensor first.** Declare two quantities physically coupled with `sensor-pair <id> <a> <b>`, for example a
stream's water level and its flow. The reader then fits their relationship on the history:

- **If it holds:** a change in one channel that breaks it is a probable sensor fault, and a change both channels make
  together is a probable real change.
- **If it does not hold** (a tidal reach, a backwater): it says it cannot tell. So does a single channel, because one
  channel cannot tell a slow sensor drift from the weather.

The reader reports what it measured and never acts on it. It was tested on public USGS stream records, with faults
injected at positions sealed before it ran. This is release test PI42b, on four sites it had never seen:

| | Result |
|---|---|
| injected faults caught | 91% (60 of 66) |
| typed right | 90% on coupled pairs, 78% on single channels |
| on coupled pairs | 90% of sensor faults called sensor faults (43 of 48); all 16 real changes called real |
| false flags | 0.34 per channel-day (about one every three days on each channel) |

The first 4.2 candidate failed its release test (PI42): on pairs it called 77% of sensor faults sensor faults, and the
bar was 80%. It judged a fault at the moment the flagged channel moved most, and that moment could fall on a natural rise
both channels shared. The reader now judges a fault where the pair's relationship departs most from its earlier level.
On one earlier sealed set this version still calls only 77% of sensor faults and 75% of real changes correctly, so pair
calls vary from site to site. Every run is published, including the failures.

Known limit: while one channel of a pair is stuck, the pair's relationship breaks for both. The stuck channel is named
correctly, but changes on the other channel during that time can also be called sensor faults. (4.5 tried a rule for this;
it failed its sealed test and showed no measured benefit, so it is not used.)

**How reliable is it here? (4.5)** Every baseline reply now ends with the reader's record on that channel. It injects
faults of each kind (spike, step, drift, stuck, dropout, oscillation) one at a time into a copy of the channel's own
readings, at sizes set by the channel's own normal, and reports how many it caught. In release test PI45 (part E, four new
USGS sites), the channels reported catching 97.5% on their own records, and the reader caught 95% of the faults injected
into the test. On four earlier sealed sets the reports ran about 7 points above what was measured, so treat the figure as
an upper bound. In the same test, false sensor accusations ran at 0.08 per channel-day, and the reader called 12 of 16
real changes real, under the 80% bar: that part of the test failed and is published.

## Build: write a specialist and examine it

"New specialist" makes a folder you edit in the page:
- `manifest.json`: what it takes and its sources;
- an organ: rules, tables or computation, no language model;
- `panel.json`: dev items and held-out items;
- `scorer.py`.

"Add the worked example" installs a complete one built from a single published paper: the habitable zone of a star (Kopparapu et al. 2013), from its temperature and luminosity, declining stars outside the range the formulas were fitted on.

- **Dev exam:** run it as often as you like.
- **Held-out exam:** run it once. Its items are hashed and logged, and the same held-out set is refused a second time.

A specialist joins your model only if all of these hold on its held-out items:

1. **Domain:** with it, your model gets at least max(3, 2% of n) more right than without it.
2. **No false yes:** it answers no more must-decline items than the core alone.
3. **Few wrong:** at most max(1, 2% of n) answered wrong.
4. **Stays in lane:** it would take at most max(5, 1%) of 924 general questions.
5. **Self:** identity questions stay the core's.
6. **Budget:** median reply time within its budget.

This is the same idea as the gate that admitted the release's own specialists, made portable. An admitted specialist
appears on the diagram's Specialists ring. It answers only where the core declined for lack of a reading. It never
replaces an answer the core gave, and it never answers where a check stopped the core (false premise, private question,
changed sign). If you change one of its files, it leaves your model until it passes a new held-out set.

### Let it build the specialist

**From example questions** ("Ask the swarm", or `build`). Write 3 to 6 questions the specialist should answer:

```bash
python oracle7.py build "What is the vertical depth of Lake Baikal?" "What is the vertical depth of Crater Lake?" "What is the vertical depth of Loch Ness?"
```

1. Every installed specialist is asked about your examples. Their replies are read as answered, declined or recognised. A
   7% nudge to each number checks which ones a specialist really uses.
2. The swarm writes a brief: a typed hole (the givens you supply, the thing you ask for), the neighbouring specialists, the
   named gap and the sources.
3. If the specialists you have already cover it, nothing is built and you are told which ones do. Medical dosing, legal
   advice and private people's details are refused outright.
4. For a table of named things, the builder finds the property on Wikidata (CC0), downloads the table, and records the
   download's hash in `local/swarm/sources`. It writes the specialist with an exam split by entity, then checks it on the
   dev half.
5. You run its held-out exam once, like any other specialist.

**From worked examples** ("Compose", or `compose`). For a calculation, name the inputs and the output with their units, then
give 8 or more worked examples:

```
title: Current through a resistor
inputs: voltage (V), resistance (ohm)
output: current (A)
12, 6 -> 2
9, 3 -> 3
...
```

```bash
python oracle7.py compose --file workbench/examples/compose/current_through_a_resistor.txt
```

Half the examples go to the **code composer**; the other half become the held-out exam, which the composer never sees.

The composer writes the program from typed moves:
- arithmetic, powers, roots and logarithms;
- constants with a cited definition and a unit;
- the numbers inside a code such as `205/55R16`;
- cited cycles (weekdays, months, the zodiac) and numeral tables (Roman, binary, octal, hexadecimal);
- at most two fitted constants, which are reported as fitted.

**Units are types.** A sum needs both sides in the same unit, and a program with no fitted constant must come out in the
output's unit. A fitted program must reproduce your examples to the precision you gave them.

The program is written in Python and JavaScript, with arguments named after your inputs (`compute(voltage, resistance)`).
It is run in a separate interpreter against your examples (read-back). It declines, and names the gap, when your examples
are not a function of their inputs or no program within its bounds reproduces them.

The specialist it makes:
- answers the output asked with every input given;
- declines when an input you name has no value;
- declines a value of a sign your examples never had, rather than extrapolate;
- (4.5) declines an input that breaks an ordering every one of your examples kept, between the two numbers of one code or
  two inputs with the same named unit ("120/80": systolic above diastolic), and an input the quantity cannot have (a day of
  2025 past 365, a temperature below absolute zero, a fraction of a tooth), and says which rule and why.

**What you admit becomes a building block (4.5).** The composer now uses programs already admitted as single moves: the
release's 20 composed specialists, and every program you composed and then passed on its held-out exam. A long calculation
can then be found as a short combination of parts that were each checked. Compose "kelvin from Fahrenheit" and it calls the
admitted Fahrenheit-to-Celsius program, then adds 273.15. The program it writes spells every call out in full, so it still
reads back in a separate interpreter on its own.

Measured on a sealed curriculum of ten finance tasks in four rounds, each round needing what the earlier ones admitted (PI45
part D-b): with the library, 6 of 6 deep tasks composed and right on every held-out example; without it, 0 of 6. The last
one, total interest paid on a loan, is a 25-node program found by a search of 5 moves; without a library the composer reaches
11. The first version of that test (part D) failed because its labels gave the interest rate no unit per year, so units as
types refused 1 + r/n; it is published with the rerun.

On two pre-registered sealed lists the composer wrote programs for 12 of 12 and 11 of 12 tasks. Version 2 (units as types)
got all 11 of its programs right on held-out examples, and declined every task with no program
(`specbuild/RESULTS_composer.md` in the source repository).

### Shared memory: what other groups already built (4.2)

When a specialist you built or composed passes its held-out exam, it is written to your group's memory. The memory records
the request it answered (what the questions ask for, and what they give) and the specialist that answered it.

**On the Tree of Life spine.** The memory is ten holographic vectors, one per Sephirah:

- a request is filed under the node where its operation lives (Hod computes, Binah relates);
- an exact key is filed evenly by its hash;
- routes are read back by the Tree's whole-walk decoder.

In the release test (PI42), the memory held 128 routes from 4.0's own release tests and recalled 98% of them exactly.
For routes it had never seen, the Tree decoder read 77%, against 35% for plain cleanup of the same size. A recall takes
about 2 ms on a CPU.

Share it, and import other groups' memories:

```bash
python oracle7.py memory                          # your group's entries
python oracle7.py memory export mygroup.json      # the shareable ones, each with its chain hash
python oracle7.py memory import theirgroup.json   # every entry's hash is checked before it is accepted
```

Before building or composing, the Workbench recalls from your **commons** (your memory plus the ones you imported). If
another group already built and examined a specialist for the same request, even worded differently, you are told which
one and where it came from, so you can import it and run its exam here rather than build it again. Add `--anyway` to build
regardless.

A recall is a suggestion, never an answer. In release test PI42b, 11 of 12 sealed request families recalled the
specialist another group had built, from questions worded differently. None of the 10 control requests recalled anything,
and several of them were near misses (a lake's area against its depth, a dog's weight against its lifespan). The median
recall took 1.8 ms. The miss was alcohol by volume asked as "How strong is a cider that went from 1.050 to 1.000?". The
first 4.2 candidate recalled 7 of 12 (PI42): it did not read questions written as fragments ("Pace for a speed of 14
km/h?") or the acronyms of what they asked for ("mean arterial pressure" is "MAP"). Version 2 reads both.

## Gaps: the model tells you what it is missing

Turn on the gap journal and every question you ask, answered or not, is kept in `workbench/local/journal.jsonl`, on
this machine only. Declines are grouped by why they happened and by the words they share. "Start a specialist" turns a
group into a new specialist whose first dev items are your own questions. That is the loop by which your copy improves:
- declines show what is missing;
- you, or tools you trust, write a specialist;
- the exam decides whether it joins.

Nothing joins without passing.

## Code

The code organ hands over only programs it has run. It writes and proves functions from a fixed set:
- a small website;
- palindromes, factorials, vowel and word counts, word frequencies;
- HTTP routes, regular-expression extraction, memoisation;
- a bank-account class, matrix multiplication, fizzbuzz, fibonacci;
- string reversal, a JSON round-trip, concurrent work;
- binary search, tower of hanoi, quicksort, list sums, prime tests;
- a number-guessing game and tic tac toe.

It declines anything else. The bench runs any code against your own tests, in a separate Python process with a
10-second limit.

## Film

Record answers as a video (1280×720 .webm, made in your browser).
- The left of the frame shows the diagram tracing each path.
- The right shows the question, the answer and the path step by step.

Every new answer is ticked; untick any to leave it out. "Film this" under an answer records just that one. Keep the tab
in front while it records: if you switch away, recording pauses and picks up where it stopped.

You can optionally connect your own ElevenLabs account. This is the only feature that sends content to a third party:
the narration text, the sound description and the image prompts. It can:
- narrate each answer in a voice you pick;
- lay a sound you describe underneath;
- open each answer with a generated illustration. This uses Gemini 2.5 Flash Image or GPT Image 1 through the ElevenLabs
  Image & Video API, which needs their Pro plan. The film labels these images as generated.

The key stays in the page unless you tick "remember on this computer".

## Verify

Specialists > Verify this install (or `/verify`) recomputes the SHA-256 of every shipped part and rebuilds the Merkle root
published in `RELEASE_HASHES.json`. The parts are all 307 specialist folders, the admitted fold chain, the workbench, the
launcher and the store manifest. A changed or missing specialist is listed by name.

"Check the anchor on Solana" then reads the release's anchor transaction from a public Solana RPC. This is read-only and
the only network call Verify makes. It confirms the memo carries the same root.

## The $ORACLE7 registry: one specialist, one $ORACLE7

A specialist you built and examined becomes **verified on-chain** when you register it (Share > Register on Solana, or
`python oracle7.py registry-memo <id> register`). Registering is one Solana transaction, signed in your own wallet (Phantom),
that does two things together:
- it **burns exactly 1 $ORACLE7** from your wallet (mint `DU7Lhe2QtcRBJdor7KbpjfUDmLyA2kdhR49Li3czpump`);
- it records the specialist's fingerprint in a memo: the SHA-256 of its files, of its held-out exam verdict and of its
  held-out set, and the release it was examined on.

Before your wallet is asked, the Workbench simulates the exact transaction on Solana and stops if it would fail (for example a
balance under 1 $ORACLE7). Anyone who imports the specialist and sees it pass its held-out exam on their own machine can
**Attest** for free.

**Check on Solana** (or `python oracle7.py registry <id>`) reads every registration and attestation back from the chain and
confirms each one:
- that the memo matches the specialist's files as they are now;
- that a registration burned 1 $ORACLE7, signed by the same wallet.

It shows each signer and how much $ORACLE7 they hold. The records live in the specialist's `registry.json` and travel with
it when shared. The Workbench never sees a key. The only token that moves is that one burn, which you approve in your
wallet. The public Solana RPC refuses browser pages, so the page's few read calls go through the local Workbench server.

## Share

Share packages an admitted specialist for the community registry: its folder, its exam verdict and the SHA-256 of every
file. Upload it with your own Hugging Face account using the command it prints. To import a shared specialist, give the
path of its .zip:
- every hash is checked;
- its verdict is set aside;
- it joins your model only after it passes its held-out exam on your machine.

Readers of your computer, servers and files are never packaged.

## What comes with it

**267 specialists.** Each was admitted by a held-out exam it saw once. The Specialists tab lists every one with its
held-out score against the core alone and its card. The 23 failed exams are published.

| Group | Count | Examples |
|---|---:|---|
| Relation readers | 161 | moons, directors, novels, painters, composers, airports, battles, bridges: each reads one family of Wikidata relations and names the record |
| Earth & life | 26 | geology, hydrology, soil, ecology, botany, medicine, genetics, meteorology |
| Everyday | 22 | warehouse, cold chain, cooking, first aid, fleet, retail, wiring, woodworking |
| Physical science | 21 | acoustics, chemistry, densities, decay, energy, optics, thermo, units |
| Humanities | 16 | law, grammar, literature, music, economics, world history |
| Computing | 10 | python, javascript, sql, git, linux, networking, data formats |
| Space | 6 | astronomy, orbits, planetary, spacecraft, space comms |
| Mathematics | 5 | calculus, geometry, statistics, logic, algorithms |

**Five systems built the same way.** Each is its own repository in the release, with no language model, a receipt for
every decision, and held-out results run once.

| System | What it does | Measured |
|---|---|---|
| **DeepSpace** | fault response for deep-space spacecraft, from telemetry to admissible response | 98.9% on 1,700 fresh single faults, 0 harmful (baseline 29.4%) |
| **Trafficcop** | a decision service: one choice from a set of options, with a receipt, or abstain | 30/32 held-out routes; about 0.1 ms a decision |
| **Chameleon** | builds websites and components; done only when contracts written in advance pass in a browser | 0 false completions on held-out repositories |
| **Vision** | sees with no trained weights; cites the stored examples behind every answer | MNIST 98.58%, Fashion-MNIST 90.46%, CIFAR-10 62.99% |
| **Artist** | images by citation: every object is a real photographed instance, cited | GenEval-style 50.9% on 2,212 images (independent judge) |

## Essays: ProseFold

```bash
python oracle7.py essay "volcano"
python oracle7.py essay "volcano" --voice my_writing.md
```

`essay` writes a few paragraphs about a topic from this model's own cited answers, with no language model. It asks the
model the questions a writer would (what it is, how it works, where it is used, its history), keeps only the sentences
that came back with a record id, and arranges them. ProseFold chooses the arrangement: where sentences join with "and" or
a semicolon, where a short sentence stands alone, where "it" replaces the subject. It searches those choices for the voice
closest to a target text (by default Prometheus7's essay *The Slow Fire*; `--voice` takes any text of yours) on four
measures a composition can change: comma rhythm, sentence-length spread, longest sentence and short "snap" sentences.

What it does not do: change a word of what the record says, add a connective the record does not support, or write about
anything the model has no record of. Every sentence keeps its source numbers, and every composed sentence is checked to
carry the content words of its sources and nothing else (the output says how many passed). On the full release the
topic's own page is read in order; slim works from the model's answers only, so its essays are shorter.

Measured on 20 topics: 205 of 205 composed sentences faithful to their sources, a planted word change caught 20 of 20
times, and the fold closer to the target voice than random legal choices on all 20. Whether the essays read well has not
been measured: that needs blind human scoring, which has not been done.

## Commands

```
/help                         every feature and command
/scan                         read this computer
/connect user@host [port] [key]   read a server over SSH
/files                        add files
/mcp                          connect an MCP server
/sensors                      connect and watch sensors
/verify                       check this install against the published hashes
/history                      open or close the conversations panel
/new-chat                     start a new conversation
/remember [days]              keep this conversation as a temporary specialist
/new <id> [words]             a new specialist
/exam <id> dev|heldout        run an exam
/specialists <word>           find a specialist
/systems                      the five systems
/gaps on|off                  the gap journal
/code <what it does>          compose a function
/film                         film the answers
/share <id>                   package a specialist
/clear                        clear the conversation
```

## Files

```
workbench/server.py     the local server (standard library only)
workbench/exam.py       the exam and the source-reader check
workbench/sources.py    scan, server, files readers
workbench/mcp.py        MCP client and the adaptive tool specialist
workbench/sensors.py    sensor connections, polling, physical-range checks and the sensor reader
workbench/verify.py     release hashes, Merkle root and the Solana anchor check
workbench/template/     what "New specialist" copies
workbench/examples/     the worked example
workbench/data/         the specialist list, cards, the five systems, the core panel
workbench/static/       the page (three.js r128 and the fonts are bundled; SIL Open Font Licence)
workbench/local/        YOURS: specialists, conversations, sensor readings, journal, settings, outbox. Never shipped,
                        never uploaded, never hashed.
```