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 도구를 준비하고 생성물을 동기화한다.

make setup

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

make db-up
make migrate-up

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

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 서비스를 실행할 수 있다.

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 후 다음 명령으로 실행한다.

.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을 전달한다.

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와 매칭되는 domain rule을 먼저 확인한다. 현재 제품 방향은 공유 Roadmap에서, 활성 Milestone 후보는 로컬 agent-roadmap/current.md가 있을 때 해당 파일에서 확인한다. README에는 특정 작업 위치를 고정하지 않는다.

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

참고 문서

• Architecture
• 공개 RAG API 계약
• 내부 executor 계약
• 프로젝트 작업 규칙
• Roadmap