# 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

```text
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:

```sh
make setup
```

Run checks and build the three Go services:

```sh
make test
make build
```

Start PostgreSQL when a container runtime is available:

```sh
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:

```sh
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:

```sh
.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.