# PAMPAr — Repository Guidelines

> **PAMPAr** = Procesador Autónomo Modular de Patrones y Razonamiento
> Para AI agents: Claude Code, Codex, Gemini CLI, GitHub Copilot.

---

## Visión

PAMPAr es un **motor de razonamiento puro** de 108M parámetros. No memoriza respuestas — aprende a **pensar con información de referencia**.

La analogía: un físico que entiende termodinámica puede resolver problemas de química, ingeniería o biología. No memorizó cada campo — tiene los axiomas correctos.

- Los **pesos** (108M params) contienen la capacidad de **razonar**: leer documentación, entender un problema, derivar una solución step-by-step.
- El **dispositivo** (PC, móvil, servidor) provee el **conocimiento**: docs de Python, MDN, man pages, archivos del usuario — vía RAG local.
- El modelo no necesita "saber Python". Necesita saber **usar la referencia que tiene disponible** para resolver cualquier problema.

**Objetivo**: un modelo local que razona con la misma metodología que los mejores modelos, usando la información del dispositivo como RAG.

---

## Estado actual

- **Modelo activo**: `PamparV3` — **108.3M params**, vocab 48K, 4 streams × 5 niveles
- **Mejor checkpoint**: `v3_ghidra_v9.pt` — Routing Score 89, eval 6/16 (38%)
- **Tokenizer**: `data/tokenizer/pampar_48k.model` (48K, bilingüe ES+código)
- **Runtime**: Agente + RAGResidual + Scanner + BootProtocol — funcional
- **Classroom**: Mentor conversacional con Qwen-plus — lecciones dinámicas, 21 conceptos adaptativos, absorción + práctica + corrección
- **Bio-Mechanisms**: Neuromodulación, LTP, Sleep Consolidation, Neurogenesis, Synaptic Pruning — `bio_mechanisms.py`
- **Teacher API**: Qwen-plus via DashScope (principal), GitHub Models gpt-4o-mini (alternativa)
- **Training data**: `master_sft.jsonl` — 1,253 ejemplos (en expansión vía Classroom)

---

## Quick Reference

| Area       | Convention                                             |
| ---------- | ------------------------------------------------------ |
| Language   | Python 3.13+                                           |
| Framework  | PyTorch 2.6+                                           |
| Tokenizer  | SentencePiece BPE — **48K** (`pampar_48k.model`)       |
| Type hints | Always required                                        |
| Docstrings | Google style                                           |
| Training   | Local GTX 1650 (4 GB) + RunPod A100 para fases pesadas |
| Budget     | $300-500 USD total                                     |

---

## Arquitectura — PamparV3

### Grilla 2D: 4 streams × 5 niveles

```
tok_emb [48K × 640]
  → TalamoInicial → terr_acts [B, L, 4]  /  zona_acts [B, L, 52]
  → 4 streams paralelos (dim=640)

Cada NivelProfundo (×5):
  1. GQA Atención compartida (8 Q heads / 2 KV heads, head_dim=80)
  2. Re-routing ligero del Tálamo (Linear dim→52, sin bias)
  3. 4 × StreamFFN SwiGLU independientes (uno por stream)
  4. Lateral gates por stream (bottleneck=128, fibras blancas)

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

### Streams ↔ Capas lingüísticas

| Stream | Territorio  | Zonas   | Especialización                           | Capa lingüística |
| ------ | ----------- | ------- | ----------------------------------------- | ---------------- |
| 0      | SINTAXIS    | B01-B15 | Keywords, delimitadores, puntuación       | Sintaxis         |
| 1      | SEMANTICA   | B16-B30 | Variables, tipos, literales               | Semántica        |
| 2      | LOGICO      | B31-B42 | Operadores, flujo de control, excepciones | Pragmática       |
| 3      | ESTRUCTURAL | B43-B52 | Indentación, bloques, patrones            | Discurso         |

### PRESET_V3

| Parámetro        | Valor       |
| ---------------- | ----------- |
| `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** | **108.3M**  |

---

## Subsistemas

### 1. Modelo (`pampar/coder/v3/`)

| Archivo             | Líneas | Propósito                                                                       |
| ------------------- | ------ | ------------------------------------------------------------------------------- |
| `modelo.py`         | 310    | PamparV3: forward, generate (nucleus sampling)                                  |
| `config.py`         | 226    | ConfigV3, 3 presets (V3/SMALL/LARGE)                                            |
| `bloques.py`        | 395    | RMSNorm, RoPE, BloqueAttn (GQA), StreamFFN (SwiGLU), LateralGate, NivelProfundo |
| `talamo.py`         | 133    | TalamoInicial: LLAVES 80% + attn_proj 20% + context_conv                        |
| `llaves.py`         | 266    | LlavesV2: clasificar_token(), tabla INT8, agregar_zonas_a_territorios           |
| `zonas.py`          | 265    | Territorio(IntEnum), Zona(IntEnum), ZONAS dict, ZONA_TERRITORIO                 |
| `ghidra_probe.py`   | 343    | GhidraProbe: 36 forward hooks, diagnosis/debugging                              |
| `engrama_stream.py` | 359    | BancoEngrama: O(1) activation memory, cosine-gated injection                    |

### 2. Memoria (`pampar/memoria/`)

| Archivo            | Propósito                                                                     |
| ------------------ | ----------------------------------------------------------------------------- |
| `clasificador.py`  | ClasificadorPareto: scoring L0-L3 por densidad, novedad, loss, frecuencia     |
| `rag.py`           | RAGResidual: FAISS + sentence-transformers (fallback TF-IDF), 5K entradas max |
| `cola_finetune.py` | ColaFinetune: acumula L3, exporta JSONL, propone mini-SFT                     |

### 3. Runtime (`pampar/runtime/`)

| Archivo             | Propósito                                                          |
| ------------------- | ------------------------------------------------------------------ |
| `agente.py`         | Orquestador: prompt→RAG→generar→skills→retry→auto-SFT              |
| `scanner.py`        | Inspección del dispositivo: OS, GPU, paquetes, servicios, archivos |
| `boot.py`           | BootProtocol: CONCIENCIA.md (L3) → Scanner (L2) → Workspace (L1)   |
| `generar_agents.py` | Genera AGENTS.md contextual desde ResultadoScan                    |

### 4. Skills (`pampar/skills/`)

| Archivo              | Propósito                                                 |
| -------------------- | --------------------------------------------------------- |
| `lector_archivos.py` | Lee archivos del dispositivo (30+ extensiones, sandboxed) |
| `ejecutar_codigo.py` | Ejecuta código en subprocess con timeout y blocklist      |

### 5. Inference (`pampar/inference.py`)

Servidor JSON-lines stdin/stdout para extensión VS Code. Commands: `infer`, `boot`.

### 6. Classroom — Mentor Conversacional + Bio-Mechanisms

Sistema donde Qwen-plus actúa como mentor conversacional — genera explicaciones, ejemplos y ejercicios dinámicos. PamparV3 absorbe el conocimiento via gradient descent en 3 phases por lección.

**Flujo**: StudentProfile → Mentor genera lección → Phase A (absorber explicación+ejemplo) → Phase B (alumno intenta ejercicio) → Phase C (mentor corrige, entrenar en solución+replay) → actualizar perfil.

| Módulo                     | Líneas | Responsabilidad                                                                |
| -------------------------- | ------ | ------------------------------------------------------------------------------ |
| `classroom.py`             | ~608   | ClassroomEngine — motor conversacional (orquestador)                           |
| `classroom_curriculum.py`  | ~433   | ClassroomConfig + CONCEPT_TREE (21 conceptos) + StudentProfile + concept_level |
| `classroom_teacher.py`     | ~252   | Mentor API (Qwen/GitHub/OpenRouter) + parse de lecciones                       |
| `classroom_training.py`    | ~211   | Tokenización + LR diferencial + train_step                                     |
| `classroom_memory.py`      | ~187   | EWC + ReplayBuffer + LessonResult + compute_ewc_baseline                       |
| `classroom_events.py`      | ~104   | Formateo dict-based de eventos para consola                                    |
| `classroom_persistence.py` | ~123   | Guardado de checkpoints, sesiones JSONL, grabaciones HTML                      |
| `classroom_server.py`      | ~255   | HTTP SSE server + CLI entry point                                              |
| `bio_mechanisms.py`        | ~497   | 5 bio-mechanisms coordinados por BioOrchestrator                               |

**CONCEPT_TREE**: 21 conceptos en 5 niveles con prerequisitos (arithmetic → algorithms).
**StudentProfile**: mastery tracking adaptativo — prioriza refuerzo, luego nuevos, luego repaso.

| Mecanismo          | Propósito                                                         |
| ------------------ | ----------------------------------------------------------------- |
| **EWC**            | Elastic Weight Consolidation — penaliza cambios en pesos críticos |
| **Replay Buffer**  | Mezcla ejemplos nuevos con anteriores (consolidación tipo sueño)  |
| **LR Diferencial** | LLAVES 0.01x, atención 0.1x, embed 0.1x, FFN 1.0x                 |
| **Curriculum**     | 5 niveles progresivos: básico → avanzado                          |
| **Grabación**      | Genera HTML con replay interactivo de cada sesión                 |

**Bio-Mechanisms** (5 mecanismos de neurociencia en `bio_mechanisms.py`):

| Mecanismo               | Implementación                                                       |
| ----------------------- | -------------------------------------------------------------------- |
| **Neuromodulación**     | Dopamina/Norepinefrina modulan LR dinámicamente (×0.3 a ×3.0)        |
| **LTP**                 | Fortalece `LateralGate.scale` de streams activos (Hebb rule, cada 5) |
| **Sleep Consolidation** | REM (aleatorio) + SWS (ordenado por dificultad), cada 15 lecciones   |
| **Neurogenesis**        | LoRA adapters (rank=8) en StreamFFN cuando loss > 4.0, max 8         |
| **Synaptic Pruning**    | Poda `LateralGate.scale < 0.03` cada 30 lecciones (decay ×0.5)       |

Coordinados por `BioOrchestrator.after_lesson()`. Desactivables con `--no-bio`.

**Resultados piloto mentor conversacional (5 lecciones)**: Loss absorción ~7-8, loss ejercicios 5.89→3.94 (mejora), brain score 88.24% estable.

**APIs soportadas**: `qwen` (Qwen-plus via DashScope, principal), `github` (gpt-4o-mini), `openrouter` (requiere créditos).

---

## Estructura del proyecto

```
PAMPAr-Coder/
├── AGENTS.md                    # Este archivo — guía para AI agents
├── README.md                    # Documentación pública
├── PLAN.md                      # Plan de training y evolución
├── pampar/
│   ├── CONCIENCIA.md            # Identidad invariante del modelo
│   ├── coder/
│   │   └── v3/                  # ARQUITECTURA ACTIVA (108M)
│   │       ├── modelo.py        # PamparV3 — forward, generate
│   │       ├── config.py        # ConfigV3, presets
│   │       ├── talamo.py        # TalamoInicial — routing
│   │       ├── bloques.py       # GQA, SwiGLU, LateralGate, NivelProfundo
│   │       ├── llaves.py        # LlavesV2 — lookup INT8
│   │       ├── zonas.py         # 52 Zonas de Brodmann
│   │       ├── ghidra_probe.py  # Instrumentación read-only
│   │       └── engrama_stream.py# Memoria de activaciones
│   ├── memoria/
│   │   ├── clasificador.py      # ClasificadorPareto — niveles L0-L3
│   │   ├── rag.py               # RAGResidual — vector store local
│   │   └── cola_finetune.py     # ColaFinetune — buffer auto-SFT
│   ├── skills/
│   │   ├── lector_archivos.py   # Lee archivos (sandboxed)
│   │   └── ejecutar_codigo.py   # Ejecuta código (subprocess)
│   ├── runtime/
│   │   ├── agente.py            # Orquestador principal
│   │   ├── scanner.py           # Inspección del dispositivo
│   │   ├── boot.py              # Secuencia de arranque
│   │   └── generar_agents.py    # Generador de AGENTS.md
│   └── inference.py             # Servidor JSON-lines para VS Code
├── scripts/
│   ├── classroom.py             # ClassroomEngine — motor conversacional (~608 líneas)
│   ├── classroom_curriculum.py  # ClassroomConfig + CONCEPT_TREE + StudentProfile + concept_level
│   ├── classroom_teacher.py     # Mentor API — Qwen/GitHub/OpenRouter + parse de lecciones
│   ├── classroom_training.py    # Tokenización + LR diferencial + train_step
│   ├── classroom_events.py      # Formateo dict-based de eventos para consola
│   ├── classroom_memory.py      # EWC + ReplayBuffer + LessonResult + compute_ewc_baseline
│   ├── classroom_persistence.py # Guardado de checkpoints, sesiones, grabaciones HTML
│   ├── classroom_server.py      # HTTP SSE server + CLI entry point
│   ├── bio_mechanisms.py        # 5 bio-mechanisms (Neuromod, LTP, Sleep, Neurogenesis, Pruning)
│   └── classroom_replay.html    # Player HTML para replays
├── sessions/                    # Grabaciones de sesiones classroom
├── data/
│   ├── tokenizer/
│   │   └── pampar_48k.model     # Vocab 48K bilingüe
│   └── *.jsonl                  # Datasets de training
├── checkpoints/
│   └── v3_ghidra_v9.pt          # Mejor checkpoint actual
├── _archive/                    # Backups de archivos antes de refactorizar
└── tests/
```

---

## Critical Rules

- **vocab_size = 48K** → DEBE coincidir con `pampar_48k.model`
- **Tokenizer path**: usar `PRESET_V3.tokenizer_path` o constante compartida — no hardcodear
- LLAVES son INT8 pre-computadas — **nunca** en el grafo de gradientes
- Los 4 streams procesan en **paralelo** — sin secuencialidad entre streams
- `targets.reshape(-1)` siempre, nunca `.view(-1)` (tensores no-contiguos)
- `generate()` usa `max_tokens`, NO `max_new_tokens`
- Imports: `pampar.memoria.*`, `pampar.skills.*`, `pampar.runtime.*`
- **Backups**: antes de borrar/refactorizar, mover el original a `_archive/`

## Naming Conventions

- **Español** para conceptos del dominio: `Talamo`, `Territorio`, `Zona`, `LLAVES`, `Agente`, `Scanner`
- **Inglés** para ML estándar: `forward`, `embedding`, `hidden_states`, `loss`, `generate`

## Paradigma de inferencia

```
1. Usuario hace una pregunta/pedido
2. Scanner provee contexto del dispositivo (OS, paquetes, archivos)
3. RAGResidual busca referencia relevante (docs, código, memoria)
4. Prompt se arma: [SYSTEM] + [REFERENCIA RAG] + [CONTEXTO DISPOSITIVO] + [PREGUNTA]
5. Modelo RAZONA sobre la referencia y genera solución step-by-step
6. Skills ejecutan la solución si aplica (código, lectura, tests)
7. Si falla → retry con error como contexto → ColaFinetune acumula patrones
```

---

## Instructions Files

Detailed instructions in `.github/instructions/`:

- `global-profile.instructions.md` — perfil del desarrollador
- `testing.instructions.md` — reglas de testing (pytest)
- `git-workflow.instructions.md` — commits convencionales
- `docker-devops.instructions.md` — Docker, CI/CD