Skip to content
reaatechREAATECH

@reaatech/hybrid-rag-cli

npm v0.1.0

Provides a command-line interface for managing hybrid RAG pipelines, including document ingestion, querying, evaluation, and benchmarking. It requires a Qdrant instance and supports running as an MCP server for integration with LLM-based applications.

@reaatech/hybrid-rag-cli

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Command-line interface for hybrid RAG systems. Provides commands for document ingestion, querying, evaluation, ablation studies, benchmarking, chunking preview, and MCP server startup.

Installation

terminal
npm install -g @reaatech/hybrid-rag-cli
# or
pnpm add -g @reaatech/hybrid-rag-cli

Binaries

BinaryDescription
hybrid-ragMain CLI with all commands
hybrid-rag-healthcheckQdrant connectivity check for container orchestration

Commands

hybrid-rag server

Start the MCP server over stdio.

terminal
hybrid-rag server \
  --qdrant-url http://localhost:6333 \
  --collection documents \
  --config rag-config.yaml
OptionDescription
--qdrant-url <url>Qdrant server URL
--collection <name>Qdrant collection name (default: documents)
--config <path>YAML config file for pipeline settings

hybrid-rag ingest

Ingest documents into the knowledge base.

terminal
hybrid-rag ingest ./docs/*.pdf ./docs/*.md \
  --qdrant-url http://localhost:6333 \
  --strategy semantic \
  --chunk-size 512 \
  --overlap 50
OptionDescription
--qdrant-url <url>Qdrant server URL
--collection <name>Target collection (default: documents)
--strategy <name>Chunking strategy: fixed-size, semantic, recursive, sliding-window
--chunk-size <n>Chunk size in tokens (default: 512)
--overlap <n>Overlap in tokens (default: 50)
--config <path>YAML config file for pipeline settings

hybrid-rag query

Query the knowledge base.

terminal
hybrid-rag query "How do I reset my password?" \
  --top-k 10 \
  --reranker cohere \
  --mode hybrid \
  --output json
OptionDescription
--qdrant-url <url>Qdrant server URL
--top-k <n>Number of results (default: 10)
--reranker <provider>Reranker: cohere, jina, openai, local, or none
--mode <mode>Retrieval mode: hybrid, vector, bm25 (default: hybrid)
--vector-weight <n>Vector score weight (default: 0.7)
--bm25-weight <n>BM25 score weight (default: 0.3)
--filter <json>JSON metadata filter
--output <format>Output format: text, json, table (default: text)
--config <path>YAML config file

hybrid-rag evaluate

Run evaluation on a dataset.

terminal
hybrid-rag evaluate \
  --dataset ./datasets/eval.jsonl \
  --metrics precision@10,recall@10,ndcg@10,map,mrr \
  --output eval-results.json
OptionDescription
--dataset <path>Path to .jsonl evaluation dataset
--metrics <list>Comma-separated metrics (default: all)
--top-k <n>K value for @K metrics (default: 10)
--output <path>Output file for results JSON

hybrid-rag ablate

Run an ablation study.

terminal
hybrid-rag ablate \
  --config ./ablation-config.yaml \
  --dataset ./datasets/eval.jsonl \
  --output ablation-results.json
OptionDescription
--config <path>YAML ablation config file
--dataset <path>Path to .jsonl evaluation dataset
--output <path>Output file for results JSON

hybrid-rag benchmark

Run performance benchmarks.

terminal
hybrid-rag benchmark \
  --queries 100 \
  --iterations 50 \
  --warmup 10 \
  --concurrent 5 \
  --output benchmark-report.md
OptionDescription
--queries <n>Number of queries to run (default: 100)
--iterations <n>Measurement iterations (default: 50)
--warmup <n>Warmup iterations (default: 10)
--concurrent <n>Concurrent query count (default: 1)
--output <path>Output file for Markdown report

hybrid-rag chunk

Preview chunking strategies on a document.

terminal
hybrid-rag chunk ./docs/report.pdf \
  --strategy semantic \
  --chunk-size 512 \
  --overlap 50 \
  --output chunks.json
OptionDescription
--strategy <name>Chunking strategy (default: fixed-size)
--chunk-size <n>Chunk size in tokens (default: 512)
--overlap <n>Overlap in tokens (default: 50)
--output <path>Output file for chunk data

hybrid-rag-healthcheck

Verify Qdrant connectivity. Returns exit code 0 on success, 1 on failure.

terminal
hybrid-rag-healthcheck --qdrant-url http://localhost:6333

Configuration File (YAML)

All commands accept a --config flag to load pipeline settings from YAML:

yaml
qdrantUrl: http://localhost:6333
collectionName: documents
 
embeddingProvider: openai
embeddingModel: text-embedding-3-small
embeddingApiKey: ${OPENAI_API_KEY}
 
chunkingStrategy: semantic
chunkSize: 512
chunkOverlap: 50
 
useHybrid: true
vectorWeight: 0.7
bm25Weight: 0.3
fusionStrategy: rrf
 
rerankerProvider: cohere
rerankerModel: rerank-english-v3.0
rerankerApiKey: ${COHERE_API_KEY}
rerankTopK: 20
rerankFinalK: 10
 
topK: 10
bm25K1: 1.2
bm25B: 0.75

Environment variable references (e.g. ${OPENAI_API_KEY}) are resolved at runtime.

Environment Variables

VariableDescriptionDefault
QDRANT_URLQdrant server URLhttp://localhost:6333
QDRANT_API_KEYQdrant API key
OPENAI_API_KEYOpenAI API key
COHERE_API_KEYCohere API key (for reranking)
JINA_API_KEYJina API key (for reranking)
LOG_LEVELLog levelinfo

License

MIT