SoupDB

Motor de base de datos multimodal (relacional, espacial y vectorial) construido desde cero en Python, con integración de IA. La aplicación final es un RAG sobre documentos académicos: indexa, recupera y genera respuestas sobre el contenido de papers, informes y otros materiales académicos.

IA aplicada

• RAG (retrieval-augmented generation) sobre documentos académicos.
• Búsqueda vectorial (embeddings, HNSW) para similitud semántica.
• Recuperación léxica (BM25) y fusión con la búsqueda vectorial.
• Extracción de características multimodales (SIFT, MFCC, K-Means).

_{Proyecto académico · UTEC · Base de Datos 2 · ciclo 2026-2}

Arquitectura

Arquitectura de plugins: el núcleo (storage, tipos base, B+/hash/R-tree, SQL y transacciones) se mantiene nativo. Full-text (soupdb-inverted) y vectorial (soupdb-vector) son plugins instalables que declaran capacidades y se descubren por entry points. El SQL uniforme de búsqueda es SEARCH(col, expr) USING <plugin> WITH (...) + SCORE(). Ver plugins y SQL de plugins.

flowchart LR
    subgraph Chef["SoupChef (Cliente)"]
        UI["Svelte + Tauri"]
    end
    subgraph R["rsoup (Driver de red / transacciones)"]
        DRV["Rust — TCP/IP capa 4"]
    end
    subgraph DB["SoupDB (Gestor de base de datos)"]
        Q["Query Processor"] --> IX["Indexes"]
        Q --> AL["Algorithms"]
        Q --> ST["Storage"]
        ST --> DM["DiskManager"]
        Q --> TX["Transacciones y Concurrencia"]
        TX --> ST
    end
    UI <-->|"Tauri invoke / specta TS"| DRV
    DRV <-->|"protocolo binario"| Q
    DRV <--> TX
    PG[("PostgreSQL 16")] -. "comparación experimental" .-> Q

Trabajo multirepo: SoupDB (gestor de base de datos), desarrollado en este repositorio; rsoup (driver de red y control de transacciones y concurrencia, en BD2-Project/rsoup — documentación); SoupChef (cliente de escritorio del gestor). El desarrollo se coordina mediante contexto compartido de arquitectura, reglas y convenciones que aplican a todos los equipos y a los agentes de IA.

El driver rsoup es el cliente Rust que los consumidores usan para conectarse al pool del gestor (TCP/IP, protocolo binario v1/v2, puerto DRIVER_PORT); el frontend SoupChef lo integra vía Tauri. Ver docs/driver.md y el protocolo en docs/protocolo.md.

Dependencias

Setup

# Instalar dependencias y crear el entorno
uv sync --all-groups

# Tests y lint
uv run pytest
uv run ruff check .

# Documentación (build local)
uv run --group docs mkdocs build

# Informe técnico
typst compile paper/main.typ paper/soupdb.pdf

# Levantar el gestor sin docker (escucha en 55432)
uv run python -m engine

# Despliegue local (gestor + postgres con PostGIS)
docker compose up

El gestor queda escuchando el protocolo binario en el puerto 55432, que es al que se conectan el driver rsoup y el cliente SoupChef.

Si el puerto ya está ocupado en tu máquina:

DRIVER_PORT=55435 POSTGRES_PORT=55434 docker compose up

Configuración por variables de entorno: SOUPDB_DATA (directorio de datos), DRIVER_HOST, DRIVER_PORT, PAGE_SIZE, BUFFER_POOL_SIZE, MAX_CONNECTIONS y LOCK_TIMEOUT_MS.

Gestión de paquete y contenedor

• Paquete: el motor se gestiona con uv (pyproject.toml + uv.lock versionado). El wheel se construye con uv build y se adjunta a cada release. El runtime no tiene dependencias externas (solo stdlib).
• Contenedor: Dockerfile multi-stage (build con uv sobre imagen slim) + docker-compose.yml con los servicios engine, postgres:16 y web (placeholder SoupChef). La imagen del engine se publica en GHCR (ghcr.io/BD2-Project/soupdb) al crear un tag de versión.

Documentación

• API reference y guías: https://BD2-Project.github.io/SoupBD
• Informe técnico (typst): se publica como PDF en las Releases.
• Estrategia de versionado de releases: docs/estrategia-release.md.

Licencia

MIT — ver LICENSE.