cbcren2026/README.md

# 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)
└── Dockerfile                   # Container Docker
```

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

```bash
# 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)

```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 logs -f cbcfacil
```

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