aigrep 2.2.0
AI-powered semantic search for markdown files and knowledge bases via MCP (Model Context Protocol)
License: MIT
Requires Python: >=3.12
Keywords: ai-search, aigrep, claude, embeddings, knowledge-base, lancedb, markdown, mcp, ollama, semantic-search, vector-search

# aigrep

[![PyPI version](https://badge.fury.io/py/aigrep.svg)](https://badge.fury.io/py/aigrep)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-1544%20passed-brightgreen.svg)](https://github.com/mdemyanov/aigrep)
[![Status](https://img.shields.io/badge/status-production--ready-brightgreen.svg)](https://github.com/mdemyanov/aigrep)

AI-powered semantic search for markdown files and knowledge bases via MCP (Model Context Protocol).

## Что это

aigrep — это умный grep с AI. Индексирует ваши markdown-файлы (Obsidian, заметки, документацию) и предоставляет быстрый семантический поиск через MCP. Агенты (Claude, Cursor) могут искать информацию в ваших vault'ах и использовать её для ответов.

**Версия:** 2.0.9
**Статус:** ✅ Production-ready

## Основные возможности

### 🔍 Поиск
- 🎯 **Adaptive Search v5**: Автоматическое определение intent и выбор оптимальной стратегии поиска
- 📊 Document-level и chunk-level поиск с автоматическим выбором
- 🔍 Семантический поиск (векторный, полнотекстовый, гибридный)
- 🏷️ Расширенные фильтры (теги, даты, типы документов, связанные заметки)
- 🎨 Оптимизация для агентов (нормализация запросов, кэширование, re-ranking)
- ✨ Улучшенный UX результатов (группировка по файлам, дедупликация, метки релевантности)

### 📦 Индексация
- 🤖 Автоматическое индексирование и отслеживание изменений
- 🔄 Инкрементальная индексация (только изменённые файлы)
- 🎨 Markdown-aware chunking с поддержкой структуры документов
- ✨ LLM-обогащение для улучшения качества поиска (context prefix, document summary)
- 📊 Фоновая индексация через job queue
- 💾 Кэширование embeddings для ускорения повторной индексации

### 🔌 Multi-Provider Support
- 🏠 **Ollama** (локальный) — embeddings и chat completion
- ☁️ **Yandex Cloud** — YandexGPT (SDK/gRPC) и OpenAI-compatible модели (HTTP)
- 🔄 Унифицированное переключение провайдеров для embedding/chat/enrichment
- ⚡ Адаптивный rate limiting с автоматическим backoff
- 💰 Отслеживание стоимости использования

### 🛠️ Управление
- 📊 Мониторинг прогресса индексации
- 💰 Отчёты о затратах на LLM
- 📈 Метрики производительности и качества
- 🔍 Аудит индекса и покрытия
- 🧪 Тестирование качества поиска

## Быстрый старт

### 1. Установка

```bash
# Установите uv (если не установлен)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Установите aigrep
uv pip install aigrep
```

**Требования:**
- Python 3.12+
- Один из провайдеров:
  - **Ollama** (локальный) с моделью `mxbai-embed-large` (см. [INSTALLATION.md](INSTALLATION.md))
  - **Yandex Cloud** с API-ключом или IAM-токеном (см. [docs/configuration/providers.md](docs/configuration/providers.md))

### 2. Настройка

```bash
# Добавьте vault в конфигурацию
uv run aigrep config add-vault --name "my-vault" --path "/path/to/vault"

# Проиндексируйте vault
uv run aigrep index-all
```

### 3. Интеграция с Claude Desktop

```bash
# Примените конфигурацию автоматически
uv run aigrep claude-config --apply

# Перезапустите Claude Desktop
```

После этого агент сможет использовать инструменты `search_vault` и `search_multi_vault` для поиска в ваших заметках.

> **Подробнее:** См. [QUICK_START.md](QUICK_START.md) для пошаговой инструкции

## Использование

### Через агента (MCP)

После настройки Claude Desktop агент автоматически получает доступ к инструментам:

**Поиск:**
- `search_vault("my-vault", "Python async programming")` — поиск в одном vault'е
- `search_multi_vault(["vault1", "vault2"], "query")` — поиск по нескольким vault'ам

**Управление индексацией:**
- `index_documents("my-vault")` — индексация изменённых документов
- `reindex_vault("my-vault", confirm=True)` — полная переиндексация
- `index_status("my-vault")` — статус индексации

**Управление провайдерами:**
- `list_providers()` — список доступных провайдеров с их статусом
- `list_yandex_models()` — список доступных chat моделей Yandex Cloud
- `set_provider("yandex", provider_type="embedding", model="text-search-doc/latest")` — переключение провайдера
- `set_provider("yandex", provider_type="chat", model="qwen")` — отдельно для chat (поддерживает алиасы)
- `test_provider("ollama")` — тестирование провайдера

**Анализ качества:**
- `index_coverage("my-vault")` — анализ покрытия индекса
- `test_retrieval("my-vault", queries=["query1", "query2"])` — тестирование поиска
- `cost_report(days=7)` — отчёт о затратах

Агент может использовать расширенные фильтры:
- `search_vault("vault", "Python tags:python async")` — поиск с фильтром по тегам
- `search_vault("vault", "created:>2024-01-01 type:протокол")` — поиск по датам и типу

### Через CLI

```bash
# Поиск
uv run aigrep search --vault "my-vault" --query "Python async"

# Индексация
uv run aigrep index-all                    # Индексация всех vault'ов
uv run aigrep index --vault "my-vault"     # Индексация одного vault'а
uv run aigrep reindex --vault "my-vault"   # Переиндексация

# Статистика
uv run aigrep stats --vault "my-vault"

# Диагностика
uv run aigrep doctor
```

> **Подробнее:** См. [примеры](docs/user-guide/examples.md) и [руководство](docs/user-guide/usage.md)

## Документация

### Начало работы
- [QUICK_START.md](QUICK_START.md) — быстрый старт
- [INSTALLATION.md](INSTALLATION.md) — установка и настройка

### Руководство пользователя
- [Использование](docs/user-guide/usage.md) — CLI и MCP инструменты
- [Примеры](docs/user-guide/examples.md) — примеры использования
- [Расширенный поиск](docs/user-guide/advanced-search.md) — синтаксис запросов
- [Лучшие практики](docs/user-guide/best-practices.md) — рекомендации
- [FAQ](docs/user-guide/faq.md) — часто задаваемые вопросы

### Настройка
- [Конфигурация](docs/configuration/configuration.md) — настройки
- [Провайдеры](docs/configuration/providers.md) — Ollama, Yandex Cloud
- [Индексация](docs/configuration/indexing.md) — процесс индексации

### Интеграция
- [MCP интеграция](docs/integration/mcp-integration.md) — интеграция с агентами

### Для разработчиков
- [Архитектура](docs/developer/architecture.md) — архитектура проекта
- [API документация](docs/developer/api-documentation.md) — API reference
- [Руководство разработчика](docs/developer/developer-guide.md) — contributing guide
- [Схема БД](docs/developer/database-schema.md) — структура данных

### Помощь
- [Решение проблем](docs/reference/troubleshooting.md) — troubleshooting
- [CONTRIBUTING.md](CONTRIBUTING.md) — как внести вклад

## Архитектура

aigrep построен на модульной архитектуре:

```
src/aigrep/
├── core/                  # Базовые компоненты (TTLCache, DataNormalizer, DBConnectionManager)
├── storage/
│   ├── builders/          # Построители записей (ChunkRecordBuilder, DocumentRecordBuilder)
│   └── indexing/          # Сервис индексации (IndexingService)
├── search/                # Поисковые сервисы (VectorSearchService, SearchService)
├── providers/             # LLM провайдеры (Ollama, Yandex)
├── enrichment/            # Стратегии обогащения (BaseEnrichmentStrategy)
├── mcp/tools/             # MCP инструменты (SearchVaultTool, IndexVaultTool)
└── lance_db.py            # Фасад для LanceDB (~476 строк)
```

**Ключевые компоненты:**
- **Multi-Provider Support** — поддержка Ollama и Yandex Cloud
- **Hybrid Indexing Pipeline** — markdown-aware chunking и LLM-обогащение
- **VectorSearchService** — векторный, полнотекстовый и гибридный поиск
- **IndexingService** — управление индексацией документов
- **MetadataService** — работа с метаданными документов
- **Background Job Queue** — фоновая индексация с мониторингом прогресса
- **Cost Tracking** — отслеживание затрат на использование LLM

> **Подробнее:** См. [docs/developer/architecture.md](docs/developer/architecture.md) для детального описания архитектуры

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

**Версия:** 2.0.7.1 (HOTFIX: Document Lookup Fix)
**Тесты:** 1026+ unit/integration тестов (все проходят)
**Покрытие:** ≥85% для критических модулей
**Статус:** ✅ Production-ready

### Версии пакетов

- **PyPI (Production):** [![PyPI version](https://badge.fury.io/py/aigrep.svg)](https://pypi.org/project/aigrep/)
- **GitHub Releases:** [Последний релиз](https://github.com/mdemyanov/aigrep/releases/latest)

### Основные изменения v2.0.7.1

- 🐛 **Критическое исправление "Document not found"** — исправлен баг, когда 95% результатов поиска терялось
- 💾 **Dual-Write в SQLite** — данные теперь записываются параллельно в LanceDB и SQLite
- ✅ **Consistency Check** — проверка согласованности данных между SQLite и LanceDB
- 🔄 **Миграция данных** — скрипт для исправления пустых `created_at` полей

> **Подробнее:** См. [CHANGELOG.md](CHANGELOG.md) для полного списка изменений

## Лицензия

MIT