SPIRAL — Architecture & Dataflow

Spiral System
Organization & Dataflow

Closed-loop GPU-saturation render daemons. A deliberate council + executive architecture with strong guardrails after the 2026-06-10 runaway load audit.

Fundamental Split — read this first

◉ Steering Layer (this repo)

Analysis, proposals, decisions, steering parameters.
Never loads FLUX or renders pixels.

~/spiral → agents, core, orchestration, ops

◉ Render Workers (quivent/render)

The actual FLUX inference daemons. Drain the queue and execute jobs using parameters supplied by this layer.

render/ui/inference/spiral/{worker,saturator}.py

Runtime Services (systemd --user)

spiral-head — executive closer

spiral-controller — real-time governor

spiral-mathematician

spiral-cartographer

spiral-evaluator

spiral-gemma — vision + LLM

spiral-overnight — runner (manual)

spiral-refill / guardian / reaper

Worker & saturator run from the render repo (documented contract).

Code Layout (Python package)

spiral/
  core/      — crew, convergence, crewcfg, modules
  agents/   — head, integrator, gemma_eval, translator, …
  orchestration/ — controller, runner
  observability/
  ops/      — *.sh (refill, guardian…)
  systemd/ — units
*.json   — live shared state (SPIRAL_ROOT contract)

The Decision Organization

Council of specialists + Conservative executive + Guardrails

Every CPU agent (and Gemma) is a proposer. Nothing in the crew directly touches the workers or control surface. The integrator applies. The head is the single closer of the loop and owner of enqueue.

Runtime Hierarchy (proposal → decision → action)

Top Authority

Director (human standing orders in director.json) — can completely override Gemma

Council

The Crew — uniform proposer contract (core/crew.py)

mathematician

cartographer

evaluator

researcher

wrangler

physicist

gemma_eval + translator

overseer

All do heartbeat() + propose() to decisions.jsonl + crew/*.status.
“The integrator decides whether a proposal is applied.” — core/crew.py

decisions.jsonl (blackboard) + beat.json + gemma_verdict.json

Executive

integrator — the main consumer

“It is the ONLY crew member that WRITES control.json. … The head still owns enqueue.”

head — per-experiment LEAD (spiral-head.service)

“The per-experiment LEAD that closes the loop the crew left open: it SYNTHESIZES… APPLIES… ENQUEUES the next render… this IS the autonomous system self-driving.”

controller — real-time closed-loop on calibration.json (speed_gain, amp_strength…)

overseer — flounder / abandon / reseed / cursor authority

EXECUTION BOUNDARY → other repo

Model-manager API (:8188) → queue/ → worker.py (FLUX) + saturator → done/*.json + sheets

Primary Dataflow (one render cycle)

Render Cycle ← feedback loop

━ Gemma path ━ Execution path ┈ Proposal / blackboard

HUMAN / TOP OVERRIDE

director.json (standing orders) — highest priority, bypasses Gemma

CREW SPECIALISTS

mathematician
gaps + learned surface

cartographer
fire/gain maps

evaluator
accept/reject + ratings

gemma_eval
vision judgment → gemma_verdict.json

wrangler / physicist / researcher

overseer

PROPOSE

decisions.jsonl + beat.json (coordination heartbeat) + gemma_verdict.json

APPLY (bounded)

integrator
Conservative writer to control.json. Small steps, clamps, learned corrections, degeneracy guards.

head (the closer)
Synthesizes all signals • decides move • enqueues via model-manager • advances experiment • publishes beat

controller (independent loop) — reads CPU/GPU metrics → nudges calibration.json (speed_gain, flutter, etc.)

ENQUEUE

Model Manager :8188 → queue/*.json → worker.py + saturator.py (other repo)
Renders with current control/globals/calibration baked in. Writes done/ + contact sheets.

Feedback: new done/*.json + metrics + sheets → crew re-measures (convergence.measure_8) → new proposals

GEMMA PATH (highlighted above)

gemma_eval (spiral-gemma.service) looks at contact sheets with llama-server:8080 (OpenAI /v1/chat/completions + images). Produces beauty / intent_match / verdict. Writes gemma_verdict.json.

translator (“Gemma’s hand”) reads the verdict, asks Gemma to translate English judgment into concrete lever moves, applies learned effect corrections, then writes directly to control.json.

Still flows through the same council → head coordination. Director can veto entirely. Graceful degradation when vision is unavailable.

GEMMA_URL
(default :8080)
vision + language only

Key self-descriptions from the source

“Every crew member … is a lightweight CPU loop that: heartbeat… propose… The integrator decides whether a proposal is applied.”
— core/crew.py

“The per-experiment LEAD that closes the loop the crew left open: it SYNTHESIZES the crew’s decisions + the convergence state, APPLIES the next operator move, ENQUEUES the next render (this IS the autonomous system self-driving — the intelligent head, not a dumb runner blindly feeding).”
— agents/head.py

“The mathematician/cartographer/evaluator/gemma all PROPOSE moves into decisions.jsonl but NOTHING applied them… This worker is the missing consumer… It is the ONLY crew member that WRITES control.json. … The head still owns enqueue.”
— agents/integrator.py

“Reads experiments.json (the program) and drives each experiment IN SEQUENCE to convergence… It is the SOLE task dispenser + pipeline-keeper for the night.”
— orchestration/runner.py (overnight mode)

Why this shape exists

The architecture is a direct reaction to the 2026-06-10 system audit: "uncoordinated producers + multiple restart authorities + an in-process governor, with no shared arbiter or convergence stop."

✓ One primary closer (head)

✓ Proposals → blackboard (not direct control)

✓ Centralized cursor authority (flock + pin)

✓ Conservative application + learned surfaces

✓ Explicit live mode vs overnight mode

✓ RAM / restart / saturation / reaper guardrails on every unit

✓ Director + overseer override channels

How to explore right now

python -m spiral status

services + queue + prompt + convergence snapshot

python -m spiral monitor --watch 2

live dashboard (wraps observability/monitor.py)

python -m spiral.agents.head

run the executive (usually via systemd)

ls -l ~/spiral/*.json | head

the live shared memory (control, experiments, learned_surface…)

tail -f ~/spiral/decisions.jsonl

watch the proposal bus in real time

Generated for internal clarity • matches comfort-ui design language (aurora, glass, Space Grotesk, Inter, JetBrains Mono, status semantics)