Semantic Code Intelligence

Локальный семантический поиск и цитируемые обзоры кода для программных репозиториев.

Semantic Code Intelligence разбирает репозиторий на чанки с учётом символов, индексирует эти чанки с помощью FAISS и BM25, объединяет оба набора результатов и ранжирует наиболее сильных кандидатов с помощью кросс-энкодера. Результаты содержат точные пути к файлам и диапазоны строк. Всё работает локально; ключ облачного API не требуется.

Что предоставляет

• Гибридный семантический и лексический поиск по коду

• Повышение значимости точных символов, путей и контекстных терминов

• Метки надёжности поиска на основе согласованности результатов выдачи

• Python AST разбор и структурный разбор для распространённых языков программирования

• Точные цитаты, например src/auth.py:L42-L67

• Веб-дашборд и REST API

• Интерфейсы CLI, MCP и LSP

• Локальные обзоры кода на базе Ollama с детерминированным запасным вариантом на основе фактов

• Постоянное хранение индексов FAISS, BM25 и SQLite

• Инкрементальное отслеживание файловой системы

• Графы символов и зависимостей

• Воспроизводимые бенчмарки индексации и поиска

Related MCP server: Qurio MCP Server

Требования

• macOS или Linux

• Python 3.10 или новее

• Git

• Примерно 2–4 ГБ свободного места на диске для зависимостей Python и локальных кэшей моделей

• Необязательно: uv для более быстрого управления окружением

• Необязательно: Ollama для генерируемых обзоров кода

Первые операции индексации и повторного ранжирования требуют доступа в интернет для загрузки весов моделей Hugging Face. После кэширования моделей поиск работает офлайн.

Быстрый старт на чистой машине

1. Клонируйте репозиторий

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

2. Создайте окружение и установите приложение

С помощью uv:

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

С помощью стандартных инструментов Python:

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

Windows в настоящее время не является протестированной целевой платформой, но эквивалентная команда активации — .venv\Scripts\activate.

3. Загрузите модели поиска и создайте индекс

Загрузка моделей по умолчанию намеренно отключена, чтобы обычные запросы приложения никогда не вызывали неожиданный сетевой трафик. Явно разрешите загрузку при первой индексации и поиске:

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

Это подготовит:

• sentence-transformers/all-MiniLM-L6-v2 для плотных эмбеддингов

• cross-encoder/ms-marco-MiniLM-L-6-v2 для повторного ранжирования

Индекс репозитория хранится в .code_intel_index/. Каталог содержит индекс FAISS, данные BM25 и метаданные SQLite; его не следует коммитить.

4. Запустите веб-приложение

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

Откройте http://127.0.0.1:8000.

Дашборд включает:

• Семантический поиск

• Обзор кода

• Карта зависимостей

• Инструменты Diff и LSP

• Управление выбором репозитория и переиндексацией

• Индикаторы задержки по этапам и надёжности поиска

Индексация другого репозитория

Данные индекса по умолчанию хранятся внутри целевого репозитория:

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

Выполните поиск по этому репозиторию:

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

Используйте отдельный каталог индекса, если исходный репозиторий должен оставаться нетронутым:

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

Принудительно выполните чистую пересборку после изменения поведения парсера или эмбеддингов:

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

Семантический поиск

Рекомендуется гибридный режим. Он сочетает сходство по естественному языку с точным сопоставлением идентификаторов:

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

Точный поиск символа:

code-intel query "Where is serve_ui implemented?"

Вернуть больше результатов:

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

Показать цитаты без вывода кода:

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

Выберите отдельную стратегию поиска для диагностики:

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

Отключите повторное ранжирование кросс-энкодером, когда низкая задержка важнее точности:

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

Как работает ранжирование

Конвейер гибридного поиска по умолчанию выполняет следующие этапы:

1. Расширяет типичные намерения разработчика детерминированными терминами предметной области кода.

2. Извлекает до 50 плотных кандидатов FAISS.

3. Извлекает до 50 лексических кандидатов BM25.

4. Объединяет до 60 уникальных кандидатов с помощью Reciprocal Rank Fusion.

5. Повторно ранжирует до 40 кандидатов локальным кросс-энкодером.

6. Повышает значимость точных символов, путей и совпадений контекстных терминов.

7. Удаляет дублирующиеся цитаты и ограничивает повторяющиеся результаты из одного файла.

8. Возвращает метку надёжности с подтверждающими её данными.

Надёжность — это не оценка уверенности LLM. Она отражает наблюдаемые сигналы поиска, такие как согласованность плотного/лексического поиска, точные совпадения символов, пересечение путей и семантическое сходство.

Обзоры кода

Режим детерминированных фактов

Этот режим не требует Ollama. Он возвращает найденные символы, области видимости, зависимости, фрагменты исходного кода и цитаты, не выдумывая поведение:

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

Генерируемые локальные обзоры с Ollama

Установите и запустите Ollama, затем загрузите модель по умолчанию:

ollama pull qwen2.5-coder:7b

Запустите обзор с цитатами:

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

Используйте другую локальную модель или сервер Ollama:

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

Если Ollama недоступен, приложение явно помечает ответ как extractive-fallback и возвращает детерминированные данные из исходного кода.

Интерактивный CLI

Запустите непрерывную сессию поиска:

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

Просмотрите статистику индекса:

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

Покажите все команды:

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

REST API

Запустите сервер:

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

Проверка состояния:

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

Индексируйте репозиторий:

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

Выполните гибридный поиск:

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

Сгенерируйте обзор:

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

Важные конечные точки:

Привязывайте сервер к 127.0.0.1, если удалённый доступ не требуется намеренно. Конечные точки патчей и открытия файлов работают с локальной файловой системой и не должны быть доступны из недоверенных сетей.

Интеграция MCP

MCP-сервер позволяет VS Code, Cursor, Claude Code и другим совместимым агентам кодинга искать по проиндексированной кодовой базе и получать точные диапазоны исходного кода. Сначала установите проект и создайте индекс:

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

В приведённых ниже примерах используйте абсолютный путь к исполняемому файлу, выводимый командой which code-intel.

VS Code

Создайте .vscode/mcp.json в проекте, который должен искать агент:

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

Выполните MCP: List Servers из палитры команд, запустите semanticCodeIntelligence и одобрите его инструменты. Если старый список инструментов закэширован, выполните MCP: Reset Cached Tools.

Cursor

Создайте .cursor/mcp.json в целевом проекте:

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

Claude Code

Зарегистрируйте локальный stdio-сервер из проекта, по которому хотите выполнять поиск:

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

Для другого MCP-совместимого агента настройте тот же исполняемый файл как локальный stdio-сервер с аргументами mcp --dir /absolute/path/to/your/project. Сервер пишет в stdout только JSON-RPC сообщения, как требуется для stdio-клиентов.

Доступные MCP-инструменты:

• code_intel_search: гибридный, плотный или разреженный поиск с точными строками и метаданными надёжности

• code_intel_symbol_graph: данные о зависимостях и графе вызовов для репозитория или символа

• code_intel_index: создание или обновление индекса из агента кодинга

• code_intel_read_file: безопасное чтение до 400 строк в пределах настроенного репозитория

Целевой проект должен быть проиндексирован до поисковых запросов. По умолчанию его индекс хранится в <project>/.code_intel_index; передайте --index-dir /path/to/index в MCP-команду, если используется отдельный каталог индекса. Загрузка моделей остаётся добровольной: установите CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1, если модель эмбеддингов или повторного ранжирования ещё не закэширована.

LSP и наблюдатель файловой системы

Запустите stdio LSP-мост:

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

Запустите инкрементальный наблюдатель:

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

Наблюдатель отслеживает поддерживаемые исходные файлы и обновляет состояние индекса после изменений. Используйте Ctrl+C, чтобы остановить любой из процессов.

Конфигурация

Переменные окружения:

Программная конфигурация:

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)

Поддерживаемые файлы

Сканер по умолчанию включает:

• Python

• JavaScript и TypeScript

• Go

• Rust

• Java

• C и C++

• C#

• Ruby

• PHP

• Swift

• Kotlin и Scala

• Скрипты оболочки

• SQL

• HTML и CSS

• JSON, YAML, TOML и Markdown

Общие генерируемые каталоги, виртуальные окружения, папки зависимостей, lock-файлы, бинарные файлы, минифицированные ресурсы, .git, .code_intel_index и oss_evaluation по умолчанию исключены. Смотрите ParserConfig в semantic_code_intel/config.py, чтобы настроить расширения и шаблоны игнорирования.

Архитектура

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]

Основные модули:

Тестирование

Запустите полный набор тестов:

uv run pytest -q

Или с активированным окружением:

pytest -q

Набор покрывает парсеры, FAISS, BM25, расширение запросов, повышение значимости точных совпадений, объединение, цитаты, конечные точки API, локальное поведение синтеза, MCP, LSP, патчи, отслеживание и генерацию бенчмарков.

Бенчмаркинг

Запустите воспроизводимый синтетический бенчмарк:

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

Исполнитель записывает benchmark_report.json, содержащий:

• Размеры набора данных и индекса

• Пропускная способность индексации

• Процентили задержки плотного, разреженного, повторного ранжирования и сквозного поиска

• Доля попаданий и средний обратный ранг

• Записи выполненных запросов

• Метаданные Python, платформы, оборудования, пакетов и моделей

Результаты бенчмарков зависят от оборудования, состояния кэша моделей, состава репозитория и набора запросов. Относитесь к историческим показателям как к измерениям, а не гарантиям.

Поиск и устранение неполадок

Модель недоступна локально

Выполните завершившуюся с ошибкой операцию один раз с включённой загрузкой:

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

Индекс не найден

Значения --dir и --index-dir, используемые для поиска, должны совпадать с использованными при индексации.

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

Обзор сообщает, что Ollama недоступен

Проверьте локальный сервер и установленные модели:

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

Вы всегда можете использовать режим детерминированных фактов:

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

Результаты поиска слабые

• Используйте точное имя класса, функции, метода, конечной точки или конфигурации, если оно известно.

• Для обычного использования предпочитайте гибридный режим.

• Увеличьте --top-k, если ответ охватывает несколько файлов.

• Переиндексируйте с помощью --force после изменения конфигурации парсера или эмбеддингов.

• Проверяйте индикатор надежности; низкая надежность означает, что поисковые сигналы недостаточно согласованы.

Порт сервера уже занят

Выберите другой порт:

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

Статус проекта

Проект находится в активной разработке. Проверяйте сгенерированные патчи перед их применением, держите API привязанным к localhost для обычного использования и проверяйте утверждения о производительности на собственных целевых репозиториях.

Лицензия

Открытая лицензия пока не добавлена. Публичный доступ к репозиторию сам по себе не дает разрешения на копирование, изменение или распространение кода.