Solid Knowledge AI

Un asistente de conocimiento documental de múltiples fuentes impulsado por un agente LangGraph autorreflexivo. Ingiere PDF + Markdown + páginas web en un único almacén vectorial, y luego responde preguntas mediante un agente que evalúa su propia recuperación y verifica su propia respuesta para fundamentarla — reintentando con una consulta reescrita cuando alguna de las comprobaciones falla, y negándose a inventar cuando no puede fundamentar una respuesta. Rastreado con Langfuse, probado en calidad con DeepEval y expuesto a través de MCP.

Construido para mostrar el desarrollo agéntico: LangGraph · LiteLLM · ChromaDB · MCP · Langfuse · DeepEval.

Por qué esto no es "solo RAG"

El agente es un bucle RAG correctivo / autorreflexivo, no una cadena lineal 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 — omite la recuperación en preguntas de charla trivial / fuera de alcance.

• grade_docs — una puerta de relevancia LLM; en caso de fallo, reescribe la consulta y reintenta.

• self_check — verifica que la respuesta redactada está implicada por el contexto recuperado; si no, reintenta o se cubre en lugar de alucinar.

• Un presupuesto de reintentos compartido (max_retries, por defecto 2) limita ambos bucles.

• Memoria — un checkpointer SQLite mantiene el estado de conversación multi-turno por thread_id.

Related MCP server: PDF MCP Server

Inicio rápido

# 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

Interfaz web

skai ui lanza una aplicación Gradio con las características que necesita una demo en vivo:

• Chat con memoria por sesión; cada respuesta muestra sus fuentes, ruta y modelo.

• Feedback después de cada respuesta — 👍/👎 + un comentario opcional, almacenado en SQLite (.skai/feedback.sqlite) y enviado como una puntuación de Langfuse en el trace de ese turno cuando el rastreo está activado. Ese es el bucle cerrado: el uso real se convierte en una señal de evaluación.

• Prompts de ejemplo para guiar la primera interacción.

• Amplía la base de conocimiento en vivo — sube un .md/.txt/.pdf o pega una URL y se ingiere en Chroma al instante, para que la demo no se limite al corpus inicial.

• Selectores de modelo (haiku/sonnet) y filtro de fuente (all/pdf/md/web).

El feedback se puede exportar a una semilla de evaluación JSONL mediante skai.feedback.export_jsonl.

Comandos

Configuración del cliente MCP

El servidor expone dos herramientas — search_kb(query, source_type?) (recuperación bruta) y ask(question) (agente completo). Apunta un cliente MCP a él:

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

Selección de modelo

El valor por defecto es Haiku 4.5 (rápido, barato — bueno para un bucle de router+calificador+generador de Q&A). Cambia por llamada con --model, o globalmente mediante SKAI_MODEL en .env:

Opus está bloqueado intencionadamente (resolve_model lanza una excepción), para que el asistente no pueda apuntarse accidentalmente al nivel más caro.

Observabilidad

Configura LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY (y opcionalmente LANGFUSE_HOST) en .env. Cada ejecución del grafo produce entonces un trace con un span por nodo y por llamada LLM. Sin claves, el rastreo es un no-op limpio — nada más cambia.

Evaluación de calidad (DeepEval)

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

El juez es Claude vía LiteLLM, por lo que no se necesita clave de OpenAI. Métricas: fidelidad, relevancia de la respuesta, relevancia contextual — además de una compuerta de palabras clave barata.

Pruebas

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

El LLM se inyecta como dependencia, por lo que todo el grafo se ejecuta en pruebas contra un stub determinista, y Chroma utiliza una función de incrustación determinista en proceso.

Cómo está compuesto

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

Diagramas de grafo del agente y componentes (Mermaid): consulta docs/ARCHITECTURE.md. Racional de diseño y compensaciones técnicas: consulta docs/DECISIONS.md.

Estado

Verificado: uv run skai ingest carga los tres tipos de fuente (2 md + 1 pdf + 1 web → 170 fragmentos) y la recuperación semántica real devuelve pasajes relevantes. 39 pruebas offline pasan. ask/chat/eval requieren una ANTHROPIC_API_KEY.