# 아리(Ari) — AI Life OS

일·삶을 한곳에서 관리하는 한국어 AI 개인비서 **아리**의 MVP.
핵심 철학: **"적을 때는 분류하지 않는다 — 분류·배치·자동화는 아리가."**
사용자는 *읽고 탭 한 번*, 나머지는 아리가 합니다.

MVP 3페이지 — **작업(/tasks) · 인박스(/inbox) · 대시보드(/dashboard)**.
나머지 10개 내비 항목은 "준비 중" 플레이스홀더(내비 일관성 유지).

```
workspace/
├─ frontend/   Next.js 16 (App Router, TypeScript) · next-themes · SWR · Vitest · Playwright
├─ backend/    FastAPI · SQLite(SQLModel·Alembic) · Ollama 추상화(모델 비종속, heuristic 폴백)
├─ dev/        개발 문서 (overview.md + phase-0~6)
└─ design-reference/  원본 프로토타입 (픽셀 충실 재현 기준)
```

## 스택

| 레이어 | 선택 |
|---|---|
| 프론트엔드 | Next.js(App Router) + React 19 + TypeScript, 순수 CSS 변수 토큰, next-themes 테마 |
| 백엔드 | Python + FastAPI + SQLite(SQLModel + Alembic) |
| LLM | 로컬 Ollama + `LLMProvider` 추상화(모델 비종속, `OLLAMA_MODEL` 주입). 미가용 시 `HeuristicProvider` 폴백 |
| 테스트 | pytest(백엔드) / Vitest·Playwright·axe(프론트) |

## 빠른 시작

### 0) 사전 설치
Node ≥ 20 · pnpm · Python ≥ 3.11 · uv · (선택) Ollama

### 1) 의존성 + 환경변수 + 시드

```bash
make install                                  # frontend(pnpm) + backend(uv) 의존성

cp backend/.env.example backend/.env          # 필요 시 OLLAMA_MODEL 등 수정
cp frontend/.env.local.example frontend/.env.local

cd backend && uv run alembic upgrade head && uv run python -m app.seed && cd ..
```

### 2) (선택) Ollama — 모델 비종속

```bash
ollama serve &
ollama pull <설치할_모델>      # backend/.env 의 OLLAMA_MODEL 과 일치시킬 것 (특정 모델 강제 아님)
```

> Ollama가 없거나 느리면 자동으로 규칙 기반(HeuristicProvider)으로 분류가 계속됩니다.
> `LLM_PROVIDER=heuristic` 로 강제할 수도 있습니다(테스트·오프라인).

### 3) 실행

```bash
make dev            # backend :8000 + frontend :3000 (또는 scripts/dev.sh)
# http://localhost:3000 → / 는 /dashboard 로 리다이렉트
```

### 4) 스모크 / 테스트

```bash
make health         # /api/health, /api/llm/health
make test           # pytest + vitest
make lint           # ruff + eslint

# E2E (백엔드는 리셋 허용 + heuristic 으로 기동해야 federation/a11y/responsive 전부 통과)
ARI_ALLOW_TEST_RESET=1 LLM_PROVIDER=heuristic uv run --directory backend uvicorn app.main:app --port 8000 &
cd frontend && pnpm exec playwright test
```

## 시드 초기화(데모 리셋)

```bash
cd backend && rm -f ari.db && uv run alembic upgrade head && uv run python -m app.seed
# 또는 E2E용(가드): ARI_ALLOW_TEST_RESET=1 로 기동 후
curl -X POST http://localhost:8000/api/_test/reset
```

## 환경변수

| 변수 | 위치 | 기본값 | 설명 |
|---|---|---|---|
| `OLLAMA_HOST` | backend `.env` | `http://localhost:11434` | Ollama HTTP 엔드포인트 |
| `OLLAMA_MODEL` | backend `.env` | (설치 모델 주입) | 분류용 모델명 — **비종속**(env로만 지정) |
| `LLM_PROVIDER` | backend env | `auto` | `auto`\|`ollama`\|`heuristic` (테스트/E2E는 `heuristic`) |
| `LLM_TIMEOUT` | backend env | `30` | 분류 1건 타임아웃(초). 초과 시 heuristic 폴백 |
| `DATABASE_URL` | backend `.env` | `sqlite:///./ari.db` | DB 경로 |
| `FRONTEND_ORIGIN` | backend `.env` | `http://localhost:3000` | CORS 허용 출처(콤마구분) |
| `ARI_ALLOW_TEST_RESET` | backend env | (미설정) | `1`이면 `/api/_test/reset` 허용(E2E 전용, 운영 403) |
| `NEXT_PUBLIC_API_BASE` | frontend `.env.local` | `http://localhost:8000` | 프론트가 호출할 백엔드 베이스 |

## 연합(federation) 흐름 — MVP의 핵심

1. **인박스**에 한 줄 적기 → 아리가 즉시 **작업/일정/아이디어 + 업무/개인 + 행선지 프로젝트**로 분류.
2. **확인(탭 한 번)** → 실제 `task`로 실체화(`materialized_task_id` 연결).
3. **작업 페이지**의 `개인 › 여행 — 한국`에 등장 — 개인 일도 숨기지 않고 업무 작업과 *같은 트리에서 필터로만* 구분.
4. 작업 데이터로 **리스크 레이더**(지연·쏠림·의존성)가 자동 재계산, **대시보드**가 작업/인박스/결재함을 집계.

## 데모 스크립트(약 3분)

1. 대시보드 진입 — 아침 브리핑/일정/할 일/목표/결재함·인박스 요약.
2. 인박스에서 `다음 주에 한국 놀러가는 비행기 티켓 사기` 캡처 → 자동 분류(작업/개인 › 여행 — 한국 + 이유).
3. "좋아요, 그렇게 해줘" → 실체화.
4. 작업 → 개인 필터 → 여행 — 한국에 등장(개인도 숨기지 않음).
5. 업무 필터 → 리스크 레이더 "분기 리포트가 오늘 마감인데 진행 중".
6. 대시보드 복귀 → 요약 반영.

## 문서

개발 문서 진입점은 `dev/overview.md`. 빌드 순서: `phase-0` → `phase-1` → `phase-2` → (`phase-3` 작업 → `phase-4` 인박스 → `phase-5` 대시보드) → `phase-6` 통합.