Inteligencia Semántica de Código

Búsqueda semántica local y recorridos de código con citas para repositorios de software.

Semantic Code Intelligence analiza un repositorio en fragmentos conscientes de símbolos, indexa esos fragmentos con FAISS y BM25, fusiona ambos conjuntos de resultados y reordena los candidatos más fuertes con un cross-encoder. Los resultados incluyen rutas de archivo exactas y rangos de líneas. Todo se ejecuta localmente; no se requiere clave de API en la nube.

Qué ofrece

• Búsqueda híbrida de código semántica y léxica

• Impulso exacto de símbolos, rutas y términos contextuales

• Etiquetas de fiabilidad de búsqueda basadas en el acuerdo de recuperación

• Análisis AST de Python y análisis estructural para lenguajes de programación comunes

• Citas exactas como src/auth.py:L42-L67

• Panel de control en el navegador y API REST

• Interfaces CLI, MCP y LSP

• Recorridos de código locales impulsados por Ollama con un respaldo de evidencia determinista

• Persistencia de índices FAISS, BM25 y SQLite

• Vigilancia incremental del sistema de archivos

• Gráficos de símbolos y dependencias

• Benchmarks reproducibles de indexación y recuperación

Related MCP server: Qurio MCP Server

Requisitos

• macOS o Linux

• Python 3.10 o más reciente

• Git

• Aproximadamente 2–4 GB de espacio libre en disco para dependencias de Python y cachés de modelos locales

• Opcional: uv para una gestión de entornos más rápida

• Opcional: Ollama para recorridos de código generados

Las primeras operaciones de indexación y reordenamiento requieren acceso a Internet para descargar los pesos de los modelos de Hugging Face. Después de que los modelos estén en caché, la recuperación funciona sin conexión.

Inicio rápido desde una máquina limpia

1. Clonar el repositorio

git clone https://github.com/saitarrun/Semantic-code-intelligence.git
cd semantic-code-intelligence

2. Crear un entorno e instalar la aplicación

Usando uv:

uv venv
source .venv/bin/activate
uv pip install -e .

Usando herramientas estándar de Python:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Windows no es actualmente un objetivo probado, pero el comando de activación equivalente es .venv\Scripts\activate.

3. Descargar los modelos de recuperación y crear un índice

Las descargas de modelos están deliberadamente deshabilitadas por defecto para que las solicitudes normales de la aplicación nunca generen tráfico de red inesperado. Habilite explícitamente las descargas durante el primer índice y consulta:

export CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1

code-intel index .
code-intel query "Where is HybridRetrievalPipeline implemented?" --citations-only

unset CODE_INTEL_ALLOW_MODEL_DOWNLOADS

Esto prepara:

• sentence-transformers/all-MiniLM-L6-v2 para embeddings densos

• cross-encoder/ms-marco-MiniLM-L-6-v2 para reordenamiento

El índice del repositorio se almacena en .code_intel_index/. El directorio contiene el índice FAISS, los datos BM25 y los metadatos SQLite y no debe ser confirmado.

4. Iniciar la aplicación web

code-intel serve --host 127.0.0.1 --port 8000

Abra http://127.0.0.1:8000.

El panel de control incluye:

• Búsqueda semántica

• Recorrido de código

• Mapa de dependencias

• Herramientas de diff y LSP

• Controles de selección de repositorio y reindexación

• Indicadores de latencia por etapa y fiabilidad de recuperación

Indexar otro repositorio

Los datos del índice se almacenan dentro del repositorio de destino por defecto:

code-intel index /absolute/path/to/project

Buscar en ese repositorio:

code-intel query \
  "How are access tokens validated?" \
  --dir /absolute/path/to/project

Use un directorio de índice separado cuando el repositorio fuente deba permanecer intacto:

code-intel index /absolute/path/to/project \
  --index-dir /absolute/path/to/index-storage

code-intel query \
  "Where is the database connection pool created?" \
  --dir /absolute/path/to/project \
  --index-dir /absolute/path/to/index-storage

Forzar una reconstrucción limpia después de cambiar el comportamiento del analizador o de los embeddings:

code-intel index /absolute/path/to/project --force

Búsqueda semántica

Se recomienda el modo híbrido. Combina similitud de lenguaje natural con coincidencia exacta de identificadores:

code-intel query "How does the application serve the web UI?"

Búsqueda exacta de símbolos:

code-intel query "Where is serve_ui implemented?"

Devolver más resultados:

code-intel query "authentication middleware" --top-k 10

Mostrar citas sin imprimir código:

code-intel query "database transaction rollback" --citations-only

Seleccionar una estrategia de recuperación individual para diagnósticos:

code-intel query "PaymentProcessor" --mode sparse
code-intel query "logic responsible for charging a customer" --mode dense
code-intel query "charge customer payment" --mode hybrid

Deshabilitar el reordenamiento con cross-encoder cuando la latencia importa más que la precisión:

code-intel query "configuration loader" --no-rerank

Cómo funciona la clasificación

El pipeline híbrido por defecto realiza estas etapas:

1. Expandir intenciones comunes de desarrolladores con términos deterministas del dominio del código.

2. Recuperar hasta 50 candidatos densos de FAISS.

3. Recuperar hasta 50 candidatos léxicos de BM25.

4. Fusionar hasta 60 candidatos únicos con Reciprocal Rank Fusion.

5. Reordenar hasta 40 candidatos con un cross-encoder local.

6. Impulsar coincidencias exactas de símbolos, rutas y términos contextuales.

7. Eliminar citas duplicadas y limitar resultados repetitivos del mismo archivo.

8. Devolver una etiqueta de fiabilidad con la evidencia que la respalda.

La fiabilidad no es una puntuación de confianza de un LLM. Informa señales de recuperación observables, como el acuerdo denso/léxico, coincidencias exactas de símbolos, superposición de rutas y similitud semántica.

Recorridos de código

Modo de evidencia determinista

Este modo no requiere Ollama. Devuelve símbolos recuperados, ámbitos, dependencias, bloques de código y citas sin inventar comportamiento:

code-intel ask \
  "How does the indexing pipeline persist metadata?" \
  --provider extractive

Recorridos locales generados con Ollama

Instale e inicie Ollama, luego descargue el modelo por defecto:

ollama pull qwen2.5-coder:7b

Ejecutar un recorrido con citas:

code-intel ask "Explain the hybrid retrieval control flow"

Usar otro modelo local o servidor Ollama:

export CODE_INTEL_OLLAMA_MODEL=deepseek-coder-v2:lite
export OLLAMA_BASE_URL=http://127.0.0.1:11434

Si no se puede alcanzar Ollama, la aplicación etiqueta claramente la respuesta como extractive-fallback y devuelve evidencia de código determinista.

CLI interactivo

Iniciar una sesión de búsqueda continua:

code-intel interactive --dir /absolute/path/to/project

Inspeccionar estadísticas del índice:

code-intel stats --dir /absolute/path/to/project

Mostrar todos los comandos:

code-intel --help
code-intel query --help

API REST

Iniciar el servidor:

code-intel serve --host 127.0.0.1 --port 8000

Verificación de salud:

curl http://127.0.0.1:8000/api/health

Indexar un repositorio:

curl -X POST http://127.0.0.1:8000/api/index \
  -H 'Content-Type: application/json' \
  -d '{
    "target_dir": "/absolute/path/to/project",
    "force": false
  }'

Ejecutar búsqueda híbrida:

curl -X POST http://127.0.0.1:8000/api/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Where is token validation implemented?",
    "repo_path": "/absolute/path/to/project",
    "top_k": 5,
    "mode": "hybrid",
    "rerank": true
  }'

Generar un recorrido:

curl -X POST http://127.0.0.1:8000/api/synthesize \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Explain token validation failure paths",
    "repo_path": "/absolute/path/to/project",
    "top_k": 8,
    "provider": "extractive"
  }'

Endpoints importantes:

Enlace a 127.0.0.1 a menos que se requiera acceso remoto intencionalmente. Los endpoints de parche y apertura de archivos operan en el sistema de archivos local y no deben exponerse a redes no confiables.

Integración MCP

El servidor MCP permite que VS Code, Cursor, Claude Code y otros agentes de codificación compatibles busquen en el código indexado y recuperen rangos de código exactos. Instale e indexe el proyecto primero:

git clone https://github.com/saitarrun/Semantic-code-intelligence.git
cd Semantic-code-intelligence
python -m venv .venv
source .venv/bin/activate
pip install -e .
code-intel index --dir /absolute/path/to/your/project

Use la ruta ejecutable absoluta impresa por which code-intel en los ejemplos a continuación.

VS Code

Cree .vscode/mcp.json en el proyecto que desea que el agente busque:

{
  "servers": {
    "semanticCodeIntelligence": {
      "type": "stdio",
      "command": "/absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel",
      "args": ["mcp", "--dir", "${workspaceFolder}"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Ejecute MCP: List Servers desde la Paleta de Comandos, inicie semanticCodeIntelligence y apruebe sus herramientas. Si su lista de herramientas antigua está en caché, ejecute MCP: Reset Cached Tools.

Cursor

Cree .cursor/mcp.json en el proyecto de destino:

{
  "mcpServers": {
    "semantic-code-intelligence": {
      "command": "/absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel",
      "args": ["mcp", "--dir", "${workspaceFolder}"]
    }
  }
}

Claude Code

Registre el servidor stdio local desde el proyecto que desea buscar:

claude mcp add --transport stdio --scope project semantic-code-intelligence -- \
  /absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel mcp --dir /absolute/path/to/your/project
claude mcp get semantic-code-intelligence

Para otro agente compatible con MCP, configure el mismo ejecutable como un servidor stdio local con argumentos mcp --dir /ruta/absoluta/a/tu/proyecto. El servidor escribe solo mensajes JSON-RPC en stdout, como lo requieren los clientes stdio.

Herramientas MCP disponibles:

• code_intel_search: recuperación híbrida, densa o dispersa con líneas exactas y metadatos de fiabilidad

• code_intel_symbol_graph: datos de dependencias y gráfico de llamadas para un repositorio o símbolo

• code_intel_index: construir o actualizar un índice desde el agente de codificación

• code_intel_read_file: leer de forma segura hasta 400 líneas dentro del repositorio configurado

El proyecto de destino debe estar indexado antes de las solicitudes de búsqueda. Por defecto, su índice se almacena en <proyecto>/.code_intel_index; pase --index-dir /ruta/al/índice al comando MCP cuando use un directorio de índice separado. Las descargas de modelos siguen siendo opcionales: establezca CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 si el modelo de embeddings o de reordenamiento no está ya en caché.

LSP y vigilancia del sistema de archivos

Iniciar el puente LSP stdio:

code-intel lsp --dir /absolute/path/to/project

Iniciar el vigilante incremental:

code-intel watch --dir /absolute/path/to/project

El vigilante observa los archivos fuente compatibles y actualiza el estado del índice después de los cambios. Use Ctrl+C para detener cualquiera de los dos procesos.

Configuración

Variables de entorno:

Configuración programática:

from pathlib import Path

from semantic_code_intel.config import CodeIntelConfig
from semantic_code_intel.indexing.engine import HybridIndexer
from semantic_code_intel.retrieval.pipeline import HybridRetrievalPipeline

project = Path("/absolute/path/to/project")
config = CodeIntelConfig(project_root=project)
config.retrieval.dense_top_k = 75
config.retrieval.sparse_top_k = 75
config.retrieval.final_top_k = 8

HybridIndexer(config).index_codebase(project)
response = HybridRetrievalPipeline(config).query(
    "Where is request authentication enforced?",
    top_k=8,
)

for result in response.results:
    print(result.citation, result.chunk.symbol_name, result.score)

print(response.reliability, response.reliability_reasons)

Archivos compatibles

El escáner por defecto incluye:

• Python

• JavaScript y TypeScript

• Go

• Rust

• Java

• C y C++

• C#

• Ruby

• PHP

• Swift

• Kotlin y Scala

• Scripts de shell

• SQL

• HTML y CSS

• JSON, YAML, TOML y Markdown

Los directorios generados comunes, entornos virtuales, carpetas de dependencias, archivos de bloqueo, binarios, activos minificados, .git, .code_intel_index y oss_evaluation se excluyen por defecto. Consulte ParserConfig en semantic_code_intel/config.py para personalizar extensiones y patrones de ignorado.

Arquitectura

flowchart LR
    A[Repository] --> B[Scanner and ignore rules]
    B --> C[Python AST or polyglot parser]
    C --> D[Symbol-aware chunks]
    D --> E[Local embedding model]
    E --> F[(FAISS)]
    D --> G[Code-aware tokenizer]
    G --> H[(BM25)]
    D --> I[(SQLite metadata)]

    Q[Query] --> X[Intent expansion]
    X --> F
    X --> H
    F --> R[Reciprocal Rank Fusion]
    H --> R
    R --> J[Cross-encoder reranker]
    J --> K[Exact symbol and path boosts]
    K --> L[Diversity and reliability]
    L --> M[CLI, API, Web, MCP, LSP]

Módulos principales:

Pruebas

Ejecutar la suite de pruebas completa:

uv run pytest -q

O con un entorno activado:

pytest -q

La suite cubre analizadores, FAISS, BM25, expansión de consultas, impulso de coincidencia exacta, fusión, citas, endpoints de API, comportamiento de síntesis local, MCP, LSP, parches, vigilancia y generación de benchmarks.

Benchmarking

Ejecutar un benchmark sintético reproducible:

code-intel benchmark \
  --workspace ./benchmark_workspace \
  --loc 40000 \
  --queries 30

El ejecutor escribe benchmark_report.json que contiene:

• Tamaños de dataset e índice

• Rendimiento de indexación

• Percentiles de latencia densa, dispersa, de reordenador y de extremo a extremo

• Tasa de aciertos y rango recíproco medio

• Registros de consultas ejecutadas

• Metadatos de Python, plataforma, hardware, paquetes y modelos

Los resultados del benchmark dependen del hardware, el estado de la caché del modelo, la composición del repositorio y el conjunto de consultas. Trate las cifras históricas como mediciones, no como garantías.

Solución de problemas

El modelo no está disponible localmente

Ejecute la operación fallida una vez con descargas habilitadas:

CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 code-intel index /absolute/path/to/project --force
CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 code-intel query "warm up reranker" --dir /absolute/path/to/project

Índice no encontrado

Los valores de --dir y --index-dir usados para consultar deben coincidir con los usados para indexar.

code-intel stats --dir /absolute/path/to/project

El recorrido dice que Ollama no está disponible

Verifique el servidor local y los modelos instalados:

ollama list
curl http://127.0.0.1:11434/api/tags

Siempre puede usar el modo de evidencia determinista:

code-intel ask "your question" --provider extractive

Los resultados de búsqueda son débiles

• Use el nombre exacto de la clase, función, método, endpoint o configuración cuando se conozca.

• Prefiere el modo híbrido para el uso normal.

• Aumenta --top-k cuando la respuesta abarque varios archivos.

• Reindexa con --force después de cambiar la configuración del parser o del embedding.

• Comprueba la etiqueta de fiabilidad; una fiabilidad baja significa que las señales de recuperación no coinciden claramente.

El puerto del servidor ya está en uso

Elige otro puerto:

code-intel serve --host 127.0.0.1 --port 8010

Estado del proyecto

Este proyecto está en desarrollo activo. Revisa los parches generados antes de aplicarlos, mantén la API vinculada a localhost para el uso normal y valida las afirmaciones de los benchmarks en tus propios repositorios de destino.

Licencia

Todavía no se ha añadido ninguna licencia de código abierto. El acceso público al repositorio no otorga por sí mismo permiso para copiar, modificar o redistribuir el código.