Infrastructure documentation - Initial commit
- Added comprehensive infrastructure overview - Server documentation: ARCHITECT, DECK, CORP, HST - Service documentation: Odoo, Directus, Context Manager - Includes configuration, monitoring, and backup procedures
This commit is contained in:
ARCHITECT
296
services/context-manager.md
Normal file
296
services/context-manager.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user