README.md

# Gemma-GLM v1.0 — Geometric Language Machine

**The deterministic brain for any LLM. Zero trainable parameters.**

A single-file LLM-GLM hybrid that combines probabilistic language model fluency
with exact mathematical grounding from the Golay [24,12,8] code, Leech lattice Λ₂₄,
and the Universal Binary Principle (UBP).

---

## Quick Start

```bash
# Verify everything works
python3 gemma_glm.py --test

# Interactive REPL
python3 gemma_glm.py

# With a local LLM (Gemma, LLaMA, etc.)
python3 gemma_glm.py --api http://localhost:8080
```

**No pip installs needed.** Python ≥ 3.10, stdlib only.

---

## What It Does

| Feature | How |
|---------|-----|
| **Block hallucinations** | CRG semantic graph (114 concepts) vetoes irrelevant tokens |
| **Exact math** | `fractions.Fraction` — muon ratio 0.029% error, α_s 0.27% error |
| **Write & run Python** | Sandboxed execution with AST analysis and quality scoring |
| **Process images** | 4×6 MOG patch grid → Golay snap → visual coherence (NRCI) |
| **Grow its own knowledge** | Dynamic CRG infers unknown words, flags as ⚡speculative |
| **Drop into any LLM** | One-line `LogitsProcessor` for HuggingFace models |
| **Self-assembling geometry** | Every token gets a geometric profile from its prime factorization |

---

## File Structure

```
gemma-glm/
├── gemma_glm.py           # Full system (1,866 lines) — start here
├── ubp_unified_v5.py      # UBP engine (3,447 lines) — Golay, Leech, physics
├── value_geometry.py       # ValueGeometry (1,477 lines) — integer geometry
├── llm_glm/               # Modular library (same code, organized by topic)
│   ├── __init__.py
│   ├── vector_engine.py    # 24-bit Golay substrate, SVD vocab, NRCI
│   ├── resonance.py        # Geometric resonance scoring
│   ├── hard_veto.py        # CRG-first constraint masking
│   ├── vision.py           # Visual NRCI, dual-modality resonance
│   ├── real_vision.py      # Real image processing (ViT/CLIP → Golay)
│   ├── math_engine.py      # Exact rational arithmetic
│   ├── script_engine.py    # Python code sandbox + AST analysis
│   ├── dynamic_crg.py      # Self-growing knowledge graph
│   ├── hf_logits_processor.py  # HuggingFace LogitsProcessor
│   ├── kv_pruner.py        # CRG-based attention cache pruning
│   ├── speculative.py      # GLM draft → LLM verify
│   ├── pipeline.py         # System 1/2 loop
│   └── vg_integration.py   # ValueGeometry integration
├── README.md               # This file
└── MOBILE_INSTALL.md       # Phone/tablet installation guide
```

---

## Usage

### Interactive REPL

```bash
python3 gemma_glm.py

> /muon
  m_μ/m_e = 206.7075  (target: 206.7683, err: 0.0294% [PREDICTIVE])

> /alpha_s
  α_s = 0.117778  (target: 0.1181, err: 0.2723%)

> /profile photon
  Token:    photon
  Grid:     square
  ω (dim):  3
  NRCI:     0.6470
  Lattice:  HW-14

> /veto boson kitchen protagonist
  PASS boson            pass
  PASS kitchen          pass
  VETO protagonist      CRG dist 7>6

> /code from fractions import Fraction
  print(Fraction(1,3) + Fraction(1,6))
  Output: 1/2

> what is the muon mass ratio
  The muon/electron mass ratio is 206.7075
```

### Command Line

```bash
python3 gemma_glm.py --profile photon         # ValueGeometry profile
python3 gemma_glm.py --math "169 / 0.8176"    # Exact math
python3 gemma_glm.py --code "print(42)"        # Sandbox execution
python3 gemma_glm.py --pipeline "explain energy"  # System 1/2 loop
python3 gemma_glm.py --draft 5                 # Speculative draft
```

### HuggingFace Model (one line)

```python
from llm_glm.hf_logits_processor import create_glm_processor

processor = create_glm_processor(tokenizer=tokenizer, bias_strength=1.0)
outputs = model.generate(input_ids, logits_processor=[processor])
```

### Python Sandbox

```python
from llm_glm.script_engine import run_code, validate_code

r = run_code("from fractions import Fraction\nprint(Fraction(1,3))")
print(r.stdout)  # "1/3"

v = validate_code(open("my_script.py").read())
print(v["verdict"])  # "EXCELLENT"
print(v["nrci_score"])  # 0.80
```

### Exact Physics Math

```python
from llm_glm.math_engine import MathEngine

math = MathEngine()
r = math.muon_ratio()
print(r.approx)  # 206.7075
print(r.fingerprint["target_error_pct"])  # 0.0294
print(r.fingerprint["verdict"])  # "PREDICTIVE"
```

---

## The 13 Sections of gemma_glm.py

| § | Component | What It Does |
|---|-----------|-------------|
| 1 | UBP Substrate | Golay [24,12,8] with 2325-entry syndrome table, Leech Λ₂₄, exact constants |
| 2 | Vector Engine | 24-bit substrate, SVD vocabulary, IdeaZone centroid |
| 3 | CRG | 114-concept knowledge graph, self-growing, persists to disk |
| 4 | Math Engine | Exact rational arithmetic, UBP physics formulas |
| 5 | Script Engine | Python sandbox, AST analysis, NRCI quality scoring |
| 6 | Vision Pipeline | MOG patches, visual NRCI, dual-modality resonance |
| 7 | Resonance & Veto | Multi-signal scoring, CRG-first constraints |
| 8 | LogitsProcessor | Drop-in for HuggingFace models |
| 9 | Pipeline | System 1/2 loop (LLM proposes → GLM verifies) |
| 10 | Speculative | GLM draft → LLM verify (instant, no forward pass) |
| 11 | KV Pruning | CRG-based attention cache relevance |
| 12 | ValueGeometry | Self-assembling integer geometry from factorization |
| 13 | Agent | Interactive REPL with all commands |

---

## Key Numbers

| Metric | Value |
|--------|-------|
| Self-test | 18/18 pass |
| Math accuracy | muon/e 0.029%, α_s 0.27%, H₀ 0.21% |
| Hallucination block | 100% (CRG distance > 6) |
| Physics pass | 100% (boson, electron, etc.) |
| Sandbox safety | 4/4 dangerous imports blocked |
| Vision NRCI gap | 0.0811 (crisp vs noisy) |
| CRG taxonomy | 114 static concepts |
| Pipeline latency | < 1ms |
| File size | ~48 KB (gemma_glm.py only) |

---

## Mobile Installation

See `MOBILE_INSTALL.md` for Termux (Android), Pythonista (iOS), iSH, and more.

TL;DR: Copy `gemma_glm.py` to your phone. Run `python3 gemma_glm.py`. Done.

---

## Connecting to a Local LLM

```bash
# llama.cpp
./server -m gemma-2b.gguf --port 8080
python3 gemma_glm.py --api http://localhost:8080/v1/completions

# Ollama
ollama run gemma:2b
python3 gemma_glm.py --api http://localhost:11434/api/generate
```

---

## How It Works

```
You type → GLM processes → zone updated → CRG checks
                                              ↓
                            ┌─────────────────────────────┐
                            │  Is the word in the CRG?    │
                            │  Yes → check distance       │
                            │  No  → infer + flag ⚡spec   │
                            └──────────────┬──────────────┘
                                           ↓
                            ┌─────────────────────────────┐
                            │  Veto: CRG dist > 6? → BLOCK│
                            │  Veto: d_H > 14?    → BLOCK │
                            │  Veto: NRCI < 0.58? → BLOCK │
                            └──────────────┬──────────────┘
                                           ↓
                            ┌─────────────────────────────┐
                            │  Resonance score candidate   │
                            │  proximity + NRCI + grid     │
                            └──────────────┬──────────────┘
                                           ↓
                            Output or LLM call (if --api)
```

The CRG grows each session. Unknown words get inferred from context
and flagged as ⚡speculative until seen 3+ times. It persists to
`~/.gemma_glm_crg.json`.