rara/README.md

# RARA

RARA는 저장소와 모델 제품에 종속되지 않고 RAG 전체 수명주기를 운영하기 위한 내부
플랫폼이다. 검증된 데이터를 선택적으로 LoRA/QLoRA workflow로 연결하는 경계까지
포함한다.

RARA가 다루는 논리적 수명주기는 다음과 같다.

- source 동기화와 정규화
- versioned dataset과 artifact lineage
- retrieval, reranking, context 조립, 답변 생성
- 평가, release 승격, rollback
- 학습 후보 선별과 adaptation 실행

실제 retrieval store, artifact store, model provider, executor는
capability-aware integration 뒤에서 교체할 수 있도록 분리한다.

## 현재 상태

현재 저장소는 플랫폼 scaffold 단계다. Control Plane, 온라인 RAG API, Go workflow
worker, Python executor의 실행 기준선과 계약·데이터베이스·관측성 골격을 제공한다.
실제 retrieval backend, model provider, source connector, production workflow는
하드코딩하지 않고 versioned integration으로 확장한다.

기술 기준선은 Go 1.26, Python 3.12, PostgreSQL 18, OpenAPI 3.1,
Protobuf/gRPC, HTTP/JSON, SSE다.

PostgreSQL은 필수 control-state 및 lineage 저장소다. 기본 RAG retrieval backend로
사용하지 않으며 SQLite fallback도 제공하지 않는다.

## 빠른 시작

로컬 개발에는 Go 1.26, Python 3.12, `protoc`, Make가 필요하다. PostgreSQL을
컨테이너로 실행하려면 Docker Compose도 필요하다.

Python 개발 환경과 version-pinned code generation 도구를 준비하고 생성물을
동기화한다.

```sh
make setup
```

로컬 PostgreSQL을 시작하고 migration을 적용한다.

```sh
make db-up
make migrate-up
```

테스트를 실행하고 세 Go 서비스를 빌드한다.

```sh
make test
make build
```

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|
| 전체 로컬 검증 | `make all` | setup, format, test, build 순서로 실행 |
| 개발 환경 및 생성물 준비 | `make setup` | `.tools/`, `.venv/` 준비 후 Protobuf와 sqlc 생성 |
| Protobuf와 sqlc 생성 | `make generate` | `make proto`, `make sqlc` 실행 |
| 코드 format/lint | `make fmt` | Go `gofmt`, Python Ruff format 및 autofix |
| 전체 테스트 | `make test` | Go와 Python 테스트 실행 |
| Go 테스트 | `make test-go` | `go test ./...` |
| Python 테스트 | `make test-python` | pytest 실행 |
| Go 서비스 빌드 | `make build` | 결과물을 `bin/`에 생성 |
| PostgreSQL 시작/종료 | `make db-up` / `make db-down` | `deploy/compose.yaml` 사용 |
| migration 적용/되돌리기 | `make migrate-up` / `make migrate-down` | Goose 사용 |
| migration 상태 확인 | `make migrate-status` | 기본 `DATABASE_URL` 사용 |

## 서비스 실행

PostgreSQL migration과 `make build`가 끝나면 Go 서비스를 실행할 수 있다.

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

Python executor는 `make setup` 후 다음 명령으로 실행한다.

```sh
.venv/bin/rara-python-worker
```

ML dependency는 선택 사항이다. adaptation job을 실행하는 호스트에만
`packages/python[training]` 또는 `packages/python[training,quantized]` extra를
설치한다.

## 구조

| 경로 | 역할 |
|------|------|
| `apps/control-plane/` | Go lifecycle 및 management API 진입점 |
| `apps/rag-api/` | Go 온라인 retrieve/answer data plane 진입점 |
| `apps/worker/` | Go workflow step worker 진입점 |
| `apps/client/` | 향후 operations UI 영역 |
| `api/openapi/` | 공개 HTTP/JSON 및 SSE 계약 |
| `api/proto/` | Go/Python executor 사이의 내부 gRPC 계약 |
| `packages/go/` | Go 도메인 로직, port, 공통 runtime adapter |
| `packages/python/` | Python adaptation executor와 테스트 |
| `db/migrations/`, `db/queries/` | PostgreSQL schema와 sqlc query 원본 |
| `gen/` | Protobuf에서 생성된 Go 코드 |
| `configs/` | 서비스별 로컬 설정 예시 |
| `deploy/` | 로컬 PostgreSQL 및 container build 자산 |
| `agent-ops/`, `agent-roadmap/` | 작업 규칙, skill, 제품 roadmap |

## 구성과 환경 변수

Go 서비스의 기본 설정은 `configs/*.yaml`에 있다. 공통 환경 변수는 YAML 값을
override한다.

| 이름 | 설명 | 필수 |
|------|------|------|
| `RARA_DATABASE_URL` | Go 서비스가 사용할 PostgreSQL URL | 아니요 |
| `RARA_DATABASE_MAX_CONNECTIONS` | PostgreSQL 최대 connection 수 | 아니요 |
| `RARA_DATABASE_MIN_CONNECTIONS` | PostgreSQL 최소 connection 수 | 아니요 |
| `RARA_ARTIFACT_ROOT` | filesystem artifact root | 아니요 |
| `RARA_LOG_LEVEL` | logging level | 아니요 |
| `RARA_OTEL_ENDPOINT` | OpenTelemetry collector endpoint | 아니요 |
| `RARA_LISTEN` | Go 서비스 listen address | 아니요 |
| `RARA_WORKER_ID` | Go worker 식별자 | 아니요 |
| `RARA_WORKER_EXECUTOR_KIND` | Go worker executor kind | 아니요 |
| `RARA_WORKER_POLL_INTERVAL` | workflow polling 주기 | 아니요 |
| `RARA_WORKER_LEASE_DURATION` | workflow lease 기간 | 아니요 |
| `RARA_PYTHON_LISTEN_HOST` | Python executor listen host, 기본 `0.0.0.0` | 아니요 |
| `RARA_PYTHON_LISTEN_PORT` | Python executor listen port, 기본 `19090` | 아니요 |

Make migration target에 외부 PostgreSQL을 지정할 때는 `RARA_DATABASE_URL`이 아니라
Make 변수 `DATABASE_URL`을 전달한다.

```sh
make migrate-up DATABASE_URL='postgres://user:password@host:5432/rara?sslmode=require'
```

## 개발 흐름

- `api/proto/`와 `db/migrations/`, `db/queries/`를 생성 코드의 원본으로 취급한다.
- `gen/go/`, `packages/python/src/rara/v1/*_pb2*.py`,
  `packages/go/database/dbgen/`은 직접 수정하지 않고 `make proto` 또는 `make sqlc`로
  갱신한다.
- 공개 RAG handler 변경 시 `api/openapi/rara-v1.yaml`과 HTTP/JSON 및 SSE 동작을
  함께 검토한다.
- executor wire contract 변경 시 Protobuf 호환성을 유지하고 Go/Python 생성물을 함께
  갱신한다.
- 변경 후 기본 검증은 `make test`와 `make build`다.

## 작업 맥락

사람과 AI agent 모두 작업 전에 루트 [`AGENTS.md`](AGENTS.md)와 매칭되는
[`domain rule`](agent-ops/rules/project/domain/)을 먼저 확인한다. 현재 제품 방향은
공유 [`Roadmap`](agent-roadmap/ROADMAP.md)에서, 활성 Milestone 후보는 로컬
`agent-roadmap/current.md`가 있을 때 해당 파일에서 확인한다. README에는 특정 작업
위치를 고정하지 않는다.

요청 범위를 넘어 플랫폼 경계를 확장하지 않는다. PostgreSQL에는 control state와
lineage만 저장하고, 대형 artifact와 retrieval index는 integration port 뒤에 둔다.

## 참고 문서

- [Architecture](ARCHITECTURE.md)
- [공개 RAG API 계약](api/openapi/rara-v1.yaml)
- [내부 executor 계약](api/proto/rara/v1/executor.proto)
- [프로젝트 작업 규칙](agent-ops/rules/project/rules.md)
- [Roadmap](agent-roadmap/ROADMAP.md)