Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,91 @@
+---
+license: mit
+base_model: Qwen/Qwen2.5-Coder-7B-Instruct
+tags:
+  - riscv
+  - cross-attention
+  - flamingo
+  - grounded
+  - code-generation
+  - rv32i
+library_name: transformers
+pipeline_tag: text-generation
+---
+
+# Reflex-Coder7B-RISCV
+
+**A frozen `Qwen2.5-Coder-7B-Instruct` wired to a RISC-V CPU through Flamingo-style cross-attention. Emits one 32-bit RV32I instruction per cycle, conditioned on live machine state. No text tokens generated at inference.**
+
+This repo contains the **adapter weights only** (~4.2 GB fp32). The frozen backbone is pulled from `Qwen/Qwen2.5-Coder-7B-Instruct` at runtime. Total inference memory: ~18 GB bf16 backbone + 4.2 GB fp32 adapters + activations.
+
+## What it does
+
+Given a natural-language prompt (`"say hi"`, `"multiply 7 and 8"`, `"compute 5 factorial"`), Reflex drives a Unicorn-backed RV32I emulator instruction by instruction. Each cycle:
+
+1. Read live CPU state (32 registers, PC, memory windows around PC and SP).
+2. Encode as 65 K/V tokens.
+3. Run the frozen backbone forward over the prompt, cross-attn adapters fuse state K/V into hidden states at depths 4, 8, 12, 16, 20, 24.
+4. Last-token pool → MLP → 32 bit sigmoid heads → one 32-bit RV32I instruction word.
+5. Write the word at PC in Unicorn, step one cycle, loop.
+
+## Base model
+
+[`Qwen/Qwen2.5-Coder-7B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) — frozen, bf16, untouched.
+
+## Training
+
+- **Corpus**: 80,396 (prompt, program) pairs across 56 RV32I program families (arithmetic, loops, comparisons, memory ops, display writes). Every program verified by running it end-to-end through Unicorn before training.
+- **Flattened cycle pool**: ~1.06M `(state, next_instruction)` pairs. Balanced-subsampled to 173k across families per epoch.
+- **Objective**: per-bit binary cross-entropy over the 32 instruction bits, with `rs2` bits (positions 20–24) weighted 5× to overcome the register/immediate polysemy ceiling.
+- **Optimizer**: standard AdamW, cosine LR schedule `1e-4 → 1e-6` over 20k steps, batch 64.
+- **Hardware**: A100 80GB.
+
+## Results (18-task eval + 15-task sweep)
+
+- **13 / 15 on a mixed zero-shot sweep** (see README), including six tasks the model was never trained on: multiply-by-repeated-add, power, abs, min, popcount, say-arbitrary-3-char-strings.
+- **popcount(255) = 8 in 199 correct consecutive RISC-V instructions** — an emergent algorithm derived at inference from the frozen backbone's prior on what "popcount" means.
+- Full eval script: `uv run eval --checkpoint reflex_coder7b.pt`.
+
+## Usage
+
+```python
+import torch
+from reflex.demo import load, run_grounded
+
+model, tok, cfg = load("reflex_coder7b.pt", device="cuda")
+cpu, emitted, halted, err = run_grounded(
+    model, tok, "multiply 7 and 8", device="cuda", max_cycles=200,
+)
+print(f"halted={halted}  mem[0x5000]={cpu.mem_word(0x5000)}")
+# halted=True  mem[0x5000]=56
+```
+
+Or, interactively:
+
+```bash
+uv run demo --checkpoint reflex_coder7b.pt
+```
+
+## Installation
+
+```bash
+git clone https://github.com/ilbertt/reflex
+cd reflex
+uv sync
+# Download this checkpoint into the repo root:
+huggingface-cli download ilbertt/reflex-coder7b-riscv reflex_coder7b.pt --local-dir .
+```
+
+The first time you run inference, HuggingFace will automatically fetch the frozen `Qwen2.5-Coder-7B-Instruct` backbone (~15 GB).
+
+## Limitations
+
+- **rs2 precision ceiling.** Per-cycle rs2 accuracy ~0.99; long loops (>50 ops) can emit a single-bit-wrong instruction that crashes the program before it stores its result.
+- **No domain-knowledge transfer.** Reflex only knows the program-shaped phrasings in its training corpus. Prompts like `"if x5 is fever, display SICK"` fail — the adapters were never taught to route the backbone's semantic knowledge of "fever" through.
+- **Display strings degrade past 3 characters.** `say hi`, `say 42`, `say wow` all land cleanly; `say hello` returns `hell`.
+- **Some common phrasings are unreliable.** `add 100 and 200 and store the result` can return `100` instead of `300`. `subtract 10 from 25` sometimes returns `35` (semantic confusion on the word "from").
+- **RV32I base ISA only** — no M (multiply/divide), no Zbb (count/bitmanip), no F (float). The model synthesizes all "higher" operations from base instructions.
+
+## Files
+
+- `reflex_coder7b.pt` — adapter weights, state encoder, head, and config dict (backbone_id, hidden, inject_every, adapter_mlp_ratio, max_instr_tokens, chat_template, context_prefix).