README.md

Ragforge

A modular, multi-agent Retrieval-Augmented Generation (RAG) platform designed for extensibility, observability, and high developer velocity.

Ragforge breaks the RAG stack into clear, focused microservices ("agents") that handle orchestration, embedding, ontology reasoning, vector search, LLM access, and data ingestion.

This repo also includes a starter Next.js UI and a Postgres pgvector instance.

---

Features

• Modular microservices for every phase of RAG
• Embeddings, Ontology Graph, and Multi-Hop Retrieval
• Central Orchestrator that merges semantic + symbolic context
• LLM Proxy for secure prompt execution
• Full ingestion pipeline
• Docker + docker-compose support
• Fast dependency management using uv
• Ready for scaling to Kubernetes

---

Repository Structure

ragforge/
  api_gateway/
  docs/
  orchestrator/
  embeddings/
  ontology_service/
  llm_proxy/
  pipeline/
  vector_db/
  ui/
  docker-compose.yml
  Makefile
  README.md

Each Python service is a standalone uv project.

---

Requirements

• Docker + Docker Compose
• Python 3.12 (only if running locally)
• Node 20+ (for UI)
• uv (https://github.com/astral-sh/uv)

---

Getting Started

1. Clone the repo

git clone https://github.com/your-org/ragforge.git
cd ragforge

2. Create your environment file

cp .env.example .env

Add your LLM API keys here.

3. Start all services

make docker-up

Then access:

• API Gateway: http://localhost:8001/health
• UI: http://localhost:3000
• Vector DB (Postgres): localhost:5432

---

Development Commands

Format + Lint

make fmt

Run all tests

make test

Run tests per service (recommended)

For faster and more reliable feedback, run tests inside each service directory rather than from the repository root. This avoids import path issues and matches how services are packaged.

Example (from repo root):

cd embeddings && pytest -q
cd ../orchestrator && pytest -q

Or use the helper script included in scripts/:

./scripts/run_service_tests.sh embeddings

The helper will change into the specified service folder and run pytest there.

Stop containers

make docker-down

---

Service Overview

See Agents.md for full details.

---

Production Deployment

Recommended setup:

• Terraform for IaC
• AWS EKS for services
• AWS RDS for vector DB
• AWS Secrets Manager for keys
• ArgoCD or GitHub Actions for CI/CD
• Prometheus/Grafana + OpenTelemetry

---

Contributing

1. Fork the repo
2. Create a feature branch
3. Submit a PR
4. Include tests where possible

---

If you'd like, I can also generate:

• A system architecture diagram (ASCII or HTML)
• A CONTRIBUTING.md
• A SECURITY.md
• A developer onboarding guide