DOCS/journey/plans/260316_llm_model_ssot_transition_계획.md

상위 원칙

• 0_VALUE Coding Principles
• 0_VALUE Infrastructure SSOT Principle
• workspace-config 루트기준 SSOT와 하드코딩 분산 문제 오픈
• 모델 SSOT 하드코딩 분산과 workspace-config 로컬이식 통합 리서치

LLM 모델 SSOT 전환 계획

상태

• planned

목표

• 주 LLM 모델 기본값을 workspace-config/runtime.env 중심으로 해석하도록 고정합니다.
• 과도기에는 최소 rb8001/.env까지만 수정하면 실제 기본 모델이 바뀌도록 맞춥니다.
• 예외적으로 API 요청에서 model을 명시하면 그 입력값만으로 실제 호출 모델이 바뀌게 합니다.
• 새 추상화 계층을 늘리지 않고 기존 LLMService 중심으로 우회 경로를 제거합니다.

범위

포함

• rb8001의 모델 기본값/직접 handler 생성/직접 Gemini SDK 호출/fallback 배열 정리
• skill-slack의 하드코딩 모델 문자열 정리
• 모델 변경 검증 체크리스트 고정

제외

• 새 provider registry 파일 추가
• 새 gateway 패키지 추가
• 새 request schema 계층 추가
• 서버 배포 작업 자체

파일별 변경 계약

1. 기본 경로 정리

• rb8001/app/services/llm/llm_service.py
  • 기본 모델 해석과 요청 모델 override 해석을 한 곳으로 모읍니다.
  • provider/model 선택은 이 서비스가 담당합니다.
• rb8001/app/core/config.py
  • DEFAULT_LLM_MODEL 설정 경로를 유지하되, 최종 해석 원천은 workspace-config/runtime.env로 둡니다.

2. 우회 경로 제거

• rb8001/app/services/llm/gemini_handler.py
  • GEMINI_MODEL env 우회 제거
• rb8001/app/router/llm_endpoint.py
  • 직접 GeminiHandler 생성 제거
• rb8001/app/services/coldmail_llm_classifier.py
  • 직접 genai.GenerativeModel(...) 생성 제거
• rb8001/app/services/ir_analyzer.py
  • 파일 내부 fallback 배열 제거 또는 중앙 정책으로 이동

3. 스킬 계층 정리

• skill-slack/app/services/digest.py
• skill-slack/app/services/action_extractor.py
• skill-slack/app/services/summarizer.py
  • 하드코딩 모델 문자열을 설정값 또는 API 입력값으로 승격합니다.
• skill-slack/app/core/config.py
  • 필요 최소한의 기본 모델 설정만 추가 검토합니다.

정책 판단

1. 유지 가능한 정책

• API 요청에서 model override 허용
• skill-slack의 skill level별 동작 차이 자체는 유지 가능

2. 제거해야 할 하드코딩

• GEMINI_MODEL 별도 env 우회
• 파일별 fallback 배열
• router/service의 직접 handler 생성
• 서비스 파일 안의 직접 Gemini/OpenAI SDK 생성
• skill-slack의 고정 모델 문자열

3. 추가하지 않을 것

• 새 manager/registry/wrapper 계층
• 새 fallback registry 파일
• 새 provider enum 파일

검증 체크리스트

1. 기본 모델 변경 검증

• workspace-config/runtime.env의 DEFAULT_LLM_MODEL 변경 시 기본 호출 모델이 바뀝니다.
• 과도기에는 최소 rb8001/.env까지만 함께 수정하면 기본 호출 모델이 바뀝니다.
• 그보다 더 많은 파일 수정을 요구하지 않습니다.

2. API 입력 override 검증

• LLMRequest.model 또는 동등한 API 입력 모델값을 명시하면 해당 요청의 실제 호출 모델이 바뀝니다.
• 호출부는 provider SDK를 직접 고르지 않고 LLMService만 경유합니다.

3. 우회 제거 검증

• GEMINI_MODEL env 우회가 제거됩니다.
• GeminiHandler(...) 직접 생성이 router/service에서 사라집니다.
• genai.GenerativeModel(...) 직접 생성이 공용 경로 밖에서 사라집니다.
• ir_analyzer.py의 파일 내부 fallback 배열이 제거되거나 중앙 정책으로 이동합니다.
• skill-slack의 하드코딩 모델 문자열이 제거됩니다.

닫힘 조건

1. 사용자가 "주 모델을 --로 바꾸자"라고 했을 때 기본 수정 지점이 workspace-config/runtime.env로 답됩니다.
2. 과도기에도 workspace-config/runtime.env와 rb8001/.env까지만 수정하면 됩니다.
3. API 입력 모델명으로 요청 단위 override가 가능합니다.
4. 리서치 문서에 적힌 직접 우회 경로가 실제 코드에서 제거됩니다.
5. 닫힘 선언은 worklog에서만 합니다.