Apply @GPU to narrate(), remove dead ingest(), expand README

README.md

@@ -22,8 +22,29 @@ tags:
 
 A leaderboard that judges AI coding operators by **architecture, not budget**.
 Paste your token usage; get an operator profile with a tiny-model narration and
-your rank. The sort metric **Υ = (Cache·Output)/Input²** penalizes raw-input
-padding quadratically — volume can't buy rank.
+your rank. The ranking metric **Υ = (Cache·Output)/Input²** penalizes raw-input
+padding quadratically — volume can't buy rank — but Υ is only the headline of a
+larger metric system whose mathematical thesis is the **cascade decomposition**.
+
+## Origin
+SigRank grew out of an earlier attempt to rank AI coding operators by *words* —
+measuring commitment, output quality, and reuse through language rather than
+numbers. That work produced a **conservation law of commitment**: the insight
+that compounding architectures leave a measurable signature regardless of the
+instrument used to observe them.
+
+When token-level data became available via ccusage, the word-based framework
+translated directly: commitment → `cache_create/output`, reuse → `cache_read/cache_create`,
+transmission → `output/input`. The cascade identity `(O/I)×(C_w/O)×(C_r/C_w) = C_r/I`
+is the token-domain expression of the same conservation law.
+
+*[Full theoretical lineage — placeholder for extended write-up]*
+
+### Academic work & references
+<!-- TODO: add links to the word-based ranking / conservation-law write-up,
+     any preprints, talks, or external references here. -->
+- *[Conservation law of commitment — link placeholder]*
+- *[Word-based operator ranking — link placeholder]*
 
 ## What it does
 Paste `npx ccusage@latest --json` (Claude Code), `ccusage codex --json` (Codex),
@@ -37,6 +58,68 @@ or four numbers →
 narrates the operator read. It is **non-blocking**: if unavailable, a deterministic
 template is used and the app still works. Everything quantitative is pure computation.
 
+## The full metric system
+Υ is the *ranking* metric. The *mathematical thesis* is the cascade decomposition
+of leverage into three behavioral stages — Υ is what you sort by, the cascade is
+what explains *why* an operator lands where it does.
+
+### The cascade as a diagnostic
+Leverage `C_r/I` is not a single number; it factors into three compounding stages:
+
+```
+(O/I)  ×  (C_w/O)   ×  (C_r/C_w)   =   C_r/I
+ │          │            │               │
+transmission commitment  compounding   leverage
+ generate    commit to   reuse what
+ output      cache        was cached
+```
+
+`10x DEV` is the **log₁₀** of that product — the amplification *exponent*. By
+telescoping, `10^(10x DEV) = leverage = C_r/I`. The cascade tells you which stage
+an operator is winning or losing on, not just the bottom line.
+
+### Operator archetypes (`classify()` in `app.py`)
+Velocity (`O/I`) and leverage (`C_r/I`) place each operator in a behavioral class:
+
+| archetype | signature |
+|---|---|
+| **Closed-Loop Kinetic** | holds both axes — velocity ≥ 1 *and* leverage ≥ 100 |
+| **Archival Sponge** | high reuse, low generation — leverage ≥ 10, velocity < 1 |
+| **Volatile Ingestor** | generates, doesn't retain — velocity ≥ 0.8, leverage < 2 |
+| **Transient** | low on both axes |
+| **Non-Compounding** | stateless pipe — no `cache_create`, so the cascade can't form |
+
+### Scale (V) — the volume axis
+**V = log₁₀(total tokens)** measures how much volume an operator moves. Scale and
+amplification are *independent* axes: a huge operator can have Υ ≈ 0, and a small
+one can have high Υ. That independence is what produces the species map below.
+
+### Species / quadrants (`species_cards.md`)
+Plot **Scale (V)** against **Amplification (Υ)** and operators sort into four
+species by *which term of the math dominates* — not by who is "better":
+
+```
+              high amplification
+                     │
+   CASCADE (stacks)  │   (— rare / empty —)
+   low scale ◄───────┼───────► high scale
+   CONVERTER (I→O)   │   THROUGHPUT (volume)
+   CACHE ARCHITECT   │   (reuse)
+                     │
+              low amplification
+```
+
+| species | dominant term | signature |
+|---|---|---|
+| **Throughput** | raw volume | enormous total, Υ≈0 — scale without compounding |
+| **Converter** | transmission `O/I` | high velocity, low leverage |
+| **Cache Architect** | reuse `C/I` | high leverage, low velocity |
+| **Cascade** | all three compound | low scale, high amplification |
+
+MO§ES occupies the **empty quadrant** — low scale, high amplification. The claim
+is *not* "top of a ladder"; it's that this region of the token economy is empty,
+and the geometry of `(C·O)/I²` is what makes it empty.
+
 ## How the numbers work
 Four raw integers — `input`, `output`, `cache_create`, `cache_read` — drive all:
 
@@ -54,6 +137,20 @@ Four raw integers — `input`, `output`, `cache_create`, `cache_read` — drive
 Cascade (10x DEV) = transmission (O/I) × commitment (Create/O) × compounding
 (Read/Create); its log-sum is the exponent. By telescoping, 10^X = Leverage = C/I.
 
+## Benchmark convergence
+SigRank's finding is corroborated by a second, independent instrument.
+
+- **Artificial Analysis (AA)** benchmarks measure *models* at a **7:2:1**
+  (cache : input : output) token mix.
+- **SigRank** measures *operators / users* from their own token logs.
+- Both instruments converge on the same result: **cache-dominant architecture is
+  the most efficient AND the cheapest per token.**
+
+The AA **7:2:1** ratio is the source of the **4.0 efficiency baseline** used in
+the Efficiency metric: `(7 + 1) / 2 = 4.0`. Two independent instruments — model
+benchmarks on one side, real user token ledgers on the other — landing on the
+same architecture is the validation.
+
 ## Codex support
 Codex reports a *combined* input figure (fresh + cached) and never itemizes cache
 writes. SigRank splits it with the measured field anchor **input:output ≈ 2:1**
@@ -88,4 +185,6 @@ cheapest per token, by an order of magnitude.
   (Landauer, Ohmic dissipation); log Υ = X + log(Velocity). An analogy, not a
   microscopic-entropy derivation.
 
-Built for the HF/Gradio Build Small Hackathon · Thousand Token Wood 🍄 · MO§ES™
+Built for the HF/Gradio Build Small Hackathon · Thousand Token Wood 🍄 · MO§ES™ —
+SigRank began as a word-based ranking of AI operators and a conservation law of
+commitment, then translated into token-domain measurement.

SCRATCHPAD.md

@@ -40,6 +40,23 @@ cd /Users/dericmchenry/Desktop/moses-sigrank
 
 ## WORK LOG (newest first)
 
+### Devin session — 2026-06-15
+- [done] GPU FIX — applied `@GPU` decorator to `narrate()` in narrate.py (line 60).
+  ZeroGPU needs the inference function decorated or GPU alloc never happens and the
+  model silently template-falls-back every call. `_try_load()` intentionally NOT
+  decorated. No-op fallback path verified (no torch → template, import OK).
+- [done] DEAD-CODE FIX — removed unused `ingest()` from ingest.py (old lines 103-112).
+  Only `ingest_meta()` is called (app.py, sigrank.py). `ingest_meta()` unchanged.
+- [done] README rewrite — kept YAML front matter + all math/formulas/SEED identical.
+  Added Origin (word-based ranking → conservation law of commitment → token domain,
+  with academic-links placeholder), "The full metric system" (cascade diagnostic,
+  4 archetypes from classify(), Scale V, species/quadrant framing — MO§ES = empty
+  quadrant not a ladder), "Benchmark convergence" (AA 7:2:1 → 4.0 baseline = (7+1)/2,
+  two-instrument validation). Restructured so Υ is the ranking metric within the
+  broader system. Demo/Social placeholders untouched. Footer updated with origin.
+- [done] Verify green: compile OK · `python3 metrics.py` → MO§ES Y 18436.98, lev
+  2042.2, 10xDEV 3.31, $/1M 0.527 (unchanged).
+
 ### Claude/Opus session — 2026-06-15
 - [done] Verified baseline green (compile + canonical metrics print correct).
 - [done] FIX 6 — confirmed board CSS grid = 8 tracks, matches 8 header cells (theme.py:58). No code change needed; visual eyeball still owner's call.

ingest.py

@@ -100,17 +100,6 @@ def parse_codex(text):
             "cost": tot["cost"] if tot["cost"] > 0 else None}
     return I, O, create, read, meta
 
-def ingest(text):
-    """Returns (i,o,cw,cr)."""
-    text=text.strip()
-    if not text: raise ValueError("empty")
-    if text[0] in "{[":
-        d=json.loads(text)
-        if is_codex_shape(d):
-            i,o,cw,cr,_m = parse_codex(d); return i,o,cw,cr
-        i,o,cw,cr,_c = parse_ccusage(text); return i,o,cw,cr
-    return parse_four(text)
-
 def ingest_meta(text):
     """Returns (i,o,cw,cr,meta) with estimated/caveat/cost."""
     text=text.strip()

narrate.py

@@ -57,6 +57,7 @@ def _template(name, m, klass):
                 f"converting input to output efficiently.")
     return f"**{klass}.** {body}"
 
+@GPU
 def narrate(name, m, klass):
     if not _try_load():
         return _template(name, m, klass)