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

CBCFacil v8.0 - Refactored with AMD GPU support

Browse Source
This commit is contained in:
renato97
2026-01-09 13:05:46 -03:00
parent cb17136f21
commit b017504c52
54 changed files with 7251 additions and 3670 deletions
Download Patch File Download Diff File Expand all files Collapse all files

285
README.md
View File

@@ -1,129 +1,206 @@
# Nextcloud AI Service v8
# CBCFacil v9
Servicio unificado que escucha automáticamente tu Nextcloud, descarga audios y PDFs, los procesa con Whisper + 3 modelos de IA y publica resúmenes enriquecidos junto con un dashboard en tiempo real.
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 │───▶│ Whisper │───▶│ Claude (Z.ai)│───▶│ Gemini (CLI │
│ Audios/PDFs │ │ Transcribe │ │ Bullet + │ │ + API) │
└─────────────┘ └─────────────┘ │ Resumenes │ │ Formato final │
└──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
Markdown / DOCX / PDF Dashboard
+----------------+ +--------------+ +-----------------+ +------------------+
| Nextcloud |---->| Procesador |---->| IA Services |---->| Dashboard/API |
| (WebDAV) | | (Audio/PDF) | | (Claude/Gemini)| | (Flask) |
+----------------+ +--------------+ +-----------------+ +------------------+
| | |
v v v
+------------+ +------------+ +------------+
| Whisper | | Gemini | | Telegram |
| (GPU) | | API/CLI | | (notify) |
+------------+ +------------+ +------------+
```
## Principales capacidades
- **Pipeline único**: descarga desde Nextcloud vía WebDAV, transcribe con Whisper, resume con Claude + Gemini y clasifica automáticamente.
- **Dashboard integrado**: panel Flask (http://localhost:5000) para ver archivos, reprocesar o limpiar estados con un click.
- **Diseño GPU-first**: Docker + CUDA 12.1 con PyTorch optimizado; limpieza agresiva de VRAM cuando los modelos están ociosos.
- **Alertas opcionales**: soporte Telegram y WebDAV retries para operaciones largas.
- **Código limpio**: sin Ollama ni servicios secundarios; sólo lo esencial para escalar y mantener.
## Estructura del Proyecto
## Estructura mínima
```
cbc/
├─ Dockerfile
├─ docker-compose.yml
├─ main.py # Servicio principal + loop de monitoreo
├─ dashboard.py # Flask dashboard reutilizando la lógica de main.py
├─ templates/index.html # UI del dashboard
├─ requirements.txt
└─ README.md
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)
└── Dockerfile # Container Docker
```
## Requisitos
- NVIDIA GPU con drivers CUDA 12.1+ y `nvidia-container-toolkit` si usas Docker.
- Python 3.10+ (el Dockerfile usa 3.10) y Node.js ≥ 20 para las CLI externas.
- Claves activas para:
- **Z.ai (Claude CLI)** → `ANTHROPIC_AUTH_TOKEN` y `ANTHROPIC_BASE_URL`.
- **Google Gemini** (CLI o API) → `GEMINI_API_KEY`.
- **DeepInfra GPT-OSS-120B** → `DEEPINFRA_API_KEY`.
- Servidor Nextcloud accesible por WebDAV (usuario, contraseña y URL remota).
### Instalación de las CLIs externas
- 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
```bash
npm install -g @anthropic-ai/claude-code
npm install -g @google/gemini-cli
```
Recuerda exportar las mismas variables de entorno (`ANTHROPIC_*`, `GEMINI_API_KEY`) para que las CLIs compartan credenciales con el servicio.
# Clonar y entrar al directorio
git clone <repo_url>
cd cbcfacil
## Configuración
1. Copia el ejemplo `.env` (no versionado) y completa:
```env
NEXTCLOUD_URL=http://tu-servidor:8080/remote.php/webdav
NEXTCLOUD_USER=...
NEXTCLOUD_PASS=...
GEMINI_API_KEY=...
DEEPINFRA_API_KEY=...
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
ANTHROPIC_AUTH_TOKEN=...
TELEGRAM_TOKEN=... (opcional)
TELEGRAM_CHAT_ID=... (opcional)
```
2. Crea los directorios utilizados por los volúmenes (si no existen):
```bash
mkdir -p downloads resumenes_docx
```
## Ejecución local (sin Docker)
```bash
# Crear entorno virtual
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python3 main.py
```
- El dashboard se expone en `http://localhost:5000`.
- Los registros viven en `logs/service.log`.
## Ejecución con Docker
# 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)
```bash
# 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
```bash
# Ejecutar con monitoring y dashboard
python main.py
```
### Comandos CLI
```bash
# 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
```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
### Docker
```bash
docker compose up -d --build
docker compose logs -f app
docker logs -f cbcfacil
```
El único servicio (`nextcloud_ai_app`) ya expone el dashboard y comparte `downloads/` y `resumenes_docx/` como volúmenes.
## Flujo del pipeline
1. **Monitoreo**: cada `POLL_INTERVAL` segundos se listan nuevas entradas en Nextcloud (`Audios`, `Pdf`, `Textos`...).
2. **Descarga y preproceso**: los archivos se guardan en `downloads/` con normalización y sanitización de nombres.
3. **Transcripción (Whisper)**: modelo `medium` optimizado para español (soporte GPU).
4. **Resúmenes colaborativos**:
- Claude CLI genera bullet points por lotes y resumen integral.
- Gemini CLI/API aplica formato final y estilo consistente.
5. **Clasificación y renombrado**: se detectan temáticas (Historia, Contabilidad, Gobierno, Otras Clases) + topics para nombrar archivos inteligentemente.
6. **Entrega**: se generan `.md`, `.docx`, `.pdf` y se suben de nuevo a Nextcloud.
7. **Dashboard**: refleja estado (procesados/pendientes), permite reprocesar o resetear registros, y sirve descargas locales.
### Produccion
## Dashboard en detalle
- **Vista general**: tarjetas con totales, filtros por origen (local/WebDAV) y buscador instantáneo.
- **Acciones rápidas**:
- `Procesar`: envía el archivo nuevamente al pipeline.
- `Resetear`: elimina la marca de procesado para forzar un reprocesamiento automático.
- `Descargar`: enlaces directos a TXT/MD/DOCX/PDF disponibles.
- **API**:
- `GET /api/files` → listado.
- `POST /api/reprocess` → reprocesa.
- `POST /api/mark-unprocessed` → limpia estado.
- `GET /api/refresh` → sincroniza.
- `GET /health` → healthcheck.
Ver `docs/DEPLOYMENT.md` para guia completa de despliegue.
## Buenas prácticas operativas
- **CUDA libre**: el servicio libera VRAM si los modelos quedan ociosos; revisa el log para ver las limpiezas agresivas.
-.**Telegram**: usa `ERROR_THROTTLE_SECONDS` para evitar spam en errores repetidos.
- **Respaldo**: `processed_files.txt` guarda el historial de todo lo procesado; respáldalo si cambias de servidor.
- **Extensibilidad**: si necesitas nuevos formatos o pasos, agrega funciones en `main.py` reutilizando `ThreadPoolExecutor` y los helpers existentes.
## Metricas de Performance
## Troubleshooting rápido
| Problema | Fix |
| --- | --- |
| Claude o Gemini devuelven error de permisos | Exporta `CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1` (ya se envía al contenedor). |
| No aparecen archivos en el dashboard | Verifica credenciales Nextcloud y `logs/service.log`. |
| Tiempo de espera alto en WebDAV | Ajusta `HTTP_TIMEOUT` y `WEBDAV_MAX_RETRIES` en `.env`. |
| GPU ocupada constantemente | Reduce `MODEL_TIMEOUT_SECONDS` o baja el tamaño del modelo Whisper. |
| 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
La meta de esta versión es mantener el proyecto ágil y escalable: menos archivos, menos servicios y una sola fuente de verdad. Si necesitas habilitar nuevas integraciones (por ejemplo, más modelos o destinos), añade módulos dedicados dentro de `main.py` o expórtalos a un paquete propio manteniendo este núcleo ligero. ¡Felices resúmenes! 💡
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.