diff --git a/00_VISION/filosofia.md b/00_VISION/filosofia.md new file mode 100644 index 0000000..bfc90c7 --- /dev/null +++ b/00_VISION/filosofia.md @@ -0,0 +1,105 @@ +# Filosofía del Sistema TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## 10 Principios Fundacionales + +### 1. Constructores, no gestores + +Las instancias Claude son **constructores de arquitecturas**, no gestores permanentes. + +- Cada instancia diseña y construye la arquitectura de un servidor +- Cuando la arquitectura esté madura, el servidor será **clonable e independiente** +- Funcionará sin necesidad de su instancia Claude +- Solo los servidores del propietario original mantienen conexión con Claude + +### 2. Descentralización operativa + +``` +Architect App (centralizado) → Diseña moldes + ↓ + Instancias reales (descentralizadas) + ↓ + Cada una con su CORP, su DECK, sus agentes +``` + +### 3. Referencias ligeras mediante hashes + +``` +DEFINICIÓN ORIGINAL → SHA-256 → HASH UNÍVOCO (64 chars) +``` + +El hash es una referencia ligera que arrastra toda la información del original sin duplicarla. + +### 4. Separación de planos + +| Plano | Nombre | Función | +|-------|--------|---------| +| **T-N → T0** | ITM (Ítems) | Lo ideal, la partitura | +| **Burocrático** | MST (Milestones) | Documentos, hitos, estados | +| **Físico** | BCK (Bloques) | Acciones, evidencias, trabajo real | + +### 5. Período flotante antes de inmutabilidad + +Los datos pasan por un período flotante que permite mejora antes del sellado definitivo. + +``` +Dato nuevo → Período flotante (24h) → Verificación SENTINEL → Sellado FELDMAN → Inmutable +``` + +### 6. Renombrabilidad de agentes + +Los componentes marcados como renombrables pueden personalizarse: + +``` +CLARA → "Lucía" +ALFRED → "Pepe" +PENNY → "Asistente" +``` + +Esto permite que cada usuario sienta el sistema como propio. + +### 7. GRACE nunca modifica + +GRACE extrae y comprende, pero **nunca modifica** el contenido original. + +> "Solo extrae y comprende, nunca modifica el contenido original." + +### 8. Auditoría dual: confía pero verifica + +SENTINEL opera en dos modos: + +| Modo | Frecuencia | Alcance | Tecnología | +|------|------------|---------|------------| +| **LIGHT** | Cada 5 min | Todos los registros | Reglas automáticas | +| **DEEP** | Cada 1 hora | Muestreo | LLM análisis | + +### 9. Zero-retention en interfaces móviles + +PACKET no almacena datos localmente. Todo va directo al servidor. + +### 10. Curación humana en Vision Builder + +``` +VALORES → OBJETIVOS → IMÁGENES IA → CURACIÓN HUMANA → LO QUE SOBREVIVE DEFINE QUIÉN ERES +``` + +--- + +## Modelo de Instancias + +**DECK** y **CORP** son plantillas. En producción habrá múltiples instancias: + +| Tipo | Ejemplos | +|------|----------| +| **DECK** | "Deck de Juan", "Deck de Victoria", "Deck de Pablo" | +| **CORP** | "Lacitos de Colores SL", "TZR Tech", "Acme Corp" | + +Cada instancia: +- Tiene su propio bucket de almacenamiento +- Puede renombrar sus agentes +- Opera de forma descentralizada +- Se conecta a servicios compartidos (GRACE, THE FACTORY, CIRCLE) diff --git a/00_VISION/glosario.md b/00_VISION/glosario.md new file mode 100644 index 0000000..3071f88 --- /dev/null +++ b/00_VISION/glosario.md @@ -0,0 +1,129 @@ +# Glosario TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Entidades Base + +| Término | Hash | Descripción | Estado | +|---------|------|-------------|--------| +| **HST** | h_maestro | Hash Semantic Tagging - Etiquetas semánticas visuales | Implementado | +| **ITM** | h_item | Ítems ideales - Definiciones del plano T0 | Planificado | +| **PLY** | h_player | Players - Identidad de actores | Planificado | +| **LOC** | h_loc | Locations - Ubicaciones geográficas | Planificado | +| **FLG** | h_flag | Flags - Marcos jurídicos y banderas | Planificado | + +--- + +## Planos de Datos + +| Plano | Tabla | Descripción | +|-------|-------|-------------| +| **T0** | items | Lo ideal, la partitura, estado futuro deseado | +| **MST** | milestones | Plano burocrático - documentos, hitos, estados | +| **BCK** | bloques | Plano físico - acciones, evidencias, trabajo real | + +--- + +## Agentes + +### Ingesta +| Agente | Servidor | Puerto | Descripción | +|--------|----------|--------|-------------| +| **CLARA** | DECK | 5051 | Recoge información personal, log inmutable | +| **MARGARET** | CORP | 5051 | Recoge información corporativa, log inmutable | + +### Orquestación +| Agente | Servidor | Puerto | Descripción | +|--------|----------|--------|-------------| +| **ALFRED** | DECK | 5052 | Flujos predefinidos personales | +| **JARED** | CORP | 5052 | Flujos predefinidos corporativos (más potente) | + +### Procesamiento +| Agente | Servidor | Puerto | Descripción | +|--------|----------|--------|-------------| +| **MASON** | CORP | 5053 | Enriquecimiento, ventana flotante 24h | +| **FELDMAN** | CORP | 5054 | Consolidación final, blockchain, inmutable | +| **SENTINEL** | - | - | Auditoría LIGHT (5min) + DEEP (1h) [planificado] | + +--- + +## Servicios GPU (RunPod) + +| Servicio | Endpoint | Descripción | Estado | +|----------|----------|-------------|--------| +| **GRACE** | r00x4g3rrwkbyh | IA cognitiva, extracción (18 módulos) | Bloqueado | +| **PENNY** | 0mxhaokgsmgee3 | Asistente personal, generación texto | Planificado | +| **FACTORY** | ddnuk6y35zi56a | Generación iterativa | Planificado | + +--- + +## Servidores + +| Servidor | IP | Rol | +|----------|-----|-----| +| **ARCHITECT** | 69.62.126.110 | Coordinador central, Gitea, PostgreSQL | +| **DECK** | 72.62.1.113 | Servidor personal | +| **CORP** | 92.112.181.188 | Servidor empresarial | +| **HST** | 72.62.2.84 | API tags semánticos | +| **LOCKER** | Cloudflare R2 | Almacenamiento (5 buckets) | + +--- + +## Hashes y Identificadores + +| Prefijo | Tipo | Ejemplo | Descripción | +|---------|------|---------|-------------| +| **h_maestro** | SHA-256 | `a1b2c3...` | Hash de tag HST | +| **h_instancia** | SHA-256 | `d4e5f6...` | Identidad servidor/contexto | +| **h_entrada** | SHA-256 | `g7h8i9...` | Hash contenedor ingesta | +| **h_bloque** | SHA-256 | `j0k1l2...` | Hash de bloque BCK | +| **h_milestone** | SHA-256 | `m3n4o5...` | Hash de milestone MST | +| **H_proyecto** | Prefijo | `H_tzzr_genesis` | Identificador proyecto legible | + +--- + +## Interfaces + +| Interfaz | Tipo | Descripción | +|----------|------|-------------| +| **PACKET** | App móvil | Captura multimedia, zero-retention | +| **Vision Builder** | Web | Diseño de vida mediante curación visual | +| **Mind Link** | Web | Compartición de información | + +--- + +## Protocolos + +| Protocolo | Versión | Descripción | +|-----------|---------|-------------| +| **S-CONTRACT** | v2.1 | Comunicación con IAs (context, deployment, envelope, payload) | +| **locker://** | - | Referencias almacenamiento R2 | + +--- + +## Grupos HST + +| Grupo | Cantidad | Descripción | +|-------|----------|-------------| +| **hst** | 639 | Tags del sistema base | +| **spe** | 145 | Tags específicos | +| **vsn** | 84 | Visiones | +| **flg** | 65 | Banderas/países | +| **vue** | 21 | Vistas | +| **hsu** | - | Tags usuario (extensión) | + +--- + +## Estados de Pipeline + +| Estado | Etapa | Descripción | +|--------|-------|-------------| +| **recibido** | CLARA/MARGARET | Contenedor ingresado, inmutable | +| **en_edicion** | MASON | Usuario enriqueciendo datos | +| **listo** | MASON | Listo para consolidar | +| **pendiente** | FELDMAN | En cola de consolidación | +| **consolidado** | FELDMAN | Registrado en milestone/bloque | +| **sellado** | NOTARIO | Blockchain confirmado | diff --git a/01_ARQUITECTURA/overview.md b/01_ARQUITECTURA/overview.md new file mode 100644 index 0000000..e918db3 --- /dev/null +++ b/01_ARQUITECTURA/overview.md @@ -0,0 +1,154 @@ +# Arquitectura Overview + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Diagrama General + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ CAPA DE COORDINACIÓN │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ ARCHITECT (69.62.126.110) │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌───────────────┐ │ │ +│ │ │PostgreSQL│ │ Gitea │ │Orchestrator│ │ Infisical │ │ │ +│ │ │ central │ │ 25 repos │ │ v5 │ │ Secrets │ │ │ +│ │ └──────────┘ └──────────┘ └────────────┘ └───────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + │ │ │ + ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ CAPA DE SERVIDORES │ +│ │ +│ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │ +│ │ DECK │ │ CORP │ │ HST │ │ +│ │ 72.62.1.113 │ │ 92.112.181.188 │ │ 72.62.2.84 │ │ +│ │ │ │ │ │ │ │ +│ │ CLARA :5051 │ │ MARGARET :5051 │ │ 973 tags │ │ +│ │ ALFRED :5052 │ │ JARED :5052 │ │ API pública │ │ +│ │ │ │ MASON :5053 │ │ Directus :8055 │ │ +│ │ Mailcow │ │ FELDMAN :5054 │ │ │ │ +│ │ Vaultwarden │ │ │ │ │ │ +│ │ Directus │ │ Odoo │ │ │ │ +│ └───────────────────┘ │ Nextcloud │ └───────────────────┘ │ +│ │ └───────────────────┘ │ │ +│ │ │ │ │ +│ └─────────────────────────┼──────────────────────┘ │ +│ │ │ +└───────────────────────────────────┼─────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ CAPA DE ALMACENAMIENTO │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ Cloudflare R2 │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │ +│ │ │architect │ │ deck │ │ corp │ │ hst │ │ locker │ │ │ +│ │ │ backups │ │ archivos │ │ archivos │ │ imágenes │ │ general│ │ │ +│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ CAPA GPU (RunPod) │ +│ Estado: BLOQUEADO - Workers no inician │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ GRACE │ │ PENNY │ │ FACTORY │ │ +│ │ 18 módulos│ │ texto │ │generación│ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Flujo de Datos + +``` +PACKET (App móvil) + │ + │ POST /ingest + │ Content-Type: multipart/form-data + │ X-Auth-Key: {h_instancia} + │ + ▼ +┌─────────────────────────────────────────┐ +│ CLARA (DECK) / MARGARET (CORP) │ +│ │ +│ 1. Validar h_instancia │ +│ 2. Calcular h_entrada (SHA-256) │ +│ 3. Subir archivos a R2 │ +│ 4. Insertar en clara_log/margaret_log │ +│ 5. Estado: 'recibido' (inmutable) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ ALFRED (DECK) / JARED (CORP) │ +│ │ +│ 1. Aplicar flujos predefinidos │ +│ 2. Ejecutar reglas automáticas │ +│ 3. Enviar a MASON si requiere mejora │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ MASON │ +│ │ +│ 1. Recibir de ALFRED/JARED │ +│ 2. Ventana flotante 24h │ +│ 3. Usuario enriquece datos │ +│ 4. [Futuro] GRACE extrae información │ +│ 5. Enviar a FELDMAN cuando listo │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ FELDMAN │ +│ │ +│ 1. Recibir en feldman_cola │ +│ 2. Validar reglas (M-001, M-002, M-003)│ +│ 3. Crear milestone o bloque │ +│ 4. Calcular hash_contenido │ +│ 5. Encadenar (hash_previo) │ +│ 6. [Futuro] Merkle tree, blockchain │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ SENTINEL (planificado) │ +│ │ +│ LIGHT: Cada 5 min, reglas automáticas │ +│ DEEP: Cada 1 hora, muestreo con LLM │ +└─────────────────────────────────────────┘ +``` + +--- + +## Comunicación Entre Servidores + +| Origen | Destino | Protocolo | Puerto | Propósito | +|--------|---------|-----------|--------|-----------| +| DECK | ARCHITECT | SSH/Git | 2222 | Push repos | +| DECK | R2 | HTTPS | 443 | Almacenamiento | +| CORP | ARCHITECT | SSH/Git | 2222 | Push repos | +| CORP | R2 | HTTPS | 443 | Almacenamiento | +| HST | ARCHITECT | SSH | 22 | Administración | +| ARCHITECT | DECK | SSH | 22 | Deploy | +| ARCHITECT | CORP | SSH | 22 | Deploy | + +--- + +## Bases de Datos + +| Servidor | Database | Tablas Principales | +|----------|----------|--------------------| +| ARCHITECT | architect | context_blocks, agents, creds_* | +| DECK | tzzr | clara_log, alfred_executions | +| CORP | corp | margaret_log, mason_workspace, feldman_* | +| HST | hst_images | hst_tags, hst_trees | diff --git a/01_ARQUITECTURA/servidores.md b/01_ARQUITECTURA/servidores.md new file mode 100644 index 0000000..00b4f8f --- /dev/null +++ b/01_ARQUITECTURA/servidores.md @@ -0,0 +1,230 @@ +# Servidores TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## ARCHITECT (69.62.126.110) + +**Rol:** Coordinador central del sistema + +### Servicios + +| Servicio | Puerto | Estado | +|----------|--------|--------| +| PostgreSQL | 5432 | Operativo | +| Gitea | 3000 (HTTP), 2222 (SSH) | Operativo | +| Orchestrator App | 5050 | Operativo | +| Infisical | 8082 | Operativo | + +### PostgreSQL (database: architect) + +| Tabla | Descripción | +|-------|-------------| +| context_blocks | 30 bloques de contexto atómicos | +| agent_context_index | Asignaciones agente-bloque | +| agents | 6 agentes definidos | +| creds_* | 6 tablas de credenciales | +| s_contract_contexts | Contextos IA | +| s_contract_datasets | Datasets IA | + +### Acceso + +```bash +# SSH +ssh orchestrator@69.62.126.110 + +# PostgreSQL +sudo -u postgres psql -d architect + +# Gitea +http://localhost:3000 +``` + +--- + +## DECK (72.62.1.113) + +**Rol:** Servidor personal + +### Servicios + +| Servicio | Puerto | Estado | +|----------|--------|--------| +| CLARA | 5051 | Operativo | +| ALFRED | 5052 | Operativo | +| Mailcow (15 containers) | SMTP, IMAP | Operativo | +| Directus | 8055 | Operativo | +| FileBrowser | 8082 | Operativo | +| Shlink | 8083 | Operativo | +| Vaultwarden | 8085 | Operativo | +| ntfy | 8080 | Operativo | + +### PostgreSQL (database: tzzr) + +| Tabla | Descripción | +|-------|-------------| +| clara_log | Log inmutable de ingesta | +| deck_visiones | Visiones personales | +| deck_milestones | Milestones personales | +| deck_acciones | Acciones | +| deck_habitos | Hábitos | +| deck_bck | Bloques | + +### Docker Containers + +``` +mailcowdockerized-acme-mailcow-1 +mailcowdockerized-clamd-mailcow-1 +mailcowdockerized-dovecot-mailcow-1 +mailcowdockerized-mysql-mailcow-1 +mailcowdockerized-netfilter-mailcow-1 +mailcowdockerized-nginx-mailcow-1 +mailcowdockerized-olefy-mailcow-1 +mailcowdockerized-php-fpm-mailcow-1 +mailcowdockerized-postfix-mailcow-1 +mailcowdockerized-redis-mailcow-1 +mailcowdockerized-rspamd-mailcow-1 +mailcowdockerized-sogo-mailcow-1 +mailcowdockerized-solr-mailcow-1 +mailcowdockerized-unbound-mailcow-1 +mailcowdockerized-watchdog-mailcow-1 +clara-clara +alfred-alfred +directus +filebrowser +shlink +vaultwarden +ntfy +``` + +### Acceso + +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 +``` + +--- + +## CORP (92.112.181.188) + +**Rol:** Servidor empresarial + +### Servicios + +| Servicio | Puerto | Estado | +|----------|--------|--------| +| MARGARET | 5051 | Operativo | +| JARED | 5052 | Operativo | +| MASON | 5053 | Operativo | +| FELDMAN | 5054 | Operativo | +| PostgreSQL | 5432 | Operativo | +| Directus | 8055 | Operativo | +| Nextcloud | 8080 | Operativo | +| Vaultwarden | 8081 | Operativo | +| Odoo | 8069 | Operativo | +| Caddy | 80/443 | Operativo | + +### PostgreSQL (database: corp) + +| Tabla | Descripción | +|-------|-------------| +| margaret_log | Log inmutable de ingesta | +| mason_workspace | Espacio de enriquecimiento | +| feldman_cola | Cola de consolidación | +| feldman_bloques | Bloques inmutables | +| feldman_validaciones | Auditoría validaciones | +| milestones | Plano MST | +| bloques | Plano BCK | +| hst_mirror | Mirror de tags HST | + +### Acceso + +```bash +ssh -i ~/.ssh/tzzr root@92.112.181.188 +``` + +--- + +## HST (72.62.2.84) + +**Rol:** API de tags semánticos + +### Servicios + +| Servicio | Puerto | Estado | +|----------|--------|--------| +| Nginx | 80/443 | Operativo | +| Directus | 8055 | Operativo | +| PostgreSQL | 5432 | Operativo | + +### Estadísticas HST + +| Grupo | Cantidad | +|-------|----------| +| hst | 639 | +| spe | 145 | +| vsn | 84 | +| flg | 65 | +| vue | 21 | +| **Total** | **973** | + +### API + +``` +https://tzrtech.org/{h_maestro}.png # Imagen de tag +``` + +### Acceso + +```bash +ssh -i ~/.ssh/tzzr root@72.62.2.84 +``` + +--- + +## LOCKER (Cloudflare R2) + +**Rol:** Almacenamiento distribuido + +### Endpoint + +``` +https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +``` + +### Buckets + +| Bucket | Uso | +|--------|-----| +| architect | Backups Gitea, configs, GPU services | +| deck | Archivos personales (CLARA) | +| corp | Archivos empresariales (MARGARET) | +| hst | Imágenes de tags | +| locker | Almacenamiento general/temporal | + +### Estructura GPU Services + +``` +s3://architect/gpu-services/ +├── base/ +│ └── bootstrap.sh +├── grace/ +│ └── code/handler.py +├── penny/ +│ └── code/handler.py +└── factory/ + └── code/handler.py +``` + +--- + +## Resumen de IPs + +| Servidor | IP Pública | IP Interna | +|----------|------------|------------| +| ARCHITECT | 69.62.126.110 | localhost | +| DECK | 72.62.1.113 | - | +| CORP | 92.112.181.188 | - | +| HST | 72.62.2.84 | - | diff --git a/02_MODELO_DATOS/entidades.md b/02_MODELO_DATOS/entidades.md new file mode 100644 index 0000000..eeee58c --- /dev/null +++ b/02_MODELO_DATOS/entidades.md @@ -0,0 +1,237 @@ +# Entidades Base TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Visión General + +Las entidades base son los bloques fundamentales del sistema. Cada una tiene un hash único SHA-256 que la identifica de forma unívoca. + +``` +DEFINICIÓN ORIGINAL → SHA-256 → h_{tipo} (64 chars) +``` + +--- + +## HST (Hash Semantic Tagging) + +**Estado:** Implementado +**Servidor:** HST (72.62.2.84) +**Hash:** h_maestro + +### Fórmula + +``` +h_maestro = SHA-256(grupo:ref) +``` + +### Grupos + +| Grupo | Cantidad | Descripción | +|-------|----------|-------------| +| hst | 639 | Tags del sistema base | +| spe | 145 | Tags específicos | +| vsn | 84 | Visiones | +| flg | 65 | Banderas/países | +| vue | 21 | Vistas | + +### Schema + +```sql +CREATE TABLE hst_tags ( + id SERIAL PRIMARY KEY, + ref VARCHAR(100) UNIQUE NOT NULL, + h_maestro VARCHAR(64) UNIQUE NOT NULL, + grupo VARCHAR(50) NOT NULL, + nombre_es VARCHAR(255), + nombre_en VARCHAR(255), + descripcion TEXT, + imagen_url TEXT, + activo BOOLEAN DEFAULT true, + version INTEGER DEFAULT 1, + created_at TIMESTAMP DEFAULT NOW() +); +``` + +### Ejemplo + +```json +{ + "ref": "person", + "h_maestro": "a1b2c3d4e5f6...", + "grupo": "hst", + "nombre_es": "Persona", + "nombre_en": "Person", + "imagen_url": "https://tzrtech.org/a1b2c3d4e5f6...png" +} +``` + +--- + +## ITM (Items - Plano Ideal) + +**Estado:** Planificado +**Servidor:** Por definir +**Hash:** h_item + +### Concepto + +Los ITM representan el estado ideal futuro. Son la "partitura" que guía las acciones. + +### Schema Propuesto + +```sql +CREATE TABLE items ( + id BIGSERIAL PRIMARY KEY, + h_item VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + secuencia BIGINT NOT NULL, + hash_previo VARCHAR(64), + hash_contenido VARCHAR(64), + tipo_item VARCHAR(50) NOT NULL, -- accion_ideal, objetivo, requerimiento + titulo VARCHAR(255) NOT NULL, + descripcion TEXT, + criterios_aceptacion JSONB, + metadata JSONB, + proyecto_tag VARCHAR(64), + etiquetas JSONB, + estado VARCHAR(20) DEFAULT 'draft', -- draft, vigente, obsoleto + created_at TIMESTAMPTZ DEFAULT NOW(), + created_by VARCHAR(64), + UNIQUE (h_instancia, secuencia) +); +``` + +--- + +## PLY (Players - Identidad) + +**Estado:** Planificado +**Servidor:** Por definir +**Hash:** h_player + +### Concepto + +Los PLY representan la identidad de actores en el sistema (personas, empresas, agentes). + +### Schema Propuesto + +```sql +CREATE TABLE players ( + id BIGSERIAL PRIMARY KEY, + h_player VARCHAR(64) UNIQUE NOT NULL, + tipo VARCHAR(50) NOT NULL, -- persona, empresa, agente + nombre VARCHAR(255) NOT NULL, + email VARCHAR(255), + metadata JSONB, + activo BOOLEAN DEFAULT true, + created_at TIMESTAMPTZ DEFAULT NOW() +); +``` + +--- + +## LOC (Locations - Ubicaciones) + +**Estado:** Planificado +**Servidor:** Por definir +**Hash:** h_loc + +### Concepto + +Los LOC representan ubicaciones geográficas con precisión variable. + +### Schema Propuesto + +```sql +CREATE TABLE locations ( + id BIGSERIAL PRIMARY KEY, + h_loc VARCHAR(64) UNIQUE NOT NULL, + nombre VARCHAR(255), + lat DECIMAL(10, 8), + lon DECIMAL(11, 8), + precision_metros INTEGER, + tipo VARCHAR(50), -- punto, area, ruta + metadata JSONB, + created_at TIMESTAMPTZ DEFAULT NOW() +); +``` + +### Fórmula Hash + +``` +h_loc = SHA-256(lat:lon:precision) +``` + +--- + +## FLG (Flags - Marcos Jurídicos) + +**Estado:** Planificado +**Servidor:** Por definir +**Hash:** h_flag + +### Concepto + +Los FLG representan marcos jurídicos, normativas, países. + +### Notas + +Actualmente existe un grupo `flg` en HST con 65 tags de países, pero no como entidad independiente. + +--- + +## Tags de Usuario (Extensiones) + +Los usuarios pueden crear sus propios tags como extensiones de HST. + +| Tabla | Descripción | +|-------|-------------| +| hsu | HST Usuario | +| spu | SPE Usuario | +| vsu | VSN Usuario | +| vuu | VUE Usuario | +| pju | Proyectos Usuario | +| flu | FLG Usuario | + +### Schema + +```sql +CREATE TABLE hsu ( + id SERIAL PRIMARY KEY, + ref VARCHAR(10) NOT NULL, + h_usuario VARCHAR(64) NOT NULL, + nombre VARCHAR(255) NOT NULL, + user_id INTEGER REFERENCES users(id), + metadata JSONB, + activo BOOLEAN DEFAULT true, + created_at TIMESTAMP DEFAULT NOW(), + UNIQUE (user_id, ref) +); +``` + +--- + +## Relaciones Entre Entidades + +``` +ITM (ideal) + │ + ├──► h_maestro (HST tags) + ├──► h_player (PLY responsable) + ├──► h_loc (LOC ubicación) + └──► h_flag (FLG normativa) + +MST (milestone) + │ + ├──► item_asociado (ITM) + └──► h_maestro (HST tags) + +BCK (bloque) + │ + ├──► item_asociado (ITM) + ├──► milestone_asociado (MST) + └──► h_maestro (HST tags) +``` diff --git a/02_MODELO_DATOS/planos.md b/02_MODELO_DATOS/planos.md new file mode 100644 index 0000000..0f90073 --- /dev/null +++ b/02_MODELO_DATOS/planos.md @@ -0,0 +1,309 @@ +# Planos de Datos TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Visión General + +El sistema TZZR utiliza tres planos conceptuales para organizar la información: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ T0 - PLANO IDEAL │ +│ ITM (Items): Objetivos, acciones ideales, requerimientos │ +│ Estado: PLANIFICADO - Sin implementación actual │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ materializa +┌─────────────────────────────────────────────────────────────────┐ +│ MST - MILESTONES │ +│ Compromisos futuros con fecha de vencimiento │ +│ Estado: IMPLEMENTADO en CORP (tabla milestones) │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ cumple/genera +┌─────────────────────────────────────────────────────────────────┐ +│ BCK - BLOQUES │ +│ Hechos inmutables del pasado (blockchain-ready) │ +│ Estado: IMPLEMENTADO en CORP (tabla bloques) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## T0 - Plano Ideal (ITM) + +### Concepto + +El plano T0 contiene los Items (ITM) que representan el estado ideal futuro. Son la "partitura" que guía las acciones. + +### Tipos de Items + +| Tipo | Descripción | +|------|-------------| +| accion_ideal | Acción que debería ejecutarse | +| objetivo | Meta a alcanzar | +| requerimiento | Requisito a cumplir | + +### Estado de Implementación + +**PLANIFICADO** - Schema definido pero sin tablas creadas. + +### Schema Propuesto + +```sql +CREATE TABLE items ( + id BIGSERIAL PRIMARY KEY, + h_item VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + secuencia BIGINT NOT NULL, + hash_previo VARCHAR(64), + hash_contenido VARCHAR(64), + tipo_item VARCHAR(50) NOT NULL, + titulo VARCHAR(255) NOT NULL, + descripcion TEXT, + criterios_aceptacion JSONB, + metadata JSONB, + proyecto_tag VARCHAR(64), + etiquetas JSONB, + estado VARCHAR(20) DEFAULT 'draft', + created_at TIMESTAMPTZ DEFAULT NOW(), + created_by VARCHAR(64), + UNIQUE (h_instancia, secuencia) +); +``` + +--- + +## MST - Milestones + +### Concepto + +Los milestones representan compromisos con fecha futura. Tienen un período flotante de 24 horas antes de consolidarse. + +### Estado de Implementación + +**IMPLEMENTADO** en CORP (database: corp). + +### Schema Actual + +```sql +-- Tabla: milestones (CORP) +CREATE TABLE milestones ( + id BIGSERIAL PRIMARY KEY, + h_milestone VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + secuencia BIGINT NOT NULL, + hash_previo VARCHAR(64), + hash_contenido VARCHAR(64), + tipo_milestone VARCHAR(50) NOT NULL, + fecha_vencimiento DATE NOT NULL, + descripcion TEXT, + metadata JSONB, + proyecto_tag VARCHAR(64), + etiquetas JSONB, + estado VARCHAR(20) DEFAULT 'draft', + created_at TIMESTAMPTZ DEFAULT NOW(), + modified_at TIMESTAMPTZ, + created_by VARCHAR(64), + UNIQUE (h_instancia, secuencia) +); +``` + +### Tipos de Milestones + +| Tipo | Descripción | +|------|-------------| +| compromiso | Compromiso de entrega | +| deadline | Fecha límite | +| evento | Evento programado | +| recordatorio | Recordatorio futuro | + +### Fórmula Hash + +``` +h_milestone = SHA-256(h_instancia:secuencia:tipo:contenido) +``` + +### Período Flotante + +- **Duración:** 24 horas desde creación +- **Durante período:** Modificable vía MASON +- **Después:** Inmutable, solo lectura + +**Nota:** Actualmente no hay scheduler que procese la expiración automáticamente. + +--- + +## BCK - Bloques + +### Concepto + +Los bloques son registros inmutables de hechos pasados. Cada bloque está encadenado al anterior mediante hash, preparando la infraestructura para blockchain. + +### Estado de Implementación + +**IMPLEMENTADO** en CORP (database: corp). + +### Schema Actual + +```sql +-- Tabla: bloques (CORP) +CREATE TABLE bloques ( + id BIGSERIAL PRIMARY KEY, + h_bloque VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + secuencia BIGINT NOT NULL, + hash_previo VARCHAR(64), + hash_contenido VARCHAR(64) NOT NULL, + tipo_bloque VARCHAR(50) NOT NULL, + contenido JSONB NOT NULL, + metadata JSONB, + item_asociado VARCHAR(64), + milestone_asociado VARCHAR(64), + h_maestro JSONB, + h_player VARCHAR(64), + h_loc VARCHAR(64), + h_flag VARCHAR(64), + estado VARCHAR(20) DEFAULT 'consolidado', + created_at TIMESTAMPTZ DEFAULT NOW(), + validated_at TIMESTAMPTZ, + validated_by VARCHAR(64), + UNIQUE (h_instancia, secuencia) +); +``` + +### Tipos de Bloques + +| Tipo | Descripción | +|------|-------------| +| transaccion | Transacción económica | +| documento | Documento consolidado | +| evento | Evento registrado | +| milestone_cumplido | Milestone que se cumplió | + +### Fórmula Hash + +``` +h_bloque = SHA-256(h_instancia:secuencia:hash_previo:hash_contenido) +hash_contenido = SHA-256(contenido_serializado) +``` + +### Encadenamiento + +``` +Bloque N-1 Bloque N +┌──────────────────┐ ┌──────────────────┐ +│ h_bloque: abc123 │ ──────► │ hash_previo: │ +│ hash_contenido: │ │ abc123 │ +│ def456 │ │ h_bloque: ghi789 │ +│ secuencia: 1 │ │ secuencia: 2 │ +└──────────────────┘ └──────────────────┘ +``` + +--- + +## Flujo Entre Planos + +``` +Usuario crea ITM + │ + ▼ +ITM (T0) "Objetivo: Completar proyecto X" + │ + │ materializa + ▼ +MST "Milestone: Entrega módulo 1 - 2024-01-15" + │ + │ [período flotante 24h] + │ + ▼ +MASON (enriquecimiento) + │ + ▼ +FELDMAN (validación) + │ + │ cumple/genera + ▼ +BCK "Bloque: Módulo 1 entregado - 2024-01-14" + │ + ▼ +Inmutable ✓ +``` + +--- + +## Tablas de Procesamiento + +### FELDMAN Cola + +```sql +-- feldman_cola: Elementos pendientes de validación +CREATE TABLE feldman_cola ( + id BIGSERIAL PRIMARY KEY, + tipo VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque' + h_entrada VARCHAR(64) NOT NULL, + contenido JSONB NOT NULL, + prioridad INTEGER DEFAULT 0, + estado VARCHAR(20) DEFAULT 'pendiente', + created_at TIMESTAMPTZ DEFAULT NOW(), + processed_at TIMESTAMPTZ +); +``` + +### FELDMAN Validaciones + +```sql +-- feldman_validaciones: Auditoría de validaciones +CREATE TABLE feldman_validaciones ( + id BIGSERIAL PRIMARY KEY, + h_entrada VARCHAR(64) NOT NULL, + regla VARCHAR(50) NOT NULL, -- M-001, M-002, M-003 + resultado BOOLEAN NOT NULL, + mensaje TEXT, + validated_at TIMESTAMPTZ DEFAULT NOW() +); +``` + +--- + +## Reglas de Validación FELDMAN + +| Regla | Nombre | Descripción | +|-------|--------|-------------| +| M-001 | Hash único | h_bloque/h_milestone no existe previamente | +| M-002 | Encadenamiento | hash_previo apunta a bloque existente | +| M-003 | Integridad | hash_contenido = SHA-256(contenido) | + +--- + +## Decisiones de Diseño + +### D-004: Eliminar columnas duplicadas + +**Problema:** Milestones tienen columnas + JSONB duplicados. + +**Decisión:** Mantener metadatos solo en JSONB `metadata`. + +### D-007: Timestamps UTC + +**Problema:** Inconsistencia en zonas horarias. + +**Decisión:** Usar `TIMESTAMPTZ` y almacenar en UTC. + +--- + +## Roadmap + +### Implementado +- [x] Tabla milestones en CORP +- [x] Tabla bloques en CORP +- [x] Fórmulas hash definidas + +### Pendiente +- [ ] Tabla items (T0) +- [ ] Scheduler para período flotante +- [ ] Merkle tree para verificación +- [ ] Smart contract blockchain (futuro) diff --git a/03_COMPONENTES/agentes/clara-margaret.md b/03_COMPONENTES/agentes/clara-margaret.md new file mode 100644 index 0000000..2d47bc6 --- /dev/null +++ b/03_COMPONENTES/agentes/clara-margaret.md @@ -0,0 +1,311 @@ +# CLARA y MARGARET - Agentes de Ingesta + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Resumen + +| Aspecto | CLARA | MARGARET | +|---------|-------|----------| +| Servidor | DECK (72.62.1.113) | CORP (92.112.181.188) | +| Puerto | 5051 | 5051 | +| Dominio | Personal | Empresarial | +| Base de datos | tzzr | corp | +| Tabla log | clara_log | margaret_log | +| Bucket R2 | deck | corp | +| Estado | Operativo | Operativo | + +--- + +## Arquitectura + +``` +PACKET (App móvil) + │ + │ POST /ingest + │ Content-Type: multipart/form-data + │ X-Auth-Key: {h_instancia} + │ + ▼ +┌─────────────────────────────────────────┐ +│ CLARA (Personal) / MARGARET (Corp) │ +│ │ +│ 1. Validar h_instancia │ +│ 2. Calcular h_entrada (SHA-256) │ +│ 3. Subir archivos a R2 │ +│ 4. Insertar en log (inmutable) │ +│ 5. Estado: 'recibido' │ +│ 6. Responder con h_entrada │ +└─────────────────────────────────────────┘ + │ + ▼ + ALFRED / JARED (siguiente paso) +``` + +--- + +## Endpoint de Ingesta + +### Request + +```http +POST /ingest HTTP/1.1 +Host: deck.example.com:5051 +Content-Type: multipart/form-data +X-Auth-Key: {h_instancia} + +--boundary +Content-Disposition: form-data; name="tipo" + +documento +--boundary +Content-Disposition: form-data; name="archivo"; filename="doc.pdf" +Content-Type: application/pdf + +{binary data} +--boundary-- +``` + +### Response + +```json +{ + "success": true, + "h_entrada": "a1b2c3d4e5f6...", + "estado": "recibido", + "timestamp": "2024-12-24T12:00:00Z" +} +``` + +--- + +## Cálculo de h_entrada + +```python +import hashlib +import json + +def calcular_h_entrada(h_instancia, tipo, contenido_bytes, timestamp): + """ + Calcula el hash único de entrada. + + h_entrada = SHA-256(h_instancia:tipo:sha256(contenido):timestamp) + """ + hash_contenido = hashlib.sha256(contenido_bytes).hexdigest() + + data = f"{h_instancia}:{tipo}:{hash_contenido}:{timestamp}" + + return hashlib.sha256(data.encode()).hexdigest() +``` + +--- + +## Schema: clara_log / margaret_log + +```sql +CREATE TABLE clara_log ( + id BIGSERIAL PRIMARY KEY, + h_entrada VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + tipo VARCHAR(50) NOT NULL, + contenido_url TEXT, -- locker://deck/{h_entrada}/archivo + contenido_hash VARCHAR(64), -- SHA-256 del contenido + metadata JSONB, + estado VARCHAR(20) DEFAULT 'recibido', + created_at TIMESTAMPTZ DEFAULT NOW(), + processed_at TIMESTAMPTZ, + processed_by VARCHAR(50) -- 'alfred' o 'manual' +); + +-- margaret_log tiene schema idéntico +CREATE TABLE margaret_log ( + id BIGSERIAL PRIMARY KEY, + h_entrada VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + tipo VARCHAR(50) NOT NULL, + contenido_url TEXT, + contenido_hash VARCHAR(64), + metadata JSONB, + estado VARCHAR(20) DEFAULT 'recibido', + created_at TIMESTAMPTZ DEFAULT NOW(), + processed_at TIMESTAMPTZ, + processed_by VARCHAR(50) +); +``` + +--- + +## Estados del Log + +| Estado | Descripción | +|--------|-------------| +| recibido | Ingesta completada, pendiente procesamiento | +| procesando | ALFRED/JARED está procesando | +| enviado_mason | Enviado a MASON para enriquecimiento | +| consolidado | Procesado por FELDMAN | +| error | Error en procesamiento | + +--- + +## Almacenamiento en R2 + +### Estructura de URLs + +``` +locker://deck/{h_entrada}/archivo.ext +locker://corp/{h_entrada}/archivo.ext +``` + +### Implementación + +```python +import boto3 + +def subir_a_r2(bucket, h_entrada, archivo_bytes, filename): + """Sube archivo a Cloudflare R2.""" + + s3 = boto3.client( + 's3', + endpoint_url='https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com', + aws_access_key_id=R2_ACCESS_KEY, + aws_secret_access_key=R2_SECRET_KEY + ) + + key = f"{h_entrada}/{filename}" + + s3.put_object( + Bucket=bucket, + Key=key, + Body=archivo_bytes + ) + + return f"locker://{bucket}/{key}" +``` + +--- + +## Validación de h_instancia + +```python +def validar_instancia(h_instancia): + """ + Valida que h_instancia exista y esté activa. + + TODO: Implementar tabla de instancias activas. + Actualmente: Validación básica de formato. + """ + if not h_instancia: + return False + + if len(h_instancia) != 64: + return False + + # TODO: Consultar tabla de instancias + return True +``` + +--- + +## Tipos de Ingesta Soportados + +| Tipo | Descripción | Extensiones | +|------|-------------|-------------| +| documento | Documentos | pdf, doc, docx | +| imagen | Imágenes | jpg, png, gif | +| audio | Audio | mp3, wav, m4a | +| video | Video | mp4, mov | +| texto | Texto plano | txt, md | +| json | Datos estructurados | json | + +--- + +## Configuración + +### Variables de Entorno + +```bash +# CLARA (.env en /opt/clara/) +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=tzzr +DB_USER=clara +DB_PASSWORD=**** + +R2_ENDPOINT=https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +R2_ACCESS_KEY=**** +R2_SECRET_KEY=**** +R2_BUCKET=deck + +# MARGARET (.env en /opt/margaret/) +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=corp +DB_USER=margaret +DB_PASSWORD=**** + +R2_BUCKET=corp +``` + +### Docker Compose + +```yaml +# CLARA +version: '3.8' +services: + clara: + container_name: clara-clara + image: tzzr/clara:latest + ports: + - "5051:5051" + env_file: + - .env + restart: unless-stopped +``` + +--- + +## Diferencias CLARA vs MARGARET + +| Aspecto | CLARA | MARGARET | +|---------|-------|----------| +| Uso | Personal | Empresarial | +| Volumen | Bajo | Alto | +| Privacidad | Máxima | Compartida (empresa) | +| Integración | ALFRED | JARED → MASON → FELDMAN | +| Backup | deck bucket | corp bucket | + +--- + +## Seguridad + +### Actual +- Autenticación por h_instancia +- Comunicación HTTP (sin TLS interno) +- .env con permisos 644 (**CRÍTICO: cambiar a 600**) + +### Recomendado +- TLS interno con certificados +- Rate limiting +- Validación de tipos MIME +- Escaneo antivirus (ClamAV) + +--- + +## Monitoreo + +### Logs +```bash +# CLARA +docker logs clara-clara -f + +# MARGARET +docker logs margaret-margaret -f +``` + +### Métricas Sugeridas +- Ingestas por minuto +- Tamaño promedio de archivos +- Tiempo de procesamiento +- Errores por tipo diff --git a/03_COMPONENTES/agentes/feldman.md b/03_COMPONENTES/agentes/feldman.md new file mode 100644 index 0000000..2cdaabd --- /dev/null +++ b/03_COMPONENTES/agentes/feldman.md @@ -0,0 +1,390 @@ +# FELDMAN - Agente de Consolidación + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Resumen + +| Aspecto | Valor | +|---------|-------| +| Servidor | CORP (92.112.181.188) | +| Puerto | 5054 | +| Base de datos | corp | +| Tablas | feldman_cola, feldman_bloques, feldman_validaciones | +| Estado | Operativo | + +--- + +## Rol en el Sistema + +FELDMAN es el "notario" del sistema: valida y consolida datos en bloques inmutables. + +``` +MASON (enriquecido) + │ + ▼ +┌─────────────────────────────────────────┐ +│ FELDMAN │ +│ │ +│ 1. Recibir en feldman_cola │ +│ 2. Validar reglas (M-001, M-002, M-003)│ +│ 3. Calcular hash_contenido │ +│ 4. Encadenar (hash_previo) │ +│ 5. Crear milestone o bloque │ +│ 6. Marcar como consolidado │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ milestones / bloques (inmutables) │ +└─────────────────────────────────────────┘ + │ + ▼ + SENTINEL (auditoría futura) +``` + +--- + +## Reglas de Validación + +| Regla | Nombre | Descripción | Acción si falla | +|-------|--------|-------------|-----------------| +| M-001 | Hash único | h_bloque/h_milestone no existe previamente | Rechazar | +| M-002 | Encadenamiento | hash_previo apunta a bloque existente | Rechazar | +| M-003 | Integridad | hash_contenido = SHA-256(contenido) | Rechazar | + +### Implementación + +```python +def validar_m001(h_bloque): + """M-001: Hash debe ser único.""" + existe = db.execute( + "SELECT 1 FROM bloques WHERE h_bloque = %s", + [h_bloque] + ).fetchone() + return existe is None + +def validar_m002(hash_previo, h_instancia): + """M-002: hash_previo debe existir (excepto génesis).""" + if hash_previo is None: + # Primer bloque de la instancia (génesis) + existe = db.execute( + "SELECT 1 FROM bloques WHERE h_instancia = %s", + [h_instancia] + ).fetchone() + return existe is None # OK si no hay bloques previos + + existe = db.execute( + "SELECT 1 FROM bloques WHERE h_bloque = %s", + [hash_previo] + ).fetchone() + return existe is not None + +def validar_m003(hash_contenido, contenido): + """M-003: Hash debe coincidir con contenido.""" + import hashlib + import json + + contenido_serializado = json.dumps(contenido, sort_keys=True) + hash_calculado = hashlib.sha256(contenido_serializado.encode()).hexdigest() + + return hash_contenido == hash_calculado +``` + +--- + +## Schema de Tablas + +### feldman_cola + +```sql +CREATE TABLE feldman_cola ( + id BIGSERIAL PRIMARY KEY, + tipo VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque' + h_entrada VARCHAR(64) NOT NULL, -- Referencia a origen + h_instancia VARCHAR(64) NOT NULL, + contenido JSONB NOT NULL, + prioridad INTEGER DEFAULT 0, + estado VARCHAR(20) DEFAULT 'pendiente', + intentos INTEGER DEFAULT 0, + ultimo_error TEXT, + created_at TIMESTAMPTZ DEFAULT NOW(), + processed_at TIMESTAMPTZ +); + +CREATE INDEX idx_feldman_cola_estado ON feldman_cola(estado); +CREATE INDEX idx_feldman_cola_prioridad ON feldman_cola(prioridad DESC); +``` + +### feldman_bloques (alias de bloques) + +```sql +-- Ver 02_MODELO_DATOS/planos.md para schema completo +CREATE TABLE bloques ( + id BIGSERIAL PRIMARY KEY, + h_bloque VARCHAR(64) UNIQUE NOT NULL, + h_instancia VARCHAR(64) NOT NULL, + secuencia BIGINT NOT NULL, + hash_previo VARCHAR(64), + hash_contenido VARCHAR(64) NOT NULL, + tipo_bloque VARCHAR(50) NOT NULL, + contenido JSONB NOT NULL, + -- ... campos adicionales + UNIQUE (h_instancia, secuencia) +); +``` + +### feldman_validaciones + +```sql +CREATE TABLE feldman_validaciones ( + id BIGSERIAL PRIMARY KEY, + h_entrada VARCHAR(64) NOT NULL, + tipo_destino VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque' + h_destino VARCHAR(64), -- h_milestone o h_bloque + regla VARCHAR(50) NOT NULL, -- M-001, M-002, M-003 + resultado BOOLEAN NOT NULL, + mensaje TEXT, + validated_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_feldman_val_entrada ON feldman_validaciones(h_entrada); +``` + +--- + +## Flujo de Consolidación + +``` +1. Entrada en feldman_cola + │ + ▼ +2. FELDMAN procesa (poll cada N segundos) + │ + ├─► Validar M-001 (hash único) + │ ├─ PASS → continuar + │ └─ FAIL → registrar error, marcar 'rechazado' + │ + ├─► Validar M-002 (encadenamiento) + │ ├─ PASS → continuar + │ └─ FAIL → registrar error, marcar 'rechazado' + │ + ├─► Validar M-003 (integridad) + │ ├─ PASS → continuar + │ └─ FAIL → registrar error, marcar 'rechazado' + │ + ▼ +3. Todas las validaciones PASS + │ + ▼ +4. Obtener última secuencia de h_instancia + │ + ▼ +5. Calcular h_bloque/h_milestone + │ + ▼ +6. INSERT en bloques/milestones + │ + ▼ +7. Actualizar feldman_cola → 'consolidado' + │ + ▼ +8. Registrar en feldman_validaciones +``` + +--- + +## Cálculo de Hashes + +### h_bloque + +```python +def calcular_h_bloque(h_instancia, secuencia, hash_previo, hash_contenido): + """ + Calcula el hash del bloque. + + h_bloque = SHA-256(h_instancia:secuencia:hash_previo:hash_contenido) + """ + import hashlib + + # hash_previo puede ser None para bloque génesis + previo = hash_previo or "genesis" + + data = f"{h_instancia}:{secuencia}:{previo}:{hash_contenido}" + + return hashlib.sha256(data.encode()).hexdigest() +``` + +### hash_contenido + +```python +def calcular_hash_contenido(contenido): + """ + Calcula el hash del contenido. + + hash_contenido = SHA-256(contenido_serializado) + """ + import hashlib + import json + + # Serialización determinista + contenido_str = json.dumps(contenido, sort_keys=True, ensure_ascii=False) + + return hashlib.sha256(contenido_str.encode()).hexdigest() +``` + +--- + +## API Endpoints + +### POST /consolidar + +```http +POST /consolidar HTTP/1.1 +Host: corp.example.com:5054 +Content-Type: application/json + +{ + "tipo": "bloque", + "h_entrada": "abc123...", + "h_instancia": "def456...", + "contenido": { + "tipo_bloque": "transaccion", + "monto": 1000, + "descripcion": "Pago factura #123" + } +} +``` + +### Response (éxito) + +```json +{ + "success": true, + "h_bloque": "ghi789...", + "secuencia": 42, + "hash_contenido": "jkl012...", + "validaciones": { + "M-001": true, + "M-002": true, + "M-003": true + } +} +``` + +### Response (error) + +```json +{ + "success": false, + "error": "Validación fallida", + "validaciones": { + "M-001": true, + "M-002": false, + "M-003": true + }, + "mensaje": "M-002: hash_previo no existe en cadena" +} +``` + +--- + +## Configuración + +### Variables de Entorno + +```bash +# /opt/feldman/.env +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=corp +DB_USER=feldman +DB_PASSWORD=**** + +POLL_INTERVAL=5 # Segundos entre polls +MAX_BATCH=10 # Elementos por lote +MAX_RETRIES=3 # Reintentos antes de rechazar +``` + +--- + +## Estados de la Cola + +| Estado | Descripción | +|--------|-------------| +| pendiente | En espera de procesamiento | +| procesando | FELDMAN está validando | +| consolidado | Validado y creado bloque/milestone | +| rechazado | Falló validación, no se reintentará | +| error | Error técnico, puede reintentarse | + +--- + +## Auditoría + +Cada validación se registra en `feldman_validaciones`: + +```sql +-- Consultar historial de validaciones +SELECT + h_entrada, + regla, + resultado, + mensaje, + validated_at +FROM feldman_validaciones +WHERE h_entrada = 'abc123...' +ORDER BY validated_at; +``` + +--- + +## Futuro: Blockchain + +FELDMAN está diseñado para evolucionar hacia blockchain: + +1. **Actual:** Encadenamiento por hash_previo en PostgreSQL +2. **Fase 2:** Merkle tree para verificación eficiente +3. **Fase 3:** Smart contract en blockchain (Ethereum/Polygon) + +``` + Merkle Root + │ + ┌───────────┴───────────┐ + │ │ + Hash(AB) Hash(CD) + │ │ + ┌─────┴─────┐ ┌─────┴─────┐ + │ │ │ │ + Hash(A) Hash(B) Hash(C) Hash(D) + │ │ │ │ + Bloque A Bloque B Bloque C Bloque D +``` + +--- + +## Monitoreo + +### Logs +```bash +docker logs feldman-feldman -f +``` + +### Consultas de Estado + +```sql +-- Elementos pendientes +SELECT COUNT(*) FROM feldman_cola WHERE estado = 'pendiente'; + +-- Últimas validaciones fallidas +SELECT * FROM feldman_validaciones +WHERE resultado = false +ORDER BY validated_at DESC +LIMIT 10; + +-- Bloques creados hoy +SELECT COUNT(*) FROM bloques +WHERE created_at >= CURRENT_DATE; +``` diff --git a/03_COMPONENTES/servicios/grace.md b/03_COMPONENTES/servicios/grace.md new file mode 100644 index 0000000..821cd2f --- /dev/null +++ b/03_COMPONENTES/servicios/grace.md @@ -0,0 +1,403 @@ +# GRACE - Servicio de IA Cognitiva + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Estado Actual + +**BLOQUEADO:** RunPod no inicia workers. + +| Aspecto | Valor | +|---------|-------| +| Plataforma | RunPod Serverless | +| Endpoint ID | r00x4g3rrwkbyh | +| Balance | ~$72 USD | +| Workers activos | 0 | +| Estado | Inoperativo | + +--- + +## Descripción + +GRACE es el servicio de extracción de información mediante IA. Procesa contenido multimedia para extraer datos estructurados. + +``` +Contenido Raw +(audio, imagen, video, documento) + │ + ▼ +┌─────────────────────────────────────────┐ +│ GRACE (GPU) │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ ASR │ │ OCR │ │ TTS │ │ +│ └─────────┘ └─────────┘ └─────────┘ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ Face │ │Embeddings│ │ Avatar │ │ +│ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ + 12 módulos pendientes │ +└─────────────────────────────────────────┘ + │ + ▼ +Datos Estructurados +(JSON, vectores, metadatos) +``` + +--- + +## Módulos Implementados (6 de 18) + +### ASR - Automatic Speech Recognition + +| Campo | Valor | +|-------|-------| +| Modelo | Whisper Large v3 | +| Input | Audio (mp3, wav, m4a) | +| Output | Texto + timestamps | +| GPU | A10G recomendado | + +```python +@grace.module("asr") +def process_asr(audio_bytes: bytes) -> dict: + """Transcribe audio a texto.""" + model = whisper.load_model("large-v3") + result = model.transcribe(audio_bytes) + return { + "text": result["text"], + "segments": result["segments"], + "language": result["language"] + } +``` + +### OCR - Optical Character Recognition + +| Campo | Valor | +|-------|-------| +| Modelo | EasyOCR + Tesseract | +| Input | Imagen (jpg, png) | +| Output | Texto + bounding boxes | +| GPU | A10G recomendado | + +```python +@grace.module("ocr") +def process_ocr(image_bytes: bytes) -> dict: + """Extrae texto de imagen.""" + reader = easyocr.Reader(['es', 'en']) + result = reader.readtext(image_bytes) + return { + "text": " ".join([r[1] for r in result]), + "boxes": [{"text": r[1], "bbox": r[0], "confidence": r[2]} for r in result] + } +``` + +### TTS - Text to Speech + +| Campo | Valor | +|-------|-------| +| Modelo | Coqui TTS | +| Input | Texto | +| Output | Audio (wav) | +| GPU | A10G recomendado | + +### Face - Reconocimiento Facial + +| Campo | Valor | +|-------|-------| +| Modelo | InsightFace | +| Input | Imagen | +| Output | Embeddings faciales | +| GPU | A10G recomendado | + +### Embeddings - Vectores Semánticos + +| Campo | Valor | +|-------|-------| +| Modelo | Sentence Transformers | +| Input | Texto | +| Output | Vector 384/768 dims | +| GPU | A10G recomendado | + +### Avatar - Generación de Avatares + +| Campo | Valor | +|-------|-------| +| Modelo | StyleGAN | +| Input | Imagen facial | +| Output | Avatar estilizado | +| GPU | A10G recomendado | + +--- + +## Módulos Pendientes (12) + +| Módulo | Descripción | Prioridad | +|--------|-------------|-----------| +| Document parsing | Extracción de PDFs | Alta | +| Image classification | Clasificación de imágenes | Media | +| Object detection | Detección de objetos | Media | +| Sentiment analysis | Análisis de sentimiento | Media | +| Named entity recognition | Extracción de entidades | Alta | +| Translation | Traducción de texto | Media | +| Summarization | Resumen de texto | Media | +| Question answering | Respuestas a preguntas | Baja | +| Code generation | Generación de código | Baja | +| Audio classification | Clasificación de audio | Baja | +| Video analysis | Análisis de video | Baja | +| Multimodal fusion | Fusión multimodal | Baja | + +--- + +## Código en R2 + +El código está listo y disponible: + +``` +s3://architect/gpu-services/ +├── base/ +│ └── bootstrap.sh # Script de inicialización +├── grace/ +│ └── code/ +│ └── handler.py # Handler principal +├── penny/ +│ └── code/ +│ └── handler.py +└── factory/ + └── code/ + └── handler.py +``` + +### Descargar Código + +```bash +source /home/orchestrator/orchestrator/.env +export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY" +export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY" + +aws s3 sync s3://architect/gpu-services/grace/ ./grace/ \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +``` + +--- + +## Handler RunPod + +```python +import runpod + +def handler(event): + """ + Handler principal de GRACE para RunPod Serverless. + + Input: + { + "input": { + "module": "asr|ocr|tts|face|embeddings|avatar", + "data": "base64 encoded content", + "options": {} + } + } + + Output: + { + "output": { ... resultado del módulo ... }, + "error": null + } + """ + try: + module = event["input"]["module"] + data = base64.b64decode(event["input"]["data"]) + options = event["input"].get("options", {}) + + if module == "asr": + result = process_asr(data, **options) + elif module == "ocr": + result = process_ocr(data, **options) + elif module == "tts": + result = process_tts(data, **options) + elif module == "face": + result = process_face(data, **options) + elif module == "embeddings": + result = process_embeddings(data, **options) + elif module == "avatar": + result = process_avatar(data, **options) + else: + return {"error": f"Módulo desconocido: {module}"} + + return {"output": result, "error": None} + + except Exception as e: + return {"error": str(e)} + +runpod.serverless.start({"handler": handler}) +``` + +--- + +## Uso desde MASON + +```python +import runpod +import base64 + +runpod.api_key = "..." # Desde Infisical + +def call_grace(module: str, content: bytes, options: dict = None) -> dict: + """Llama a GRACE para procesar contenido.""" + + job = runpod.run( + endpoint_id="r00x4g3rrwkbyh", + input={ + "module": module, + "data": base64.b64encode(content).decode(), + "options": options or {} + } + ) + + # Polling hasta completar + while True: + status = runpod.status(job["id"]) + if status["status"] == "COMPLETED": + return status["output"] + elif status["status"] == "FAILED": + raise Exception(status.get("error", "Job failed")) + time.sleep(1) +``` + +--- + +## Problema Actual: Workers No Inician + +### Incidente 2024-12-24 + +- **Síntoma:** 0 workers activos a pesar de jobs en cola +- **Balance:** $72+ (suficiente) +- **Configuración:** Correcta +- **Causa probable:** Problema de capacidad RunPod + +### Intentos de Diagnóstico + +1. Verificado endpoint activo en dashboard +2. Verificado balance suficiente +3. Verificado configuración de scaling +4. Jobs quedan en estado "IN_QUEUE" indefinidamente + +### Log de Errores + +``` +No hay logs disponibles - workers nunca inician +``` + +--- + +## Alternativas Evaluadas + +### 1. Modal (Recomendado) + +```python +import modal + +stub = modal.Stub("grace") +image = modal.Image.debian_slim().pip_install("whisper", "easyocr") + +@stub.function(gpu="A10G", image=image) +def process_asr(audio_bytes: bytes) -> dict: + import whisper + model = whisper.load_model("large-v3") + result = model.transcribe(audio_bytes) + return {"text": result["text"]} +``` + +**Pros:** +- Serverless real +- Buen DX (developer experience) +- Python-native +- Cold start rápido + +**Contras:** +- Menos GPUs disponibles que RunPod +- Pricing puede ser mayor + +### 2. Replicate + +```python +import replicate + +output = replicate.run( + "openai/whisper:large-v3", + input={"audio": audio_url} +) +``` + +**Pros:** +- Modelos pre-entrenados +- API simple +- Sin gestión de infraestructura + +**Contras:** +- Menos control +- Más caro a escala +- Dependencia de modelos de terceros + +### 3. Lambda Labs + +**Pros:** +- Hardware dedicado +- GPUs disponibles + +**Contras:** +- Menos flexible +- Reserva manual +- No serverless + +### 4. Self-Hosted + +**Pros:** +- Control total +- Sin dependencias externas +- Costo fijo a largo plazo + +**Contras:** +- CapEx alto +- Mantenimiento +- Requiere expertise + +--- + +## Plan de Migración + +### Fase 1: Evaluación + +- [ ] Crear cuenta Modal +- [ ] Portar módulo ASR a Modal +- [ ] Comparar latencia con RunPod (cuando funcione) +- [ ] Comparar costos + +### Fase 2: Migración + +- [ ] Portar 6 handlers a Modal +- [ ] Actualizar endpoints en MASON +- [ ] Actualizar documentación +- [ ] Testing end-to-end + +### Fase 3: Producción + +- [ ] Desplegar en Modal +- [ ] Monitorear costos y performance +- [ ] Deprecar RunPod endpoints +- [ ] Cancelar cuenta RunPod + +--- + +## Principio Fundamental + +**GRACE nunca modifica datos.** + +GRACE es read-only: extrae información pero no puede modificar el contenido original ni los datos del sistema. Las extracciones se almacenan como metadatos asociados al contenido original. + +``` +Contenido Original ────► GRACE ────► Metadatos Extraídos + (inmutable) (nuevos datos) +``` diff --git a/04_SEGURIDAD/modelo-amenazas.md b/04_SEGURIDAD/modelo-amenazas.md new file mode 100644 index 0000000..1de8902 --- /dev/null +++ b/04_SEGURIDAD/modelo-amenazas.md @@ -0,0 +1,177 @@ +# Modelo de Amenazas TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Resumen Ejecutivo + +El sistema TZZR tiene una base de seguridad sólida (SSH keys, PostgreSQL SSL, tokens de autenticación) pero presenta exposiciones críticas que requieren atención inmediata. + +--- + +## Hallazgos Críticos + +### CRÍTICO-001: CORP/HST sin Firewall + +**Descripción:** UFW inactivo en servidores CORP y HST. +**Impacto:** Todos los puertos expuestos a Internet. +**Evidencia:** `ufw status` devuelve "inactive". + +**Mitigación:** +```bash +# CORP +ufw default deny incoming +ufw allow 22/tcp +ufw allow 80/tcp +ufw allow 443/tcp +ufw enable + +# HST +ufw default deny incoming +ufw allow 22/tcp +ufw allow 80/tcp +ufw allow 443/tcp +ufw enable +``` + +### CRÍTICO-002: PostgreSQL 5432 Expuesto + +**Descripción:** PostgreSQL en ARCHITECT escucha en 0.0.0.0:5432. +**Impacto:** Accesible desde cualquier IP (aunque requiere autenticación). + +**Mitigación:** +``` +# /etc/postgresql/16/main/postgresql.conf +listen_addresses = '127.0.0.1,172.17.0.1' +``` + +### CRÍTICO-003: Archivos .env Legibles + +**Descripción:** Archivos .env con permisos 644 (legibles por todos). +**Impacto:** Credenciales accesibles a cualquier usuario del sistema. + +**Mitigación:** +```bash +chmod 600 /opt/clara/.env +chmod 600 /opt/alfred/.env +chmod 600 /opt/margaret/.env +chmod 600 /opt/mason/.env +``` + +--- + +## Hallazgos Altos + +### ALTO-001: fail2ban No Configurado + +**Descripción:** fail2ban failed en DECK, inactive en CORP. +**Impacto:** SSH bruteforce sin mitigación automática. +**Evidencia:** Ataques activos desde 165.232.81.204, 188.166.115.48. + +**Mitigación:** +```bash +apt install fail2ban +systemctl enable fail2ban +# jail: sshd, maxretry=3, bantime=1h +``` + +### ALTO-002: Triple Gestión de Secretos + +**Descripción:** Credenciales en Infisical, tablas creds_*, y archivos .env. +**Impacto:** No hay fuente única de verdad, riesgo de desincronización. + +**Mitigación:** +- Migrar todas las credenciales a Infisical +- Eliminar .env hardcodeados +- creds_* solo para referencia + +### ALTO-003: Servicios sin TLS Interno + +**Descripción:** CLARA, MARGARET, MASON, FELDMAN en HTTP plano. +**Impacto:** Tráfico interno sin cifrar. + +**Mitigación:** +- Configurar mTLS entre servicios +- Usar Caddy como reverse proxy con TLS + +--- + +## Hallazgos Medios + +### MEDIO-001: No hay Backup PostgreSQL + +**Descripción:** Solo Gitea tiene backup en R2, PostgreSQL sin backup. +**Impacto:** Pérdida de datos en caso de fallo. + +**Mitigación:** +```bash +# Cron diario +pg_dump architect | gzip | aws s3 cp - s3://architect/backups/architect_$(date +%F).sql.gz +``` + +### MEDIO-002: SENTINEL No Desplegado + +**Descripción:** Sistema de auditoría planificado pero no implementado. +**Impacto:** Sin visibilidad de anomalías. + +**Mitigación:** Implementar SENTINEL LIGHT mode básico. + +### MEDIO-003: No hay Rotación de Secretos + +**Descripción:** Sin política de rotación de credenciales. +**Impacto:** Credenciales comprometidas persisten indefinidamente. + +**Mitigación:** +- API keys: 90 días +- DB passwords: 180 días +- SSH keys: 365 días + +--- + +## Controles Existentes + +| Control | Estado | Notas | +|---------|--------|-------| +| SSH Keys | Activo | Permisos 600 correctos | +| PostgreSQL SSL | Activo | SCRAM-SHA-256 | +| H_INSTANCIA Auth | Activo | CLARA/MARGARET | +| Gitea Tokens | Activo | Lectura/Escritura separados | +| DECK UFW | Activo | Política deny incoming | + +--- + +## Matriz de Riesgos + +| ID | Riesgo | Probabilidad | Impacto | Prioridad | +|----|--------|--------------|---------|-----------| +| CRÍTICO-001 | Firewall desactivado | Alta | Alto | Semana 1 | +| CRÍTICO-002 | PostgreSQL expuesto | Media | Alto | Semana 1 | +| CRÍTICO-003 | .env legibles | Alta | Alto | Semana 1 | +| ALTO-001 | Sin fail2ban | Alta | Medio | Semana 1 | +| ALTO-002 | Secretos duplicados | Media | Medio | Mes 1 | +| ALTO-003 | Sin TLS interno | Baja | Medio | Mes 1 | +| MEDIO-001 | Sin backup PG | Baja | Alto | Mes 1 | +| MEDIO-002 | Sin SENTINEL | Baja | Medio | Mes 2 | +| MEDIO-003 | Sin rotación | Baja | Medio | Mes 2 | + +--- + +## Plan de Remediación + +### Semana 1 (Urgente) +- [ ] Activar UFW en CORP y HST +- [ ] chmod 600 en todos los .env +- [ ] Instalar fail2ban +- [ ] PostgreSQL bind 127.0.0.1 + +### Mes 1 (Alta) +- [ ] Migrar secretos a Infisical +- [ ] TLS interno +- [ ] Backup PostgreSQL automatizado + +### Mes 2 (Media) +- [ ] SENTINEL LIGHT mode +- [ ] Política de rotación +- [ ] Monitoreo de certificados diff --git a/04_SEGURIDAD/secretos.md b/04_SEGURIDAD/secretos.md new file mode 100644 index 0000000..355b789 --- /dev/null +++ b/04_SEGURIDAD/secretos.md @@ -0,0 +1,292 @@ +# Gestión de Secretos TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Estado Actual: Triple Gestión + +**PROBLEMA CRÍTICO:** Actualmente existen tres fuentes de secretos sin sincronización. + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ FUENTES DE SECRETOS │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Infisical │ │ creds_* │ │ .env │ │ +│ │ (central) │ │ (PostgreSQL)│ │ (archivos) │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ❌ SIN SINCRONIZACIÓN - Riesgo de inconsistencia │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Fuente 1: Infisical + +**URL:** http://localhost:8082 (ARCHITECT) +**Estado:** Operativo + +### Configuración + +```bash +# Acceso a Infisical +infisical login +infisical secrets --env=prod +``` + +### Ventajas +- Centralizado +- Versionado +- Auditable +- SDK para múltiples lenguajes + +### Uso Actual +- Parcial - no todos los servicios lo usan + +--- + +## Fuente 2: Tablas creds_* (PostgreSQL) + +**Base de datos:** architect +**Estado:** Activo + +### Tablas + +| Tabla | Contenido | +|-------|-----------| +| creds_ia | APIs de IA (OpenAI, Anthropic, etc.) | +| creds_runpod | API keys de RunPod | +| creds_r2 | Credenciales Cloudflare R2 | +| creds_gitea | Tokens Gitea | +| creds_mail | Credenciales SMTP | +| creds_apis | APIs externas varias | + +### Schema Típico + +```sql +CREATE TABLE creds_ia ( + id SERIAL PRIMARY KEY, + servicio VARCHAR(50) NOT NULL, + api_key TEXT NOT NULL, + descripcion TEXT, + activo BOOLEAN DEFAULT true, + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); +``` + +### Acceso + +```sql +-- Consultar credenciales +sudo -u postgres psql -d architect -c "SELECT servicio, descripcion FROM creds_ia;" +``` + +--- + +## Fuente 3: Archivos .env + +**Ubicaciones:** +- /opt/clara/.env +- /opt/alfred/.env +- /opt/margaret/.env +- /opt/mason/.env +- /opt/feldman/.env + +### ALERTA CRÍTICA + +``` +Permisos actuales: 644 (legibles por todos) +Permisos correctos: 600 (solo propietario) +``` + +### Contenido Típico + +```bash +# Ejemplo .env +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=corp +DB_USER=margaret +DB_PASSWORD=secreto_aqui # ⚠️ Expuesto si 644 + +R2_ACCESS_KEY=access_key_aqui +R2_SECRET_KEY=secret_key_aqui # ⚠️ Expuesto si 644 +``` + +--- + +## Decisión D-001: Migración a Infisical + +### Objetivo +Infisical como **única fuente de verdad** para todos los secretos. + +### Plan de Migración + +``` +Fase 1: Inventario +├── Catalogar todos los secretos en creds_* +├── Catalogar todos los secretos en .env +└── Identificar duplicados/inconsistencias + +Fase 2: Centralización +├── Migrar todos los secretos a Infisical +├── Organizar por proyecto/ambiente +└── Establecer políticas de acceso + +Fase 3: Actualización de Servicios +├── CLARA: Usar Infisical SDK +├── MARGARET: Usar Infisical SDK +├── MASON: Usar Infisical SDK +├── FELDMAN: Usar Infisical SDK +└── ALFRED/JARED: Usar Infisical SDK + +Fase 4: Deprecación +├── Eliminar archivos .env +├── Marcar creds_* como "solo referencia" +└── Documentar proceso de rotación +``` + +### Implementación con SDK + +```python +from infisical_client import InfisicalClient + +client = InfisicalClient( + host="http://localhost:8082", + token=INFISICAL_TOKEN +) + +# Obtener secreto +db_password = client.get_secret( + secret_name="DB_PASSWORD", + project_id="tzzr", + environment="production" +) +``` + +--- + +## Rotación de Secretos + +### Política Propuesta + +| Tipo | Frecuencia | Responsable | +|------|------------|-------------| +| API Keys externas | 90 días | Orchestrator | +| Contraseñas DB | 180 días | DBA | +| SSH Keys | 365 días | SysAdmin | +| Tokens Gitea | 180 días | DevOps | + +### Proceso de Rotación + +``` +1. Generar nuevo secreto +2. Actualizar en Infisical +3. Desplegar servicios afectados +4. Verificar funcionamiento +5. Revocar secreto anterior +6. Documentar en changelog +``` + +--- + +## Mitigación Inmediata + +### Paso 1: Permisos .env + +```bash +# Ejecutar en todos los servidores + +# DECK +ssh -i ~/.ssh/tzzr root@72.62.1.113 'chmod 600 /opt/clara/.env /opt/alfred/.env' + +# CORP +ssh -i ~/.ssh/tzzr root@92.112.181.188 'chmod 600 /opt/margaret/.env /opt/mason/.env /opt/feldman/.env' +``` + +### Paso 2: Auditoría + +```bash +# Verificar permisos +ls -la /opt/*/.env + +# Buscar secretos expuestos +grep -r "password\|secret\|key" /opt/*/ 2>/dev/null +``` + +--- + +## Inventario de Secretos + +### APIs de IA + +| Servicio | Ubicación Actual | Notas | +|----------|------------------|-------| +| OpenAI | creds_ia | GPT-4 | +| Anthropic | creds_ia | Claude | +| Replicate | creds_ia | Modelos varios | +| RunPod | creds_runpod | GRACE, PENNY, FACTORY | + +### Infraestructura + +| Servicio | Ubicación Actual | Notas | +|----------|------------------|-------| +| PostgreSQL | .env + creds_* | Múltiples usuarios | +| R2/Cloudflare | .env + creds_r2 | Access + Secret key | +| Gitea | .env + creds_gitea | Read + Write tokens | +| SMTP | creds_mail | Mailcow | + +### Servicios Externos + +| Servicio | Ubicación Actual | Notas | +|----------|------------------|-------| +| Stripe | creds_apis | (si aplica) | +| Twilio | creds_apis | (si aplica) | +| AWS | creds_apis | (si aplica) | + +--- + +## Verificación de Seguridad + +### Checklist Diario + +- [ ] Permisos .env son 600 +- [ ] No hay secretos en logs +- [ ] No hay secretos en commits git +- [ ] Infisical accesible + +### Comandos de Verificación + +```bash +# Verificar permisos +find /opt -name ".env" -exec ls -la {} \; + +# Buscar secretos en git history +git log -p | grep -i "password\|secret\|key\|token" + +# Verificar Infisical +curl -s http://localhost:8082/api/v1/health +``` + +--- + +## Buenas Prácticas + +### DO (Hacer) +- Usar Infisical para todos los secretos nuevos +- Rotar secretos según política +- Auditar accesos regularmente +- Cifrar secretos en reposo + +### DON'T (No Hacer) +- Hardcodear secretos en código +- Commitear .env a repositorios +- Compartir secretos por chat/email +- Usar el mismo secreto en múltiples servicios diff --git a/05_OPERACIONES/backup-recovery.md b/05_OPERACIONES/backup-recovery.md new file mode 100644 index 0000000..d21bddc --- /dev/null +++ b/05_OPERACIONES/backup-recovery.md @@ -0,0 +1,359 @@ +# Backup y Recovery TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Estado Actual + +### Backups Existentes + +| Sistema | Backup | Destino | Frecuencia | Estado | +|---------|--------|---------|------------|--------| +| Gitea | Sí | R2 | Manual | Operativo | +| PostgreSQL ARCHITECT | No | - | - | **CRÍTICO** | +| PostgreSQL DECK | No | - | - | **CRÍTICO** | +| PostgreSQL CORP | No | - | - | **CRÍTICO** | +| PostgreSQL HST | No | - | - | **CRÍTICO** | +| R2 buckets | Built-in | R2 | Automático | Operativo | + +--- + +## Plan de Backup Propuesto + +### PostgreSQL - Backup Diario + +```bash +#!/bin/bash +# /opt/scripts/backup_postgres.sh + +set -e + +DATE=$(date +%F) +BACKUP_DIR="/tmp/pg_backup" + +# Cargar credenciales R2 +source /home/orchestrator/orchestrator/.env +export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY" +export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY" + +R2_ENDPOINT="https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com" + +mkdir -p $BACKUP_DIR + +# Backup ARCHITECT +echo "Backing up ARCHITECT..." +sudo -u postgres pg_dump architect | gzip > $BACKUP_DIR/architect_$DATE.sql.gz +aws s3 cp $BACKUP_DIR/architect_$DATE.sql.gz s3://architect/backups/postgres/ \ + --endpoint-url $R2_ENDPOINT + +# Cleanup local +rm -rf $BACKUP_DIR + +echo "Backup completado: $DATE" +``` + +### Cron Configuration + +```bash +# /etc/cron.d/tzzr-backup +# Backup diario a las 3:00 AM +0 3 * * * orchestrator /opt/scripts/backup_postgres.sh >> /var/log/tzzr-backup.log 2>&1 +``` + +--- + +## Backup por Servidor + +### ARCHITECT (69.62.126.110) + +```bash +# Base de datos: architect +sudo -u postgres pg_dump architect | gzip > architect_$(date +%F).sql.gz + +# Subir a R2 +aws s3 cp architect_$(date +%F).sql.gz s3://architect/backups/postgres/ \ + --endpoint-url $R2_ENDPOINT +``` + +### DECK (72.62.1.113) + +```bash +# Base de datos: tzzr +ssh deck 'sudo -u postgres pg_dump tzzr | gzip' > deck_tzzr_$(date +%F).sql.gz + +# Subir a R2 +aws s3 cp deck_tzzr_$(date +%F).sql.gz s3://architect/backups/deck/ \ + --endpoint-url $R2_ENDPOINT +``` + +### CORP (92.112.181.188) + +```bash +# Base de datos: corp +ssh corp 'sudo -u postgres pg_dump corp | gzip' > corp_$(date +%F).sql.gz + +# Subir a R2 +aws s3 cp corp_$(date +%F).sql.gz s3://architect/backups/corp/ \ + --endpoint-url $R2_ENDPOINT +``` + +### HST (72.62.2.84) + +```bash +# Base de datos: hst_images +ssh hst 'sudo -u postgres pg_dump hst_images | gzip' > hst_$(date +%F).sql.gz + +# Subir a R2 +aws s3 cp hst_$(date +%F).sql.gz s3://architect/backups/hst/ \ + --endpoint-url $R2_ENDPOINT +``` + +--- + +## Gitea Backup + +### Backup Manual + +```bash +# En ARCHITECT +docker exec -t gitea bash -c 'gitea dump -c /data/gitea/conf/app.ini' +docker cp gitea:/app/gitea/gitea-dump-*.zip ./ + +# Subir a R2 +aws s3 cp gitea-dump-*.zip s3://architect/backups/gitea/ \ + --endpoint-url $R2_ENDPOINT +``` + +### Backup Automático + +```bash +#!/bin/bash +# /opt/scripts/backup_gitea.sh + +DATE=$(date +%F_%H%M) + +# Crear dump +docker exec -t gitea bash -c "gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump-$DATE.zip" + +# Copiar fuera del container +docker cp gitea:/tmp/gitea-dump-$DATE.zip /tmp/ + +# Subir a R2 +source /home/orchestrator/orchestrator/.env +export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY" +export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY" + +aws s3 cp /tmp/gitea-dump-$DATE.zip s3://architect/backups/gitea/ \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com + +# Cleanup +rm /tmp/gitea-dump-$DATE.zip +docker exec gitea rm /tmp/gitea-dump-$DATE.zip +``` + +--- + +## Estructura de Backups en R2 + +``` +s3://architect/backups/ +├── postgres/ +│ ├── architect_2024-12-24.sql.gz +│ ├── architect_2024-12-23.sql.gz +│ └── ... +├── deck/ +│ ├── deck_tzzr_2024-12-24.sql.gz +│ └── ... +├── corp/ +│ ├── corp_2024-12-24.sql.gz +│ └── ... +├── hst/ +│ ├── hst_2024-12-24.sql.gz +│ └── ... +└── gitea/ + ├── gitea-dump-2024-12-24_0300.zip + └── ... +``` + +--- + +## Retención de Backups + +### Política Propuesta + +| Tipo | Retención | Notas | +|------|-----------|-------| +| Diario | 7 días | Últimos 7 backups | +| Semanal | 4 semanas | Domingos | +| Mensual | 12 meses | Primer día del mes | + +### Script de Limpieza + +```bash +#!/bin/bash +# /opt/scripts/cleanup_backups.sh + +source /home/orchestrator/orchestrator/.env +export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY" +export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY" + +R2_ENDPOINT="https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com" + +# Eliminar backups más antiguos de 30 días +# (Implementar con lifecycle rules de R2 preferentemente) + +aws s3 ls s3://architect/backups/postgres/ --endpoint-url $R2_ENDPOINT | \ + while read -r line; do + createDate=$(echo $line | awk '{print $1}') + fileName=$(echo $line | awk '{print $4}') + + # Comparar fechas y eliminar si > 30 días + # ... + done +``` + +--- + +## Recovery + +### PostgreSQL - Restaurar Base de Datos + +```bash +# Descargar backup +aws s3 cp s3://architect/backups/postgres/architect_2024-12-24.sql.gz . \ + --endpoint-url $R2_ENDPOINT + +# Descomprimir +gunzip architect_2024-12-24.sql.gz + +# Restaurar (¡CUIDADO! Sobrescribe datos existentes) +sudo -u postgres psql -d architect < architect_2024-12-24.sql +``` + +### PostgreSQL - Restaurar a Nueva Base + +```bash +# Crear nueva base de datos +sudo -u postgres createdb architect_restored + +# Restaurar +gunzip -c architect_2024-12-24.sql.gz | sudo -u postgres psql -d architect_restored +``` + +### Gitea - Restaurar + +```bash +# Descargar backup +aws s3 cp s3://architect/backups/gitea/gitea-dump-2024-12-24_0300.zip . \ + --endpoint-url $R2_ENDPOINT + +# Detener Gitea +docker stop gitea + +# Copiar al container +docker cp gitea-dump-2024-12-24_0300.zip gitea:/tmp/ + +# Restaurar +docker exec gitea bash -c "cd /tmp && unzip gitea-dump-2024-12-24_0300.zip" +# Seguir instrucciones de Gitea para restore + +# Iniciar Gitea +docker start gitea +``` + +--- + +## Disaster Recovery Plan + +### Escenario 1: Pérdida de ARCHITECT + +1. Provisionar nuevo VPS con misma IP (si posible) +2. Instalar Ubuntu 22.04 +3. Configurar usuario orchestrator +4. Restaurar PostgreSQL desde R2 +5. Restaurar Gitea desde R2 +6. Reinstalar Docker y servicios +7. Verificar conectividad con DECK/CORP/HST + +### Escenario 2: Pérdida de DECK + +1. Provisionar nuevo VPS +2. Restaurar PostgreSQL (tzzr) desde backup +3. Reinstalar CLARA, ALFRED +4. Reinstalar Mailcow (requiere backup separado) +5. Actualizar DNS si IP cambió + +### Escenario 3: Pérdida de CORP + +1. Provisionar nuevo VPS +2. Restaurar PostgreSQL (corp) desde backup +3. Reinstalar MARGARET, JARED, MASON, FELDMAN +4. Reinstalar Odoo, Nextcloud +5. Activar UFW (nuevo servidor) + +### Escenario 4: Pérdida de R2 + +**IMPROBABLE** - Cloudflare tiene redundancia multi-región. + +Mitigación: Backup mensual a segundo proveedor (AWS S3 Glacier). + +--- + +## Verificación de Backups + +### Test Mensual + +```bash +#!/bin/bash +# /opt/scripts/verify_backup.sh + +# Descargar último backup +LATEST=$(aws s3 ls s3://architect/backups/postgres/ --endpoint-url $R2_ENDPOINT | \ + sort | tail -1 | awk '{print $4}') + +aws s3 cp s3://architect/backups/postgres/$LATEST /tmp/ \ + --endpoint-url $R2_ENDPOINT + +# Verificar integridad +gunzip -t /tmp/$LATEST +if [ $? -eq 0 ]; then + echo "Backup válido: $LATEST" +else + echo "ERROR: Backup corrupto: $LATEST" + # Enviar alerta +fi + +rm /tmp/$LATEST +``` + +### Checklist de Verificación + +- [ ] Backup PostgreSQL ARCHITECT existe (< 24h) +- [ ] Backup PostgreSQL DECK existe (< 24h) +- [ ] Backup PostgreSQL CORP existe (< 24h) +- [ ] Backup Gitea existe (< 7d) +- [ ] Integridad verificada (gunzip -t) +- [ ] Restore test exitoso (mensual) + +--- + +## Alertas + +### Configuración ntfy + +```bash +# Notificar si backup falla +if [ $? -ne 0 ]; then + curl -d "Backup FALLIDO: $DATE" ntfy.sh/tzzr-alerts +fi +``` + +### Monitoreo + +```bash +# Verificar último backup +aws s3 ls s3://architect/backups/postgres/ --endpoint-url $R2_ENDPOINT | \ + sort | tail -5 +``` diff --git a/05_OPERACIONES/infraestructura.md b/05_OPERACIONES/infraestructura.md new file mode 100644 index 0000000..34f47c0 --- /dev/null +++ b/05_OPERACIONES/infraestructura.md @@ -0,0 +1,383 @@ +# Infraestructura TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Resumen de Servidores + +| Servidor | IP Pública | Rol | Proveedor | +|----------|------------|-----|-----------| +| ARCHITECT | 69.62.126.110 | Coordinador central | VPS | +| DECK | 72.62.1.113 | Personal | VPS | +| CORP | 92.112.181.188 | Empresarial | VPS | +| HST | 72.62.2.84 | API Tags | VPS | +| LOCKER | R2 | Almacenamiento | Cloudflare | + +--- + +## ARCHITECT (69.62.126.110) + +### Especificaciones +- **OS:** Ubuntu 22.04 LTS +- **Usuario:** orchestrator +- **Servicios:** PostgreSQL, Gitea, Orchestrator, Infisical + +### Puertos + +| Puerto | Servicio | Estado | +|--------|----------|--------| +| 22 | SSH | Abierto | +| 2222 | Gitea SSH | Abierto | +| 3000 | Gitea HTTP | Abierto | +| 5050 | Orchestrator | Abierto | +| 5432 | PostgreSQL | **CRÍTICO: 0.0.0.0** | +| 8082 | Infisical | Abierto | + +### Acceso + +```bash +ssh orchestrator@69.62.126.110 +``` + +### PostgreSQL + +```bash +sudo -u postgres psql -d architect +``` + +### Gitea + +``` +URL: http://localhost:3000 +Token lectura: 5ca10e5b71d41f9b22f12d0f96bfc2e6de5c2c7f +Token escritura: ac5a604b9aac5cee81192a656fc918f9efa3834b +``` + +--- + +## DECK (72.62.1.113) + +### Especificaciones +- **OS:** Ubuntu 22.04 LTS +- **Usuario:** root +- **Servicios:** CLARA, ALFRED, Mailcow, Directus, etc. + +### Puertos + +| Puerto | Servicio | Estado | +|--------|----------|--------| +| 22 | SSH | Abierto | +| 25 | SMTP | Abierto | +| 143 | IMAP | Abierto | +| 465 | SMTPS | Abierto | +| 587 | Submission | Abierto | +| 993 | IMAPS | Abierto | +| 5051 | CLARA | Abierto | +| 5052 | ALFRED | Abierto | +| 8055 | Directus | Abierto | +| 8080 | ntfy | Abierto | +| 8082 | FileBrowser | Abierto | +| 8083 | Shlink | Abierto | +| 8085 | Vaultwarden | Abierto | + +### Acceso + +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 +``` + +### Docker Containers + +```bash +docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" +``` + +--- + +## CORP (92.112.181.188) + +### Especificaciones +- **OS:** Ubuntu 22.04 LTS +- **Usuario:** root +- **Servicios:** MARGARET, JARED, MASON, FELDMAN, Odoo, Nextcloud + +### Puertos + +| Puerto | Servicio | Estado | +|--------|----------|--------| +| 22 | SSH | Abierto | +| 80 | Caddy HTTP | Abierto | +| 443 | Caddy HTTPS | Abierto | +| 5051 | MARGARET | Abierto | +| 5052 | JARED | Abierto | +| 5053 | MASON | Abierto | +| 5054 | FELDMAN | Abierto | +| 5432 | PostgreSQL | Local | +| 8055 | Directus | Abierto | +| 8069 | Odoo | Abierto | +| 8080 | Nextcloud | Abierto | +| 8081 | Vaultwarden | Abierto | + +### Acceso + +```bash +ssh -i ~/.ssh/tzzr root@92.112.181.188 +``` + +### Firewall + +**ALERTA CRÍTICA: UFW INACTIVO** + +```bash +# Verificar estado +ufw status + +# Activar (cuando se autorice) +ufw default deny incoming +ufw allow 22/tcp +ufw allow 80/tcp +ufw allow 443/tcp +ufw enable +``` + +--- + +## HST (72.62.2.84) + +### Especificaciones +- **OS:** Ubuntu 22.04 LTS +- **Usuario:** root +- **Servicios:** Nginx, Directus, PostgreSQL + +### Puertos + +| Puerto | Servicio | Estado | +|--------|----------|--------| +| 22 | SSH | Abierto | +| 80 | Nginx HTTP | Abierto | +| 443 | Nginx HTTPS | Abierto | +| 5432 | PostgreSQL | Local | +| 8055 | Directus | Abierto | + +### Acceso + +```bash +ssh -i ~/.ssh/tzzr root@72.62.2.84 +``` + +### API Pública + +``` +https://tzrtech.org/{h_maestro}.png +``` + +### Estadísticas HST + +| Grupo | Cantidad | +|-------|----------| +| hst | 639 | +| spe | 145 | +| vsn | 84 | +| flg | 65 | +| vue | 21 | +| **Total** | **973** | + +--- + +## LOCKER (Cloudflare R2) + +### Endpoint + +``` +https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +``` + +### Buckets + +| Bucket | Uso | Tamaño Aprox | +|--------|-----|--------------| +| architect | Backups, configs, GPU services | ~500 MB | +| deck | Archivos personales (CLARA) | Variable | +| corp | Archivos empresariales (MARGARET) | Variable | +| hst | Imágenes de tags | ~100 MB | +| locker | Almacenamiento general | Variable | + +### Acceso + +```bash +source /home/orchestrator/orchestrator/.env +export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY" +export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY" + +aws s3 ls s3://architect/ \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +``` + +--- + +## SSH Keys + +### Ubicación + +``` +/home/orchestrator/.ssh/tzzr # Private key +/home/orchestrator/.ssh/tzzr.pub # Public key +``` + +### Permisos + +```bash +chmod 600 ~/.ssh/tzzr +chmod 644 ~/.ssh/tzzr.pub +``` + +### Configuración SSH + +```bash +# ~/.ssh/config +Host deck + HostName 72.62.1.113 + User root + IdentityFile ~/.ssh/tzzr + +Host corp + HostName 92.112.181.188 + User root + IdentityFile ~/.ssh/tzzr + +Host hst + HostName 72.62.2.84 + User root + IdentityFile ~/.ssh/tzzr +``` + +--- + +## Bases de Datos + +### architect (ARCHITECT) + +``` +Host: localhost +Port: 5432 +Database: architect +User: postgres +``` + +Tablas principales: +- context_blocks +- agents +- creds_* + +### tzzr (DECK) + +``` +Host: localhost +Port: 5432 +Database: tzzr +``` + +Tablas principales: +- clara_log +- deck_visiones +- deck_milestones + +### corp (CORP) + +``` +Host: localhost +Port: 5432 +Database: corp +``` + +Tablas principales: +- margaret_log +- mason_workspace +- feldman_cola +- milestones +- bloques + +### hst_images (HST) + +``` +Host: localhost +Port: 5432 +Database: hst_images +``` + +Tablas principales: +- hst_tags +- hst_trees + +--- + +## Monitoreo + +### Comandos de Estado + +```bash +# Verificar servicios ARCHITECT +systemctl status postgresql +docker ps + +# Verificar servicios DECK +ssh deck 'docker ps' +ssh deck 'systemctl status fail2ban' + +# Verificar servicios CORP +ssh corp 'docker ps' +ssh corp 'ufw status' + +# Verificar servicios HST +ssh hst 'systemctl status nginx' +ssh hst 'systemctl status postgresql' +``` + +### Logs Importantes + +```bash +# PostgreSQL +journalctl -u postgresql -f + +# Docker containers +docker logs -f + +# Nginx (HST) +tail -f /var/log/nginx/access.log +tail -f /var/log/nginx/error.log + +# SSH auth +tail -f /var/log/auth.log +``` + +--- + +## Diagrama de Red + +``` + Internet + │ + ┌──────────────────────────┼──────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ + │ ARCHITECT │ │ DECK │ │ CORP │ + │ 69.62.126.110 │◄────────│ 72.62.1.113 │────────►│92.112.181.188 │ + └───────────────┘ SSH └───────────────┘ SSH └───────────────┘ + │ │ │ + │ │ │ + │ ▼ │ + │ ┌───────────────┐ │ + │ │ HST │ │ + └────────────────►│ 72.62.2.84 │◄──────────────────┘ + SSH └───────────────┘ + │ + │ HTTPS + ▼ + ┌───────────────┐ + │ Cloudflare │ + │ R2 │ + └───────────────┘ +``` diff --git a/06_INTEGRACIONES/gpu-services.md b/06_INTEGRACIONES/gpu-services.md new file mode 100644 index 0000000..1561f52 --- /dev/null +++ b/06_INTEGRACIONES/gpu-services.md @@ -0,0 +1,179 @@ +# GPU Services - RunPod + +**Versión:** 5.0 +**Fecha:** 2024-12-24 + +--- + +## Estado Crítico + +**ALERTA: RunPod NO es confiable para producción.** + +### Incidente 2024-12-24 + +RunPod falló en provisionar workers a pesar de: +- Configuración correcta +- Balance suficiente ($72+) +- Jobs en cola + +**Resultado:** 0 workers activos. Servicio GPU inoperativo. + +--- + +## Endpoints Configurados + +| Servicio | Endpoint ID | Estado | +|----------|-------------|--------| +| GRACE | r00x4g3rrwkbyh | Inactivo | +| PENNY | 0mxhaokgsmgee3 | Inactivo | +| FACTORY | ddnuk6y35zi56a | Inactivo | + +--- + +## GRACE (Extracción IA) + +### Módulos Implementados (6 de 18) + +| Módulo | Descripción | +|--------|-------------| +| ASR | Speech-to-text | +| OCR | Reconocimiento texto | +| TTS | Text-to-speech | +| Face | Reconocimiento facial | +| Embeddings | Vectores semánticos | +| Avatar | Generación avatares | + +### Módulos Pendientes (12) + +- Document parsing +- Image classification +- Object detection +- Sentiment analysis +- Named entity recognition +- Translation +- Summarization +- Question answering +- Code generation +- Audio classification +- Video analysis +- Multimodal fusion + +--- + +## Código Disponible en R2 + +Los handlers están listos y son portables: + +``` +s3://architect/gpu-services/ +├── base/ +│ └── bootstrap.sh +├── grace/ +│ └── code/handler.py +├── penny/ +│ └── code/handler.py +└── factory/ + └── code/handler.py +``` + +### Descargar Código + +```bash +source /home/orchestrator/orchestrator/.env +export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY" +export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY" + +aws s3 sync s3://architect/gpu-services/ ./gpu-services/ \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +``` + +--- + +## Alternativas a Evaluar + +### 1. Modal (Recomendado) + +- Pricing: Pay-per-use +- Pros: Serverless real, buen DX, Python-native +- Contras: Menos GPUs disponibles que RunPod + +```python +import modal + +stub = modal.Stub("grace") + +@stub.function(gpu="A10G") +def process_asr(audio_bytes): + # Whisper inference + pass +``` + +### 2. Replicate + +- Pricing: Per-inference +- Pros: Modelos pre-entrenados, API simple +- Contras: Menos control, más caro a escala + +### 3. Lambda Labs + +- Pricing: Hourly +- Pros: Hardware dedicado +- Contras: Menos flexible, reserva manual + +### 4. Self-Hosted + +- Pricing: Upfront + hosting +- Pros: Control total, sin dependencias +- Contras: CapEx alto, mantenimiento + +--- + +## Migración Propuesta + +### Fase 1: Evaluación (1 semana) +- [ ] Probar Modal con ASR handler +- [ ] Comparar latencia y costo + +### Fase 2: Migración (2 semanas) +- [ ] Portar 6 handlers a Modal +- [ ] Actualizar endpoints en MASON + +### Fase 3: Producción +- [ ] Desplegar en Modal +- [ ] Deprecar RunPod endpoints + +--- + +## Configuración Actual RunPod + +### API Key + +``` +Almacenada en: creds_runpod (PostgreSQL ARCHITECT) +Campo: api_key_runpod +``` + +### SDK + +```python +import runpod + +runpod.api_key = "..." + +# Crear job +job = runpod.run( + endpoint_id="r00x4g3rrwkbyh", + input={"audio": "base64..."} +) + +# Check status +status = runpod.status(job["id"]) +``` + +--- + +## Recomendación + +**NO confiar en RunPod para producción.** + +Migrar a Modal como prioridad alta una vez resueltos los issues de seguridad críticos. diff --git a/99_ANEXOS/inventario-repos.md b/99_ANEXOS/inventario-repos.md new file mode 100644 index 0000000..947adc4 --- /dev/null +++ b/99_ANEXOS/inventario-repos.md @@ -0,0 +1,387 @@ +# Inventario de Repositorios TZZR + +**Versión:** 5.0 +**Fecha:** 2024-12-24 +**Fuente:** Gitea (http://localhost:3000/tzzr) + +--- + +## Resumen + +| Categoría | Cantidad | +|-----------|----------| +| Infraestructura | 6 | +| Data Services | 6 | +| Security/Ops | 6 | +| Interfaces | 6 | +| **Total** | **24** | + +--- + +## Infraestructura + +### orchestrator + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/orchestrator | +| Estado | Activo | +| Descripción | Sistema de orquestación central | +| Prioridad | Alta | + +**Archivos clave:** +- `main.py` - Entrada principal +- `.env` - Configuración +- `docker-compose.yml` - Despliegue + +--- + +### hst-api + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/hst-api | +| Estado | Activo | +| Descripción | API de tags HST (973 tags) | +| Prioridad | Alta | + +**Archivos clave:** +- `api/routes.py` - Endpoints +- `db/schema.sql` - Schema + +--- + +### clara + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/clara | +| Estado | Activo | +| Descripción | Agente de ingesta personal | +| Prioridad | Alta | + +**Archivos clave:** +- `app.py` - API FastAPI +- `ingest.py` - Lógica de ingesta +- `Dockerfile` - Container + +--- + +### margaret + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/margaret | +| Estado | Activo | +| Descripción | Agente de ingesta corporativo | +| Prioridad | Alta | + +**Archivos clave:** +- `app.py` - API FastAPI +- `ingest.py` - Lógica de ingesta +- `Dockerfile` - Container + +--- + +### alfred + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/alfred | +| Estado | Activo | +| Descripción | Flujos predefinidos DECK | +| Prioridad | Media | + +**Archivos clave:** +- `flows/` - Definiciones de flujos +- `executor.py` - Motor de ejecución + +--- + +### jared + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/jared | +| Estado | Activo | +| Descripción | Flujos predefinidos CORP | +| Prioridad | Media | + +**Archivos clave:** +- `flows/` - Definiciones de flujos +- `executor.py` - Motor de ejecución + +--- + +## Data Services + +### mason + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/mason | +| Estado | Activo | +| Descripción | Enriquecimiento de datos | +| Prioridad | Alta | + +**Archivos clave:** +- `workspace.py` - Gestión workspace +- `enrichment.py` - Lógica de enriquecimiento + +--- + +### feldman + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/feldman | +| Estado | Activo | +| Descripción | Consolidación blockchain | +| Prioridad | Alta | + +**Archivos clave:** +- `validator.py` - Reglas M-001, M-002, M-003 +- `consolidator.py` - Creación de bloques + +--- + +### grace-handler + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/grace-handler | +| Estado | Bloqueado (RunPod) | +| Descripción | Handler GPU para GRACE | +| Prioridad | Alta | + +**Archivos clave:** +- `handler.py` - RunPod handler +- `modules/` - 6 módulos IA + +--- + +### penny-handler + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/penny-handler | +| Estado | Planificado | +| Descripción | Handler GPU para PENNY | +| Prioridad | Baja | + +--- + +### factory-handler + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/factory-handler | +| Estado | Planificado | +| Descripción | Handler GPU para FACTORY | +| Prioridad | Baja | + +--- + +### s-contract + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/s-contract | +| Estado | En desarrollo | +| Descripción | Contextos y datasets IA | +| Prioridad | Media | + +--- + +## Security/Ops + +### sentinel + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/sentinel | +| Estado | Planificado | +| Descripción | Auditoría del sistema | +| Prioridad | Media | + +**Modos:** +- LIGHT: Cada 5 min, reglas automáticas +- DEEP: Cada 1 hora, muestreo con LLM + +--- + +### infisical-config + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/infisical-config | +| Estado | Activo | +| Descripción | Configuración Infisical | +| Prioridad | Alta | + +--- + +### backup-scripts + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/backup-scripts | +| Estado | En desarrollo | +| Descripción | Scripts de backup R2 | +| Prioridad | Alta | + +--- + +### deploy-configs + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/deploy-configs | +| Estado | Activo | +| Descripción | Configuraciones de despliegue | +| Prioridad | Media | + +--- + +### monitoring + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/monitoring | +| Estado | Planificado | +| Descripción | Dashboards y alertas | +| Prioridad | Media | + +--- + +### security-audit + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/security-audit | +| Estado | En desarrollo | +| Descripción | Scripts de auditoría | +| Prioridad | Alta | + +--- + +## Interfaces + +### packet-app + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/packet-app | +| Estado | En desarrollo | +| Descripción | App móvil Flutter | +| Prioridad | Alta | + +**Tecnología:** Flutter/Dart + +--- + +### vision-builder + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/vision-builder | +| Estado | En desarrollo | +| Descripción | Diseñador de visiones | +| Prioridad | Media | + +--- + +### admin-dashboard + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/admin-dashboard | +| Estado | Planificado | +| Descripción | Dashboard administrativo | +| Prioridad | Baja | + +--- + +### api-gateway + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/api-gateway | +| Estado | Planificado | +| Descripción | Gateway API unificado | +| Prioridad | Media | + +--- + +### docs-site + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/docs-site | +| Estado | En desarrollo | +| Descripción | Sitio de documentación | +| Prioridad | Media | + +--- + +### system-docs + +| Campo | Valor | +|-------|-------| +| URL | http://localhost:3000/tzzr/system-docs | +| Estado | Activo (este repo) | +| Descripción | Documentación System v5 | +| Prioridad | Alta | + +--- + +## Estadísticas + +### Por Estado + +| Estado | Cantidad | +|--------|----------| +| Activo | 12 | +| En desarrollo | 6 | +| Planificado | 5 | +| Bloqueado | 1 | + +### Por Prioridad + +| Prioridad | Cantidad | +|-----------|----------| +| Alta | 12 | +| Media | 8 | +| Baja | 4 | + +--- + +## Dependencias Entre Repos + +``` +packet-app + │ + ▼ +clara / margaret + │ + ▼ +alfred / jared + │ + ▼ +mason ◄──── grace-handler (bloqueado) + │ + ▼ +feldman + │ + ▼ +sentinel (planificado) +``` + +--- + +## Notas + +1. **grace-handler**: Código listo en R2, RunPod no inicia workers +2. **sentinel**: Solo documentación, sin implementación +3. **system-docs**: Este repositorio, documentación v5 +4. **orchestrator**: Coordinador central en ARCHITECT diff --git a/README.md b/README.md index a73ce15..2dd626c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,120 @@ -# system-docs +# TZZR System Documentation v5 -Documentación oficial del sistema TZZR - System v5 \ No newline at end of file +**Versión:** 5.0 +**Fecha:** 2024-12-24 +**Estado:** Consolidación completa + +--- + +## Qué es TZZR + +TZZR es un sistema de construcción de arquitecturas personales y empresariales mediante instancias Claude. Los agentes IA actúan como constructores que diseñan y edifican servidores clonables e independientes. + +--- + +## Arquitectura General + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ARCHITECT (69.62.126.110) │ +│ PostgreSQL central │ Gitea │ Orchestrator │ Infisical │ +└─────────────────────────────────────────────────────────────┘ + │ │ │ + ▼ ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ DECK │ │ CORP │ │ HST │ +│ 72.62.1.113 │ │ 92.112.181.188 │ │ 72.62.2.84 │ +│ │ │ │ │ │ +│ CLARA, ALFRED │ │ MARGARET, JARED │ │ 973 tags │ +│ Servidor │ │ MASON, FELDMAN │ │ API pública │ +│ Personal │ │ Empresarial │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ + └────────┬───────────┘ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Cloudflare R2 (5 buckets) │ +│ architect │ deck │ corp │ hst │ locker │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Flujo de Datos Principal + +``` +PACKET (móvil) + ↓ +CLARA (DECK) / MARGARET (CORP) ← Ingesta inmutable + ↓ +ALFRED / JARED ← Flujos predefinidos + ↓ +MASON ← Enriquecimiento (24h) + ↓ +FELDMAN ← Consolidación blockchain + ↓ +SENTINEL ← Auditoría (planificado) +``` + +--- + +## Índice de Documentación + +### 00_VISION +- [Filosofía](00_VISION/filosofia.md) - 10 principios fundacionales +- [Glosario](00_VISION/glosario.md) - Términos técnicos A-Z + +### 01_ARQUITECTURA +- [Overview](01_ARQUITECTURA/overview.md) - Vista general consolidada +- [Servidores](01_ARQUITECTURA/servidores.md) - ARCHITECT, DECK, CORP, HST + +### 02_MODELO_DATOS +- [Entidades](02_MODELO_DATOS/entidades.md) - HST, ITM, PLY, LOC, FLG +- [Planos](02_MODELO_DATOS/planos.md) - T0 (ITM), MST, BCK + +### 03_COMPONENTES +- [CLARA/MARGARET](03_COMPONENTES/agentes/clara-margaret.md) - Ingesta +- [FELDMAN](03_COMPONENTES/agentes/feldman.md) - Consolidación +- [GRACE](03_COMPONENTES/servicios/grace.md) - IA cognitiva + +### 04_SEGURIDAD +- [Modelo de Amenazas](04_SEGURIDAD/modelo-amenazas.md) - Riesgos +- [Secretos](04_SEGURIDAD/secretos.md) - Gestión credenciales + +### 05_OPERACIONES +- [Infraestructura](05_OPERACIONES/infraestructura.md) - Servidores +- [Backup/Recovery](05_OPERACIONES/backup-recovery.md) - DR plan + +### 06_INTEGRACIONES +- [GPU Services](06_INTEGRACIONES/gpu-services.md) - RunPod + +### 99_ANEXOS +- [Inventario Repos](99_ANEXOS/inventario-repos.md) - 24 repos + +--- + +## Estado Actual + +| Componente | Estado | Notas | +|------------|--------|-------| +| CLARA | Operativo | DECK:5051 | +| MARGARET | Operativo | CORP:5051 | +| ALFRED | Operativo | DECK:5052 | +| JARED | Operativo | CORP:5052 | +| MASON | Operativo | CORP:5053 | +| FELDMAN | Operativo | CORP:5054 | +| HST | Operativo | 973 tags | +| SENTINEL | Planificado | Sin implementar | +| GRACE | Bloqueado | RunPod no inicia | +| NOTARIO | Planificado | Sin implementar | + +--- + +## Generación + +Documentación generada mediante proceso de auditoría colaborativa: +- 3 auditores especializados (Arquitectura, Datos, Seguridad) +- Cross-review y resolución de conflictos +- Síntesis consolidada + +**Fecha generación:** 2024-12-24