[Example/Test] Spring AI 없는 plain-Java Core preflight 예제

[HuitaePark]

목적

Week 2의 estimator → model lookup → context admission 흐름을 Spring AI 없이 public Core API만으로 실행한다. 예제 자체가 scope 계약의 사용법을 보여주며, UTF-8 heuristic TEXT_ONLY 결과를 전체 요청 허용으로 잘못 소개하지 않는다.

현재 코드 근거

• token-pilot-core runtime dependency는 현재 없다.
• 저장소에는 Spring Boot 기반 token-pilot-sample-app만 있고 plain-Java preflight 예제가 없다.
• 공개 artifact의 clean-environment 소비 검증은 #42가 담당하므로 이 이슈와 중복하지 않는다.

목표 시나리오

plain String
→ HeuristicTokenEstimator
→ HEURISTIC / TEXT_ONLY TokenCountResult
→ ModelRegistry canonical lookup + tokenizer compatibility
→ TokenBudget.check()
→ INDETERMINATE 또는 EXCEEDS와 bounded reason 확인

필수 예제 결과:

1. 짧은 문자열 + 충분한 context: INDETERMINATE, fits=false
   • 문자열 자체는 window 안이지만 role/tool/schema/provider framing을 포함하지 않았기 때문이다.
2. 매우 큰 문자열 또는 큰 reserved output: EXCEEDS, fits=false
   • TEXT_ONLY 보수적 admission 값만으로 이미 window를 넘는다.

예제가 FITS를 보여줄 필요가 있다면 heuristic 결과의 scope만 변경하지 않는다. 요청 전체를 포함하는 별도 REQUEST-scoped test fixture/estimator와 compatibility 근거를 명시해야 하며, MVP plain-string 예제의 필수 범위는 아니다.

구현 범위

• public API만 사용하는 compile/run 가능한 plain-Java 예제
• 예제 코드를 테스트에서 실행해 API drift 방지
• TEXT_ONLY INDETERMINATE와 EXCEEDS 사례 각 1개
• canonical model id, estimator id/version, tokenizer compatibility와 reason 출력
• Core runtime classpath에서 다음 dependency 부재 자동 검증
  • Spring AI
  • Spring Boot
  • Micrometer
  • Reactor
• README/quickstart가 재사용할 최소 코드와 예상 출력
• repository 내부 예제는 project dependency를 사용할 수 있음

예제는 Spring AI, Spring Boot, Micrometer와 Reactor 타입을 import하지 않고 internal 구현 클래스를 직접 생성하지 않는다. 필요한 기본 구현은 public constructor 또는 의도된 public factory로 얻는다.

테스트 시나리오

• ASCII 또는 한글 문자열을 heuristic으로 계산한다.
• 결과가 HEURISTIC/TEXT_ONLY이며 estimator descriptor를 포함한다.
• versioned model/alias가 canonical definition으로 조회된다.
• model과 estimator compatibility를 검사한다.
• 짧은 TEXT_ONLY 입력은 INDETERMINATE/fits=false다.
• 큰 입력 또는 reserved output은 EXCEEDS/fits=false다.
• 예제가 TEXT_ONLY 값을 REQUEST로 덮어쓰지 않는다.
• public API만 사용하고 framework import가 없다.
• Core runtime dependency graph가 framework-independent다.
• ./gradlew :token-pilot-core:test 또는 별도 example task로 실행 가능하다.

Acceptance criteria

• plain-Java preflight 예제가 compile/run된다.
• estimator, registry와 상태 기반 context admission의 최소 흐름을 보여준다.
• heuristic TEXT_ONLY를 전체 요청의 fits=true로 출력하지 않는다.
• INDETERMINATE와 EXCEEDS의 차이와 reason을 예상 출력에 설명한다.
• internal 구현과 Spring AI 타입을 사용하지 않는다.
• Core runtime dependency 검사가 자동화된다.
• [Docs] sample app, 10분 quickstart와 configuration reference 작성 #43 quickstart가 동일한 안전한 예제를 재사용할 수 있다.

제외 범위

• publish된 Maven artifact 외부 소비 — [Test] Core와 token-pilot-starter 외부 consumer 검증 #42
• Starter consumer
• Maven Central/GitHub Packages 검증
• Spring AI Advisor와 autoconfiguration
• REQUEST framing 구현 — [Spring AI] Request/Usage Adapter와 Advisor E2E 연결 #39

의존관계와 순서

#30~#33 이후 Week 2 마지막 smoke issue로 진행한다. #34는 필수 선행이 아니다.

Source

• 30일 MVP — core-only sample과 framework independence