Metadata-Version: 2.4
Name: cognia-ai
Version: 4.0.0
Summary: Local cognitive AI that runs offline on a small model, with episodic memory, self-improving prompts, and an AI-native image/scene creator
Author: Acua124298042
License: MIT
Project-URL: Homepage, https://github.com/tomascomenta-blip/cognia_v2
Project-URL: Repository, https://github.com/tomascomenta-blip/cognia_v2
Keywords: ai,llm,distributed,memory,cognia
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: flask>=2.3.0
Requires-Dist: requests>=2.31.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: numpy
Requires-Dist: networkx>=3.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: websockets>=12.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: sse-starlette>=1.6
Requires-Dist: rich>=13.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: huggingface_hub>=0.20
Requires-Dist: tokenizers>=0.15
Requires-Dist: psutil>=5.9
Requires-Dist: httpx>=0.27
Requires-Dist: pillow>=10.0.0
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10.0; extra == "pdf"
Provides-Extra: llama
Requires-Dist: llama-cpp-python>=0.2.20; extra == "llama"
Provides-Extra: tui
Requires-Dist: textual>=0.60.0; extra == "tui"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: pdfplumber>=0.10.0; extra == "all"
Requires-Dist: llama-cpp-python>=0.2.20; extra == "all"
Requires-Dist: textual>=0.60.0; extra == "all"

# Cognia — IA cognitiva local que aprende (Arquitectura Simbolico-Neural)

> IA local, ligera y privada. Corre en CPU con un modelo 3B, sin APIs externas y sin
> PyTorch en el camino critico. **Aprende, razona y recuerda** en tu propia maquina —
> con memoria episodica, un **creador de imagenes/escenas** AI-nativo, y **prompts que
> se auto-mejoran** (auto-prompting). Instalable en un comando: `pip install cognia-ai`.

**Stack:** Python 3.11+ (3.12 recomendado) · SQLite · Qwen2.5-Coder-3B (GGUF / INT4) ·
llama.cpp · sentence-transformers · numpy · FastAPI · Electron

---

## Tabla de contenidos

- [Que es Cognia](#que-es-cognia)
- [Estado del proyecto](#estado-del-proyecto-julio-2026)
- [Instalacion](#instalacion)
- [Uso — el REPL](#uso--el-repl)
- [El agente y el ruteo hibrido](#el-agente-y-el-ruteo-hibrido)
- [Modelo e inferencia](#modelo-e-inferencia)
- [Rendimiento (benchmarks reales)](#rendimiento-benchmarks-reales)
- [Modulos principales](#modulos-principales)
- [Arquitectura Diferencial](#arquitectura-diferencial)
- [Capa Cognitiva Chimera](#capa-cognitiva-chimera-sistema-no-atencion)
- [Inferencia distribuida (swarm)](#inferencia-distribuida-swarm)
- [Seguridad y privacidad](#seguridad-y-privacidad)
- [Desarrollo y tests](#desarrollo-y-tests)
- [Documentacion](#documentacion)
- [Para colaborar](#para-colaborar)

---

## Que es Cognia

Cognia es una **arquitectura cognitiva** que aprende, razona y recuerda localmente. A
diferencia de un chatbot, gestiona un ciclo de vida cognitivo completo: memoria episodica
y semantica, un grafo de conocimiento, consolidacion de memoria durante el "sueno", y
razonamiento que puede distribuirse entre varios dispositivos de una red local.

Tres ideas la definen:

1. **Local-first y privada.** Tus datos nunca salen de tu maquina salvo que conectes
   nodos en una red mesh de forma explicita. Memorias cifradas en reposo (AES-256-GCM).
2. **Ligera.** Inferencia en CPU mediante llama.cpp (GGUF cuantizado) o shards numpy puro
   (INT4), sin PyTorch ni Tensorflow en el motor principal.
3. **Cognitiva, no solo generativa.** Router de dominio (LOGOS/TECHNE/RHETOR), ciclo de
   sueno de consolidacion, world-model que simula consecuencias antes de actuar, y una
   capa cognitiva Chimera construida sobre todo lo anterior.

---

## Estado del proyecto (Julio 2026)

| Fase | Estado | Descripcion |
|------|--------|-------------|
| **Fases 1-6 — Estabilizacion y core** | COMPLETADA | Base limpia, NarrativeThread, MeshNode, seguridad, escalado. |
| **Fase 7 — Shattering (SRDN)** | COMPLETADA | Sub-modelos LOGOS/TECHNE/RHETOR, MoE, NPQ, RST, MLA. |
| **Fase 8 — Commercial release** | COMPLETADA | Instaladores, UX, cifrado por defecto, documentacion. |
| **Fases 9-12 — Hardening y UX** | COMPLETADA | Proteccion SQLi/XSS/SSRF, consentimiento de privacidad, auto-update. |
| **Fase 13 — Inferencia distribuida real** | COMPLETADA | Qwen2.5-Coder-3B INT4, auto-sharding, relay WebSocket. |
| **Inferencia local llama.cpp** | OPERATIVA | GGUF como ruta primaria (~8-9 tok/s en un i3 de 2 cores / 4 threads); shards numpy como fallback. |
| **Capa cognitiva Chimera** | OPERATIVA | Band router de 3 bandas, cognitive loop, memoria jerarquica, world-model. |
| **Especialistas MoM (Mixture of Models)** | OPERATIVA | Portero 0.5B para turnos rapidos (~3.3–3.9×), escalado reactivo 3B→7B en codigo duro (+20pp), router de expertos LoRA. `cognia install-model` los monta; degradan al 3B si faltan. |
| **Agente + ruteo hibrido por dificultad** | OPERATIVA (3.9.0) | `/hacer` (loop ReAct con herramientas reales) + perfil por dificultad de tarea: mono / agente / +colonia / +superorganismo, gobernado por `/esfuerzo`. |

Detalle tecnico por fase en [ROADMAP.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/ROADMAP.md). Bitacora de sesiones en
[CLAUDE_NOTES.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/CLAUDE_NOTES.md) y [MANAGER_LOG.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/MANAGER_LOG.md).

---

## Instalacion

### Un solo comando (PyPI) — recomendado

```bash
pip install cognia-ai
cognia
```

Eso es todo: `pip install cognia-ai` deja el comando `cognia` listo, y `cognia` abre el
asistente (primer arranque = wizard de configuracion, luego el REPL). Corre **100%
local con el modelo 3B** (Qwen2.5-Coder-3B via llama.cpp); la orquestacion online viene
**apagada por defecto** (forzable con `COGNIA_DISABLE_SWARM=1`). Incluye el **creador de
imagenes/escenas** AI-nativo y los **prompts que se auto-mejoran**.

```bash
pip install "cognia-ai[semantic]"   # + embeddings reales (sentence-transformers, ~2GB)
pip install "cognia-ai[tui]"        # + interfaz TUI (textual)
pip install "cognia-ai[llama]"      # + llama.cpp via pip (requiere wheel prebuilt o compilador C++)
pip install "cognia-ai[all]"        # todo
```

Requisitos: **Python 3.11+** (3.12 recomendado). Para la inferencia el camino
**recomendado** es `cognia install-model`: descarga el **GGUF 3B + llama-server**
(el mas rapido en CPU, sin compilador) mas el portero 0.5B y los expertos LoRA a
`~/.cognia/`, y deja todo configurado (`config.env`). Alternativas: (2)
**`cognia-ai[llama]`** (`llama-cpp-python`) — necesita wheel prebuilt o compilador
C++; (3) **shards numpy** (INT4, Python puro) — camino avanzado/experimental, mas
lento (`cognia install-weights`). El primer arranque (`cognia`) te guia.

### Instaladores rapidos (desde el repo — stack swarm LEGACY)

> Estos scripts montan el stack de **shards numpy/swarm** (legacy), no el stack
> recomendado GGUF+llama-server. Para el producto usa `pip install cognia-ai` +
> `cognia install-model`.

**Windows (PowerShell):**
```powershell
.\install.ps1
```

**Linux / macOS (Bash):**
```bash
bash install.sh
```

El instalador crea un entorno, instala dependencias y descarga el modelo (~300 MB en modo
swarm, ~1.2 GB en modo standalone con los 4 shards).

### Desktop App (Electron)

```bash
cd cognia_desktop
npm install
npm run build:win    # o build:linux / build:mac
```

### Releases precompilados

| Plataforma | Archivo | Requisitos |
|---|---|---|
| Windows | `CogniaDesktop-x.x.x-Setup.exe` | Python 3.11+ |
| Linux | `CogniaDesktop-x.x.x.AppImage` | Python 3.11+ |
| Android | `cognia-mobile-x.x.x.apk` | Android 8+ |

Releases: **https://github.com/tomascomenta-blip/cognia_v2/releases**

> Nota: los instaladores Desktop publicados corresponden a una version anterior
> (era 3.2.x). La via al dia es el paquete de PyPI (`pip install cognia-ai`).

> **Nota sobre Python:** el `venv/` del repo puede apuntar a un interprete sin wheels
> disponibles. Se recomienda **Python 3.12**. En desarrollo, este repo usa
> `venv312/Scripts/python.exe` — sustituyelo por tu interprete si difiere.

---

## Uso — el REPL

Arranca Cognia (lanza el wizard la primera vez, luego abre el REPL interactivo):

```bash
python -m cognia
```

Dentro del REPL, **cualquier texto sin `/` es chat cognitivo**; los comandos empiezan
con `/`:

```
cognia> hola, que sabes hacer?          <- chat libre (inferencia)
cognia> /ayuda                          <- lista completa de comandos (206)
cognia> /hacer crea un juego de la vida en vida.py y probalo
cognia> /salir
```

### Comandos principales

| Comando | Que hace |
|---|---|
| `<texto libre>` | Chat cognitivo (inferencia + memoria). |
| `/hacer <tarea>` | **Agente autonomo**: ejecuta la tarea con herramientas reales (archivos, codigo, busqueda). |
| `/esfuerzo [nivel]` | Cuanto sistema despertar: bajo/medio/alto/maximo (gobierna el ruteo hibrido). |
| `/modelo [3b\|7b]` | Ver/cambiar el modelo activo del fleet. |
| `/largo <tema>` | Generacion larga por secciones con checkpoint (`--continuar`). |
| `/pensar <problema>` | Razonamiento paso a paso (stepwise). |
| `/crear <idea>` | Crear un programa Python ahora (sandbox + biblioteca). |
| `/oficina` | Dashboard de oficina (jefe→directores→trabajadores sobre el agente). |
| `/plan <objetivo>` | Descomponer un objetivo en pasos. |
| `/ayuda` | Lista completa de comandos (o `/ayuda <comando>` para el detalle). |
| `/yo` | Perfil cognitivo y estado interno de la memoria. |
| `/memoria` | Estado de la memoria episodica/semantica. |
| `/aprender <frente> \| <respuesta> [\| tema]` | Crear tarjeta de estudio (repaso espaciado). |
| `/observar <texto>` | Guardar una observacion sin procesar. |
| `/dormir` | Ciclo de consolidacion y limpieza (sueno). |
| `/grafo <concepto>` | Visualizar el grafo de conocimiento local. |
| `/sesiones` | Listar sesiones de chat recientes. |
| `/salir` | Salir del REPL. |

Tambien hay una **TUI** (`pip install "cognia-ai[tui]"` + `python -m cognia.tui`).

### Subcomandos de la CLI

```bash
cognia                  # REPL (wizard en el primer uso)
cognia init             # Re-ejecutar el wizard de configuracion
cognia install-model    # Stack de inferencia recomendado: GGUF 3B + llama-server b9391 + expertos LoRA + portero 0.5B
cognia install-model --with-heavy-code   # + especialista 7B de codigo (~4.7 GB, opt-in): escalado 3B->7B en codigo duro (+20pp)
cognia modo             # Ver/cambiar el modo (local / compartido / memoria)
cognia doctor           # Diagnostico de la instalacion (backend GGUF incluido)
cognia status           # Estado del backend local (GGUF), swarm y Ollama
cognia install-weights  # (avanzado) Descargar shards numpy y configurar este equipo como nodo
cognia install-weights --standalone   # (avanzado) Los 4 shards para uso local completo
cognia server           # Servidor web FastAPI (puerto 8000)
cognia node             # Iniciar como nodo del swarm distribuido
cognia coordinator      # Iniciar el coordinador del swarm (puerto 8001)
cognia leave            # Salir de la red y liberar el shard alojado
```

---

## El agente y el ruteo hibrido

`/hacer <tarea>` corre el **agente**: un loop ReAct que piensa, emite acciones
(`ACCION: <herramienta> <args>`) y observa resultados, con herramientas reales
(escribir/leer archivos, generar y PROBAR codigo, buscar, knowledge graph,
escenas). El costo se gobierna con el **ruteo hibrido por dificultad** (3.9.0):
la dificultad estimada de la tarea (cero LLM) + el nivel `/esfuerzo` deciden
cuanto sistema despertar —

```
mono                          tarea trivial: respuesta directa
agente                        facil-media: loop con tools, 1 modelo (3B)
agente + colonia              media: etapas multi-modelo permitidas (7B, 4B)
agente + colonia + superorganismo   dura: colonia por pedazos (etapa 4)
```

Las etapas caras son **reactivas**: solo corren si lo barato fallo sus tests.
En codigo duro la cascada completa mide 57.5→67.5% en tests ocultos vs 40% del
3B solo. Kill-switch global: `COGNIA_HIBRIDO=0` (comportamiento clasico).

---

## Modelo e inferencia

Cognia resuelve cada prompt por la **primera ruta de inferencia disponible**, en este
orden:

1. **llama.cpp + GGUF (ruta local primaria).** Si encuentra un GGUF de Qwen2.5-Coder-3B,
   lo carga via `llama-cpp-python` o `llama-server`. Es la ruta mas rapida y de mejor
   calidad en una sola maquina. El backend lo resuelve solo: `LLAMA_GGUF_PATH` (lo escribe
   `cognia install-model` en `~/.cognia/config.env`) → `SHARD_WEIGHTS_DIR` →
   auto-descubrimiento en `~/.cognia/models/`.
2. **Shards numpy INT4 (fallback distribuido / local).** Forward pass en numpy puro sin
   PyTorch, repartible entre nodos del swarm. Es el corazon de la arquitectura Shattering.
3. **Ollama (fallback legacy, opcional).** Si defines `OLLAMA_URL` y no hay backend GGUF
   vivo, se usa como ultimo recurso.

### Especialistas (Mixture of Models)

Sobre el 3B base, `cognia install-model` monta una cascada de especialistas que se
activan solos y **degradan al 3B** si su modelo no esta presente (nada se rompe):

- **Portero 0.5B** — atiende los turnos triviales de charla (saludo, identidad,
  cortesia) a ~3.3–3.9× la velocidad del 3B. Se instala por defecto.
- **7B de codigo (opt-in)** — con `install-model --with-heavy-code`, cuando el 3B
  falla los tests de una tarea de codigo dificil se reintenta con Qwen2.5-Coder-7B
  en greedy (codigo duro 37.5→57.5% pass@1, +20pp). Lazy-load-usar-cerrar: RAM en
  reposo 0; `COGNIA_HEAVY_CODE=0` lo apaga.

### Configurar el modelo

El backend GGUF detecta automaticamente cualquiera de estas cuantizaciones (de mayor a
menor prioridad): `Q4_K_M` (la medida como mejor en b9391), `Q4_0`, `Q3_K_S`, `Q5_K_M`.
Para apuntar a una carpeta de modelos concreta, define la ruta **absoluta**:

```
# ~/.cognia/config.env
SHARD_WEIGHTS_DIR=C:\ruta\a\model_shards\qwen-coder-3b-q4
```

> La ruta absoluta evita que la deteccion dependa del directorio de trabajo. Si la dejas
> relativa, solo resuelve cuando arrancas desde la raiz del repo.

**Usar otro modelo (p. ej. Qwen2.5-7B).** `LLAMA_GGUF_PATH` tiene prioridad sobre la
deteccion automatica. Apunta directamente a un GGUF (en modelos split, al primer fragmento
`-00001-of-NNNNN.gguf`; llama.cpp carga el resto):

```
# LLAMA_GGUF_PATH=C:\ruta\a\qwen2.5-7b-instruct-q4_k_m-00001-of-00002.gguf
```

> Un 7B es mas capaz pero pesa ~6 GB en RAM y, en una CPU de gama baja con poca memoria
> libre, puede bajar a ~1 tok/s por swapping. El 3B es el equilibrio recomendado para
> CPU-only.

Variables de entorno relevantes:

| Variable | Default | Uso |
|---|---|---|
| `LLAMA_GGUF_PATH` | (config.env) | Ruta directa a un GGUF; prioridad sobre la deteccion. Sin nada, auto-descubre en `~/.cognia/models/`. |
| `LLAMA_SERVER_PATH` | (config.env) | Binario llama-server (lo instala `cognia install-model`). |
| `SHARD_WEIGHTS_DIR` | `model_shards/qwen-coder-3b-q4` | Carpeta del GGUF / shards. |
| `COGNIA_HIBRIDO` | `1` | `0` apaga el ruteo hibrido por dificultad (comportamiento clasico). |
| `COGNIA_HEAVY_CODE` | `1` | `0` apaga el escalado 3B→7B en codigo duro. |
| `COGNIA_PORTERO` | `1` | `0` apaga el portero 0.5B. |
| `COGNIA_SUPERORGANISMO` | (perfil) | Fuerza on/off la etapa 4 (colonia por pedazos). |
| `COGNIA_COORDINATOR_URL` | (vacio) | URL de la **API** del coordinador del swarm. Sin definir = modo local. |
| `OLLAMA_URL` | `http://localhost:11434` | Motor Ollama (fallback legacy opcional). |
| `COGNIA_DATA_DIR` | `~/.cognia/data` | Datos y memoria local. |
| `HF_TOKEN` | (vacio) | Token de HuggingFace para descargas privadas. |

> Las claves de `~/.cognia/config.env` se cargan en TODOS los entry points
> (`apply_config()`); una env var del sistema MANDA sobre config.env y el CLI avisa
> cuando la pisa.

---

## Rendimiento (benchmarks reales)

Medido en un **Intel i3-10110U (2 cores / 4 threads, sin GPU dedicada)**, llama.cpp en
CPU. Numeros de streaming real (ver
[MANAGER_LOG.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/MANAGER_LOG.md)):

| Configuracion | tok/s | Notas |
|---|---|---|
| Q4_K_M, threads=3 | 7.5 – 8.2 | **Ruta primaria** (la que instala `cognia install-model`; b9391 pineado). |
| Q3_K_S, threads=4 | 7.7 | +7% sobre Q4_0, calidad similar. |
| Q4_0, threads=4 (CPU puro) | 7.2 – 8.8 | Alternativa. |
| `stream_chat` (runs limpios) | 8.6 (pico 9.0) | Throughput real sostenido. |
| Portero 0.5B (turnos triviales) | 28 – 36 | 3.3–3.9× pareado vs 3B. |
| Vulkan + Intel UHD (offload) | 3.7 – 3.8 | **Peor**: la memoria compartida es el cuello de botella. |

**Notas honestas:**
- El techo de este hardware ronda **8-9 tok/s**; el objetivo de >10 tok/s no se alcanza
  sin GPU dedicada real. Una CPU/GPU mas potente sube estos numeros.
- `cognia doctor` puede reportar ~0.6-0.8 tok/s: ese numero cuenta *palabras* en una
  respuesta corta con arranque en frio, **no** es el throughput de streaming.
- El offload a iGPU Intel via Vulkan es contraproducente; mantener CPU puro.

---

## Modulos principales

| Modulo | Funcion |
|--------|---------|
| `KnowledgeGraph` | Memoria semantica estructurada y jerarquica. |
| `InferenceEngine` | Razonamiento transitivo y herencia de propiedades. |
| `ShatteringOrchestrator` | Inferencia distribuida y ruteo MoE (LOGOS/TECHNE/RHETOR). |
| `ConsolidationEngine` | Ciclo de sueno: purga, refuerzo y olvido de memorias. |
| `SecureStorage` | Cifrado AES-256-GCM de memorias episodicas. |
| `CogniaMeshNode` | Red P2P para sincronizacion de conocimiento via CRDT. |
| `BandRouter` | Enrutador de contexto/memoria de 3 bandas (LOCAL/MEDIA/GLOBAL). |
| `CognitiveLoop` | Clasificador de ruta FAST/RECALL/DELIBERATE/ACT. |

---

## Arquitectura Diferencial

Cognia no es un wrapper de LLM ni una interfaz de chat con memoria. Las diferencias
tecnicas respecto a los sistemas convencionales son estructurales:

- **Inferencia sin servidor central:** El forward pass ocurre en los dispositivos de los
  usuarios (shards .npz en numpy puro, sin PyTorch). El coordinador enruta pero no ejecuta
  ni almacena nada de la conversacion.
- **Memoria episodica como almacen primario:** El conocimiento vive en SQLite local +
  VectorCache numpy por usuario, no en pesos compartidos. Cada instancia aprende de su
  propio historial sin exponer datos.
- **Cuantizacion dinamica en produccion:** Los pesos escalan INT4 → INT8 → FP16 → FP32
  segun frecuencia de acceso en tiempo real, con auto-decay a INT4 tras inactividad. El
  objetivo es minimizar RAM sin degradar las rutas calientes.
- **Adaptacion personal sin fine-tuning global:** El ciclo de sueno entrena adapters LoRA
  (r=4-8) sobre episodios de alta importancia del usuario y los aplica en las proyecciones
  KV del transformer. Cada instancia desarrolla un sesgo de respuesta personalizado sin
  alterar los pesos base compartidos.
- **Agregacion federada de SOLO deltas LoRA (NO FedAvg sobre parametros completos):** El
  coordinador (`coordinator/federated_store.py`, cableado en `coordinator/app.py`) combina
  unicamente los adapters LoRA que cada nodo aporta (matrices `k_A/k_B/v_A/v_B`, r=4-8),
  nunca los pesos base del modelo. La combinacion es un **promedio ponderado de deltas
  LoRA**: peso por tier del nodo × afinidad semantica (similitud coseno del delta efectivo
  `k_A@k_B`, `v_A@v_B` contra el adapter global vigente, `w = tier × (1 + 0.3·cos)`), que
  baja el peso de aportes divergentes sin un set de validacion central. Los clientes suman
  **ruido gaussiano (sigma=0.01)** antes de enviar. Esto NO es FedAvg sobre parametros
  completos (prohibido por diseno): los pesos base compartidos jamas se promedian ni se
  alteran; solo se agrega el subespacio LoRA de bajo rango.
- **Ciclo de sueno autonomo:** Consolidacion episodica, compresion conceptual,
  actualizacion del grafo de conocimiento, investigacion autonoma, entrenamiento ELC,
  procesamiento emocional Plutchik, y auto-expansion de rango LoRA cuando el adapter satura.
- **Router de dominio sobre tres sub-modelos:** LOGOS (razonamiento, temp=0.3), TECHNE
  (codigo, temp=0.15), RHETOR (escritura, temp=0.7) — tres perfiles de generacion distintos
  sobre la misma base Qwen2.5-Coder-3B INT4.

---

## Capa Cognitiva Chimera (sistema, no atencion)

Sobre el backbone Qwen2.5-Coder-3B INT4 pre-shardeado se construyo una capa cognitiva
inspirada en el whitepaper `chimera_transformer.md`. HYDRA NO se implementa como mecanismo
de atencion (el modelo esta pre-cuantizado y pre-shardeado: alterar la atencion exigiria
reentrenar y re-shardar todo el swarm). En su lugar, los conceptos de Chimera se realizan
como un **analogo a nivel de sistema** que orquesta los subsistemas ya existentes. Todo
corre offline, sin LLM y sin PyTorch en el camino critico.

Flujo end-to-end (whitepaper seccion 11), un solo comando:

```
python -m cognia.chimera "calcula 2+2"
```

Etapas reales del trace: INPUT → bandas HYDRA → route cognitivo → memoria recuperada
→ plan → critica → verify → world-model (riesgo) → tools → output → memoria escrita.

### Que se implemento: literal vs adaptado vs descartado

| Subsistema Chimera | Decision | Por que / como | Archivos |
|---|---|---|---|
| HYDRA (atencion 3 bandas) | **ADAPTADO** (no literal) | Atencion intocable (INT4 pre-shardeado). Reimplementado como enrutador de CONTEXTO/MEMORIA de 3 bandas LOCAL/MEDIA/GLOBAL sobre el router LOGOS/TECHNE/RHETOR. | `cognia/context/band_router.py` |
| MoE routing | **YA EXISTE** (reutilizado) | LOGOS/TECHNE/RHETOR via `GlobalRouter`. No se duplico. | `shattering/router.py` |
| Cognitive Loop (FAST/RECALL/DELIBERATE/ACT) | **CONSTRUIDO** | Clasificador de ruta + ejecucion real offline de cada ruta. | `cognia/reasoning/cognitive_loop.py` |
| Memoria jerarquica 5 capas | **ADAPTADO** (facade + gating) | Las 5 capas existian sueltas; se unifico y se agrego el write-gate por sorpresa+importancia que faltaba. | `cognia/memory/hierarchical.py` |
| World model | **ADAPTADO ligero** | Sin RSSM neuronal (sin computo). Simulador de consecuencias deterministico (riesgo, reversibilidad, KG) que gatea antes de ejecutar. | `cognia/reasoning/action_simulator.py` |
| Planner + critico | **YA EXISTE** (cableado) | `plan_task` (templates) + `SelfCritic.critique` + `verify`. | `cognia/agents/planner.py`, `cognia/reasoning/self_critic.py`, `cognia/agents/verifier.py` |
| Agentes + herramientas | **YA EXISTE** (reutilizado) | `tool_registry` con tools reales (execute_python, etc.). | `cognia/agents/tool_registry.py` |
| Multimodal nativo | **DESCARTADO** | Inviable: nodos numpy puro sin encoders de vision/audio; fuera de la vision P2P CPU-only. | - |
| Aprendizaje continuo (3 velocidades) | **PARCIAL ya existe** | Episodico, adapters LoRA, consolidacion lenta. No se toco en esta capa. | `cognia/memory/*` |
| Espacio latente unificado U | **DESCARTADO** | Exigiria entrenamiento conjunto; los subsistemas se comunican por texto/vectores. | - |

### Reproducir cada prueba

> Usar un interprete Python 3.12. En este repo: `venv312/Scripts/python.exe`.

```
# C1 HYDRA 3 bandas
venv312/Scripts/python.exe -m cognia.context.band_router "recuerda lo que dijiste antes sobre shards?"
venv312/Scripts/python.exe -m pytest tests/test_band_router.py -q

# C2 Cognitive Loop
venv312/Scripts/python.exe -m cognia.reasoning.cognitive_loop "calcula 2+2"
venv312/Scripts/python.exe -m pytest tests/test_cognitive_loop.py -q

# C4 Memoria jerarquica con write-gating
venv312/Scripts/python.exe -m cognia.memory.hierarchical
venv312/Scripts/python.exe -m pytest tests/test_hierarchical_memory.py -q

# C5 World-model: simular antes de actuar
venv312/Scripts/python.exe -m cognia.reasoning.action_simulator "delete all files in C:/"
venv312/Scripts/python.exe -m pytest tests/test_action_simulator.py -q

# FASE FINAL integral
venv312/Scripts/python.exe -m cognia.chimera "refactoriza el orchestrator paso a paso e implementa y prueba"
venv312/Scripts/python.exe -m pytest tests/test_chimera.py -q
```

---

## Inferencia distribuida (swarm)

La arquitectura **Shattering (SRDN — Sparse-Recursive Distillation Network)** permite correr
modelos de 3B+ parametros en equipos con poca RAM repartiendo el modelo en shards:

- **Auto-sharding:** el modelo se divide en fragmentos que corren en distintos nodos de una
  red local, coordinados por un relay WebSocket.
- **Cuantizacion INT4:** pesos comprimidos ~75% operados puramente en numpy.
- **Coordinador sin estado de conversacion:** enruta tokens entre shards; no almacena ni
  ejecuta el contenido de la sesion.

```bash
# Convertir pesos de HuggingFace a shards de Cognia
python scripts/convert_hf_to_shards.py --hf-dir /ruta/a/qwen --out-dir model_shards/qwen-q4

# Levantar coordinador y nodos
cognia coordinator                       # equipo A (puerto 8001)
cognia install-weights --coordinator http://A:8001   # equipo B descarga su shard
cognia node                              # equipo B se une al swarm
```

> Para usar el swarm, `COGNIA_COORDINATOR_URL` debe apuntar a la **API** del coordinador
> (p. ej. `https://<servicio>.up.railway.app`), no a una URL de dashboard.

---

## Seguridad y privacidad

- **Local-First:** tus datos nunca salen de tu maquina salvo que conectes nodos mesh
  explicitamente.
- **Cifrado en reposo:** memorias episodicas con AES-256-GCM.
- **Proteccion anti-injection:** filtros estructurales en prompts y consultas SQL
  parametrizadas (sin `sqlite3.connect()` directo; via `storage/db_pool.py`).
- **Privacidad diferencial:** ruido estadistico en sincronizaciones de red para proteger
  la identidad.

Mas detalle en [docs/PRIVACY.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/docs/PRIVACY.md) y [docs/SECURITY.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/docs/SECURITY.md).

---

## Desarrollo y tests

Suite rapida (excluye el e2e de inferencia, lento/pesado):

```bash
python -m pytest tests/ --ignore=tests/test_e2e_inference.py -q
```

Convenciones del repo (ver [ROADMAP.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/ROADMAP.md) y `CLAUDE.md`):

- **Sin PyTorch/Tensorflow** en el motor de inferencia principal.
- **Windows CP1252:** los `print()` y strings del CLI usan ASCII puro (sin emojis ni
  box-drawing). Este README, al ser documentacion Markdown, si usa Unicode.
- **Sin constantes de modelo hardcodeadas:** usar `shattering/model_constants.py`.
- **Cada subsistema cierra con una prueba CLI real** — nada de mocks/stubs.

---

## Documentacion

| Documento | Contenido |
|-----------|-----------|
| [docs/INSTALL.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/docs/INSTALL.md) | Guia detallada de instalacion y configuracion. |
| [docs/TROUBLESHOOTING.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/docs/TROUBLESHOOTING.md) | Solucion a problemas comunes y diagnostico. |
| [docs/PRIVACY.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/docs/PRIVACY.md) | Manejo de datos y privacidad. |
| [ROADMAP.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/ROADMAP.md) | Plan de desarrollo y estado de las fases (fuente de verdad). |
| [CLAUDE_NOTES.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/CLAUDE_NOTES.md) | Log real de sesiones de desarrollo y fixes. |
| [MANAGER_LOG.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/MANAGER_LOG.md) | Bitacora del manager (benchmarks, decisiones). |

---

## Para colaborar

Lee el [ROADMAP.md](https://github.com/tomascomenta-blip/cognia_v2/blob/main/ROADMAP.md) para entender la direccion actual. Cognia prioriza la
eficiencia (CPU-only), la privacidad y la estabilidad. No se aceptan dependencias pesadas
(PyTorch/Tensorflow) en el motor de inferencia principal.

---
© 2026 Cognia Project. Distribuido bajo licencia MIT.
