renato97/cbcren2026
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: nuevo README completo con especificaciones del dashboard y API

Browse Source
This commit is contained in:
renato97
2026-01-10 19:34:57 +00:00
parent f04c1cd548
commit 47896fd50a
1 changed files with 166 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

313
README.md
View File

@@ -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 | │ CBCFacil v9 │
| (WebDAV) | | (Audio/PDF) | | (Claude/Gemini)| | (Flask) | ├─────────────────────────────────────────────────────────────────────────┤
+----------------+ +--------------+ +-----------------+ +------------------+ │ │
| | | │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
v v v │ │ Nextcloud │────▶│ Processor │────▶│ AI Service │ │
+------------+ +------------+ +------------+ │ │ (WebDAV) │ │Audio/PDF/TXT│ │Claude/Gemini│ │
| Whisper | | Gemini | | Telegram | │ └─────────────┘ └─────────────┘ └─────────────┘ │
| (GPU) | | API/CLI | | (notify) | │ │ │ │ │
+------------+ +------------+ +------------+ │ │ ▼ ▼ │
│ │ ┌─────────────┐ ┌─────────────┐ │
│ │ │ 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/ cbcfacil/
├── main.py # Punto de entrada del servicio ├── main.py # Punto de entrada principal
├── run.py # Script de ejecucion alternativo ├── config/
├── config/ # Configuracion centralizada │ └── settings.py # Configuración centralizada
│ ├── settings.py # Variables de entorno y settings ├── services/
│ └── validators.py # Validadores de configuracion │ ├── webdav_service.py # Cliente WebDAV/Nextcloud
├── core/ # Nucleo del sistema │ ├── vram_manager.py # Gestión memoria GPU
│ ├── exceptions.py # Excepciones personalizadas │ ├── telegram_service.py # Notificaciones
│ ├── result.py # Patron Result │ └── ai/
│ └── base_service.py # Clase base para servicios │ ├── claude_provider.py # Provider Claude (Z.ai)
├── services/ # Servicios externos │ ├── gemini_provider.py # Provider Gemini
│ ├── webdav_service.py # Operacones WebDAV/Nextcloud │ └── provider_factory.py
│ ├── vram_manager.py # Gestion de memoria GPU ├── processors/
│ ├── telegram_service.py # Notificaciones Telegram │ ├── audio_processor.py # Transcripción Whisper
│ └── ai/ # Proveedores de IA │ ├── pdf_processor.py # OCR y extracción
│ ├── base_provider.py # Interfaz base │ └── text_processor.py # Clasificación
│ ├── claude_provider.py # Claude (Z.ai) ├── document/
│ ├── gemini_provider.py # Gemini API/CLI │ └── generators.py # Genera DOCX, PDF, Markdown
│ └── provider_factory.py # Factory de proveedores ├── storage/
├── processors/ # Procesadores de archivos │ └── processed_registry.py # Registro de procesados
│ ├── audio_processor.py # Transcripcion Whisper ├── api/
│ ├── pdf_processor.py # OCR y extraccion PDF │ └── routes.py # API REST + Dashboard
│ └── text_processor.py # Resumenes y clasificacion ├── templates/
├── document/ # Generacion de documentos │ └── index.html # Dashboard UI
│ └── generators.py # DOCX, PDF, Markdown └── downloads/ # Archivos descargados
├── 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)
``` ```
## Requisitos ## 🚀 Instalación
### Requisitos
- Python 3.10+ - Python 3.10+
- NVIDIA GPU con drivers CUDA 12.1+ (opcional, soporta CPU fallback) - NVIDIA GPU + CUDA 12.1+ (opcional, fallback a CPU)
- Nextcloud accesible via WebDAV - Nextcloud con WebDAV habilitado
- Claves API para servicios de IA (opcional)
## Instalacion Rapida ### Instalación Rápida
```bash ```bash
# Clonar y entrar al directorio # Clonar repositorio
git clone <repo_url> git clone https://gitea.cbcren.online/renato97/cbcren2026.git
cd cbcfacil cd cbcren2026
# Crear entorno virtual # Crear entorno virtual
python3 -m venv .venv python3 -m venv .venv
@@ -86,116 +97,124 @@ source .venv/bin/activate
# Instalar dependencias # Instalar dependencias
pip install -r requirements.txt pip install -r requirements.txt
# Configurar variables de entorno # Configurar
cp .env.example .env.secrets cp .env.example .env
# Editar .env.secrets con tus credenciales nano .env # Editar con tus credenciales
# Ejecutar el servicio # Ejecutar
python main.py python3 main.py
``` ```
## Configuracion ## ⚙️ Configuración
### Variables de Entorno (.env.secrets) ### Variables de Entorno (.env)
```bash ```bash
# Nextcloud/WebDAV (requerido para sincronizacion) # === NEXTCLOUD/WEBDAV ===
NEXTCLOUD_URL=https://tu-nextcloud.com/remote.php/webdav NEXTCLOUD_URL=https://tu-nextcloud.com/remote.php/webdav
NEXTCLOUD_USER=usuario NEXTCLOUD_USER=usuario
NEXTCLOUD_PASSWORD=contrasena NEXTCLOUD_PASSWORD=contraseña
# AI Providers (requerido para resúmenes) # === AI PROVIDERS ===
ANTHROPIC_AUTH_TOKEN=sk-ant-... GEMINI_API_KEY=AIza... # Para resúmenes con Gemini
GEMINI_API_KEY=AIza... # o
ANTHROPIC_AUTH_TOKEN=sk-ant-... # Para resúmenes con Claude
# Telegram (opcional) # === TELEGRAM (Opcional) ===
TELEGRAM_TOKEN=bot_token TELEGRAM_TOKEN=bot_token
TELEGRAM_CHAT_ID=chat_id TELEGRAM_CHAT_ID=chat_id
# GPU (opcional) # === DASHBOARD ===
CUDA_VISIBLE_DEVICES=0 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/<f> # Obtiene transcripción
GET /api/summary/<f> # Obtiene resumen
GET /api/versions/<f> # 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 ```bash
# Ejecutar con monitoring y dashboard # Ejecutar servicio completo
python main.py 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 | Componente | Performance |
# Transcribir audio |------------|-------------|
python main.py whisper <archivo_audio> <output_dir> | 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 ## 🔧 Tecnologías
python main.py pdf <archivo_pdf> <output_dir>
```
### 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: ## 📝 Licencia
- Vista de archivos procesados/pendientes
- API REST para integraciones
- Endpoints de salud
## Testing MIT License
```bash ---
# Ejecutar todos los tests
pytest tests/
# Tests con coverage **Desarrollado por CBC** | Última actualización: Enero 2026
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.