infrastructure-docs/services/context-manager.md

# Context Manager - Sistema de Gestión de Contexto

## Información General

- **Servidor**: ARCHITECT (69.62.126.110)
- **Ubicación**: /home/architect/captain-claude/context-manager/
- **Tecnología**: Python + PostgreSQL
- **Base de datos**: PostgreSQL (local)

## Descripción

Context Manager es un sistema de gestión de contexto diseñado para coordinar agentes de IA en el sistema TZZR. Proporciona:

- Almacenamiento centralizado de contexto
- Control de acceso a contexto entre agentes
- Versionamiento de contexto
- Auditoría de cambios
- Integración con múltiples proveedores de IA (Anthropic, OpenAI)

## Arquitectura

### Componentes

```
context-manager/
├── schemas/              # Definiciones de base de datos
│   ├── 00_base.sql
│   ├── 01_immutable_log.sql
│   ├── 02_context_manager.sql
│   └── 03_algorithm_engine.sql
├── src/
│   ├── __init__.py
│   ├── database.py       # Conexión a PostgreSQL
│   ├── models.py         # Modelos de datos
│   ├── context_selector.py
│   └── providers/        # Integraciones con IA
│       ├── base.py
│       ├── anthropic.py
│       └── openai.py
└── tests/               # Tests unitarios
```

### Base de Datos

**Host**: localhost (ARCHITECT)
**Puerto**: 5432
**Base de datos**: tzzr_db

**Tablas principales**:
- `context` - Almacenamiento de contexto
- `agents` - Registro de agentes
- `access_log` - Auditoría de accesos
- `context_history` - Versionamiento

## Instalación

### Requisitos
- Python 3.9+
- PostgreSQL 12+
- pip

### Setup
```bash
cd /home/architect/captain-claude/context-manager/

# Crear entorno virtual
python3 -m venv venv
source venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt

# Inicializar base de datos
python -m src.database init
```

## Configuración

### Variables de Entorno
Archivo: `/home/architect/captain-claude/context-manager/.env`

```env
# PostgreSQL
DATABASE_URL=postgresql://architect:password@localhost:5432/tzzr_db

# Providers de IA
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...

# Configuración del sistema
CONTEXT_MANAGER_PORT=5000
LOG_LEVEL=INFO
```

## API

### Endpoints Principales

#### Crear Contexto
```bash
POST /api/context
Content-Type: application/json

{
  "agent_id": "agent_name",
  "context_data": {
    "key": "value"
  },
  "metadata": {
    "priority": "high"
  }
}
```

#### Obtener Contexto
```bash
GET /api/context/{context_id}
```

#### Actualizar Contexto
```bash
PATCH /api/context/{context_id}
Content-Type: application/json

{
  "context_data": {
    "key": "new_value"
  }
}
```

#### Eliminar Contexto
```bash
DELETE /api/context/{context_id}
```

#### Obtener Historial
```bash
GET /api/context/{context_id}/history
```

#### Listar Contextos de Agente
```bash
GET /api/agent/{agent_id}/contexts
```

## Uso desde Agentes

### Ejemplo Python
```python
from src.database import DatabaseManager
from src.context_selector import ContextSelector

# Conectar a base de datos
db = DatabaseManager()

# Crear contexto
context = db.create_context(
    agent_id="mi_agente",
    context_data={"información": "valor"},
    metadata={"priority": "high"}
)

# Obtener contexto
contexto = db.get_context(context_id)

# Actualizar
db.update_context(context_id, new_data)

# Seleccionar contexto relevante
selector = ContextSelector(db)
contextos_relevantes = selector.select_for_agent(
    agent_id="mi_agente",
    query="búsqueda"
)
```

## Proveedores de IA

### Anthropic
```python
from src.providers.anthropic import AnthropicProvider

provider = AnthropicProvider(api_key="sk-...")
response = provider.process_with_context(
    model="claude-opus-4.5-20251101",
    messages=[...],
    context=context_data
)
```

### OpenAI
```python
from src.providers.openai import OpenAIProvider

provider = OpenAIProvider(api_key="sk-...")
response = provider.process_with_context(
    model="gpt-4",
    messages=[...],
    context=context_data
)
```

## Esquemas de Base de Datos

### Tabla: context
```sql
CREATE TABLE context (
    id UUID PRIMARY KEY,
    agent_id VARCHAR NOT NULL,
    context_data JSONB NOT NULL,
    metadata JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    version INTEGER DEFAULT 1
);
```

### Tabla: access_log
```sql
CREATE TABLE access_log (
    id SERIAL PRIMARY KEY,
    context_id UUID REFERENCES context(id),
    agent_id VARCHAR NOT NULL,
    action VARCHAR NOT NULL,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## Monitoreo y Logs

### Logs de Aplicación
```bash
tail -f /var/log/captain-claude/context-manager.log
```

### Estadísticas
```bash
# Número de contextos por agente
psql -U architect tzzr_db -c "SELECT agent_id, COUNT(*) FROM context GROUP BY agent_id;"

# Últimos accesos
psql -U architect tzzr_db -c "SELECT * FROM access_log ORDER BY timestamp DESC LIMIT 10;"
```

## Backup y Recuperación

### Backup
```bash
pg_dump -U architect tzzr_db > /home/backups/context_manager_backup.sql

# Subir a R2
aws s3 cp /home/backups/context_manager_backup.sql s3://architect/backups/ \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```

### Restaurar
```bash
psql -U architect tzzr_db < context_manager_backup.sql
```

## Testing

```bash
cd /home/architect/captain-claude/context-manager/

# Ejecutar tests
pytest tests/

# Tests con coverage
pytest --cov=src tests/

# Tests específicos
pytest tests/test_database.py -v
```

## Troubleshooting

### Error de conexión a BD
```python
from src.database import DatabaseManager
db = DatabaseManager()
db.test_connection()
```

### Logs detallados
```bash
# Cambiar nivel de log
export LOG_LEVEL=DEBUG
python -m src.main
```

## Últimas Actualizaciones

- 2025-12-30: Documentación inicial
- 2025-12-28: Implementación inicial de Context Manager