# 🤖 CBC Nextcloud AI Service - Documentación para Asistentes IA

## 📋 Resumen Ejecutivo

Este es un sistema automatizado de procesamiento de contenido académico que utiliza inteligencia artificial para transcribir audios, procesar PDFs y generar resúmenes colaborativos mediante la integración de 3 modelos de IA diferentes.

**Estado Actual**: ✅ ACTIVO y FUNCIONANDO
- **Servicio**: `cbc-main.service` (systemd)
- **Proceso Principal**: PID 49696 (única instancia)
- **GPU**: NVIDIA RTX 3050 (1.5GB/8GB en uso)
- **Última Actualización**: 2025-09-26

---

## 🖥️ Especificaciones del Sistema

### Hardware
- **CPU**: AMD Ryzen 5 5600X 6-Core Processor (12 hilos)
- **RAM**: 15GB DDR4 (9.7GB disponible)
- **GPU**: NVIDIA GeForce RTX 3050 (8GB VRAM)
- **Almacenamiento**: 439GB SSD (330GB libre)
- **Sistema Operativo**: Linux x86_64

### Software
- **Python**: 3.10.12
- **CUDA**: 12.2 (Driver 535.247.01)
- **Gestor de Servicios**: systemd
- **Directorio Principal**: `/home/ren/cbc/`

### Librerías Clave
- `torch` 2.8.0 (PyTorch con soporte CUDA)
- `transformers` 4.56.1 (Hugging Face)
- `whisper` 20240930 (OpenAI)
- `easyocr` 1.7.2 (OCR)
- `openai` 1.107.0 (API clientes)
- `python-docx` 1.2.0 (manipulación Word)
- `pdf2image` 1.17.0 (procesamiento PDF)

---

## 🚀 Funcionalidades Principales

### 1. Procesamiento de Audio
- **Formatos Soportados**: MP3, WAV, M4A, OGG
- **Transcripción**: Whisper (medium) con GPU aceleración
- **Salida**: Archivos de texto con timestamps
- **Ubicación**: Carpeta `Audios` en Nextcloud

### 2. Procesamiento de PDF
- **OCR Múltiple**: EasyOCR + Tesseract + TrOCR
- **Procesamiento por Lotes**: 3 páginas por chunk
- **Corrección IA**: Gemini para limpieza de texto
- **Salida**: Documentos DOCX editables
- **Ubicación**: Carpeta `Pdf` en Nextcloud

### 3. Sistema de Resúmenes Colaborativos
**3 Modelos de IA trabajando en secuencia**:

1. **GPT-OSS-120B** (DeepInfra API):
   - Genera bullet points clave
   - Análisis inicial del contenido

2. **Claude/Zhai** (CLI - API Z.ai):
   - Desarrolla resumen integral
   - 400-500 palabras estructuradas

3. **Gemini** (CLI - Google):
   - Aplica formato final
   - Optimiza presentación

### 4. Clasificación Inteligente de Contenido
El sistema clasifica automáticamente en 4 categorías temáticas:
- `historia` - Eventos históricos, cronologías
- `analisis_contable` - Contabilidad, finanzas, balances
- `instituciones_gobierno` - Política, gobierno, leyes
- `otras_clases` - Ciencias, tecnología, literatura, etc.

### 5. Generación de Quizzes
- **10 preguntas** de opción múltiple por documento
- **4 opciones** (A, B, C, D) por pregunta
- **Respuestas incluidas** en documentos separados

---

## ⚙️ Configuración Actual

### Variables de Entorno
```bash
CUDA_LAUNCH_BLOCKING=1          # Depuración CUDA síncrona
PYTHONPATH=/home/ren/cbc        # Ruta del proyecto
HOME=/home/ren                  # Directorio home
```

### Rutas del Sistema
- **Descargas**: `/app/downloads/`
- **Resúmenes**: `./downloads/`
- **Documentos DOCX**: `./resumenes_docx/`
- **Archivos Procesados**: `/app/processed_files.txt`

### Límites de Recursos
- **Memoria RAM**: 8GB máximo
- **CPU**: 90% de cuota
- **Archivos Abiertos**: 65536
- **Reinicio Automático**: Siempre (10 segundos de espera)

---

## 📁 Estructura de Archivos Principal

```
/home/ren/cbc/
├── main.py                    # Servicio principal (72,405 líneas)
├── .env                       # Variables de entorno
├── requirements.txt           # Dependencias Python
├── README_AI_ASSISTANT.md    # Este documento
├── MEGA_HISTORIA_parte*.txt   # Historiales académicos
├── resumen_*.py              # Scripts de resumen
├── procesador_academico.py   # Procesamiento especializado
├── analizador_*.py           # Análisis de contenido
├── config_telegram.txt       # Configuración Telegram
└── txt/                      # Directorio de textos
```

---

## 🔧 Gestión del Servicio

### Comandos Essenciales
```bash
# Ver estado del servicio
sudo systemctl status cbc-main

# Ver logs en tiempo real
sudo journalctl -u cbc-main -f

# Detener servicio
sudo systemctl stop cbc-main

# Iniciar servicio
sudo systemctl start cbc-main

# Reiniciar servicio
sudo systemctl restart cbc-main

# Ver uso de GPU
nvidia-smi

# Ver uso de memoria del sistema
free -h
```

### Monitoreo de Salud
```bash
# Verificar proceso único
ps aux | grep "python3.*main.py" | grep -v grep

# Verificar memoria GPU
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

# Verificar espacio en disco
df -h /

# Verificar actividad de red
sudo netstat -tlnp | grep :80
```

---

## 🚨 Problemas Comunes y Soluciones

### Error CUDA: "CUDA-capable device(s) is/are busy or unavailable"
**Causa**: Múltiples procesos compitiendo por recursos GPU
**Solución**:
```bash
# Verificar procesos múltiples
ps aux | grep "python3.*main.py"

# Si hay múltiples, reiniciar servicio
sudo systemctl restart cbc-main
```

### Error de Permiso: "Permission denied"
**Causa**: El servicio no tiene permisos para escribir en `/app/`
**Solución**:
```bash
# Crear directorios con permisos correctos
sudo mkdir -p /app/downloads /app/resumenes
sudo chown -R ren:ren /app/
```

### Alto Uso de Memoria GPU
**Configuración actual optimizada**:
- `MAX_PAGES_PER_CHUNK = 3` (reducido de 5)
- `PDF_DPI = 200` (reducido de 300)
- `batch_size = 1` (procesamiento individual)
- `_MODEL_TIMEOUT_SECONDS = 300` (liberación rápida)

---

## 🔄 Flujo de Trabajo Automático

### 1. Detección de Archivos
- Monitorea carpetas Nextcloud cada 5 segundos
- Verifica archivos no procesados en `processed_files.txt`

### 2. Procesamiento según Tipo
**Audio** → Transcripción → Resumen Colaborativo → Clasificación → Subida
**PDF** → OCR → Corrección IA → Documento Editable → Resumen → Subida

### 3. Clasificación y Organización
- Análisis de contenido con Gemini
- Clasificación en categorías temáticas
- Renombrado automático con temas extraídos
- Organización en carpetas específicas

### 4. Notificaciones
- Envío de alertas por Telegram
- Reportes de progreso y errores
- Confirmación de procesamiento completado

---

## 📊 Métricas de Rendimiento

### Rendimiento Actual
- **Procesamiento PDF**: ~3-5 minutos por documento (12 páginas)
- **Transcripción Audio**: ~2-3 minutos por 10 minutos de audio
- **Generación Resúmenes**: ~1-2 minutos por documento
- **Uso GPU**: 1.5GB (estable)
- **Uso CPU**: 44% promedio
- **Memoria RAM**: 1.1GB utilizada

### Optimizaciones Aplicadas
- ✅ Procesamiento único (sin duplicados)
- ✅ Gestión agresiva de VRAM
- ✅ Límites de recursos controlados
- ✅ Reintentos automáticos para errores CUDA
- ✅ Sistema de clasificación inteligente

---

## 🔮 Estado y Próximos Pasos

### Estado Actual: SISTEMA ESTABLE
- ✅ Servicio systemd funcionando correctamente
- ✅ GPU operativa sin errores
- ✅ Procesamiento de PDF activo
- ✅ Clasificación automática funcionando
- ✅ Notificaciones Telegram operativas

### Posibles Mejoras Futuras
- Implementar cola de procesamiento para manejar carga pesada
- Añadir interfaz web para monitoreo
- Optimizar tiempos de procesamiento con modelos más eficientes
- Implementar sistema de backup automático
- Añadir métricas detalladas de rendimiento

---

## 📞 Información de Contacto y Soporte

### Para Emergencias del Sistema
```bash
# Reinicio completo del sistema
sudo systemctl restart cbc-main

# Liberación forzada de VRAM
sudo pkill -f python3
sudo systemctl start cbc-main
```

### Archivos de Log Importantes
- **Journal Systemd**: `sudo journalctl -u cbc-main`
- **Log GPU**: `nvidia-smi --query-gpu=timestamp,memory.used --format=csv -l 1`
- **Log Memoria**: `free -h -s 5`

### Puntos Críticos del Sistema
1. **Disponibilidad GPU**: NVIDIA RTX 3050 (8GB)
2. **Espacio en Disco**: 330GB disponibles
3. **Conexión Nextcloud**: WebDAV funcional
4. **API Keys**: Configuradas y operativas

---

*Este documento fue generado automáticamente el 2025-09-26 para proporcionar a asistentes IA una comprensión completa del estado y funcionalidad del sistema CBC Nextcloud AI Service.*