soupdb 0.6.1__tar.gz

soupdb-0.6.1/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.agents
+.github
+.venv
+.pytest_cache
+.ruff_cache
+htmlcov
+.coverage
+site
+docs
+paper
+tests
+benchmarks
+scripts

soupdb-0.6.1/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group multimedia
+      - run: uv run pytest --cov=engine --cov-report=xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+
+  plugins:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - package: soupdb-inverted
+            paths: tests/unit/indexes/inverted
+          - package: soupdb-vector
+            paths: tests/unit/indexes/test_ivf.py tests/unit/indexes/test_hnsw.py
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group multimedia
+      - run: uv run pytest ${{ matrix.paths }}
+      - run: uv run python -c "import importlib.metadata as m; print('${{ matrix.package }}', bool(m.entry_points(group='soupdb.plugins')))"

soupdb-0.6.1/.github/workflows/container.yml

@@ -0,0 +1,38 @@
+name: container
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/BD2-Project/soupdb
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ github.ref_type == 'tag' || github.ref_name == 'main' }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

soupdb-0.6.1/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "engine/**"
+      - "pyproject.toml"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group docs
+      - run: uv run mkdocs build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

soupdb-0.6.1/.github/workflows/paper.yml

@@ -0,0 +1,28 @@
+name: paper
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: typst-community/setup-typst@v3
+        with:
+          typst-version: 0.14.2
+      - run: typst compile paper/main.typ paper/soupdb.pdf
+      - uses: actions/upload-artifact@v4
+        with:
+          name: soupdb-paper
+          path: paper/soupdb.pdf
+      - name: Attach to release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: paper/soupdb.pdf

soupdb-0.6.1/.github/workflows/plugins-release.yml

@@ -0,0 +1,34 @@
+name: plugins-release
+
+# Publica el core y los plugins en PyPI.
+# - Tag dedicado `plugins-v*` (no cada release del gestor, para evitar
+#   republicar versiones ya existentes).
+# - O manualmente con workflow_dispatch.
+#
+# Requiere el secret PYPI_TOKEN (o configurar Trusted Publishing en PyPI y
+# reemplazar el paso por pypa/gh-action-pypi-publish).
+on:
+  push:
+    tags: ["plugins-v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build wheels (core + plugins)
+        run: |
+          uv build --package soupdb --out-dir dist
+          uv build --package soupdb-inverted --out-dir dist
+          uv build --package soupdb-vector --out-dir dist
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          test -n "$UV_PUBLISH_TOKEN" || { echo "Falta el secret PYPI_TOKEN"; exit 1; }
+          uv publish dist/*

soupdb-0.6.1/.gitignore

@@ -0,0 +1,270 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/PROCESAMIENTO-CONSULTAS.md
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+shell.nix
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+/docs/**/*.md
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# Artefactos generados
+paper/soupdb.pdf
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Agents
+.agents/
+.claude/
+.cursor/
+.codeium/
+.windsurf/
+
+# Agentes autónomos y CLI de IA
+.aider*
+.gpt-pilot/
+.openinterpreter/
+
+# Caché de LLMs y Bases de Datos Vectoriales Locales
+.langchain/
+.llamaindex/
+*.db
+*.log
+.chroma/
+
+# Historiales de chat generados por extensiones (Copilot, Claude, Gemini)
+*.chat.md
+*.chat.txt
+.chat-history/
+.copilot_history/
+copilot-chat/
+
+# Configuraciones de agentes locales (para evitar filtrar API keys de OpenAI/Anthropic)
+.llm_config.json
+.oai_keys
+aider.conf.yml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDEs genéricos
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+.idea/
+
+# Datos multimedia generados (manifests, caché de descriptores, codebooks, vectores.bin).
+# Se regeneran con benchmarks/scripts/{prepare_multimedia_datasets,build_multimedia_vectors}.py
+benchmarks/data/

soupdb-0.6.1/Dockerfile

@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1
+
+# La imagen oficial de uv con Python ya incluye shell: la variante `uv:<versión>`
+# a secas es scratch con el binario y nada más, así que ningún RUN funciona ahí.
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS build
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+COPY plugins ./plugins
+RUN uv sync --frozen --no-dev --no-install-project --no-install-workspace
+
+FROM python:3.12-slim AS runtime
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    SOUPDB_DATA=/app/data \
+    SOUPDB_PLUGINS_DIR=/opt/soupdb/plugins \
+    SOUPDB_PLUGIN_SITE=/opt/soupdb/plugin-site \
+    PYTHONPATH=/opt/soupdb/plugin-site
+COPY --from=build /app/.venv ./.venv
+# El venv de uv no siembra pip; el entrypoint lo necesita para instalar wheels
+# de plugins en caliente (SOUPDB_PLUGINS=1).
+RUN python -m ensurepip --upgrade
+COPY engine ./engine
+COPY docker/entrypoint.sh /usr/local/bin/soupdb-entrypoint
+RUN chmod +x /usr/local/bin/soupdb-entrypoint
+EXPOSE 55432
+ENTRYPOINT ["soupdb-entrypoint"]

soupdb-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BD2-Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soupdb-0.6.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: soupdb
+Version: 0.6.1
+Summary: Motor de base de datos multimodal (relacional, espacial, vectorial) con RAG sobre papers académicos.
+Project-URL: Homepage, https://github.com/BD2-Project/SoupBD
+Project-URL: Documentation, https://BD2-Project.github.io/SoupBD
+Author: BD2-Project
+License-Expression: MIT
+License-File: LICENSE
+Keywords: database,rag,spatial,sql,storage,vector
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# SoupDB
+
+[![ci](https://github.com/BD2-Project/SoupBD/actions/workflows/ci.yml/badge.svg)](https://github.com/BD2-Project/SoupBD/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/badge/coverage-pending-orange)](https://github.com/BD2-Project/SoupBD/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/badge/pypi-0.1.0-blue)]()
+[![license](https://img.shields.io/github/license/BD2-Project/SoupBD)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.11%2B-blue)]()
+
+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).
+
+<p align="center"><sub>Proyecto académico · UTEC · Base de Datos 2 · ciclo 2026-2</sub></p>
+
+## 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](docs/plugins.md) y [SQL de plugins](docs/sql_plugins.md).
+
+```mermaid
+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](https://github.com/BD2-Project/rsoup) — [documentación](https://github.com/BD2-Project/rsoup/tree/main/docs)); `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](docs/driver.md) y el protocolo en [docs/protocolo.md](docs/protocolo.md).
+
+## Dependencias
+
+| Dependencia | Uso | Instalación |
+|---|---|---|
+| Python ≥ 3.11 | Motor de base de datos | python.org o gestor del SO |
+| uv | Gestor de paquetes y entornos | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Docker | Contenedor y despliegue local | Docker Desktop o gestor del SO |
+| PostgreSQL 16 | Comparación experimental | `docker compose up postgres` o gestor del SO |
+| typst | Informe técnico (`paper/`) | gestor del SO |
+
+## Setup
+
+```bash
+# 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:
+
+```bash
+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](https://github.com/BD2-Project/SoupBD/releases).
+- Estrategia de versionado de releases: `docs/estrategia-release.md`.
+
+## Licencia
+
+MIT — ver [LICENSE](LICENSE).