# Experiment Management — `fithia2 exp`

전략 실험(experiment) 생성, 검색, 계보 추적, 비교를 위한 관리 시스템.

## 개요

실험 설정 파일(`configs/experiments/*.json`)에 **메타데이터 필드**를 추가하고, `fithia2 exp` CLI를 통해 체계적으로 관리한다.

- **파일 기반 워크플로우 유지** — AI 에이전트가 JSON을 직접 읽고/쓰는 기존 방식과 100% 호환
- **숫자 ID** — 각 실험에 고유 정수 ID 부여. 모든 커맨드에서 이름 대신 ID 사용 가능
- **계보(lineage) 추적** — `parent` 필드로 실험 간 ancestor 관계 명시
- **자동 인덱스** — `.index.json` 캐시로 빠른 검색
- **journal/registry와 독립** — 결과/스코어는 기존 journal이 source of truth; 메타데이터는 실험 JSON이 source of truth

---

## 식별자

각 실험은 두 가지 식별자를 가진다.

| 식별자 | 예시 | 설명 |
|--------|------|------|
| **`id`** (숫자) | `228` | 고유 정수 ID. 모든 커맨드에서 이름 대신 사용 가능 |
| **`experiment_name`** (문자열) | `return_max_long_v6new.362` | 파일명과 동일한 전통적 식별자 |

리더보드와 `fithia2 exp search` 출력에는 ID 컬럼이 표시된다. ID는 `fithia2 exp info`, `diff`, `tree`, `promote`, `retire`, `create --parent`, `fithia2 paper start/backtest --config` 등 모든 곳에서 이름 대신 쓸 수 있다.

```bash
# 이름으로
fithia2 exp info return_max_long_v6new.362
fithia2 exp diff return_max_long_v6new.362 return_max_long_v6new.376
fithia2 paper start --config return_max_long_v6new.362 --name my_session

# ID로 (동일한 결과)
fithia2 exp info 228
fithia2 exp diff 228 242
fithia2 paper start --config 228 --name my_session
```

---

## 실험 JSON 스키마

### 기존 필드 (변경 없음)
```json
{
  "experiment_name": "return_max_long_v6new.380",
  "dataset_snapshot_id": "midlarge-liquid-long-v1_bucketfix_full_audit_canonical",
  "description": "v362 + tighter entropy cap",
  "base_config": "configs/backtest/return_max_long_v1.json",
  "overrides": { ... },
  "strategy_engines": [ ... ],
  "splits": [ ... ],
  "tags": ["return-max", "v6new"],
  "notes": "..."
}
```

### 새로 추가된 메타데이터 필드
```json
{
  "id": 318,
  "parent": "return_max_long_v6new.362",
  "created_at": "2026-03-27T10:00:00+00:00",
  "created_by": "ai_agent",
  "status": "draft",
  "generation": 6,
  "version_family": "v6new",
  "changelog": "tighter entropy cap on OME",
  "aliases": ["entropy_safe"],
  "performance_summary": {
    "sqs_score": 74.1,
    "public_sqs": 71.3,
    "trade_count_test": 180
  }
}
```

| 필드 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `id` | `int \| null` | `null` | **고유 정수 ID** — 새 실험 생성 시 자동 할당 |
| `parent` | `str \| null` | `null` | 부모 실험 이름 |
| `created_at` | `str \| null` | `null` | ISO-8601 생성 시각 |
| `created_by` | `str \| null` | `null` | `"human"` \| `"ai_agent"` \| agent 이름 |
| `status` | `str` | `"active"` | `draft` \| `active` \| `promoted` \| `retired` |
| `generation` | `int \| null` | `null` | parent chain 깊이 (root=0) |
| `version_family` | `str \| null` | `null` | `"v6new"`, `"v8"`, `"v1"` 등 |
| `changelog` | `str \| null` | `null` | parent 대비 변경 요약 |
| `aliases` | `list[str]` | `[]` | 사람이 읽기 쉬운 별칭 |
| `performance_summary` | `dict \| null` | `null` | auto-sync 후 캐시된 SQS 등 |

모든 필드가 optional이므로 **기존 파일은 그대로 로딩**된다.

### Snapshot 규칙

- snapshot registry source of truth는
  [`configs/snapshots/registry.json`](/Users/yirugi/mycloud/personal/workspace/fithia2/configs/snapshots/registry.json)
  이다.
- canonical physical snapshot은 두 개만 관리한다.
  - `midlarge-liquid-long-v1_bucketfix_full_audit_canonical`
  - `midlarge-liquid-long-v1-oot-2020-2021_canonical`
- 기존 `..._tier3`, `..._tier3tech`, `..._mom`, `..._tech` 같은 값은 legacy alias로는 계속 허용되지만,
  runtime에서는 canonical snapshot id로 resolve된다.
- **새 실험은 canonical snapshot id를 직접 쓰는 것이 기본값**이다.
- phase 1에서는 old manifest bulk rewrite는 하지 않는다.
  즉, 기존 manifest가 legacy alias를 들고 있어도 loader/tracker가 canonical lineage로 흡수한다.

---

## CLI 커맨드

> **모든 커맨드에서 실험 이름 자리에 숫자 ID를 쓸 수 있다.**

### `fithia2 exp create` — 새 실험 생성

부모 실험을 복사하고 메타데이터를 설정한다. status는 `draft`, ID는 자동 할당.

```bash
fithia2 exp create \
  --parent 228 \
  --name return_max_long_v6new.381 \
  --changelog "entropy cap 0.15→0.10으로 강화"
```

옵션:
- `--parent` / `-p` (필수) — 부모 실험 이름 또는 ID
- `--name` / `-n` (필수) — 새 실험 이름
- `--changelog` / `-c` — 변경 내용 설명
- `--created-by` — 생성자 (기본값: `"ai_agent"`)

생성 후 `configs/experiments/{name}.json`을 열어서 `overrides`와 `strategy_engines`를 수정한다.

---

### `fithia2 exp search` — 실험 검색

```bash
# 패밀리로 검색
fithia2 exp search --family v6new

# 태그 + 상태로 필터
fithia2 exp search --tag entropy --status active

# 부모로 검색 (직접 자식만)
fithia2 exp search --parent 228

# 이름 패턴 (regex)
fithia2 exp search --pattern "v6new\.3[5-9]\d$"
```

출력: **ID** / 이름 / 상태 / 패밀리 / generation / parent / SQS / aliases / tags

---

### `fithia2 exp tree` — 계보 트리

```bash
fithia2 exp tree 228
```

출력 예시:
```
return_max_long_v6new.362 [active] SQS=74.7
├── return_max_long_v6new.363
├── return_max_long_v6new.373
│   └── return_max_long_v6new.374
└── return_max_long_v6new.380
```

---

### `fithia2 exp info` — 상세 조회

```bash
fithia2 exp info 228
```

실험 ID, 메타데이터, journal 교차참조 결과(entry_id, sqs_score, rqs_score 등)를 한 화면에 표시한다.

---

### `fithia2 exp diff` — 두 실험 비교

```bash
fithia2 exp diff 228 242
```

`overrides`의 파라미터 변경, engine별 on/off 및 파라미터 변경을 표시한다.
메타데이터 필드(parent, created_at 등)는 diff에서 제외된다.

---

### `fithia2 exp promote` — 실험 승격

```bash
fithia2 exp promote 228 --alias my_best
```

status를 `promoted`로 변경. `--alias`로 별칭 추가 가능.

---

### `fithia2 exp retire` — 실험 은퇴

```bash
fithia2 exp retire 228
```

status를 `retired`로 변경.

---

### `fithia2 exp validate` — 스키마 검증

```bash
fithia2 exp validate
```

검사 항목:
- Pydantic 스키마 유효성
- `base_config` 파일 존재 여부
- `parent` 참조가 실제 존재하는지
- `experiment_name`이 파일명과 일치하는지
- `status` 값이 유효한지

---

### `fithia2 exp migrate` — 기존 파일 메타데이터 백필

기존 실험 파일에 메타데이터를 자동으로 추가한다. ID도 이 커맨드로 일괄 부여된다.

```bash
# 먼저 dry-run으로 확인
fithia2 exp migrate --dry-run

# 실제 적용
fithia2 exp migrate
```

자동 추론/처리 내용:
- `id` — 파일명 알파벳 순 기준으로 순차 정수 할당
- `version_family` — 파일명 regex에서 추출
- `parent` — description 텍스트 패턴 분석
  - `[v312+] ...` 또는 `v288 + ...` 형태에서 부모 버전 번호 추출
  - `Derivative of NAME` 형태에서 직접 추출
- `created_at` — git log에서 파일의 최초 커밋 시각 (없으면 파일 mtime)
- `generation` — parent chain에서 계산
- `changelog` — description에서 부모 참조 이후 텍스트 추출
- `created_by` — `"human"` (기존 파일 보수적 기본값)
- `status` — `"active"` (기존 파일 기본값)

---

### `fithia2 exp rebuild-index` — 인덱스 재생성

```bash
fithia2 exp rebuild-index
```

`configs/experiments/.index.json`을 강제 재생성한다. 일반적으로 자동 처리되지만, 파일을 직접 수정한 후 검색 결과가 stale하다면 수동으로 실행.

---

## `fithia2 paper`에서 ID 사용

`--config` 옵션에 숫자 ID, 실험 이름, 파일 경로 모두 사용할 수 있다.

```bash
# 세 가지 형태 모두 동일
fithia2 paper start --config 228 --name my_session
fithia2 paper start --config return_max_long_v6new.362 --name my_session
fithia2 paper start --config configs/experiments/return_max_long_v6new.362.json --name my_session

# backtest도 동일
fithia2 paper backtest --config 228 --year 2025
fithia2 paper backtest --config 228 --config 242 --year 2025
```

---

## AI 에이전트 워크플로우

### 새 실험 만들 때

```bash
# 1. 부모에서 스캐폴딩 (ID 또는 이름)
fithia2 exp create --parent 228 --name return_max_long_v6new.381 \
  --changelog "broad_oneoff engine risk 0.008→0.012"
# → ID 자동 할당, status=draft로 생성

# 2. JSON 수정 (overrides / strategy_engines 조정)
#    configs/experiments/return_max_long_v6new.381.json 편집

# 3. 백테스트 실행 (기존과 동일)
python -m apps.backtester.run --manifest configs/experiments/return_max_long_v6new.381.json --split train
python -m apps.backtester.run --manifest configs/experiments/return_max_long_v6new.381.json --split valid
python -m apps.backtester.run --manifest configs/experiments/return_max_long_v6new.381.json --split test

# 4. 결과 등록 — auto-sync가 draft→active로 자동 전환 + performance_summary 캐시
fithia2 record -e return_max_long_v6new.381 -H "..." -v better
```

### 기존 방식 유지 (JSON 직접 작성)

`fithia2 exp create` 없이 JSON을 직접 만들어도 된다. `id` 필드를 넣지 않으면 `fithia2 exp migrate`로 나중에 일괄 부여할 수 있다.

---

## status 전환 흐름

```
draft → active (백테스트 완료 후 auto-sync가 자동 전환)
      → promoted (fithia2 exp promote)
active → retired (fithia2 exp retire)
```

---

## 구현 파일

| 파일 | 역할 |
|------|------|
| `libs/backtest/experiments.py` | 핵심 라이브러리 (create, search, tree, diff, migrate, validate, index, resolve_experiment_name) |
| `apps/experiment/cli.py` | `fithia2 exp` CLI |
| `apps/paper_trader/cli.py` | `_resolve_config_path`: `--config`에서 ID/이름/경로 모두 지원 |
| `libs/backtest/domain.py` | `ExperimentManifest` 스키마 (메타데이터 필드 포함) |
| `libs/backtest/tracker.py` | `sync_official_manifests`: auto-sync 후 `performance_summary` 자동 업데이트, 리더보드에 ID 컬럼 추가 |
| `configs/experiments/.index.json` | 메타데이터 인덱스 캐시 (자동 관리) |
