RAG Chat Microservice (`rag-chat-minimal`)

Production-ready standalone Retrieval-Augmented Generation (RAG) HTTP microservice powered by Google Gemini 2.5 Flash / 3.1 Flash and Local CPU ONNX Engines with multi-backend vector storage (Hybrid, Local JSON, Supabase PGVector).

Key Features

Grounding & Citation Guarantee: Answers are strictly generated from retrieved document chunks with explicit source citations and HTML-sanitized URLs/snippets to prevent XSS.
Dual Cloud & Local Engines:
- Cloud API: Powered by Google Gemini 2.5 Flash / 3.1 Flash Lite and gemini-embedding-2.
- Local ONNX CPU: 100% autonomous, zero-GPU offline execution via HuggingFace ONNX transformers (embeddinggemma-300m-ONNX and Qwen1.5-0.5B-Chat / LFM2.5-350M-ONNX).
Flexible Vector Storage (VECTOR_BACKEND):
- Hybrid Store (Recommended): Automatic dual-store synchronization & fallback between local JSON flat-file and Supabase PGVector.
- JSON Store: Fast, zero-dependency local flat-file storage with atomic .tmp file persistence.
- Supabase PGVector: High-scalability PostgreSQL vector store via parameterized RPC match_documents.
OWASP Security Guardrails:
- Prompt Injection Shield: Regex detection filter for jailbreaks, instruction overrides, and prompt extraction attempts.
- Sliding-Window Rate Limiting: In-memory rate limiting per agent/IP with unref'd automatic memory cleanup.
- Hardened HTTP Headers: Strict CSP (default-src 'none'), HSTS, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Permissions-Policy, and anti-fingerprinting (x-powered-by disabled).
- Payload Size Control: Rejects payloads exceeding MAX_PAYLOAD_BYTES with HTTP 413.
IAM Bearer & OAuth2 Token Security:
- HMAC SHA-256 JWT signature verification with constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks.
- Strict rejection of alg: none bypass attacks and token expiration validation (exp).
- Remote IAM Token Introspection support (IAM_AUTH_URL).
Client Integration SDKs: First-class ready-to-use packages for Next.js / React (clients/nextjs/) and Laravel / PHP (clients/laravel/).
Enterprise Multi-Tenant Isolation: Multi-project query isolation via project_id parameter and x-project-id HTTP header.

Quickstart (< 5 mins)

1. Prerequisites

Node.js >= 20.0.0 (Node.js 22+ recommended)
pnpm 9.x (or npm / yarn)
Optional: A Google Gemini API key (only required when using Cloud API providers)

2. Installation & Environment Setup

# Clone repository & install dependencies
git clone https://github.com/owlinstack/rag-chat-minimal.git
cd rag-chat
pnpm install

# Copy environment & YAML configuration templates
cp .env.example .env
cp rag.config.example.yaml rag.config.yaml

3. Ingest Sample Documents & Index Vectors

Ingest sample markdown documents into the active vector store:

# Ingest local Markdown / JSON articles
pnpm ingest --source=./examples/sample-markdown

# Or fetch and index directly from a remote Laravel CMS API
pnpm ingest:api

# Or generate/reindex ONNX local & Gemini API vector bases
pnpm reindex

4. Start Development or Production Server

# Development mode (tsx watch with hot-reload)
pnpm dev

# Production build & start
pnpm build
pnpm start
# Microservice running at http://localhost:3000

5. Query the Microservice

curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer valid-token" \
  -d '{
    "question": "What is Next.js App Router?",
    "top_k": 3,
    "project_id": "rag-chat-blog"
  }'

Architecture Overview

 ┌─────────────────┐       ┌─────────────────┐       ┌────────────────┐
 │ Next.js Client  │       │ Laravel Client  │       │  cURL / HTTP   │
 └────────┬────────┘       └────────┬────────┘       └───────┬────────┘
          │                         │                        │
          └─────────────────────────┼────────────────────────┘
                                    │ HTTP POST /chat (Bearer Token)
                                    ▼
                     ┌──────────────────────────────┐
                     │    Express.js Microservice   │
                     │  (Rate Limit & Auth Guard)   │
                     └──────────────┬───────────────┘
                                    │
               ┌────────────────────┴────────────────────┐
               ▼                                         ▼
   ┌───────────────────────┐                 ┌───────────────────────┐
   │ Vector Retrieval      │                 │ Grounded Generator    │
   │ (Hybrid/JSON/Supabase)│                 │ (Gemini 2.5 / ONNX)   │
   └───────────────────────┘                 └───────────────────────┘

Ingestion & Reindexing CLI

The ingestion engine parses Markdown (with YAML Frontmatter) and JSON documents, strips UTF-8 BOM, chunks text into sliding windows, and generates vector embeddings.

# Ingest single file
pnpm ingest --source=path/to/document.md

# Ingest directory recursively
pnpm ingest --source=./examples/sample-markdown/

# Sync from remote Laravel API
pnpm ingest:api

# Reindex local ONNX or API vector store
pnpm reindex

# Clean vector stores and temp files
pnpm clean:stores

HTTP API Endpoints

`GET /health`

Liveness probe returning service status, project ID, and active generation provider.

Response (200 OK):

{
  "status": "ok",
  "project": "rag-chat-blog",
  "generation_provider": "google"
}

`POST /chat`

Executes semantic vector retrieval and grounded answer synthesis.

Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-project-id: <project_id> (optional header override)

Request Payload:

{
  "question": "How to integrate with Next.js App Router?",
  "top_k": 3,
  "project_id": "rag-chat-blog",
  "embedding_provider": "google",
  "llm_provider": "google"
}

Response Payload (200 OK):

{
  "answer": "To integrate with Next.js App Router, install @rag-chat/nextjs and use the RagChatWidget component...",
  "citations": [
    {
      "article_id": "doc-nextjs-integration",
      "title": "Next.js Integration Guide",
      "url": "https://blog.example.com/posts/nextjs-integration",
      "snippet": "Install the SDK and configure the proxy route..."
    }
  ],
  "trace_id": "96f655bf-873a-41ee-9875-48c2b7e778ae",
  "embedding_provider": "google",
  "generation_provider": "google"
}

Error Payload (400 / 401 / 413 / 429 / 500):

{
  "error": "Bad Request: Question cannot be empty",
  "code": "INVALID_REQUEST",
  "trace_id": "96f655bf-873a-41ee-9875-48c2b7e778ae"
}

Configuration Reference

The service is configured via rag.config.yaml or environment variables in .env.

Key	Env Variable	Default	Description
`project_id`	`PROJECT_ID`	`rag-chat-blog`	Microservice project identifier
`server_port`	`PORT`	`3000`	HTTP server listening port
`vector_backend`	`VECTOR_BACKEND`	`json`	Vector storage engine (`hybrid`, `json`, `supabase`)
`json_store_path`	`JSON_STORE_PATH`	`./data/vector-store.json`	Path to local JSON vector store
`embedding_provider`	`EMBEDDING_PROVIDER`	`google`	Embedding engine (`google` or `local`)
`generation_provider`	`GENERATION_PROVIDER`	`google`	LLM generation engine (`google` or `local`)
`gemini_api_key`	`GEMINI_API_KEY`	`""`	Google Gemini API Key
`gemini_model`	`GENERATION_MODEL`	`gemini-2.5-flash`	Cloud LLM generation model
`embedding_model`	`EMBEDDING_MODEL`	`gemini-embedding-2`	Cloud embedding model
`local_embedding_model`	`LOCAL_EMBEDDING_MODEL`	`onnx-community/embeddinggemma-300m-ONNX`	Local HuggingFace ONNX embedding model
`local_generation_model`	`LOCAL_GENERATION_MODEL`	`onnx-community/LFM2.5-350M-ONNX`	Local HuggingFace ONNX ChatML generator
`rate_limit_rpm`	`RATE_LIMIT_RPM`	`60`	Max requests per minute per IP / agent
`max_payload_bytes`	`MAX_PAYLOAD_BYTES`	`1048576` (1MB)	Max request payload size in bytes
`cors_origins`	`CORS_ORIGINS`	`["*"]`	Allowed CORS origin URLs
`iam_auth_url`	`IAM_AUTH_URL`	`""`	Optional IAM token introspection URL
`iam_required_scope`	`IAM_REQUIRED_SCOPE`	`execute:rag_chat`	Scope required for Bearer token
`jwt_secret`	`JWT_SECRET`	`""`	HMAC SHA-256 secret for local JWT validation

Client Integration SDKs

1. Next.js Client Package (`clients/nextjs/`)

Provides TypeScript client function askRagChat, RagChatError class, and RagChatWidget React component. See clients/nextjs/README.md for details.

2. Laravel Client Package (`clients/laravel/`)

Provides PHP service RagChatService, RagChatServiceProvider, and RagChat facade (RagChat::ask(...)). See clients/laravel/README.md for details.

Testing & Benchmarks

The test suite contains 104 automated tests across 27 test suites:

# Typecheck TypeScript files
pnpm typecheck

# Run full Node.js test suite
pnpm test

# Run full matrix RAG benchmark (Local vs Cloud Provider combinations)
pnpm test:matrix

# Build production bundle
pnpm build

Project Documentation

Detailed architecture and deployment guides are available in documentation/:

📘 Guide d'Utilisation — Comprehensive user and developer french manual.
📐 Architecture du Projet — Internal file & module structure documentation.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
clients		clients
data		data
documentation		documentation
examples		examples
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
rag.config.example.yaml		rag.config.example.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

RAG Chat Microservice (`rag-chat-minimal`)

Key Features

Quickstart (< 5 mins)

1. Prerequisites

2. Installation & Environment Setup

3. Ingest Sample Documents & Index Vectors

4. Start Development or Production Server

5. Query the Microservice

Architecture Overview

Ingestion & Reindexing CLI

HTTP API Endpoints

`GET /health`

`POST /chat`

Configuration Reference

Client Integration SDKs

1. Next.js Client Package (`clients/nextjs/`)

2. Laravel Client Package (`clients/laravel/`)

Testing & Benchmarks

Project Documentation

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

RAG Chat Microservice (rag-chat-minimal)

Key Features

Quickstart (< 5 mins)

1. Prerequisites

2. Installation & Environment Setup

3. Ingest Sample Documents & Index Vectors

4. Start Development or Production Server

5. Query the Microservice

Architecture Overview

Ingestion & Reindexing CLI

HTTP API Endpoints

GET /health

POST /chat

Configuration Reference

Client Integration SDKs

1. Next.js Client Package (clients/nextjs/)

2. Laravel Client Package (clients/laravel/)

Testing & Benchmarks

Project Documentation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

RAG Chat Microservice (`rag-chat-minimal`)

`GET /health`

`POST /chat`

1. Next.js Client Package (`clients/nextjs/`)

2. Laravel Client Package (`clients/laravel/`)