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

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

# 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

POST /api/context
Content-Type: application/json

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

Obtener Contexto

GET /api/context/{context_id}

Actualizar Contexto

PATCH /api/context/{context_id}
Content-Type: application/json

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

Eliminar Contexto

DELETE /api/context/{context_id}

Obtener Historial

GET /api/context/{context_id}/history

Listar Contextos de Agente

GET /api/agent/{agent_id}/contexts

Uso desde Agentes

Ejemplo 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

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

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

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

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

tail -f /var/log/captain-claude/context-manager.log

Estadísticas

# 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

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

psql -U architect tzzr_db < context_manager_backup.sql

Testing

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

from src.database import DatabaseManager
db = DatabaseManager()
db.test_connection()

Logs detallados

# 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