RAG Vector Search rag-service

Optional standalone vector search service providing semantic topic chunking, term-frequency vector embeddings, content hashing verification, and MCP server integration.

Service Overview

The rag-service operates as an optional background service running on port 4002 by default. It converts DITA AST JSON topic files into clean Markdown chunks along heading boundaries (# to ###, capped at roughly 450 tokens with tiny sections merged), embeds each chunk with a locally hosted model (multilingual bge-m3 by default, or another supported multilingual or English-only model selected at image build time), and exposes a hybrid search endpoint that fuses embedding similarity with BM25 keyword ranking.

Data Ingestion & Currency Pipeline

To ensure vector search returns current data only, the service performs automated hash checks and active TOC manifest synchronization:

  • AST to Markdown Chunking — Transforms JSON AST tuples into clean Markdown text and splits content along natural section heading boundaries.
  • SHA-256 Content Hashing — Calculates cryptographic hashes for each topic file. Unchanged topics are skipped instantly during updates; modified topics are re-chunked and re-indexed.
  • Active TOC Sync & Purging — Verifies active topic paths against toc.json. Topics deleted from disk or removed from the TOC manifest are automatically hard-purged from vector memory.

HTTP REST Endpoints

GET /health
Returns server health status, resolved data directory path, total indexed topics, and total vector chunk count.
POST /api/search
Accepts JSON payload {"query": "...", "docId": "...", "lang": "...", "topK": 10} and returns ranked semantic search hits.
POST /api/reindex
Triggers an on-demand incremental hash scan and vector re-indexing pass across all documentation sets in DATA_DIR.

Integration with MCP Server

When the RAG_SERVICE_URL environment variable is set on mcp-server (e.g. http://<rag-service>, where <rag-service> is the host and port the service is running on, e.g. localhost:4002), search requests made via the search_documentation tool are transparently delegated to rag-service for vector similarity scoring. If the RAG service is unreachable or unconfigured, mcp-server automatically falls back to local MiniSearch full-text indexing.

Triggering RAG Index Updates

RAG re-indexing occurs automatically on service startup and can be triggered on-demand following DITA-OT publishing runs:

# Trigger on-demand RAG re-indexing via HTTP POST:
curl -X POST http://<rag-service>/api/reindex

Container Deployment & Configuration

Deploy using Docker Compose or a standalone Docker container:

# Launch using Docker Compose:
docker compose -f docker-compose.yml -f docker-compose.rag.yml up -d

# Or run as a standalone Docker container:
docker run -d -p 4002:4002 \
  -v /path/to/data:/app/data \
  ghcr.io/jason-fox/ast-rag-service:latest

Configuration Environment Variables:

PORT
HTTP port for the Express vector search server (default: 4002).
DATA_DIR
Directory path containing published documentation sets (default: /app/data).
EMBED_MODEL
Embedding model name (default: bge-m3). Docker images fix this at build time with --build-arg EMBED_MODEL=....
CACHE_DIR
Directory where embeddings are persisted between restarts (default: /app/cache in Docker).