Semantische Code-Intelligenz

Lokale semantische Suche und zitierte Code-Durchläufe für Software-Repositories.

Semantic Code Intelligence parst ein Repository in symbolbewusste Chunks, indexiert diese Chunks mit FAISS und BM25, fusioniert beide Ergebnismengen und bewertet die stärksten Kandidaten mit einem Cross-Encoder neu. Die Ergebnisse enthalten exakte Dateipfade und Zeilenbereiche. Alles läuft lokal; kein Cloud-API-Schlüssel erforderlich.

Was es bietet

• Hybride semantische und lexikalische Codesuche

• Exakte Symbol-, Pfad- und Kontextbegriffs-Boostings

• Zuverlässigkeitskennzeichnungen der Suche basierend auf Retrieval-Übereinstimmung

• Python-AST-Parsing und strukturelles Parsing für gängige Programmiersprachen

• Exakte Zitate wie src/auth.py:L42-L67

• Browser-Dashboard und REST-API

• CLI-, MCP- und LSP-Schnittstellen

• Lokale, von Ollama unterstützte Code-Durchläufe mit deterministischem Evidenz-Fallback

• FAISS-, BM25- und SQLite-Index-Persistenz

• Inkrementelle Dateisystemüberwachung

• Symbol- und Abhängigkeitsgraphen

• Reproduzierbare Indexierungs- und Retrieval-Benchmarks

Related MCP server: Qurio MCP Server

Anforderungen

• macOS oder Linux

• Python 3.10 oder neuer

• Git

• Ungefähr 2–4 GB freier Speicherplatz für Python-Abhängigkeiten und lokale Modell-Caches

• Optional: uv für schnellere Umgebungsverwaltung

• Optional: Ollama für generierte Code-Durchläufe

Die ersten Indexierungs- und Reranking-Vorgänge erfordern Internetzugriff, um Hugging-Face-Modellgewichte herunterzuladen. Nachdem die Modelle zwischengespeichert sind, funktioniert das Retrieval offline.

Schnellstart auf einem sauberen Rechner

1. Repository klonen

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

2. Umgebung erstellen und Anwendung installieren

Mit uv:

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

Mit Standard-Python-Werkzeugen:

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

Windows ist derzeit kein getestetes Ziel, aber der entsprechende Aktivierungsbefehl lautet .venv\Scripts\activate.

3. Retrieval-Modelle herunterladen und Index erstellen

Modell-Downloads sind standardmäßig absichtlich deaktiviert, damit normale Anwendungsanfragen nie unerwarteten Netzwerkverkehr auslösen. Aktivieren Sie Downloads explizit beim ersten Index und der ersten Abfrage:

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

Dies bereitet vor:

• sentence-transformers/all-MiniLM-L6-v2 für dichte Einbettungen

• cross-encoder/ms-marco-MiniLM-L-6-v2 für das Reranking

Der Repository-Index wird in .code_intel_index/ gespeichert. Das Verzeichnis enthält den FAISS-Index, BM25-Daten und SQLite-Metadaten und sollte nicht eingecheckt werden.

4. Webanwendung starten

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

Öffnen Sie http://127.0.0.1:8000.

Das Dashboard umfasst:

• Semantische Suche

• Code-Durchlauf

• Abhängigkeitskarte

• Diff- und LSP-Werkzeuge

• Repository-Auswahl und Neuindizierungssteuerung

• Latenz pro Stufe und Retrieval-Zuverlässigkeitsindikatoren

Ein anderes Repository indizieren

Indexdaten werden standardmäßig im Ziel-Repository gespeichert:

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

Dieses Repository durchsuchen:

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

Verwenden Sie ein separates Indexverzeichnis, wenn das Quell-Repository unberührt bleiben soll:

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

Erzwingen Sie einen sauberen Neuaufbau nach Änderungen am Parser- oder Einbettungsverhalten:

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

Semantische Suche

Der Hybridmodus wird empfohlen. Er kombiniert Ähnlichkeit in natürlicher Sprache mit exakter Bezeichnerübereinstimmung:

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

Exakte Symbolsuche:

code-intel query "Where is serve_ui implemented?"

Mehr Ergebnisse zurückgeben:

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

Zitate anzeigen, ohne Code zu drucken:

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

Eine einzelne Retrieval-Strategie für Diagnosen auswählen:

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

Cross-Encoder-Reranking deaktivieren, wenn geringere Latenz wichtiger ist als Präzision:

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

So funktioniert das Ranking

Die standardmäßige Hybrid-Pipeline führt diese Schritte aus:

1. Erweitert häufige Entwicklerabsichten um deterministische Code-Domänenbegriffe.

2. Ruft bis zu 50 dichte FAISS-Kandidaten ab.

3. Ruft bis zu 50 lexikalische BM25-Kandidaten ab.

4. Fusioniert bis zu 60 eindeutige Kandidaten mit Reciprocal Rank Fusion.

5. Bewertet bis zu 40 Kandidaten mit einem lokalen Cross-Encoder neu.

6. Verstärkt exakte Symbole, Pfade und kontextuelle Begriffstreffer.

7. Entfernt doppelte Zitate und begrenzt sich wiederholende Ergebnisse aus derselben Datei.

8. Gibt ein Zuverlässigkeitslabel mit den zugrunde liegenden Belegen zurück.

Zuverlässigkeit ist kein LLM-Konfidenzwert. Sie berichtet beobachtbare Retrieval-Signale wie dichte/lexikalische Übereinstimmung, exakte Symboltreffer, Pfadüberlappung und semantische Ähnlichkeit.

Code-Durchläufe

Deterministischer Evidenzmodus

Dieser Modus erfordert kein Ollama. Er gibt abgerufene Symbole, Bereiche, Abhängigkeiten, Quellblöcke und Zitate zurück, ohne Verhalten zu erfinden:

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

Generierte lokale Durchläufe mit Ollama

Installieren und starten Sie Ollama, dann laden Sie das Standardmodell herunter:

ollama pull qwen2.5-coder:7b

Führen Sie einen zitierten Durchlauf aus:

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

Verwenden Sie ein anderes lokales Modell oder einen anderen Ollama-Server:

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

Wenn Ollama nicht erreichbar ist, kennzeichnet die Anwendung die Antwort deutlich als extractive-fallback und gibt deterministische Quellbelege zurück.

Interaktive CLI

Starten Sie eine kontinuierliche Suchsitzung:

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

Indexstatistiken anzeigen:

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

Alle Befehle anzeigen:

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

REST-API

Server starten:

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

Gesundheitscheck:

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

Ein Repository indizieren:

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
  }'

Hybride Suche ausführen:

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
  }'

Einen Durchlauf generieren:

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"
  }'

Wichtige Endpunkte:

Binden Sie an 127.0.0.1, sofern kein Remote-Zugriff beabsichtigt ist. Patch- und Dateiöffnungs-Endpunkte arbeiten auf dem lokalen Dateisystem und sollten nicht ungeschützten Netzwerken ausgesetzt werden.

MCP-Integration

Der MCP-Server ermöglicht es VS Code, Cursor, Claude Code und anderen kompatiblen Coding-Agenten, die indizierte Codebasis zu durchsuchen und exakte Quellbereiche abzurufen. Installieren und indizieren Sie das Projekt zuerst:

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

Verwenden Sie den absoluten ausführbaren Pfad, der von which code-intel ausgegeben wird, in den folgenden Beispielen.

VS Code

Erstellen Sie .vscode/mcp.json in dem Projekt, das der Agent durchsuchen soll:

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

Führen Sie MCP: List Servers aus der Befehlspalette aus, starten Sie semanticCodeIntelligence und genehmigen Sie dessen Werkzeuge. Wenn die alte Werkzeugliste zwischengespeichert ist, führen Sie MCP: Reset Cached Tools aus.

Cursor

Erstellen Sie .cursor/mcp.json im Zielprojekt:

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

Claude Code

Registrieren Sie den lokalen stdio-Server aus dem Projekt, das Sie durchsuchen möchten:

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

Konfigurieren Sie für einen anderen MCP-kompatiblen Agenten dieselbe ausführbare Datei als lokalen stdio-Server mit den Argumenten mcp --dir /absoluter/pfad/zu/ihrem/projekt. Der Server schreibt nur JSON-RPC-Nachrichten auf stdout, wie von stdio-Clients gefordert.

Verfügbare MCP-Werkzeuge:

• code_intel_search: hybride, dichte oder spärliche Abfrage mit exakten Zeilen und Zuverlässigkeitsmetadaten

• code_intel_symbol_graph: Abhängigkeits- und Aufrufgraphendaten für ein Repository oder Symbol

• code_intel_index: Index aus dem Coding-Agenten erstellen oder aktualisieren

• code_intel_read_file: sicher bis zu 400 Zeilen innerhalb des konfigurierten Repositorys lesen

Das Zielprojekt muss vor Suchanfragen indiziert sein. Standardmäßig wird sein Index unter <projekt>/.code_intel_index gespeichert; übergeben Sie --index-dir /pfad/zum/index an den MCP-Befehl, wenn Sie ein separates Indexverzeichnis verwenden. Modell-Downloads bleiben optional: Setzen Sie CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1, wenn das Einbettungs- oder Reranking-Modell nicht bereits zwischengespeichert ist.

LSP- und Dateisystem-Watcher

Starten Sie die stdio-LSP-Brücke:

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

Starten Sie den inkrementellen Watcher:

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

Der Watcher beobachtet unterstützte Quelldateien und aktualisiert den Indexstatus nach Änderungen. Verwenden Sie Ctrl+C, um einen der beiden Prozesse zu stoppen.

Konfiguration

Umgebungsvariablen:

Programmatische Konfiguration:

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)

Unterstützte Dateien

Der Standard-Scanner umfasst:

• Python

• JavaScript und TypeScript

• Go

• Rust

• Java

• C und C++

• C#

• Ruby

• PHP

• Swift

• Kotlin und Scala

• Shell-Skripte

• SQL

• HTML und CSS

• JSON, YAML, TOML und Markdown

Gängige generierte Verzeichnisse, virtuelle Umgebungen, Abhängigkeitsordner, Sperrdateien, Binärdateien, minifizierte Assets, .git, .code_intel_index und oss_evaluation sind standardmäßig ausgeschlossen. Siehe ParserConfig in semantic_code_intel/config.py, um Erweiterungen und Ignorier-Muster anzupassen.

Architektur

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]

Kernmodule:

Testen

Führen Sie die vollständige Testsuite aus:

uv run pytest -q

Oder mit einer aktivierten Umgebung:

pytest -q

Die Suite deckt Parser, FAISS, BM25, Abfrageerweiterung, Exakt-Treffer-Boosting, Fusion, Zitate, API-Endpunkte, lokales Syntheseverhalten, MCP, LSP, Patchen, Überwachung und Benchmark-Generierung ab.

Benchmarking

Führen Sie einen reproduzierbaren synthetischen Benchmark aus:

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

Der Runner schreibt benchmark_report.json mit:

• Datensatz- und Indexgrößen

• Indexierungsdurchsatz

• Latenz-Perzentile für dichte, spärliche, Reranker- und End-to-End-Abfragen

• Trefferquote und mittlerer reziproker Rang

• Ausgeführte Abfragedatensätze

• Python-, Plattform-, Hardware-, Paket- und Modellmetadaten

Benchmark-Ergebnisse hängen von Hardware, Modell-Cache-Zustand, Repository-Zusammensetzung und Abfragesatz ab. Behandeln Sie historische Zahlen als Messungen, nicht als Garantien.

Fehlerbehebung

Modell ist lokal nicht verfügbar

Führen Sie den fehlgeschlagenen Vorgang einmal mit aktivierten Downloads aus:

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

Index nicht gefunden

Die für die Abfrage verwendeten --dir- und --index-dir-Werte müssen mit denen der Indizierung übereinstimmen.

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

Durchlauf sagt, Ollama sei nicht verfügbar

Überprüfen Sie den lokalen Server und die installierten Modelle:

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

Sie können jederzeit den deterministischen Evidenzmodus verwenden:

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

Suchergebnisse sind schwach

• Verwenden Sie den genauen Klassen-, Funktions-, Methoden-, Endpunkt- oder Konfigurationsnamen, wenn bekannt.

• Bevorzugen Sie den Hybrid-Modus für den normalen Gebrauch.

• Erhöhen Sie --top-k, wenn sich die Antwort über mehrere Dateien erstreckt.

• Indizieren Sie mit --force erneut, nachdem Sie die Parser- oder Embedding-Konfiguration geändert haben.

• Überprüfen Sie das Zuverlässigkeits-Label; eine geringe Zuverlässigkeit bedeutet, dass die Abrufsignale nicht stark übereinstimmen.

Serverport ist bereits belegt

Wählen Sie einen anderen Port:

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

Projektstatus

Dieses Projekt befindet sich in aktiver Entwicklung. Überprüfen Sie generierte Patches, bevor Sie sie anwenden, halten Sie die API für den normalen Gebrauch an localhost gebunden und validieren Sie Benchmark-Behauptungen an Ihren eigenen Ziel-Repositories.

Lizenz

Es wurde noch keine Open-Source-Lizenz hinzugefügt. Der öffentliche Zugriff auf das Repository gewährt für sich genommen keine Erlaubnis, den Code zu kopieren, zu modifizieren oder weiterzuverbreiten.