rara/README.md

RARA

RARA is an internal, storage-agnostic platform for operating the complete RAG lifecycle and promoting verified data into optional LoRA/QLoRA workflows.

RARA owns the logical RAG contract end to end:

• source synchronization and normalization
• versioned datasets and artifact lineage
• retrieval, reranking, context assembly, and answer generation
• evaluation, release promotion, and rollback
• training-candidate curation and adaptation execution

Physical retrieval stores, artifact stores, model providers, and executors stay replaceable behind capability-aware integrations.

Repository layout

apps/
  control-plane/   Go lifecycle and management API
  rag-api/         Go online retrieve/answer data plane
  worker/          Go workflow step worker
  client/          reserved for the operations UI
api/
  openapi/         public HTTP API contract
  proto/           internal Go/Python executor contract
packages/
  go/              shared Go packages
  python/          Python adaptation worker
db/
  migrations/      PostgreSQL schema migrations
  queries/         sqlc queries
configs/           service configuration examples
deploy/            local deployment assets

Baseline

• Go 1.26
• Python 3.12
• PostgreSQL 18
• Protobuf for internal executor contracts
• HTTP/JSON and SSE for the public RAG API

PostgreSQL is the required control-state database. It is not the default RAG retrieval backend and there is no SQLite fallback.

Development

The local prerequisites are Go, Python, and protoc. make setup installs version-pinned Go code-generation tools under .tools/ and creates .venv/.

Bootstrap the Python environment and generate contracts:

make setup

Run checks and build the three Go services:

make test
make build

Start PostgreSQL when a container runtime is available:

make db-up
make migrate-up

The current workspace may instead use an external PostgreSQL instance through RARA_DATABASE_URL.

Run services after PostgreSQL is migrated:

bin/rara-control-plane --config configs/control-plane.yaml
bin/rara-rag-api --config configs/rag-api.yaml
bin/rara-worker --config configs/worker.yaml

The Python executor starts with:

.venv/bin/rara-python-worker

ML dependencies are optional. Install packages/python[training] or packages/python[training,quantized] only on hosts that execute adaptation jobs.

Status

This repository currently contains the platform scaffold. Retrieval backends, model providers, source connectors, and production workflows are added as versioned integrations rather than hard-coded infrastructure.