본문으로 건너뛰기

JunkBox libs/shared-ai 가이드

1. 역할​

  • shared-ai는 JunkBox 앱의 공통 AI provider 연동 라이브러리임.
  • provider 어댑터, 기능별 라우팅, direct·graph runner, prompt·graph registry, AI 통신 예외 정규화, Hub AI usage log writer를 제공함.
  • Chess 앱은 실시간 AI 착수나 graph runner를 사용하지 않음. Chess 코칭은 Codex가 Chess SQLite에 별도 반영하는 흐름임.

2. 책임 경계​

  • provider 호출과 기능별 model 선택은 shared-ai 책임임.
  • 라우팅 정책 원본은 Hub master-data의 ai-routing.yml임.
  • Hub 외부 앱의 usage log 기록은 HubApiAiUsageLogWriter가 Hub internal API로 전달함. 외부 앱은 Hub SQLite를 직접 열지 않음.
  • 개발 문서 벡터 캐시 유틸은 런타임 요청 경로와 분리되어 있으며, scripts/.env.ai와 scripts/sync_dev_docs.py, scripts/search_dev_docs.py가 사용함.

3. 사용 규칙​

  • 앱은 provider를 직접 생성하지 않고 shared-ai runner 또는 service 경계를 사용함.
  • provider/model은 앱 코드가 아닌 route key와 routing YAML이 결정함.
  • 사용자 요청 처리용 AI 런타임과 개발 문서 검색·동기화는 서로 다른 설정과 실행 경로를 사용함.
  • Codex가 직접 SQLite에 코칭 데이터를 반영하는 작업은 shared-ai provider 호출이나 usage log 기록 대상이 아님.

4. 관련 문서​

  • 공통 설정과 인증은 docs/junkbox/libs/guide-lib-shared-core.md를 따름.
  • Chess 코칭 반영 계약은 docs/junkbox/apps/guide-apps-chess-api.md를 따름.