ECCO
Estación de Captura
y Conocimiento Oficial

ECCO (Estación de Captura y Conocimiento Oficial) es una plataforma de software desarrollada íntegramente en Python por PINGS, orientada a la gestión integral del ciclo documental de sesiones del Concejo Municipal. El sistema automatiza la cadena completa: grabación o importación de audio → transcripción ASR → diarización de hablantes → análisis semántico con LLM → generación de actas oficiales → búsqueda de conocimiento institucional.

El diseño prioriza la soberanía tecnológica: todos los modelos de IA corren localmente (Ollama, faster-whisper, pyannote), sin dependencia de APIs externas de pago ni envío de datos sensibles a terceros.

1.1 Objetivos del sistema

1.2 Alcance funcional

1.3 Restricciones y supuestos de diseño

ECCO sigue una arquitectura de capas desacopladas: la capa de presentación (Streamlit) invoca servicios de dominio (src/) que a su vez acceden a los datos (SQLite + ChromaDB). El pipeline de procesamiento es asíncrono: se lanza en hilo separado mientras la UI muestra progreso.

Flujo de datos principal

El flujo unidireccional garantiza que ninguna capa superior escriba directamente en la capa de persistencia obviando los servicios de dominio. La UI solo llama funciones de src/; los servicios de dominio ejecutan toda la lógica de negocio y acceden a la BD a través de un módulo centralizado src/database/db.py.

3.1 Capa UI — Streamlit Multipage

La interfaz se implementa como una aplicación Streamlit multipage. El archivo raíz app.py define el layout global (sidebar, tema, KPIs del dashboard principal). Cada página en pages/ es un módulo independiente que se carga bajo demanda.

3.2 Módulo de Inteligencia (src/intelligence/)

3.3 Módulo de Búsqueda (src/search/)

3.4 Módulo de Audio (src/audio/)

3.5 Módulo de Documentos (src/documents/)

El pipeline principal vive en src/transcription/pipeline.py y es el corazón del sistema. Transforma un archivo de audio crudo en datos estructurados listos para acta. Se ejecuta en un hilo de fondo (threading.Thread) para no bloquear la UI de Streamlit. El estado de progreso se persiste en la columna sesiones.estado_pipeline.

Estados del pipeline

La base de datos es un archivo SQLite 3 (data/ecco.db) con 12 tablas. Se inicializa con scripts/03_inicializar_bd.py que crea el esquema, los índices FTS5 y siembra los datos de concejales.

Tablas principales — descripción de campos clave

sesiones

intervenciones

Tabla FTS5 — intervenciones_fts

-- Tabla virtual FTS5 sincronizada con intervenciones via triggers
CREATE VIRTUAL TABLE intervenciones_fts USING fts5(
    texto,
    content='intervenciones',
    content_rowid='id',
    tokenize='unicode61 remove_diacritics 1'
);

-- Trigger de sincronización al insertar
CREATE TRIGGER intervenciones_ai AFTER INSERT ON intervenciones BEGIN
  INSERT INTO intervenciones_fts(rowid, texto) VALUES(new.id, new.texto);
END;

El motor de búsqueda de ECCO combina dos paradigmas complementarios para maximizar la cobertura y relevancia de resultados sobre el corpus de sesiones del concejo.

Algoritmo de fusión y reranking

# src/search/hybrid_search.py — pseudocódigo simplificado

def hybrid_search(query: str, top_k: int = 20) -> list[Result]:

    # 1. FTS5 search
    fts_results = fts_engine.search(query, limit=top_k * 2)
    # Normalizar scores FTS (BM25) a [0, 1]
    fts_norm = normalize_minmax([r.score for r in fts_results])

    # 2. Vector search
    vec_results = embedder.query(query, n_results=top_k * 2)
    # Normalizar distancias coseno a similitud [0, 1]
    vec_norm = [1 - d for d in vec_results.distances]

    # 3. Fusión ponderada
    combined = {}
    for r, score in zip(fts_results, fts_norm):
        combined[r.id] = score * 0.40
    for r, score in zip(vec_results, vec_norm):
        combined[r.id] = combined.get(r.id, 0) + score * 0.60

    # 4. Deduplicar y ordenar por score combinado
    ranked = sorted(combined.items(), key=lambda x: x[1], reverse=True)

    # 5. Enriquecer con datos de BD (concejal, sesión, snippet)
    return enrich_results(ranked[:top_k])

Flujo de indexación

RAG para Base Legal

El módulo rag_engine.py implementa Retrieval-Augmented Generation sobre la colección legislacion de ChromaDB. El flujo es:

1. Usuario formula pregunta en lenguaje natural (ej: "¿Cuál es el quórum para sesiones extraordinarias?")
2. Se generan embeddings de la pregunta con nomic-embed-text
3. Se recuperan los 5 fragmentos más similares de la base legal
4. Los fragmentos se inyectan como contexto en el prompt de qwen2.5:7b
5. El LLM responde con cita al artículo y documento fuente

7.1 Hardware recomendado

7.2 Software base (Windows)

7.3 Dependencias Python principales

# requirements.txt (extracto de dependencias críticas)
streamlit==1.35.0
faster-whisper==1.0.3
whisperx==3.1.5
pyannote.audio==3.1.1
torch==2.3.0+cu121
chromadb==0.5.3
deepfilternet==0.5.6
python-docx==1.1.0
reportlab==4.2.0
plotly==5.22.0
sounddevice==0.4.7
pydub==0.25.1
pysentimiento==0.7.2
pytesseract==0.3.13
pdf2image==1.17.0
requests==2.32.0
pyyaml==6.0.1
python-magic-bin==0.4.14  # Windows

# Verificar CUDA disponible
nvcc --version
python -c "import torch; print(torch.cuda.is_available())"

# Descargar instalador desde ollama.ai e instalar
# Luego descargar los modelos requeridos:
ollama pull qwen2.5:7b
ollama pull nomic-embed-text
# Verificar que el servicio corre en localhost:11434
ollama list

git clone https://github.com/PINGS-DSinf/ECCO.git
cd ECCO

python -m venv .venv
.venv\Scripts\activate

# PyTorch con CUDA primero
pip install torch==2.3.0+cu121 torchaudio==2.3.0+cu121 ^
    --index-url https://download.pytorch.org/whl/cu121

# Resto de dependencias
pip install -r requirements.txt

# En config.yaml, agregar:
huggingface:
  token: "hf_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

python scripts/03_inicializar_bd.py

streamlit run app.py --server.port 8501 --server.address 0.0.0.0

Inicio automático con Windows Task Scheduler

# Crear tarea programada para inicio automático
schtasks /create /tn "ECCO" /tr ^
    "C:\ECCO\.venv\Scripts\streamlit.exe run C:\ECCO\app.py" ^
    /sc onlogon /ru SYSTEM /f

Toda la configuración del sistema se centraliza en config.yaml en la raíz del proyecto. A continuación se documenta cada sección con sus campos y valores por defecto.

# ─────────────────────────────────────────────────────────────
# config.yaml — ECCO v1.0 — Configuración completa
# ─────────────────────────────────────────────────────────────

municipio:
  nombre: "Concejo de Medellín"       # Nombre que aparece en actas y UI
  ciudad: "Medellín"
  departamento: "Antioquia"
  pais: "Colombia"
  logo_path: "assets/logo_concejo.png"  # Logo para cabecera de documentos
  periodo_actual: "2024-2027"
  num_concejales: 21                   # Total de escaños
  quorum_ordinario: 11                 # Mayoría simple para quórum
  quorum_calificado: 14                # 2/3 del total para temas especiales

base_datos:
  path: "data/ecco.db"                 # Ruta al archivo SQLite
  backup_enabled: true
  backup_path: "data/backups/"
  backup_interval_days: 1             # Backup diario automático
  max_backups: 30                      # Conservar últimos 30 backups

ollama:
  base_url: "http://localhost:11434"   # URL del servicio Ollama
  llm_model: "qwen2.5:7b"              # Modelo LLM para análisis
  embed_model: "nomic-embed-text"      # Modelo para embeddings
  timeout_seconds: 120                 # Timeout por llamada LLM
  temperature: 0.1                     # Temperatura (bajo = más determinista)
  max_tokens: 4096                     # Máximo tokens de respuesta

pipeline:
  denoising_enabled: true              # Activar DeepFilterNet
  whisper_model: "large-v3"            # large-v3 | medium | small
  whisper_compute_type: "int8"         # int8 | float16 | float32
  whisper_device: "cuda"               # cuda | cpu
  whisper_language: "es"              # Código ISO de idioma
  chunk_duration_seconds: 1800         # 30 min por chunk
  chunk_overlap_seconds: 10
  diarization_enabled: true
  diarization_min_speakers: 2
  diarization_max_speakers: 40
  sentiment_enabled: true
  sentiment_batch_size: 32

busqueda:
  fts_weight: 0.40                     # Peso del componente FTS5
  vector_weight: 0.60                  # Peso del componente vectorial
  top_k: 20                            # Resultados máximos a devolver
  chunk_size: 500                      # Caracteres por chunk para embeddings
  chunk_overlap: 50
  chroma_path: "data/chroma_store"

huggingface:
  token: "hf_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"  # Token de acceso HF

audio:
  sample_rate: 48000                   # Hz — no cambiar (requerido por Whisper)
  channels: 1                          # Mono
  target_dbfs: -20                     # Normalización de volumen
  min_duration_seconds: 30             # Duración mínima de audio aceptada
  audio_path: "data/audios"

documentos:
  export_path: "data/exportaciones"
  docx_template: "assets/plantilla_acta.docx"  # Plantilla base Word
  pdf_font: "Times-Roman"              # Fuente para PDFs reportlab
  watermark_borrador: true             # Agregar marca "BORRADOR" en actas no aprobadas

ui:
  titulo: "ECCO — Concejo de Medellín"
  favicon: "assets/favicon.ico"
  items_por_pagina: 20
  tema_color: "#0D2E6E"               # Color primario de la UI

logs:
  path: "logs/"
  level: "INFO"                        # DEBUG | INFO | WARNING | ERROR
  max_bytes: 10485760                  # 10 MB por archivo de log
  backup_count: 5

ECCO está diseñado para ser replicable en cualquier concejo municipal con cambios mínimos, todos concentrados en archivos de configuración y datos. No se requiere modificar código fuente para la mayoría de adaptaciones.

10.1 Cambios en config.yaml

10.2 Reemplazar el seed de concejales

El script scripts/02_seed_concejales.py contiene los 21 concejales del periodo 2024-2027 de Medellín. Para otro municipio:

1. Editar el array CONCEJALES en el script con los nombres, partidos y comisiones del municipio destino.
2. Re-ejecutar: python scripts/02_seed_concejales.py --reset
3. Cargar fotos en data/fotos/ con nombre concejal_<id>.jpg

10.3 Plantilla de acta

El prompt de generación de acta en src/intelligence/acta_generator.py incluye una sección de configuración de plantilla. Los campos editables son:

• ENCABEZADO_LEGAL: Texto de apertura conforme al reglamento del concejo
• FORMULA_APERTURA: Frase protocolar de apertura de sesión
• FORMULA_CIERRE: Frase protocolar de cierre
• SECCIONES_ACTA: Lista de secciones obligatorias según normativa local

10.4 Base legal

Importar los documentos legales del municipio destino (Estatuto de Presupuesto, Reglamento Interno, Acuerdo Marco, POT, etc.) a través de la página Base Legal en la UI. El sistema los indexa automáticamente con FTS5 y vectores.

10.5 Adaptación de idioma / variante regional

Para concejos donde el español regional difiere significativamente (ej: España, México), se puede ajustar:

• pipeline.whisper_language: código ISO (siempre es para español)
• Los prompts de LLM en src/intelligence/ incluyen instrucción de idioma; editar si se usa variante castellana diferente.
• El modelo pysentimiento/robertuito está entrenado en español latinoamericano; para España, evaluar cambiar a pysentimiento/bertweet-base-sentiment-analysis.

11.1 Limitaciones en v1.0

11.2 Roadmap