diff --git a/03_MODELO_DATOS/context_manager_v8.md b/03_MODELO_DATOS/context_manager_v8.md new file mode 100644 index 0000000..d07aa49 --- /dev/null +++ b/03_MODELO_DATOS/context_manager_v8.md @@ -0,0 +1,346 @@ +# Context Manager v8 - Sistema de Gestión de Contexto para IA + +**Versión:** 8.1 +**Fecha:** 2026-01-01 +**Sistema:** CAPTAIN CLAUDE - TZZR +**Generador:** ARCHITECT + +--- + +## Visión General + +El **Context Manager v8** es un sistema completo para la gestión del contexto en sistemas de IA. Proporciona: + +1. **Log inmutable** con integridad criptográfica (blockchain-style) +2. **Integración con Sistema de Componentes TZZR** (players, items, locations, hashtags, flags) +3. **Referencias relacionales** a contexto, libros contables y registros de secretaría +4. **Contexto ambiental** dinámico embebido en mensajes +5. **Soporte multiagente** con owner, players y master_player + +--- + +## Arquitectura de Schemas + +``` +┌─────────────────────────────────────────────────────────────┐ +│ CONTEXT MANAGER v8.1 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ SCHEMA: log (Inmutable) │ │ +│ │ │ │ +│ │ ├── log.messages (mensajes) │ │ +│ │ └── log.message_refs (referencias a contexto) │ │ +│ │ │ │ +│ │ Características: │ │ +│ │ ├─ Solo INSERT (UPDATE/DELETE bloqueados) │ │ +│ │ ├─ Cadena SHA-256: prev_hash → hash │ │ +│ │ └─ Integración con Sistema Componentes TZZR │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ SISTEMA DE COMPONENTES TZZR (Referencias externas) │ │ +│ │ │ │ +│ │ ├── ply (Players: usuarios, agentes, empresas) │ │ +│ │ ├── hst (Hash Semantic Tagging: etiquetas) │ │ +│ │ ├── flg (Flags: jurisdicciones, normativas) │ │ +│ │ ├── itm (Items: productos, componentes) │ │ +│ │ └── loc (Locations: ubicaciones físicas) │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ FUENTES DE CONOCIMIENTO (via message_refs) │ │ +│ │ │ │ +│ │ ├── context → log.messages (historial) │ │ +│ │ ├── accountant → libros contables │ │ +│ │ └── secretary → registros de secretaría │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Schema LOG (2 tablas) + +### 1. `log.messages` - Mensajes + +Almacena todos los mensajes del sistema de forma inmutable. + +**Características:** +- Solo permite INSERT (triggers previenen UPDATE/DELETE) +- Cadena de integridad: cada mensaje contiene hash del anterior +- Integración completa con Sistema de Componentes TZZR +- Soporte multiagente: owner (emisor), players (receptores), master_player (líder) + +**Schema:** +```sql +CREATE TABLE log.messages ( + id BIGSERIAL PRIMARY KEY, + hash CHAR(64) UNIQUE NOT NULL, -- SHA-256 del mensaje + session_hash CHAR(64) NOT NULL, -- Sesión + thread_hash CHAR(64), -- Hilo (nullable) + owner_id CHAR(64) NOT NULL, -- Emisor (→ ply) + players_id CHAR(64)[] DEFAULT '{}', -- Receptores (→ ply) + master_player CHAR(64), -- Líder/coordinador (→ ply) + role TEXT, -- Rol del emisor + content TEXT NOT NULL, -- Contenido del mensaje + attachments JSONB DEFAULT '{}', -- Adjuntos + prev_hash CHAR(64), -- Hash mensaje anterior + hashtags CHAR(64)[] DEFAULT '{}', -- Etiquetas (→ hst) + flag_id CHAR(64), -- Jurisdicción (→ flg) + master_item_id CHAR(64), -- Item principal (→ itm) + item_id CHAR(64)[] DEFAULT '{}', -- Items relacionados (→ itm) + loc_id CHAR(64), -- Ubicación (→ loc) + ambient JSONB, -- Contexto ambiental + created_at TIMESTAMPTZ DEFAULT NOW() +); +``` + +**Índices:** +- `session_hash` - Mensajes de una sesión +- `thread_hash` - Mensajes de un hilo +- `owner_id` - Mensajes enviados por +- `master_player` - Mensajes con líder +- `prev_hash` - Cadena de integridad +- `created_at` - Orden cronológico +- `hashtags` (GIN) - Búsqueda por etiquetas +- `players_id` (GIN) - Búsqueda por receptores +- `item_id` (GIN) - Búsqueda por items +- `flag_id` - Filtrar por jurisdicción +- `loc_id` - Filtrar por ubicación + +--- + +### 2. `log.message_refs` - Referencias + +Relaciona cada mensaje con su contexto y fuentes de conocimiento. + +**Características:** +- Tabla relacional para evitar arrays largos de hashes +- Tres tipos de referencias: context, accountant, secretary +- Posición para ordenar el contexto +- Inmutable como log.messages + +**Schema:** +```sql +CREATE TABLE log.message_refs ( + id BIGSERIAL PRIMARY KEY, + message_hash CHAR(64) NOT NULL, -- Mensaje que se envía + ref_hash CHAR(64) NOT NULL, -- Hash de la referencia + ref_type log.ref_type NOT NULL, -- context|accountant|secretary + position INT NOT NULL, -- Orden de la referencia + thread_hash CHAR(64), -- Hilo (nullable) + UNIQUE(message_hash, ref_hash) +); +``` + +**Tipos de referencia:** +| Tipo | Descripción | +|------|-------------| +| `context` | Mensajes anteriores incluidos como contexto | +| `accountant` | Registros de libros contables (conocimiento financiero) | +| `secretary` | Registros de secretaría (conocimiento general) | + +--- + +## Integración con Sistema de Componentes TZZR + +El Context Manager referencia las tablas del Sistema de Componentes: + +| Campo log.messages | Tabla TZZR | Descripción | +|-------------------|------------|-------------| +| `owner_id` | ply | Emisor del mensaje (usuario o agente) | +| `players_id[]` | ply | Receptores del mensaje | +| `master_player` | ply | Coordinador en sistemas multiagente | +| `hashtags[]` | hst | Etiquetas semánticas del mensaje | +| `flag_id` | flg | Jurisdicción o normativa aplicable | +| `master_item_id` | itm | Item principal relacionado | +| `item_id[]` | itm | Items adicionales relacionados | +| `loc_id` | loc | Ubicación física del contexto | + +### Tablas del Sistema de Componentes + +``` +PLY (Players) +├── ply - Sistema (empresas, entidades oficiales) +├── plu - Usuario (contactos personales) +└── plx - Compartidos + +HST (Hash Semantic Tagging) +├── hst - Tags del sistema (658) +├── spe - Especificaciones técnicas (145) +├── vsn - Visiones/escenas (84) +├── vue - Valores humanos (21) +└── hsu - Tags de usuario + +FLG (Flags/Jurisdicciones) +├── flg - Sistema (65 países/normativas) +└── flu - Usuario + +ITM (Items) +├── itm - Sistema +├── itu - Usuario +└── itx - Compartidos + +LOC (Locations) +├── loc - Sistema +├── lou - Usuario +└── lox - Compartidos +``` + +--- + +## Cadena de Integridad + +Cada mensaje incluye el hash del anterior, formando una cadena verificable: + +``` +msg1.hash = SHA256(msg1_data) +msg2.prev_hash = msg1.hash +msg2.hash = SHA256(msg2_data) +msg3.prev_hash = msg2.hash +... +``` + +**Primer mensaje de sesión:** `prev_hash = NULL` + +**Función de hash:** +```sql +CREATE FUNCTION log.sha256(data TEXT) RETURNS CHAR(64) AS $$ +BEGIN + RETURN encode(digest(data, 'sha256'), 'hex'); +END; +$$ LANGUAGE plpgsql IMMUTABLE; +``` + +--- + +## Protección de Inmutabilidad + +Triggers que previenen modificación: + +```sql +-- Bloquear UPDATE +CREATE TRIGGER protect_messages_update +BEFORE UPDATE ON log.messages +FOR EACH ROW EXECUTE FUNCTION log.prevent_update(); + +-- Bloquear DELETE +CREATE TRIGGER protect_messages_delete +BEFORE DELETE ON log.messages +FOR EACH ROW EXECUTE FUNCTION log.prevent_delete(); + +-- Igual para message_refs +``` + +--- + +## Contexto Ambiental (ambient) + +Campo JSONB para capturar estado del sistema en el momento del mensaje: + +```json +{ + "timezone": "Europe/Madrid", + "locale": "es-ES", + "working_directory": "/home/architect/project", + "git_branch": "main", + "active_services": ["gitea", "postgresql"], + "server": "ARCHITECT", + "timestamp_utc": "2026-01-01T12:00:00Z" +} +``` + +Solo se incluye cuando es relevante (nullable en la mayoría de mensajes). + +--- + +## Despliegue + +**Servidores activos:** + +| Servidor | IP | Base de Datos | Estado | +|----------|-----|---------------|--------| +| ARCHITECT | 69.62.126.110 | architect | ✅ Activo | +| DECK | 72.62.1.113 | tzzr | ✅ Activo | +| CORP | 92.112.181.188 | tzzr | ✅ Activo | + +**Extensiones requeridas:** +- `pgcrypto` - Para función SHA-256 +- `pgvector` - Para embeddings (opcional, instalado) + +**Comando de aplicación:** +```bash +sudo -u postgres psql -d [database] -c "$(curl -s http://localhost:3000/admin/context-manager/raw/branch/main/schemas/04_log.sql)" +``` + +--- + +## Flujo de Trabajo + +### 1. Insertar mensaje + +```sql +INSERT INTO log.messages ( + hash, session_hash, owner_id, players_id, + content, prev_hash, hashtags, created_at +) VALUES ( + log.sha256(...), 'session_abc...', 'owner_hash...', + ARRAY['player1_hash...', 'player2_hash...'], + 'Contenido del mensaje', 'prev_msg_hash...', + ARRAY['tag1_hash...'], NOW() +); +``` + +### 2. Añadir referencias de contexto + +```sql +INSERT INTO log.message_refs ( + message_hash, ref_hash, ref_type, position, thread_hash +) VALUES + ('msg_hash...', 'context_msg_1...', 'context', 1, 'thread...'), + ('msg_hash...', 'context_msg_2...', 'context', 2, 'thread...'), + ('msg_hash...', 'accountant_record...', 'accountant', 3, 'thread...'); +``` + +### 3. Consultar mensajes con contexto + +```sql +SELECT + m.content, + m.owner_id, + array_agg(r.ref_hash ORDER BY r.position) as context_refs +FROM log.messages m +LEFT JOIN log.message_refs r ON m.hash = r.message_hash +WHERE m.session_hash = 'session_abc...' +GROUP BY m.id, m.content, m.owner_id +ORDER BY m.created_at; +``` + +--- + +## Ubicación de Documentación + +| Ubicación | Ruta | +|-----------|------| +| Gitea | http://localhost:3000/admin/context-manager | +| R2 | s3://architect/system/context-manager/ | +| Skynet v8 | s3://architect/system/skynet v8/03_MODELO_DATOS/ | + +--- + +## Historial de Cambios + +| Versión | Fecha | Cambios | +|---------|-------|---------| +| 8.0 | 2025-12-30 | Versión inicial con 9 tablas | +| 8.1 | 2026-01-01 | Simplificación a 2 tablas (log.messages, log.message_refs). Integración con Sistema de Componentes TZZR. Nuevos campos: owner_id, players_id, master_player, flag_id, master_item_id, item_id, loc_id | + +--- + +**Documento generado por:** ARCHITECT +**Timestamp:** 2026-01-01 +**Versión:** Context Manager v8.1