diff --git a/README.md b/README.md index 662d3bc..d209386 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,94 @@ -# CBCFacil v9 +# 🎡 CBCFacil v9 -Servicio de IA unificado para procesamiento inteligente de documentos (audio, PDF, texto) con integracion a Nextcloud. +Sistema de IA para procesamiento inteligente de documentos (audio, PDF, texto) con integraciΓ³n a Nextcloud y dashboard web interactivo. -## Descripcion General +## ✨ CaracterΓ­sticas Principales -CBCFacil monitoriza automaticamente tu servidor Nextcloud, descarga archivos multimedia, los transcribe/resume utilizando modelos de IA (Whisper, Claude, Gemini) y genera documentos formateados para su descarga. +- πŸŽ™οΈ **TranscripciΓ³n de Audio** - Whisper con soporte GPU/CPU +- πŸ“ **GeneraciΓ³n de ResΓΊmenes** - Claude AI o Gemini +- πŸ“„ **MΓΊltiples Formatos** - Genera TXT, MD, DOCX, PDF +- ☁️ **SincronizaciΓ³n Nextcloud** - Descarga y sube automΓ‘ticamente +- πŸ–₯️ **Dashboard Web** - Monitoreo y regeneraciΓ³n de resΓΊmenes +- πŸ“± **Notificaciones Telegram** - Alertas en tiempo real +- πŸ”„ **Reprocesamiento** - Regenera resΓΊmenes sin re-transcribir -## Arquitectura +## πŸ—οΈ Arquitectura ``` -+----------------+ +--------------+ +-----------------+ +------------------+ -| Nextcloud |---->| Procesador |---->| IA Services |---->| Dashboard/API | -| (WebDAV) | | (Audio/PDF) | | (Claude/Gemini)| | (Flask) | -+----------------+ +--------------+ +-----------------+ +------------------+ - | | | - v v v - +------------+ +------------+ +------------+ - | Whisper | | Gemini | | Telegram | - | (GPU) | | API/CLI | | (notify) | - +------------+ +------------+ +------------+ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CBCFacil v9 β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Nextcloud │────▢│ Processor │────▢│ AI Service β”‚ β”‚ +β”‚ β”‚ (WebDAV) β”‚ β”‚Audio/PDF/TXTβ”‚ β”‚Claude/Geminiβ”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β–Ό β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ Whisper β”‚ β”‚ Document β”‚ β”‚ +β”‚ β”‚ β”‚ (GPU) β”‚ β”‚ Generator β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Dashboard Web (Flask) β”‚ β”‚ +β”‚ β”‚ β€’ Vista de archivos β€’ Regenerar resΓΊmenes β”‚ β”‚ +β”‚ β”‚ β€’ Panel de versiones β€’ PrevisualizaciΓ³n β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Telegram β”‚ β”‚ +β”‚ β”‚ (Notifica) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -## Estructura del Proyecto +## πŸ“ Estructura del Proyecto ``` cbcfacil/ -β”œβ”€β”€ main.py # Punto de entrada del servicio -β”œβ”€β”€ run.py # Script de ejecucion alternativo -β”œβ”€β”€ config/ # Configuracion centralizada -β”‚ β”œβ”€β”€ settings.py # Variables de entorno y settings -β”‚ └── validators.py # Validadores de configuracion -β”œβ”€β”€ core/ # Nucleo del sistema -β”‚ β”œβ”€β”€ exceptions.py # Excepciones personalizadas -β”‚ β”œβ”€β”€ result.py # Patron Result -β”‚ └── base_service.py # Clase base para servicios -β”œβ”€β”€ services/ # Servicios externos -β”‚ β”œβ”€β”€ webdav_service.py # Operacones WebDAV/Nextcloud -β”‚ β”œβ”€β”€ vram_manager.py # Gestion de memoria GPU -β”‚ β”œβ”€β”€ telegram_service.py # Notificaciones Telegram -β”‚ └── ai/ # Proveedores de IA -β”‚ β”œβ”€β”€ base_provider.py # Interfaz base -β”‚ β”œβ”€β”€ claude_provider.py # Claude (Z.ai) -β”‚ β”œβ”€β”€ gemini_provider.py # Gemini API/CLI -β”‚ └── provider_factory.py # Factory de proveedores -β”œβ”€β”€ processors/ # Procesadores de archivos -β”‚ β”œβ”€β”€ audio_processor.py # Transcripcion Whisper -β”‚ β”œβ”€β”€ pdf_processor.py # OCR y extraccion PDF -β”‚ └── text_processor.py # Resumenes y clasificacion -β”œβ”€β”€ document/ # Generacion de documentos -β”‚ └── generators.py # DOCX, PDF, Markdown -β”œβ”€β”€ storage/ # Persistencia -β”‚ └── processed_registry.py # Registro de archivos procesados -β”œβ”€β”€ api/ # API REST -β”‚ └── routes.py # Endpoints Flask -β”œβ”€β”€ tests/ # Tests unitarios e integracion -β”œβ”€β”€ docs/ # Documentacion -β”‚ β”œβ”€β”€ archive/ # Documentacion historica -β”‚ β”œβ”€β”€ SETUP.md # Guia de configuracion -β”‚ β”œβ”€β”€ TESTING.md # Guia de testing -β”‚ └── DEPLOYMENT.md # Guia de despliegue -β”œβ”€β”€ requirements.txt # Dependencias Python -β”œβ”€β”€ requirements-dev.txt # Dependencias desarrollo -β”œβ”€β”€ .env.secrets # Configuracion local (no versionar) - +β”œβ”€β”€ main.py # Punto de entrada principal +β”œβ”€β”€ config/ +β”‚ └── settings.py # ConfiguraciΓ³n centralizada +β”œβ”€β”€ services/ +β”‚ β”œβ”€β”€ webdav_service.py # Cliente WebDAV/Nextcloud +β”‚ β”œβ”€β”€ vram_manager.py # GestiΓ³n memoria GPU +β”‚ β”œβ”€β”€ telegram_service.py # Notificaciones +β”‚ └── ai/ +β”‚ β”œβ”€β”€ claude_provider.py # Provider Claude (Z.ai) +β”‚ β”œβ”€β”€ gemini_provider.py # Provider Gemini +β”‚ └── provider_factory.py +β”œβ”€β”€ processors/ +β”‚ β”œβ”€β”€ audio_processor.py # TranscripciΓ³n Whisper +β”‚ β”œβ”€β”€ pdf_processor.py # OCR y extracciΓ³n +β”‚ └── text_processor.py # ClasificaciΓ³n +β”œβ”€β”€ document/ +β”‚ └── generators.py # Genera DOCX, PDF, Markdown +β”œβ”€β”€ storage/ +β”‚ └── processed_registry.py # Registro de procesados +β”œβ”€β”€ api/ +β”‚ └── routes.py # API REST + Dashboard +β”œβ”€β”€ templates/ +β”‚ └── index.html # Dashboard UI +└── downloads/ # Archivos descargados ``` -## Requisitos +## πŸš€ InstalaciΓ³n +### Requisitos - Python 3.10+ -- NVIDIA GPU con drivers CUDA 12.1+ (opcional, soporta CPU fallback) -- Nextcloud accesible via WebDAV -- Claves API para servicios de IA (opcional) +- NVIDIA GPU + CUDA 12.1+ (opcional, fallback a CPU) +- Nextcloud con WebDAV habilitado -## Instalacion Rapida +### InstalaciΓ³n RΓ‘pida ```bash -# Clonar y entrar al directorio -git clone -cd cbcfacil +# Clonar repositorio +git clone https://gitea.cbcren.online/renato97/cbcren2026.git +cd cbcren2026 # Crear entorno virtual python3 -m venv .venv @@ -86,116 +97,124 @@ source .venv/bin/activate # Instalar dependencias pip install -r requirements.txt -# Configurar variables de entorno -cp .env.example .env.secrets -# Editar .env.secrets con tus credenciales +# Configurar +cp .env.example .env +nano .env # Editar con tus credenciales -# Ejecutar el servicio -python main.py +# Ejecutar +python3 main.py ``` -## Configuracion +## βš™οΈ ConfiguraciΓ³n -### Variables de Entorno (.env.secrets) +### Variables de Entorno (.env) ```bash -# Nextcloud/WebDAV (requerido para sincronizacion) +# === NEXTCLOUD/WEBDAV === NEXTCLOUD_URL=https://tu-nextcloud.com/remote.php/webdav NEXTCLOUD_USER=usuario -NEXTCLOUD_PASSWORD=contrasena +NEXTCLOUD_PASSWORD=contraseΓ±a -# AI Providers (requerido para resΓΊmenes) -ANTHROPIC_AUTH_TOKEN=sk-ant-... -GEMINI_API_KEY=AIza... +# === AI PROVIDERS === +GEMINI_API_KEY=AIza... # Para resΓΊmenes con Gemini +# o +ANTHROPIC_AUTH_TOKEN=sk-ant-... # Para resΓΊmenes con Claude -# Telegram (opcional) +# === TELEGRAM (Opcional) === TELEGRAM_TOKEN=bot_token TELEGRAM_CHAT_ID=chat_id -# GPU (opcional) -CUDA_VISIBLE_DEVICES=0 +# === DASHBOARD === +DASHBOARD_HOST=0.0.0.0 +DASHBOARD_PORT=5000 ``` -Ver `.env.example` para todas las variables disponibles. +## πŸ–₯️ Dashboard Web -## Uso +El dashboard se ejecuta en `http://localhost:5000` junto con el servicio principal. -### Servicio Completo +### Funcionalidades + +| CaracterΓ­stica | DescripciΓ³n | +|----------------|-------------| +| πŸ“Š **Vista de Archivos** | Lista todos los archivos de audio con estado | +| πŸ” **BΓΊsqueda y Filtros** | Filtra por local/WebDAV, ordena por fecha/nombre | +| πŸ‘οΈ **Panel de Preview** | Visualiza transcripciones y resΓΊmenes | +| πŸ“ **Tab Versiones** | Lista todos los formatos generados (TXT, MD, DOCX, PDF) | +| ✨ **Regenerar Resumen** | Genera nueva versiΓ³n del resumen con IA | +| πŸ”„ **Resetear Estado** | Marca archivo como no procesado | + +### API REST Endpoints + +``` +GET /api/files # Lista archivos +GET /api/files-detailed # Lista con info de transcripciones +GET /api/transcription/ # Obtiene transcripciΓ³n +GET /api/summary/ # Obtiene resumen +GET /api/versions/ # Lista versiones generadas +POST /api/regenerate-summary # Regenera resumen desde transcripciΓ³n +POST /api/mark-unprocessed # Resetea estado de archivo +GET /health # Estado del servicio +``` + +## πŸ”„ Flujo de Procesamiento + +1. **DetecciΓ³n** - El servicio monitorea Nextcloud cada 5 segundos +2. **Descarga** - Archivos nuevos se descargan localmente +3. **TranscripciΓ³n** - Whisper convierte audio a texto (.txt) +4. **Resumen** - Claude/Gemini genera resumen estructurado +5. **Documentos** - Se generan .md, .docx, .pdf +6. **Subida** - Documentos se suben a Nextcloud +7. **NotificaciΓ³n** - Telegram notifica finalizaciΓ³n + +## πŸ“± Regenerar ResΓΊmenes + +Cuando un resumen no es satisfactorio, puedes regenerarlo: + +### Desde el Dashboard +1. Clic en el archivo procesado +2. Panel lateral se abre con transcripciΓ³n/resumen +3. Clic en "✨ Regenerar" o tab "πŸ“ Versiones" +4. Nueva versiΓ³n se genera y reemplaza la anterior + +### Desde la Lista +- Archivos procesados muestran botΓ³n "✨ Regenerar" +- Clic directo sin abrir panel lateral + +## πŸ› οΈ Uso CLI ```bash -# Ejecutar con monitoring y dashboard -python main.py +# Ejecutar servicio completo +python3 main.py + +# Transcribir audio especΓ­fico +python3 main.py whisper archivo.mp3 ./output/ + +# Procesar PDF especΓ­fico +python3 main.py pdf documento.pdf ./output/ ``` -### Comandos CLI +## πŸ“Š MΓ©tricas -```bash -# Transcribir audio -python main.py whisper +| Componente | Performance | +|------------|-------------| +| TranscripciΓ³n Whisper | ~1x duraciΓ³n audio (GPU) | +| Resumen Gemini | ~5-15s por documento | +| OCR PDF | ~2-5s por pΓ‘gina | +| Inicio del servicio | ~5-10s | -# Procesar PDF -python main.py pdf -``` +## πŸ”§ TecnologΓ­as -### Dashboard +- **Backend**: Python 3.10+, Flask +- **IA**: OpenAI Whisper, Google Gemini, Anthropic Claude +- **Frontend**: HTML5, CSS3, JavaScript (Vanilla) +- **Storage**: Nextcloud (WebDAV) +- **GPU**: CUDA, PyTorch -El dashboard se expone en `http://localhost:5000` e incluye: -- Vista de archivos procesados/pendientes -- API REST para integraciones -- Endpoints de salud +## πŸ“ Licencia -## Testing +MIT License -```bash -# Ejecutar todos los tests -pytest tests/ +--- -# Tests con coverage -pytest tests/ --cov=cbcfacil --cov-report=term-missing - -# Tests especificos -pytest tests/test_config.py -v -pytest tests/test_storage.py -v -pytest tests/test_processors.py -v -``` - -Ver `docs/TESTING.md` para guia completa. - -## Despliegue - - - -### Produccion - -Ver `docs/DEPLOYMENT.md` para guia completa de despliegue. - -## Metricas de Performance - -| Componente | Metrica | -|------------|---------| -| main.py | 149 lineas (antes 3167) | -| Cobertura tests | ~60%+ | -| Tiempo inicio | ~5-10s | -| Transcripcion Whisper | ~1x tiempo audio (GPU) | -| Resumen Claude | ~2-5s por documento | -| OCR PDF | Depende de paginas | - -## Contribucion - -1. Fork el repositorio -2. Crear branch feature (`git checkout -b feature/nueva-funcionalidad`) -3. Commit cambios (`git commit -am 'Add nueva funcionalidad'`) -4. Push al branch (`git push origin feature/nueva-funcionalidad`) -5. Crear Pull Request - -## Documentacion - -- `docs/SETUP.md` - Guia de configuracion inicial -- `docs/TESTING.md` - Guia de testing -- `docs/DEPLOYMENT.md` - Guia de despliegue -- `ARCHITECTURE.md` - Documentacion arquitectonica -- `CHANGELOG.md` - Historial de cambios - -## Licencia - -MIT License - Ver LICENSE para detalles. +**Desarrollado por CBC** | Última actualizaciΓ³n: Enero 2026