T-RSI Fast Reflex OCR Engine (psikosen/t-rsi-ocr)

Ultra-Lightweight, Sub-Millisecond BitNet 1.58-Bit Autonomous Document Reader Core

⚠️ EXPERIMENTAL RESEARCH RELEASE — PRELIMINARY BENCHMARK NOTICE

• Verification Advisory: This is an experimental research model. Do not trust benchmark results until independently verified by a secondary source.
• Evaluation Environment & Origin: Evaluated on an Apple Silicon M-Series (128GB Unified RAM) testbench.
• Replication Requirement: Requires additional independent benchmarks across expanded document callsets prior to production deployment.

T-RSI Fast Reflex OCR is a machine-native optical character recognition engine engineered for extreme memory efficiency, microsecond-level latency, and multiplication-free digital agent execution.

---

Key Performance Metrics

• Peak RAM Footprint: ~494 KB (sub-megabyte runtime memory).
• Decision Latency: 1.9 ms (sub-millisecond to low-millisecond character reflex).
• Arithmetic: Pure integer additions and subtractions (zero floating-point multiplications).
• Storage Size:
  • model.safetensors: 590 KB (standard Hugging Face Safetensors format).
  • weights_packed_1.58bit.bin: 80 KB (2-bit packed binary representation: 4 ternary weights per byte).
• Architecture: 1.58-bit Ternary BitNet Transformer + Visual Scanline Patch Tokenizer + Greedy CTC Decoder.

---

Architectural Pillars

1. Visual Scanline Patch Tokenizer: Slices 2D document text lines into $32 \times 8$ scanline patches and projects them to 128-dimensional latent vectors via ternary BitLinear layers.
2. Multiplication-Free BitNet Transformer: 2 layers of multi-head self-attention and FFN utilizing ternary weights $W \in {-1, 0, +1}$ and AbsMax 8-bit activation quantization.
3. Causal Memory Graph: Stores character mistake pairs and verified template hashes for instant recovery.
4. Packed 2-Bit Binary Representation: Allows deploying the complete OCR model to microcontrollers, embedded runtimes, or WebAssembly (WASM).

---

Repository Files & Model Weights

• model.safetensors: Quantized 1.58-bit ternary tensor weights ({-1, 0, +1}) in standard Hugging Face Safetensors format.
• weights_packed_1.58bit.bin: 2-bit packed binary representation (80 KB, 4 ternary weights per byte).
• config.json: Model hyperparameters, BitNet quantization schema, and evaluation hardware metadata.
• vocab.json & tokenizer.json: Vocabulary mapping for 256 OCR tokens, special tokens, and ASCII characters.
• engine.py: Standalone, multiplication-free execution engine.
• model_architecture.py: PyTorch architecture with Straight-Through Estimator (STE) ternary quantization.
• train_bitnet_ocr.py: Training and weight export pipeline.
• live_interactive_test.py: Live interactive runner with on-screen HUD telemetry and CLI REPL.
• packing_utils.py: 2-bit packing and unpacking utilities.

---

Quickstart

from PIL import Image
from engine import FastReflexOCREngine

# 1. Load model weights and config directly from Hugging Face Hub or local path
engine = FastReflexOCREngine.from_pretrained("psikosen/t-rsi-ocr")

# 2. Execute multiplication-free OCR inference
image = Image.open("sample_images/simple_invoice.png")
text, latency_us, ram_kb = engine.recognize(image)

print(f"Recognized: '{text}' in {latency_us:.1f} µs (Peak RAM: {ram_kb:.1f} KB)")

---

Live Interactive Test & REPL

# 1. Run 5-part autonomous OCR benchmark mission with HUD telemetry
python3 live_interactive_test.py --benchmark

# 2. Recognize custom text rendered on-the-fly
python3 live_interactive_test.py --text "TOTAL: $49.99"

# 3. Recognize an image file
python3 live_interactive_test.py --image path/to/image.png

# 4. Launch interactive terminal decision shell
python3 live_interactive_test.py --interactive

---

Training and Weight Export

To fine-tune or train the BitNet OCR model:

python3 train_bitnet_ocr.py

Outputs updated model.safetensors and weights_packed_1.58bit.bin.