⚡ Motor de Búsqueda de Código Multi-Repositorio

Un sistema de recuperación y búsqueda de código de nivel de producción, diseñado para consultar y navegar múltiples repositorios de código fuente simultáneamente, planificado y desarrollado con el framework de Desarrollo Dirigido por Especificaciones OpenSpec. Los resultados clasificados (con metadatos de repositorio, archivo, línea, símbolo y grafo) son el punto de integración para clientes LLM en la nube externos, que realizan la generación en su propio entorno.

🌟 Características Principales

1. Ingesta Multi-Repositorio y Sincronización Incremental:

   • Gestiona directorios de código locales y repositorios Git remotos.

   • Respeta .gitignore y excluye binarios/archivos de bloqueo automáticamente.

   • Seguimiento de hash SHA-256 y detección de commits Git para actualizaciones incrementales instantáneas.

2. Segmentación Semántica de Código Consciente de AST:

   • Análisis estructural por lenguaje para Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, HTML/CSS, SQL y Markdown.

   • Preserva los límites de funciones, métodos, clases e interfaces.

   • Inyecta encabezados de alcance (// [Context] Repository | File | Scope | Imports | Doc).

3. Indexación Híbrida Densa + Léxica:

   • Búsqueda por Vectores Densos: Vectores de características semánticas por subpalabra con similitud coseno + soporte para embeddings externos (Gemini, OpenAI, Voyage AI, Ollama). Los embeddings locales de Ollama usan por defecto qwen3-embedding:0.6b, cargados bajo demanda y liberados cuando están inactivos.

   • Búsqueda Léxica BM25 Dispersa: Tokenizador adaptado a código que divide tokens camelCase y snake_case con refuerzo de símbolos.

   • Fusión de Rangos Recíprocos (RRF): Combina clasificaciones densas y dispersas con refuerzo de identificadores exactos.

4. Grafo de Símbolos y Enlace de Dependencias entre Repositorios:

   • Extrae definiciones de símbolos, llamadores, llamados e importaciones en SQLite.

   • Mapea automáticamente llamadas a API de clientes frontend (p. ej. apiClient.post('/api/v1/auth/login')) a manejadores de rutas de API backend en distintos repositorios.

5. Interfaces:

   • Interfaz Web Moderna: Búsqueda híbrida como experiencia principal de consulta, gestor de repositorios, mapa de contratos de API entre repositorios e inspector de código.

   • Servidor de Protocolo de Contexto de Modelos (MCP): Expone herramientas stdio (search_codebases, get_symbol_definition, get_call_hierarchy, list_repositories) a asistentes de codificación con IA (Antigravity, Cursor, Claude Code, Windsurf).

   • CLI: Comandos rápidos de terminal para indexar y buscar.

   • API REST: POST /api/v1/search devuelve fragmentos de código clasificados para consumidores LLM en la nube externos.

Related MCP server: CodeGraph

📂 Planificación Dirigida por Especificaciones con OpenSpec

Todas las especificaciones, contratos arquitectónicos y desgloses de tareas se mantienen en openspec/:

openspec/
├── config.json                     # OpenSpec project configuration
├── specs/                          # Living System Specifications (Source of Truth)
│   ├── repository-management.md    # Repo ingestion & git tracking
│   ├── ast-code-chunking.md        # AST semantic parsing & context injection
│   ├── hybrid-indexing.md          # Dense vector + BM25 lexical index
│   ├── symbol-graph-retrieval.md   # Call graph & cross-repo API linkage
│   ├── context-fusion-reranking.md # RRF fusion & citation packaging
│   ├── rag-generation.md           # LLM prompting & grounded citations
│   ├── mcp-server.md               # Model Context Protocol tools
│   └── api-and-web-ui.md           # REST & Web UI specifications
└── changes/
    └── 01-foundation-and-core-rag/ # Phase 1 Change Proposal
        ├── proposal.md             # Goals, scope, and motivation
        ├── design.md               # Technical architecture & contracts
        └── tasks.md                # Implementation checklist (Completed)

🚀 Inicio Rápido

1. Registrar e Indexar Repositorios

# Add a local repository
python3 main.py add auth-service ./fixtures/repo_auth_service

# Add another repository
python3 main.py add web-client ./fixtures/repo_web_client

# List all indexed repositories
python3 main.py list

2. Gestionar Grupos de Repositorios y Relaciones de Dependencia

# Create a repository group
python3 main.py group create platform --repos auth-service shared-schemas

# Declare a dependency edge: web-client depends on auth-service
python3 main.py relation add web-client auth-service

# Inspect relations for a repository
python3 main.py relation show web-client

# Search with group scoping and upstream dependency expansion
python3 main.py search "jwt token" --group platform --expand upstream --expand-depth 1

3. Buscar en Repositorios (CLI)

# Hybrid search across all codebases
python3 main.py search "login user authenticate"

# Search scoped to a group with upstream dependency expansion
python3 main.py search "How does authentication flow between web-client and auth-service?" --group platform --expand upstream

4. Iniciar la Interfaz Web Interactiva

python3 main.py serve --host 127.0.0.1 --port 8000

Abre http://localhost:8000 en tu navegador.

5. Conectar a IDEs de IA mediante MCP (Protocolo de Contexto de Modelos)

Añade esta entrada de servidor MCP a la configuración de tu IDE de IA (Antigravity / Cursor / Claude Code):

{
  "mcpServers": {
    "multi-repo-code-rag": {
      "command": "python3",
      "args": ["/Users/nick-work-pc/.gemini/antigravity/scratch/multi-repo-code-rag/main.py", "mcp"]
    }
  }
}

🧠 Runtime del Modelo de Embeddings

El motor se ejecuta como una instancia única por directorio de datos y mantiene el modelo de embeddings local residente solo mientras está trabajando.

• Modelo predeterminado: qwen3-embedding:0.6b (instálalo una vez con ollama pull qwen3-embedding:0.6b). Se puede sobrescribir con --embedding-model o $OLLAMA_EMBEDDING_MODEL.

• Residencia bajo demanda: el modelo nunca se carga al iniciar. Se carga en el primer embedding de una ejecución de indexación o búsqueda, y se libera una vez que la última operación en curso finaliza y transcurre el período de inactividad. Las solicitudes superpuestas comparten una única carga y producen una única liberación.

• Política de residencia mediante --keep-alive o $EMBEDDING_KEEP_ALIVE:

  Valor	Comportamiento
  (sin definir)	Liberar tras 30s de inactividad (predeterminado)
  0	Liberar inmediatamente después de la última operación
  45s, 5m	Liberar tras ese período de inactividad
  always	Mantener el modelo residente durante toda la vida del proceso

• Instancia única: al iniciar se toma un bloqueo exclusivo en <data-dir>/.rag-instance.lock. Una segunda instancia falla rápidamente con el pid propietario; pasa --allow-multi-instance para degradar esto a una advertencia.

• Inspeccionar / liberar manualmente: GET /api/v1/models/status informa sobre residencia, operaciones activas, política y procedencia del índice. POST /api/v1/models/unload (o python3 main.py unload) libera el modelo, devolviendo 409 busy mientras haya una operación en curso.

Reindexación automática al cambiar el modelo

El índice denso registra el proveedor, el modelo y la dimensión vectorial que produjeron sus vectores (<data-dir>/index_meta.json). Cuando el modelo de embeddings configurado cambia — por ejemplo, al actualizar de qwen3-embedding:4b (2560 dimensiones) al predeterminado qwen3-embedding:0.6b (1024 dimensiones) — los repositorios afectados se re-embedden automáticamente antes de servir los resultados de búsqueda:

• el texto de los fragmentos, el índice léxico BM25 y el grafo de símbolos se conservan (solo se re-embedden, no se re-analizan);

• el progreso se informa a través de la salida normal de indexación;

• la procedencia se escribe por repositorio, de modo que una reconstrucción interrumpida se reanuda con los repositorios aún pendientes;

• las búsquedas que llegan durante una reconstrucción reciben 503 reindexing en lugar de ser puntuadas con vectores de otro modelo.

Reversión al comportamiento anterior: OLLAMA_EMBEDDING_MODEL=qwen3-embedding:4b EMBEDDING_KEEP_ALIVE=always restaura el modelo anterior y la política de residencia permanente; la verificación de procedencia reconstruye entonces el espacio vectorial de 4b sin cambios de código.

🏷️ Grupos de Repositorios y Arquitectura de Relaciones de Dependencia

Topología y Reglas de Dominio

• Grupos de Repositorios con Nombre: Colecciones planas de repositorios (p. ej. core, platform, billing). Eliminar un grupo nunca elimina los repositorios subyacentes.

• DAG de Dependencias Dirigido: Aristas de dependencia explícitas A -> depende de -> B. Al añadir una arista se ejecuta la detección de ciclos en escritura (lanzando DependencyCycleError si hay ciclos).

• Resolución de Alcance: Combina los IDs de repositorio explícitos y los miembros de grupos en un conjunto primario, y luego expande a lo largo del grafo en direcciones upstream (dependencias), downstream (dependientes) o both, hasta expand_depth.

• Clasificación con Decaimiento por Salto: Los fragmentos recuperados de repositorios expandidos reciben una penalización multiplicadora (0.85 ** hops) para garantizar que los repositorios primarios se clasifiquen primero.

• Metadatos de Procedencia: Los resultados originados en repositorios expandidos llevan metadatos (repo_relation='expanded', relation_direction, relation_hops) y se muestran con una insignia visual en la interfaz.

Endpoints de la API REST

Herramientas MCP

• manage_repository_relations: Acciones create_group, delete_group, add_to_group, remove_from_group, add_dependency, remove_dependency.

• get_repository_relations: Devuelve las relaciones de un solo repositorio o de todo el grafo de relaciones.

• search_codebases: Ampliado con los argumentos opcionales groups, expand y expand_depth.

🧪 Ejecución de Pruebas

python3 -m unittest discover -s tests -p "test_*.py" -v

Todas las suites de pruebas unitarias y de integración pasan, verificando la segmentación por AST, la extracción de símbolos, la detección de API entre repositorios, el DAG de relaciones de repositorios y la detección de ciclos, la resolución de alcance y la recuperación con decaimiento por salto, los manejadores de la API REST, el protocolo MCP y la recuperación híbrida de extremo a extremo.