PJ-Scribe - Sistema de Transcripción Judicial

Sistema de transcripción de audio para audiencias judiciales con corrección automática usando IA.

Arquitectura

• Backend: FastAPI + Celery + Redis
• Transcripción: faster-whisper (small/medium/large-v3)
• Corrección: Ollama + Qwen2.5:1.5b
• Frontend: HTML/JS puro con Fetch API
• Base de datos: PostgreSQL
• Infraestructura: Docker Compose + Supervisor

Estructura de Datos

Expediente (numero, caratula, tribunal)
  └── Audiencias (fecha, testigos)
       └── Archivos (audio + transcripción)

Relaciones y Modelos

• expedientes: número único, título, tribunal (JSONB)
• audiencias: fecha, testigos (JSONB), notas, FK→expediente
• files: nombre archivo, ruta audio/texto, estado, progreso, FK→audiencia
• Todos los campos son obligatorios (No NULL)
• testigos y tribunal se almacenan como JSONB para flexibilidad

Características del Frontend

• Selects con búsqueda incremental: Filtrado en tiempo real al escribir
• Drag & Drop: Zona de arrastre para subir archivos de audio
• Badges de estado: Indicadores visuales de color (pending/processing/done/failed)
• Barra de progreso: Visualización animada del estado de transcripción
• Toasts: Notificaciones flotantes con auto-dismiss
• Contexto visible: Barras informativas muestran expediente/audiencia seleccionados
• Tabs con indicador activo: Resaltado visual del tab actual
• Polling automático: Actualización cada 5 segundos sin recargar

Instalación

./start.sh

El script levanta todos los servicios y muestra las URLs de acceso.

Uso

1. Crear Expediente: Número único, título, tribunal
2. Crear Audiencia: Seleccionar expediente padre, fecha, testigos
3. Subir Audio: Seleccionar expediente/audiencia, elegir modelo de transcripción
4. Ver Progreso: Actualización automática cada 5 segundos
5. Descargar Transcripción: Archivo .txt con transcripción y resumen IA

Servicios

• API + Frontend: http://localhost:8000 (FastAPI sirve ambos)
• Documentación API: http://localhost:8000/docs (Swagger UI)
• PostgreSQL: puerto 5432
• Ollama: puerto 11434
• Redis: puerto 6379

Endpoints API

Expedientes

• GET /expedientes - Listar expedientes
• POST /expedientes - Crear expediente
• GET /expedientes/{id} - Obtener expediente con audiencias
• PUT /expedientes/{id} - Actualizar expediente
• DELETE /expedientes/{id} - Eliminar expediente (cascada)

Audiencias

• GET /expedientes/{id}/audiencias - Listar audiencias de un expediente
• POST /audiencias - Crear audiencia
• PUT /audiencias/{id} - Actualizar audiencia
• DELETE /audiencias/{id} - Eliminar audiencia

Archivos

• POST /upload - Subir audio (FormData: file, audiencia_id, whisper_model)
• GET /files - Listar archivos
• GET /progress/{id} - Obtener progreso de transcripción
• GET /download/{id}?type=audio|text - Descargar archivo
• DELETE /files/{id} - Eliminar archivo

Health

• GET /health - Estado del servicio

Configuración

Variables de entorno en compose/docker-compose.yaml:

• OLLAMA_KEEP_ALIVE=5m: Tiempo que mantiene el modelo en memoria
• DATABASE_URL: Conexión a PostgreSQL
• API_URL: URL de la API FastAPI
• OLLAMA_URL: URL de Ollama

Docker Compose

• Servicios: Redis, PostgreSQL, Ollama, aplicación (API + Worker)
• Volúmenes: postgres_data, ollama_data, archivos de audio/texto
• Redes internas: Comunicación entre contenedores

Modelos Whisper

• small (~244MB RAM): Rápido (~5 min), calidad básica
• medium (~769MB RAM): Balance calidad/velocidad (~15 min)
• large-v3 (~1.55GB RAM): Máxima calidad, más lento (~30 min)

Wake-up de Ollama

El sistema implementa un mecanismo de wake-up para evitar que Ollama se "duerma":

• Verifica si el modelo está cargado antes de cada uso
• Envía request de calentamiento si es necesario
• Retry con backoff exponencial (3 intentos)

Migración de Datos Legacy

Para migrar archivos antiguos al sistema de expedientes:

cd data/app
python3 migrations.py

Esto crea un expediente "LEGACY" y asocia archivos sin audiencia.

Estructura del Proyecto

pjaudiotext/
├── compose/
│   ├── docker-compose.yaml    # Configuración de servicios
│   ├── Dockerfile             # Imagen de la aplicación
│   └── supervisord.conf       # Supervisor (API + Worker)
├── data/
│   └── app/
│       ├── app.py             # API FastAPI
│       ├── tasks.py           # Worker Celery (Whisper + Ollama)
│       ├── index.html         # Frontend HTML
│       ├── static/
│       │   └── script.js      # JavaScript del frontend
│       └── migrations.py      # Migración legacy
├── files/
│   ├── audio/                 # Audios subidos
│   └── text/                  # Transcripciones generadas
├── start.sh                   # Script de inicio
└── README.md

Notas Técnicas

• Wake-up de Ollama: El modelo se descarga de memoria después de 5 minutos de inactividad para ahorrar RAM
• Contexto dinámico: Tribunal y testigos se pasan a Whisper y Qwen para mejorar transcripción
• Progreso en tiempo real: Polling JavaScript cada 5 segundos sin recargar la página
• Modelo dinámico: El usuario puede elegir calidad de transcripción por archivo
• Frontend puro: Sin frameworks, HTML/JS nativo servido por FastAPI