Solid Knowledge AI

A multi-source document knowledge assistant driven by a self-reflective LangGraph agent. It ingests PDF + Markdown + web pages into one vector store, then answers questions through an agent that grades its own retrieval and verifies its own answer for grounding — retrying with a rewritten query when either check fails, and refusing to fabricate when it can't ground an answer. Traced with Langfuse, quality-tested with DeepEval, and exposed over MCP.

Built to showcase agentic development: LangGraph · LiteLLM · ChromaDB · MCP · Langfuse · DeepEval.

Почему это не «просто RAG»

Агент представляет собой корректирующий / саморефлексивный RAG-цикл, а не линейную цепочку retrieve → generate:

question
   │
   ▼
 route ──chitchat/out_of_scope──▶ generate ──▶ END
   │ kb
   ▼
retrieve ──▶ grade_docs ──irrelevant (rewrite query, retry)──▶ retrieve
                 │ relevant
                 ▼
             generate ──▶ self_check ──ungrounded (retry)──▶ retrieve
                              │ grounded / budget spent
                              ▼
                     answer + citations  (or an honest "I don't know")

• route — пропускает поиск при светской беседе / вопросах вне области.

• grade_docs — LLM-шлюз релевантности; при неудаче переписывает запрос и повторяет попытку.

• self_check — проверяет, что черновой ответ вытекает из полученного контекста; если нет, повторяет попытку или уклоняется, а не галлюцинирует.

• Общий бюджет повторных попыток (max_retries, по умолчанию 2) ограничивает оба цикла.

• Память — чекпойнтер SQLite сохраняет состояние многоходового диалога для каждого thread_id.

Related MCP server: PDF MCP Server

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

# 1. Install (Python 3.11+, uv)
uv sync

# 2. Configure — only ANTHROPIC_API_KEY is required
cp .env.example .env      # then edit .env

# 3. Ingest the sample corpus (2 Markdown + 1 PDF + 1 Wikipedia article)
uv run skai ingest        # -> builds ./.chroma  (local MiniLM embeddings, no API)

# 4. Ask (defaults to Haiku 4.5; switch per-call with --model)
uv run skai ask "What do orcas eat?"
uv run skai ask "How do orcas communicate?" --source md
uv run skai ask "Summarize orca threats" --model sonnet   # haiku | sonnet (Opus blocked)

# 5. Multi-turn chat (remembers the conversation)
uv run skai chat

# 6. Web UI (chat + feedback + live data ingestion)
uv run skai ui        # http://localhost:7860

# 7. Serve over MCP (stdio) for Claude Desktop / an IDE
uv run skai mcp

Веб-интерфейс

skai ui запускает приложение Gradio с функциями, необходимыми для живого демо:

• Чат с памятью на сессию; каждый ответ показывает источники, маршрут и модель.

• Обратная связь после каждого ответа — 👍/👎 + необязательный комментарий, сохраняется в SQLite (.skai/feedback.sqlite) и отправляется как оценка Langfuse в трассировке этого хода, когда трассировка включена. Это замкнутый цикл: реальное использование становится сигналом для оценки.

• Примеры запросов для направления первого взаимодействия.

• Расширяйте базу знаний вживую — загрузите .md/.txt/.pdf или вставьте URL, и он будет немедленно добавлен в Chroma, так что демо не ограничено исходным корпусом.

• Селекторы модели (haiku/sonnet) и фильтра источников (all/pdf/md/web).

Обратная связь экспортируется в JSONL-файл для оценки через skai.feedback.export_jsonl.

Команды

Конфигурация MCP-клиента

Сервер предоставляет два инструмента — search_kb(query, source_type?) (прямой поиск) и ask(question) (полный агент). Укажите на него MCP-клиенту:

{
  "mcpServers": {
    "solid-knowledge-ai": {
      "command": "uv",
      "args": ["run", "skai", "mcp"],
      "cwd": "/absolute/path/to/solid-knowledge-ai"
    }
  }
}

Выбор модели

По умолчанию используется Haiku 4.5 (быстрый, дешёвый — хорошо подходит для цикла маршрутизатор+оценщик+генератор вопросов и ответов). Переключайте на каждый вызов с помощью --model или глобально через SKAI_MODEL в .env:

Opus намеренно заблокирован (resolve_model вызывает исключение), чтобы ассистента нельзя было случайно направить на самый дорогой уровень.

Наблюдаемость

Установите LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY (и опционально LANGFUSE_HOST) в .env. Каждый запуск графа тогда создаёт одну трассировку с спаном на каждый узел и каждый вызов LLM. Без ключей трассировка — чистая заглушка, ничего больше не меняется.

Оценка качества (DeepEval)

uv sync --group eval
export ANTHROPIC_API_KEY=...
uv run skai ingest
uv run --group eval pytest evals -v      # or: skai eval

Судья — Claude через LiteLLM, поэтому ключ OpenAI не нужен. Метрики: точность, релевантность ответа, релевантность контекста — плюс дешёвый ключевой фильтр.

Тесты

uv run pytest        # 39 tests, fully offline: no network, no API keys

LLM внедряется через зависимости, поэтому весь граф в тестах работает с детерминированным заглушкой, а Chroma использует детерминированную встроенную функцию эмбеддинга.

Как это устроено

src/skai/
  config.py            settings (.env)              agent/llm.py     ChatLiteLLM -> Claude
  models.py            Document/Chunk/AgentState    agent/nodes.py   route/retrieve/grade/generate/self_check
  ingest/loaders.py    pdf | md | web  -> Document  agent/prompts.py node prompts
  ingest/chunk.py      source-aware splitting       agent/graph.py   StateGraph + SQLite memory
  ingest/store.py      Chroma add/query             observability.py Langfuse handler (or no-op)
  cli.py               ingest|ask|chat|mcp|eval     mcp_server.py    search_kb / ask as MCP tools
evals/                 DeepEval suite               tests/           offline unit + graph tests

Граф агента и диаграммы компонентов (Mermaid): см. docs/ARCHITECTURE.md. Обоснование дизайна и технические компромиссы: см. docs/DECISIONS.md.

Статус

Проверено: uv run skai ingest загружает все три типа источников (2 md + 1 pdf + 1 web → 170 чанков), и реальный семантический поиск возвращает релевантные отрывки. 39 офлайн-тестов проходят. ask/chat/eval требуют ANTHROPIC_API_KEY.