[Docs] sample app, 10분 quickstart와 configuration reference 작성

[HuitaePark]

목적

처음 보는 Java/Spring 개발자가 10분 안에 Core 또는 Starter 경로 중 하나를 선택해 실행하고, TokenPilot이 무엇을 보장하며 무엇을 아직 보장하지 않는지 이해할 수 있는 문서를 만든다.

문서 정보 구조

1. 문제와 제품 경계

• 호출 전: token estimate, safe upper bound, context와 budget preflight
• 호출 후: provider actual usage를 통한 정산
• 동시 요청: reservation lifecycle로 over-admission 방지
• Spring AI 관측성과의 관계: provider 호출 관측은 Spring AI, admission/accounting 상태는 TokenPilot
• 현재 구현과 향후 Gateway 계획을 분리해 표기

2. Artifact 선택 가이드

경로	대상	의존성 경계
token-pilot-core	plain Java, framework-independent preflight	Spring/Spring AI 없음
token-pilot-starter	Spring Boot/Spring AI 통합	auto-configuration 포함

실제 group, artifact와 0.1.0 version은 #41 결과를 그대로 사용한다.

3. Core 10분 quickstart

• dependency 선언
• heuristic estimator 생성
• model/context policy 조회
• reserved output을 포함한 TokenBudget.check()
• fits/block 결과 처리
• heuristic의 exact=false, TEXT_ONLY scope와 safe upper bound 설명

4. Starter 10분 quickstart

• dependency와 repository 선언
• 최소 configuration
• fake provider 또는 사용자가 선택한 provider bean 연결
• preflight → provider call → actual usage 정산 흐름
• Actuator/Prometheus에서 TokenPilot metric 확인

5. Configuration reference

configuration metadata와 실제 default 값을 기준으로 다음을 표로 작성한다.

• property key
• type/default
• required 여부
• 적용 module
• 동시성·lifecycle 관련 의미
• metric/notification on-off
• 잘못된 값일 때의 failure mode

6. 운영 의미와 제한사항

• estimate와 actual usage를 구분
• cache read/create, reasoning은 total의 subset이라는 의미
• Money scale/rounding과 missing pricing 정책
• BLOCK 시 provider를 호출하지 않는 보장
• commit/release/reconciliation 상태와 unknown actual 처리
• metric tag cardinality 제한과 listener failure 격리
• exact BPE, streaming boundary와 Gateway 기능 중 MVP에 포함되지 않은 항목

구현 범위

• 루트 README의 소개, architecture, module 선택과 current/planned 표 갱신
• Core 및 Starter quickstart
• configuration reference와 metrics reference
• sample app 실행 및 문제 해결(runbook)
• #35와 #42의 검증된 snippet 재사용
• 링크와 code block이 오래되지 않게 문서 예제를 compile/test하는 방식 추가

검증 시나리오

• 새 임시 디렉터리에서 Core quickstart를 그대로 복사해 성공한다.
• Starter quickstart가 API key 없이 fake provider 경로로 성공한다.
• 문서의 property key/default가 configuration metadata와 일치한다.
• 문서의 metric 이름이 실제 meter와 일치한다.
• 아직 구현하지 않은 exact BPE, gateway routing 등을 현재 기능처럼 표현하지 않는다.
• 깨진 내부 링크와 잘못된 artifact 이름이 없다.

Acceptance criteria

• 독자가 10분 안에 두 진입점의 차이를 판단할 수 있다.
• Core와 Starter 각각 최소 한 개의 copy-paste 가능한 예제가 있다.
• 설정과 metric의 실제 이름/default/source가 명시된다.
• estimate, safe upper bound, actual usage와 reservation lifecycle의 의미가 설명된다.
• current limitation과 post-MVP 계획이 분리된다.
• [Test] Core와 token-pilot-starter 외부 consumer 검증 #42 external consumer와 동일한 artifact 좌표를 사용한다.

제외 범위

• 전체 API reference 자동 생성
• 모든 provider별 설정 튜토리얼
• 향후 Gateway 기능의 사용법
• 마케팅 사이트 제작

의존관계와 순서

구조는 미리 작성할 수 있으나 artifact 좌표는 #41, 실행 가능한 snippet은 #35와 #42, 운영 semantics는 #37~#40 완료 후 확정한다.

Source

• 30일 MVP — Week 4 문서/quickstart