CBCFacil v9

Servicio de IA unificado para procesamiento inteligente de documentos (audio, PDF, texto) con integracion a Nextcloud.

Descripcion General

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.

Arquitectura

+----------------+     +--------------+     +-----------------+     +------------------+
|   Nextcloud    |---->|  Procesador  |---->|  IA Services    |---->|  Dashboard/API   |
|   (WebDAV)     |     |  (Audio/PDF) |     |  (Claude/Gemini)|     |  (Flask)         |
+----------------+     +--------------+     +-----------------+     +------------------+
                              |                      |                       |
                              v                      v                       v
                        +------------+        +------------+         +------------+
                        |   Whisper  |        |   Gemini   |         |  Telegram  |
                        |   (GPU)    |        |   API/CLI  |         |  (notify)  |
                        +------------+        +------------+         +------------+

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)

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)

Instalacion Rapida

# Clonar y entrar al directorio
git clone <repo_url>
cd cbcfacil

# Crear entorno virtual
python3 -m venv .venv
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

# Ejecutar el servicio
python main.py

Configuracion

Variables de Entorno (.env.secrets)

# Nextcloud/WebDAV (requerido para sincronizacion)
NEXTCLOUD_URL=https://tu-nextcloud.com/remote.php/webdav
NEXTCLOUD_USER=usuario
NEXTCLOUD_PASSWORD=contrasena

# AI Providers (requerido para resúmenes)
ANTHROPIC_AUTH_TOKEN=sk-ant-...
GEMINI_API_KEY=AIza...

# Telegram (opcional)
TELEGRAM_TOKEN=bot_token
TELEGRAM_CHAT_ID=chat_id

# GPU (opcional)
CUDA_VISIBLE_DEVICES=0

Ver .env.example para todas las variables disponibles.

Uso

Servicio Completo

# Ejecutar con monitoring y dashboard
python main.py

Comandos CLI

# Transcribir audio
python main.py whisper <archivo_audio> <output_dir>

# Procesar PDF
python main.py pdf <archivo_pdf> <output_dir>

Dashboard

El dashboard se expone en http://localhost:5000 e incluye:

• Vista de archivos procesados/pendientes
• API REST para integraciones
• Endpoints de salud

Testing

# 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.