Hugging Face's logo

lucas-mella
/
PAMPAr-Coder

Model card Files
xet
 Community
PAMPAr-Coder / AGENTS.md
lucas-mella's picture
lucas-mella
feat: upload PAMPAr-Coder code and documentation
a2d6a0d verified
preview code
|
Raw
History Blame Contribute Delete
15.6 kB

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