RAGMetalworks

Modular RAG service for building high-performance retrieval-augmented generation pipelines over Markdown documents. Supports Qdrant, dense + sparse + hybrid search, pluggable embedding providers (cloud and local), rerankers, intelligent semantic Markdown chunking, metadata filtering, and a web UI.

Quick Start

1. Start Qdrant

docker compose up -d qdrant

2. Configure

cp examples/config.example.yaml config.yaml
# Edit config.yaml — set your embedding provider and API keys

Or use environment variables:

export OPENAI_API_KEY=sk-...
export QDRANT_API_KEY=...   # if using auth

3. Install

pip install -e ".[dev]"

4. Ingest documents

ragmetalworks ingest ./examples/docs --pipeline docs_default

5. Start the server

ragmetalworks serve

API available at http://localhost:8000 · Swagger UI at http://localhost:8000/docs

6. Start the web UI (development)

cd web
npm install
npm run dev
# Open http://localhost:5173

---

CLI Commands

Command	Description
ragmetalworks ingest <path> --pipeline <name>	Ingest .md files or directories
ragmetalworks serve [--host] [--port] [--reload]	Start HTTP server
ragmetalworks list-pipelines	List configured pipelines

HTTP API

Endpoint	Method	Description
/health	GET	Backend + Qdrant health check
/query	POST	Semantic search (dense/sparse/hybrid)
/chat	POST	Full RAG cycle (retrieve → rerank → LLM)
/index	POST	Index pre-prepared chunks
/ingest	POST	Upload and ingest .md / .zip files
/collections	GET	List Qdrant collections with stats
/collections/{name}/documents	GET	Browse chunks in a collection
/pipelines	GET	List configured pipelines
/pipelines/{name}	GET	Pipeline detail

Project Structure

src/
  api/           FastAPI routes, request/response models
  cli/           CLI entry point (typer)
  config/        Pydantic config models + YAML loader
  embeddings/    EmbeddingProvider abstraction + OpenAI/Ollama implementations
  ingestion/     Markdown parser, chunker, indexer
  retrieval/     RetrievalEngine (dense/sparse/hybrid search)
  rerank/        Reranker abstraction + Identity/HTTP implementations
  vector_store/  VectorStore abstraction + Qdrant adapter
web/             React + TypeScript + Tailwind frontend
tests/           Unit tests (pytest)
examples/        Example config + sample Markdown docs
docker-compose.yml

Supported Embedding Providers

Type	Config type	Notes
OpenAI	openai	text-embedding-3-small, text-embedding-3-large
OpenAI-compatible	openai_compatible	LM Studio, vLLM, Ollama OpenAI endpoint
Ollama	ollama	nomic-embed-text, etc.

Supported Rerankers

Type	Config type	Notes
Identity (no-op)	identity	Default, preserves retrieval order
HTTP cross-encoder	http	Any cross-encoder served over HTTP

Running Tests

pytest tests/ -v