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

This site is open source. Improve this page.