Carrel – Ontology‑Augmented Knowledge Base for AI Agents

What it is

• A self‑hosted service that lets AI agents retrieve up‑to‑date information from a collection of documents (PDFs, Word, code, images, etc.).
• It parses files, creates vector and keyword indexes, optionally builds a knowledge graph, and exposes a REST API that agents can query for passages, images, and graph evidence.

Key capabilities

Feature	What it does
Document parsing	Supports PDF, Word, PowerPoint, spreadsheets, HTML, Markdown, source code and images. Uses MinerU and native parsers to split files into chunks suitable for retrieval.
Automatic updates	Watches designated folders, re‑parses changed files, updates indexes and graphs on a schedule.
Hybrid retrieval	Combines dense vector search, keyword search, graph traversal and visual search; can rerank results.
Knowledge graphs	Extracts entities, relationships, timestamps and conflict flags from text via a chat model; stores them in Neo4j.
Agent‑friendly API	Returns source passages, original images, and linked graph facts; supports pagination, citation metadata and optional authentication.
Web console	UI (English/Chinese) for managing knowledge bases, model endpoints, scheduled tasks and service health.
Model integration	Works with any embedding, vision‑language and chat model you expose (local Docker containers or remote endpoints).

How it works

1. Ingestion – Files placed under runtime/mirror/<folder>/ are parsed and chunked.
2. Indexing – Chunks are sent to Qdrant (vector) and OpenSearch (keyword) stores.
3. Graph building – If enabled, a chat model extracts entities/relations and stores them in Neo4j.
4. Retrieval API – Agents call POST /search with a question; the service merges results from the vector, keyword and graph stores and returns a JSON payload containing text snippets, image URLs and graph evidence.
5. Feedback loop – Agents can request more context or follow graph edges before producing a final answer.

Typical use cases

• Giving a coding assistant (e.g., Claude, Codex) access to internal product manuals, contracts, or meeting notes.
• Building a searchable RAG system for research papers where citations and entity relationships matter.
• Enabling visual search over scanned PDFs or design diagrams alongside textual retrieval.

Quick start

# 1. Clone and deploy the stack (Docker + systemd where available)
git clone https://github.com/FengZhenfei/carrel.git && cd carrel
./deploy.sh                     # detects OS, starts Qdrant, OpenSearch, Neo4j, etc.

# 2. Configure model endpoints (embedding, vision, chat) in config/knowledge-base.env
#    – optional: ./deploy.sh --with-local-models to run bundled models locally

# 3. Add documents
#    Place files under runtime/mirror/<my_kb>/ and enable the folder in the web UI (http://127.0.0.1:9800)

# 4. Query via the bundled skill or curl
curl -sS http://127.0.0.1:9810/search \
  -H 'Content-Type: application/json' \
  -d '{"question":"What are the delivery and acceptance requirements?","top_k":8}'

The response includes the matching passages and, when available, graph nodes or image references.

Installation requirements

• Python 3.12+ and Docker 25+ (Compose v2).
• GPU (NVIDIA) + container toolkit for optional local model serving; CPU‑only works if you point to remote model APIs.
• External services: Qdrant (vectors), OpenSearch (keywords), Neo4j (graph), SQLite (metadata).
• Model endpoints: text embedding, vision‑language (for image captions) and a chat model (for graph extraction).

Documentation & extensibility

• Configuration – detailed guide for model URLs, folder settings, access control.
• Architecture – explains the parsing pipeline, storage choices and retrieval flow.
• Retrieval & API – request format, authentication, response schema, citation handling.
• Operations – console usage, CLI, systemd timers, Docker Compose profiles, testing.
• Skills – a ready‑to‑use carrel-search skill for agents that follows the same API.

License

• MIT license for the code; third‑party dependencies and model weights have their own licenses (see NOTICE.md).

---

Carrel is a full‑stack, on‑premise knowledge‑base platform that augments retrieval with ontology‑level evidence, making it suitable for any AI agent that needs reliable, up‑to‑date source material.