README.md

<p align="center">
  <img src="PAMPAR-coder.png" alt="PAMPAr-Coder" width="200" />
</p>

<h1 align="center">PAMPAr-Coder</h1>

<p align="center">
  <strong>Pure reasoning engine</strong> — 62.6M params, local-first, on-device RAG.
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-BUSL--1.1-blue" alt="License" /></a>
  <a href="https://doi.org/10.57967/hf/8329"><img src="https://img.shields.io/badge/DOI-10.57967%2Fhf%2F8329-blue" alt="DOI" /></a>
  <img src="https://img.shields.io/badge/params-62.6M-green" alt="Params" />
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python" />
  <img src="https://img.shields.io/badge/pytorch-2.x-orange" alt="PyTorch" />
</p>

---

## What is PAMPAr-Coder

PAMPAr-Coder is a 62.6M parameter language model that **reasons over reference information** rather than memorizing answers. It works like a physicist: it understands the fundamental axioms and can derive solutions for any domain using documentation available on the device.

- **Weights**: reasoning capability (read docs, understand problems, derive solutions step-by-step)
- **Device**: knowledge via local RAG (Python docs, MDN, man pages, user files)
- **Hardware**: designed to run on consumer hardware (GTX 1650, 4 GB VRAM)

**Current state**: `v3_train.pt` — 98K steps, Mixed Selectivity (FiLM). Ablation study running on RTX 3090 (4 experiments × 30K steps). Paper published on [Academia.edu](https://www.academia.edu/works/165626856) — DOI: [10.57967/hf/8329](https://doi.org/10.57967/hf/8329).

---

## 2D Architecture (PamparV3)

```
tok_emb [48K x 640]
  -> TalamoInicial (LLAVES 80% + attn_proj 20% + context_conv)
      -> terr_acts [B, L, 4]  /  zona_acts [B, L, 52]
  -> 4 parallel streams (dim=640)

  NivelProfundo x5:
    1. Shared GQA Attention (8 Q heads / 2 KV heads, head_dim=80)
    2. Lightweight Thalamus re-routing
    3. 4 x independent StreamFFN SwiGLU
    4. Lateral gates per stream (bottleneck=128)

  -> norm_f (RMSNorm) -> lm_head (weight-tied, vocab=48K)
```

### The 4 Streams

| Stream         | Brodmann Zones | Processes                         |
| -------------- | -------------- | --------------------------------- |
| **SYNTAX**     | B01-B15        | Keywords, operators, punctuation  |
| **SEMANTICS**  | B16-B30        | Types, variables, literals        |
| **LOGIC**      | B31-B42        | Control flow, conditionals, loops |
| **STRUCTURAL** | B43-B52        | Blocks, indentation, scope        |

### Parameters

| Parameter        | Value       |
| ---------------- | ----------- |
| `dim`            | 640         |
| `n_streams`      | 4           |
| `n_levels`       | 5           |
| `n_heads`        | 8           |
| `n_kv_heads`     | 2 (GQA 4:1) |
| `vocab_size`     | 48,000      |
| `max_seq_len`    | 4096        |
| **Total params** | **62.6M**   |

---

## Key Innovations

### LLAVES System (TalamoInicial)

- **80% explicit rules**: routing based on code patterns (INT8, pre-computed)
- **20% learned attention**: fine-tuning for ambiguous cases
- Produces `terr_acts` and `zona_acts` with zero inference overhead

### 2D Cortical Architecture

- **4 streams × 5 levels** = grid where rows specialize and columns refine
- **GQA 4:1**: lower VRAM, same quality
- **Lateral gates** (bottleneck 128): cross-stream communication like white-matter fibers
- **Re-routing** per level: the Thalamus adapts which stream leads based on accumulated context

### On-Device RAG

The model uses the machine where it's installed as its knowledge source:

- Scanner detects OS, packages, available files
- RAGResidual indexes local documentation (FAISS + sentence-transformers)
- The model reasons over references, it doesn't memorize content

---

## Classroom — Conversational Mentor + Bio-Mechanisms

A learning system where a mentor model (Qwen-plus via DashScope) teaches PamparV3 through dynamic conversations, like a tutor in a chat. The mentor generates unique explanations, examples, and exercises for each lesson — the student absorbs knowledge via gradient descent.

### Lesson Flow

```
1. StudentProfile selects adaptive concept (21 concepts with prerequisites)
2. Mentor generates lesson: explanation + example + exercise + solution
3. Phase A — Absorb: train on explanation + example (all tokens)
4. Phase B — Practice: student attempts the exercise
5. Phase C — Correct: mentor evaluates, train on correct solution + replay
6. Update student profile (mastery per concept)
```

### Concept Tree (CONCEPT_TREE)

21 concepts organized in 5 levels with prerequisites:

| Level | Concepts                                                              |
| ----- | --------------------------------------------------------------------- |
| 1     | arithmetic → variables_types → conditionals, strings, functions_basic |
| 2     | loops_for → loops_while, lists → tuples_sets, dicts                   |
| 3     | recursion, higher_order, generators, error_handling                   |
| 4     | classes_basic → inheritance, dunder_methods                           |
| 5     | decorators, context_managers, algorithms, file_io                     |

`StudentProfile` tracks mastery per concept and selects adaptively:

- Prioritizes concepts with attempts but not yet mastered (reinforcement)
- Then new concepts whose prerequisites are met
- Finally spaced review of mastered concepts

### Core Mechanisms

| Mechanism                              | Purpose                                                           |
| -------------------------------------- | ----------------------------------------------------------------- |
| **EWC** (Elastic Weight Consolidation) | Protects important weights — penalizes changes to critical params |
| **Replay Buffer**                      | Mixes new and previous examples (simulates sleep consolidation)   |
| **Differential LR**                    | LLAVES/Thalamus 0.01×, attention 0.1×, embedding 0.1×, FFN 1.0×   |
| **Conversational Absorption**          | Trains on mentor explanations + examples (knowledge distillation) |

### Bio-Mechanisms (`bio_mechanisms.py`)

5 mechanisms based on real neuroscience, integrated as post-lesson hooks:

| Mechanism               | Biological Inspiration    | Implementation                                                                         |
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------- |
| **Neuromodulation**     | Dopamine + Norepinephrine | Dynamically modulates LR based on success/error (×0.3 to ×3.0)                         |
| **LTP**                 | Long-term potentiation    | Strengthens `LateralGate.scale` of streams with consistent high activation (Hebb rule) |
| **Sleep Consolidation** | REM + SWS phases          | Periodic replay (every 15 lessons): random (REM) + sorted by difficulty (SWS)          |
| **Neurogenesis**        | New hippocampal neurons   | Injects LoRA adapters (rank=8, ~10K params) into StreamFFN when loss > 4.0             |
| **Synaptic Pruning**    | Synaptic pruning (~50%)   | Reduces `LateralGate.scale < 0.03` every 30 lessons (decay ×0.5)                       |

All coordinated by `BioOrchestrator.after_lesson()`. Can be disabled with `--no-bio`.

### Mentor Pilot Results (5 lessons)

- Absorption loss: ~7-8 (new content from mentor)
- Exercise loss decreasing: 5.89 → 5.44 → 4.40 → 3.94 → 4.38
- Brain score stable: 88.24% (prior knowledge preservation)
- EWC penalty growing: 0.000002 → 0.000044 (active regularization)
- Each lesson is UNIQUE — mentor generates dynamically, no repetition

### Usage

```bash
# Conversational mentor with Qwen-plus (recommended)
python scripts/classroom_server.py \
  --checkpoint checkpoints/v3_train.pt \
  --checkpoint-out checkpoints/v3_classroom_mentor.pt \
  --teacher qwen --model qwen-plus \
  --max-lessons 200 --lr 1e-5 --ewc-lambda 50 --no-bio --no-ui

# With bio-inspired mechanisms enabled
python scripts/classroom_server.py \
  --checkpoint checkpoints/v3_train.pt \
  --teacher qwen --model qwen-plus \
  --max-lessons 200 --lr 1e-5

# With web interface (SSE + dashboard)
python scripts/classroom_server.py \
  --checkpoint checkpoints/v3_train.pt \
  --teacher qwen --port 8787

# With GitHub Models API (alternative)
python scripts/classroom_server.py \
  --checkpoint checkpoints/v3_train.pt \
  --teacher github --model gpt-4o-mini

# Replay a recorded session
# Open sessions/classroom_*.html in browser
```

---

## Subsystems

| Module        | Components                  | Purpose                                                                                         |
| ------------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
| **Model**     | `pampar/coder/v3/`          | PamparV3: forward, generate, routing, blocks                                                    |
| **Memory**    | `pampar/memoria/`           | ClasificadorPareto (L0-L3), RAGResidual (FAISS), ColaFinetune                                   |
| **Runtime**   | `pampar/runtime/`           | Agent (orchestrator), Scanner (device), BootProtocol                                            |
| **Skills**    | `pampar/skills/`            | LectorArchivos (30+ ext), EjecutorCodigo (subprocess)                                           |
| **Inference** | `pampar/inference.py`       | JSON-lines stdin/stdout server for VS Code                                                      |
| **Classroom** | `scripts/classroom*.py`     | Conversational mentor: engine + teacher + curriculum + training + events + memory + persistence |
| **Bio-Mech**  | `scripts/bio_mechanisms.py` | 5 neuroscience mechanisms: Neuromod, LTP, Sleep, Neurogenesis, Pruning                          |

---

## Installation

```bash
git clone https://github.com/lucasmella-stack/PAMPAr-Coder.git
cd PAMPAr-Coder
pip install -r requirements.txt
```

---

## Usage

### Instantiate the model

```python
from pampar.coder.v3 import PamparV3, PRESET_V3
import torch

model = PamparV3(PRESET_V3)
model.eval()

# Forward pass
ids = torch.randint(0, 48_000, (1, 64))
with torch.no_grad():
    logits, loss, info = model(ids)

# Autoregressive generation
gen = model.generate(ids, max_tokens=100, temperature=0.8, top_k=50)
```

### Use the Agent (with RAG + Skills)

```python
from pampar.runtime import Agente

agent = Agente(
    checkpoint="checkpoints/v3_train.pt",
    workspace_root=".",
)
response = agent.responder("how to read a CSV with pandas?")
```

---

## Project Structure

```
PAMPAr-Coder/
├── pampar/
│   ├── coder/v3/              # Active architecture (62.6M)
│   │   ├── modelo.py          # PamparV3 — forward, generate
│   │   ├── config.py          # ConfigV3 + presets
│   │   ├── talamo.py          # TalamoInicial — routing
│   │   ├── bloques.py         # GQA, SwiGLU, LateralGate, NivelProfundo
│   │   ├── llaves.py          # LlavesV2 — INT8 lookup
│   │   ├── zonas.py           # 52 Brodmann Zones
│   │   ├── ghidra_probe.py    # Read-only instrumentation
│   │   └── engrama_stream.py  # Activation memory
│   ├── memoria/
│   │   ├── clasificador.py    # ClasificadorPareto (L0-L3)
│   │   ├── rag.py             # RAGResidual (FAISS + TF-IDF fallback)
│   │   └── cola_finetune.py   # ColaFinetune (auto-SFT buffer)
│   ├── skills/
│   │   ├── lector_archivos.py # File reader (sandboxed)
│   │   └── ejecutar_codigo.py # Code executor (subprocess)
│   ├── runtime/
│   │   ├── agente.py          # Main orchestrator
│   │   ├── scanner.py         # Device inspection
│   │   └── boot.py            # Boot sequence
│   └── inference.py           # JSON-lines server for VS Code
├── scripts/
│   ├── classroom.py           # ClassroomEngine (~600 lines)
│   ├── classroom_curriculum.py# CONCEPT_TREE (21 concepts) + StudentProfile
│   ├── classroom_teacher.py   # Mentor API (GitHub/OpenRouter/Qwen)
│   ├── classroom_training.py  # Tokenization + differential LR + train_step
│   ├── classroom_events.py    # Console event formatting
│   ├── classroom_memory.py    # EWC + ReplayBuffer + compute_ewc_baseline
│   ├── classroom_persistence.py # Checkpoint + session + HTML recording save
│   ├── classroom_server.py    # HTTP SSE server + CLI (entry point)
│   └── bio_mechanisms.py      # 5 bio mechanisms
├── data/tokenizer/
│   └── pampar_48k.model       # 48K bilingual vocab (active)
├── checkpoints/               # Model checkpoints (gitignored)
├── tests/                     # pytest test suite
└── _archive/                  # Pre-refactoring backups
```

---

## Understanding the Loss

| Loss  | Meaning               |
| ----- | --------------------- |
| ~10.7 | Untrained (log 48000) |
| 7-8   | Random weights        |
| 5-7   | Beginning to learn    |
| 2-4   | Active learning       |
| 1.5-2 | Optimal zone          |
| < 1.5 | Topic well learned    |
| < 0.7 | Topic mastered        |

---

## Tests

```bash
python -m pytest tests/ -v
```

142 tests, all passing.

---

## Philosophy

> _"You don't need 72 billion parameters. You need the right architecture and the right axioms."_

1. **Reasoning > memorization** — the model learns to use references, not to memorize
2. **The device is the knowledge base** — local RAG, not cloud
3. **Code is structured** — 4 specialized streams + LLAVES 80% rules
4. **Consumer hardware** — 1.4 GB VRAM for fp16 training

---

## Roadmap

- [x] Territorial architecture (52 Brodmann zones, 4 streams × 5 levels)
- [x] LLAVES system (INT8 routing, 80% rules)
- [x] BPE 48K bilingual tokenizer (ES + code)
- [x] GQA 4:1, SwiGLU, lateral gates
- [x] Memory module (ClasificadorPareto, RAG, ColaFinetune)
- [x] Skills (LectorArchivos, EjecutorCodigo)
- [x] Runtime.Agent (tool-use loop)
- [x] GhidraProbe (read-only diagnostics)
- [x] EngramaStream (activation memory)
- [x] Bio-inspired Classroom (EWC, replay buffer, differential LR, curriculum)
- [x] HTML session recording and replay
- [x] GitHub Models API integration (gpt-4o-mini as teacher)
- [x] Bio-mechanisms: Neuromodulation, LTP, Sleep Consolidation, Neurogenesis, Synaptic Pruning
- [x] Conversational mentor: Qwen-plus generates dynamic lessons as tutor
- [x] CONCEPT_TREE: 21 concepts with adaptive prerequisites
- [x] StudentProfile: per-concept mastery tracking
- [x] Loss masking: -100 on prompt tokens (train only on responses)
- [x] Conversational absorption: train on mentor explanations + examples
- [ ] Multimodal: image/diagram input support
- [ ] Training data expansion (textbook + SFT multi-language)
- [ ] KV cache in generate()
- [ ] Multi-language execution (JS, Rust, Bash)
- [ ] Benchmarks against reference models
- [ ] VS Code extension

---

## License

BUSL-1.1 — Copyright (c) 2024-2026 Lucas Ricardo Mella Chillemi

Change Date: April 7, 2030 — License converts to Apache-2.0. See [LICENSE](LICENSE) for details.