Skip to content

feat(search): add semantic search over vault docs - #22

Closed
Ntizar wants to merge 1 commit into
SantanderAI:mainfrom
Ntizar:feature/semantic-search
Closed

feat(search): add semantic search over vault docs#22
Ntizar wants to merge 1 commit into
SantanderAI:mainfrom
Ntizar:feature/semantic-search

Conversation

@Ntizar

@Ntizar Ntizar commented Jul 18, 2026

Copy link
Copy Markdown

What

Añade un nuevo subcomando search a gv.py que permite buscar semánticamente
sobre la documentación del vault.

Características

  • Auto-indexado: la primera búsqueda construye el índice automáticamente
  • Doble backend: sentence-transformers (búsqueda semántica real) o fallback
    n-gram (Python puro, sin dependencias ML)
  • Índice persistente: .ralphvault/search-index.json
  • Compatible: con la estructura existente del vault (frontmatter, tiers, wikilinks)
  • Dos subcomandos nuevos:
    • gv.py index → reconstruye explícitamente el índice
    • gv.py search <query> → búsqueda en lenguaje natural

Ejemplo de uso

# Auto-index + búsqueda (primera vez)
python3 scripts/gv.py --vault vault search "autenticación y autorización"

# Reconstruir índice explícitamente
python3 scripts/gv.py --vault vault index

# Con transformers (necesita pip install sentence-transformers)
python3 scripts/gv.py --vault vault search "pagos" --backend transformers

# Solo keyword matching (no necesita dependencias)
python3 scripts/gv.py --vault vault search "pagos" --backend ngram

Diseño

La búsqueda semántica es un complemento a la estructura jerárquica existente.
El vault sigue funcionando igual; el nuevo index permite descubrir documentos
que la navegación por tiers no haría evidente (ej: "encuentra todo lo que maneje
autenticación" en un vault de 100+ repos).

El módulo search.py es standalone y lazy-loaded: gv.py no importa search
hasta que se ejecuta el subcomando. Esto preserva la promesa de "stdlib only".

Add a new "search" subcommand to gv.py that enables semantic search
over vault documentation. Features:

- Auto-indexing: first search query automatically builds the index
- Dual backends: sentence-transformers (true semantic) or n-gram fallback
  (pure Python, no ML deps)
- Index stored in .ralphvault/search-index.json
- Compatible with existing vault structure (frontmatter, tiers, wikilinks)
- "gv.py index" to explicitly rebuild the index
- "gv.py search <query>" for natural language search
- Graceful degradation: works without sentence-transformers installed

Also adds an "index" subcommand for explicit index management.
@Ntizar
Ntizar requested review from a team as code owners July 18, 2026 22:32
@github-actions

Copy link
Copy Markdown


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


David Antizar seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

@Ntizar Ntizar closed this Jul 18, 2026
@github-actions github-actions Bot locked and limited conversation to collaborators Jul 18, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant