diff --git a/README.md b/README.md index 8747d22..94d49fc 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,78 @@ # RARA -RARA is an internal, storage-agnostic platform for operating the complete RAG -lifecycle and promoting verified data into optional LoRA/QLoRA workflows. +RARA는 저장소와 모델 제품에 종속되지 않고 RAG 전체 수명주기를 운영하기 위한 내부 +플랫폼이다. 검증된 데이터를 선택적으로 LoRA/QLoRA workflow로 연결하는 경계까지 +포함한다. -RARA owns the logical RAG contract end to end: +RARA가 다루는 논리적 수명주기는 다음과 같다. -- 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 +- source 동기화와 정규화 +- versioned dataset과 artifact lineage +- retrieval, reranking, context 조립, 답변 생성 +- 평가, release 승격, rollback +- 학습 후보 선별과 adaptation 실행 -Physical retrieval stores, artifact stores, model providers, and executors stay -replaceable behind capability-aware integrations. +실제 retrieval store, artifact store, model provider, executor는 +capability-aware integration 뒤에서 교체할 수 있도록 분리한다. -## 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 -``` +현재 저장소는 플랫폼 scaffold 단계다. Control Plane, 온라인 RAG API, Go workflow +worker, Python executor의 실행 기준선과 계약·데이터베이스·관측성 골격을 제공한다. +실제 retrieval backend, model provider, source connector, production workflow는 +하드코딩하지 않고 versioned integration으로 확장한다. -## Baseline +기술 기준선은 Go 1.26, Python 3.12, PostgreSQL 18, OpenAPI 3.1, +Protobuf/gRPC, HTTP/JSON, SSE다. -- Go 1.26 -- Python 3.12 -- PostgreSQL 18 -- Protobuf for internal executor contracts -- HTTP/JSON and SSE for the public RAG API +PostgreSQL은 필수 control-state 및 lineage 저장소다. 기본 RAG retrieval backend로 +사용하지 않으며 SQLite fallback도 제공하지 않는다. -PostgreSQL is the required control-state database. It is not the default RAG -retrieval backend and there is no SQLite fallback. +## 빠른 시작 -## Development +로컬 개발에는 Go 1.26, Python 3.12, `protoc`, Make가 필요하다. PostgreSQL을 +컨테이너로 실행하려면 Docker Compose도 필요하다. -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: +Python 개발 환경과 version-pinned code generation 도구를 준비하고 생성물을 +동기화한다. ```sh make setup ``` -Run checks and build the three Go services: - -```sh -make test -make build -``` - -Start PostgreSQL when a container runtime is available: +로컬 PostgreSQL을 시작하고 migration을 적용한다. ```sh make db-up make migrate-up ``` -The current workspace may instead use an external PostgreSQL instance through -`RARA_DATABASE_URL`. +테스트를 실행하고 세 Go 서비스를 빌드한다. -Run services after PostgreSQL is migrated: +```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 @@ -82,18 +80,89 @@ bin/rara-rag-api --config configs/rag-api.yaml bin/rara-worker --config configs/worker.yaml ``` -The Python executor starts with: +Python executor는 `make setup` 후 다음 명령으로 실행한다. ```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. +ML dependency는 선택 사항이다. adaptation job을 실행하는 호스트에만 +`packages/python[training]` 또는 `packages/python[training,quantized]` extra를 +설치한다. -## 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. +| 경로 | 역할 | +|------|------| +| `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) diff --git a/agent-ops/rules/project/domain/control-plane/rules.md b/agent-ops/rules/project/domain/control-plane/rules.md index b6e1f08..2ad1bb9 100644 --- a/agent-ops/rules/project/domain/control-plane/rules.md +++ b/agent-ops/rules/project/domain/control-plane/rules.md @@ -1,6 +1,6 @@ --- domain: control-plane -last_rule_review_commit: null +last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea last_rule_updated_at: 2026-07-18 --- @@ -8,13 +8,13 @@ last_rule_updated_at: 2026-07-18 ## 목적 / 책임 -RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base, dataset, artifact lineage, workflow, evaluation, release, schedule의 관리와 명시적 승격·롤백 경계를 정의한다. +RARA의 핵심 수명주기 상태 모델과 PostgreSQL 영속 계약을 소유한다. 프로젝트, knowledge base, dataset, artifact lineage, workflow, evaluation, release, schedule의 상태와 명시적 승격 경계를 정의한다. ## 포함 경로 - `apps/control-plane/` — 제어 플레인 프로세스 조립과 실행 진입점 - `apps/client/` — 향후 제어 플레인 운영 UI를 위한 예약 경로 -- `packages/go/controlplane/` — 수명주기 관리 HTTP handler +- `packages/go/controlplane/` — 제어 플레인 HTTP surface - `db/migrations/` — 제어 상태와 lineage의 PostgreSQL 스키마 원본 - `db/queries/` — 제어 상태를 다루는 sqlc 쿼리 원본 @@ -26,20 +26,20 @@ RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base ## 주요 구성 요소 -- `controlplane.Register` — 제어 플레인 HTTP route 등록 -- `db/migrations/00001_initial.sql` — 프로젝트·knowledge·workflow·release·trace 등 제어 상태 스키마 -- `db/queries/*.sql` — sqlc 입력이 되는 상태 조회·변경 쿼리 +- `controlplane.Register` — 현재 제어 플레인 경계와 버전을 노출하는 `/v1/status` route 등록 +- `db/migrations/00001_initial.sql` — 프로젝트, integration, knowledge, artifact, workflow, evaluation, release, RAG trace 스키마 +- `db/queries/*.sql` — project·knowledge·workflow·trace 상태를 다루는 sqlc 쿼리 원본 ## 유지할 패턴 -- release promotion은 명시적으로 수행하고 production index는 불변 artifact로 취급한다. -- 후보 artifact를 만든 뒤 승격하며 source 삭제와 ACL 변경을 lineage로 추적한다. +- release는 `candidate`, `active`, `retired`, `failed` 상태와 alias별 단일 active 제약을 유지한다. +- artifact는 content hash와 lineage를 보존하고 dataset/release가 artifact identity를 참조하게 한다. - 스키마와 쿼리를 변경한 뒤 `make sqlc`로 Go adapter를 재생성한다. - integration 설정에는 secret 원문 대신 secret reference만 저장한다. ## 다른 도메인과의 경계 -- **rag-data-plane**: control-plane은 release와 policy를 게시하고, rag-data-plane은 해당 식별자와 정책을 해석해 온라인 요청을 처리한다. +- **rag-data-plane**: control-plane은 release와 policy의 영속 상태를 소유하고, rag-data-plane은 active release 식별자와 정책을 읽어 온라인 요청을 처리한다. - **workflow-execution**: control-plane은 workflow/job 상태를 소유하고, worker는 lease된 step의 실행과 결과 보고를 담당한다. - **platform-common**: 데이터베이스 연결과 공통 HTTP/관측성 구현은 platform-common adapter를 사용한다. @@ -48,4 +48,3 @@ RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base - PostgreSQL을 기본 retrieval backend나 대형 artifact 저장소로 사용하지 않는다. - 생성된 `packages/go/database/dbgen/` 파일을 직접 수정하지 않는다. - 특정 retrieval, model, artifact 제품을 수명주기 모델에 하드코딩하지 않는다. - diff --git a/agent-ops/rules/project/domain/platform-common/rules.md b/agent-ops/rules/project/domain/platform-common/rules.md index 81f99ff..f2d6d95 100644 --- a/agent-ops/rules/project/domain/platform-common/rules.md +++ b/agent-ops/rules/project/domain/platform-common/rules.md @@ -1,6 +1,6 @@ --- domain: platform-common -last_rule_review_commit: null +last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea last_rule_updated_at: 2026-07-18 --- @@ -30,16 +30,18 @@ last_rule_updated_at: 2026-07-18 - `database.Store` — pgx pool과 생성된 sqlc query 접근점 - `artifact.Store` / `artifact.Filesystem` — artifact 저장 port와 로컬 구현 -- `integration.Ports` — 외부 capability의 제품 중립 계약 +- `integration.Registry` / `integration.Factory` — manifest 이름으로 외부 integration factory를 조회·구성하는 계약 +- `integration.SourceConnector`, `RetrievalBackend`, `EmbeddingProvider`, `RerankProvider`, `GenerationProvider`, `SecretResolver` — 제품 중립 capability port - `httpserver.Start` — 공통 HTTP lifecycle - `observability.SetupTracing` — trace exporter 설정 ## 유지할 패턴 - 공통 패키지는 plane별 정책을 소유하지 않고 작은 port와 lifecycle adapter에 집중한다. -- integration instance는 versioned capability와 secret reference로 구성한다. +- integration manifest는 schema version과 capability를 노출하고 factory에는 config와 secret reference만 전달한다. - artifact URI와 content hash를 유지해 lineage를 추적할 수 있게 한다. -- readiness는 실제 필수 dependency 상태를 반영하고 health와 구분한다. +- filesystem artifact key는 configured root 밖으로 벗어나는 절대 경로와 traversal을 거부한다. +- readiness는 각 앱이 주입한 필수 dependency 상태를 반영하고 health와 구분한다. - 설정 예시에는 로컬 기본값만 두며 운영 secret을 포함하지 않는다. ## 다른 도메인과의 경계 @@ -53,4 +55,3 @@ last_rule_updated_at: 2026-07-18 - 공통 패키지에 control-plane, RAG, workflow의 유즈케이스 정책을 넣지 않는다. - integration port를 특정 vendor의 request/response 타입으로 노출하지 않는다. - config, log, trace, 예제 배포 파일에 secret이나 credential 원문을 남기지 않는다. - diff --git a/agent-ops/rules/project/domain/rag-data-plane/rules.md b/agent-ops/rules/project/domain/rag-data-plane/rules.md index 456ce31..f1e09ee 100644 --- a/agent-ops/rules/project/domain/rag-data-plane/rules.md +++ b/agent-ops/rules/project/domain/rag-data-plane/rules.md @@ -1,6 +1,6 @@ --- domain: rag-data-plane -last_rule_review_commit: null +last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea last_rule_updated_at: 2026-07-18 --- @@ -25,16 +25,17 @@ last_rule_updated_at: 2026-07-18 ## 주요 구성 요소 - `rag.Handler` — `/v1/retrieve`, `/v1/answer` 요청 검증과 응답 변환 -- `rag.ReleaseResolver` — project, knowledge base, alias로 활성 release 해석 +- `rag.PostgreSQLReleaseResolver` — project, knowledge base, alias로 PostgreSQL의 active release 해석 - `rag.Engine` — retrieval과 generation 구현을 교체하기 위한 도메인 port +- `rag.UnavailableEngine` — integration 미구성 상태를 503으로 노출하는 기본 engine - `api/openapi/rara-v1.yaml` — 공개 요청·응답 및 오류 스키마 ## 유지할 패턴 -- 모든 온라인 요청은 knowledge base와 release alias를 해석하고 응답에 release identity를 포함한다. +- 성공한 온라인 요청은 knowledge base와 release alias를 해석하고 응답에 release와 trace identity를 포함한다. - release alias가 없으면 `production`, `top_k`가 없으면 10을 사용하며 검증 범위는 OpenAPI와 handler가 일치해야 한다. - engine 구현은 capability-aware integration 뒤에 두고 handler가 특정 제품 SDK에 의존하지 않게 한다. -- streaming 응답은 SSE event와 오류 의미를 비 streaming JSON 응답과 호환되게 유지한다. +- `stream=true` 응답의 `completed`/`error` SSE event 집합을 변경할 때는 OpenAPI 설명과 handler를 함께 갱신한다. ## 다른 도메인과의 경계 @@ -47,4 +48,3 @@ last_rule_updated_at: 2026-07-18 - 요청 시점에 candidate release를 암묵적으로 production으로 승격하지 않는다. - handler에 특정 vector store, reranker, model provider를 직접 결합하지 않는다. - 공개 handler 변경 시 OpenAPI와 JSON/SSE 오류 계약 검토를 생략하지 않는다. - diff --git a/agent-ops/rules/project/domain/workflow-execution/rules.md b/agent-ops/rules/project/domain/workflow-execution/rules.md index 8c1f424..63b1b2e 100644 --- a/agent-ops/rules/project/domain/workflow-execution/rules.md +++ b/agent-ops/rules/project/domain/workflow-execution/rules.md @@ -1,6 +1,6 @@ --- domain: workflow-execution -last_rule_review_commit: null +last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea last_rule_updated_at: 2026-07-18 --- @@ -8,7 +8,7 @@ last_rule_updated_at: 2026-07-18 ## 목적 / 책임 -제어 플레인이 만든 workflow step을 lease하고 실행 상태를 보고한다. Go executor와 Python adaptation executor 사이의 버전 있는 실행 계약 및 취소·진행·결과 의미를 책임진다. +Go worker가 제어 플레인의 workflow step을 lease해 in-process executor registry로 실행하고 결과 상태를 갱신한다. 별도 Python executor는 버전 있는 gRPC 계약으로 capability, streaming 진행, 취소와 결과 의미를 제공한다. ## 포함 경로 @@ -27,20 +27,21 @@ last_rule_updated_at: 2026-07-18 ## 주요 구성 요소 - `workflow.Worker` — 실행 가능한 step을 lease하고 executor 결과에 따라 상태 갱신 -- `workflow.Registry` — operation 이름과 Go executor 구현 연결 -- `ExecutorService` — Python capability 조회, streaming 실행, 취소 gRPC 서비스 +- `workflow.Registry` — operation 이름과 in-process Go executor 구현 연결 +- `rara_worker.server.ExecutorService` — Python capability 조회, streaming 실행, 취소 gRPC 서비스 - `api/proto/rara/v1/executor.proto` — job, progress, artifact, error 계약 ## 유지할 패턴 - worker identity, lease duration, retry delay를 설정에서 읽고 lease 소유권과 재시도 의미를 보존한다. -- executor operation과 capability는 명시적 이름과 버전으로 등록한다. -- ML 라이브러리 실행과 LoRA/QLoRA adaptation은 Python executor가 담당하고 제어 상태는 PostgreSQL이 소유한다. +- Go executor operation은 명시적 이름으로 registry에 등록하고, Python capability는 이름과 버전을 응답한다. +- Go worker의 상태 변경은 `leased_by`와 현재 step 상태 조건을 유지한다. +- Python executor는 `accepted`, `running`, `succeeded`/`failed`/`cancelled` event 순서와 구조화된 오류를 유지한다. - Protobuf 변경은 기존 field number를 재사용하지 않고 Go/Python 생성물을 `make proto`로 함께 갱신한다. ## 다른 도메인과의 경계 -- **control-plane**: workflow와 job의 영속 상태는 control-plane 소유이며 이 도메인은 lease된 실행과 결과만 처리한다. +- **control-plane**: workflow와 step run의 영속 스키마는 control-plane 소유이며 이 도메인은 lease된 실행과 결과 갱신만 처리한다. - **rag-data-plane**: 온라인 요청 경로를 worker에서 처리하지 않고, workflow가 만든 artifact를 release 승격 뒤 소비하게 한다. - **platform-common**: database, config, observability, artifact와 integration port는 공통 adapter에 위임한다. @@ -49,4 +50,3 @@ last_rule_updated_at: 2026-07-18 - `gen/go/rara/v1/`과 `packages/python/src/rara/v1/*_pb2*.py`를 직접 수정하지 않는다. - lease 없이 step을 실행하거나 다른 worker 소유의 step 상태를 완료 처리하지 않는다. - secret 원문이나 제품별 credential을 job payload와 추적 문서에 기록하지 않는다. -