life-helper/docs/design/215-gemma-frame-suggest/fn-model_lifecycle.md

함수 설계서: ModelLifecycle + LlmService (#215)

부모 설계서: ./README.md · 상태: Approved (v0.2.0) 작성: [AI] Architect · 구현: app/lib/data/ai/model_lifecycle.dart, llm_service.dart, gemma_llm_service.dart (stub) · 테스트: app/test/data/ai/model_lifecycle_test.dart + app/test/state/model_download_controller_test.dart (총 10 케이스) · 동기화 노트: GemmaLlmService 는 모든 메서드가 UnimplementedError 를 던지는 stub 상태 — OQ-1 (실 모델 URL+SHA) 해결 시 활성. v1 런타임은 MockLlmService 가 llmServiceProvider 에 주입.

본 문서는 모델 수명주기와 추론 인터페이스를 묶어 다룬다. 모두 I/O 경계 — flutter_gemma + 파일시스템 + 네트워크 + 네이티브 메모리.

---

§A. LlmService (추상 인터페이스)

1. 시그니처

abstract class LlmService {
  Future<void> load();
  Future<void> unload();
  bool get isLoaded;
  Future<Map<String, dynamic>> generateStructured(
    String prompt,
    Map<String, dynamic> schema,
  );
}

2. 책임 (1줄)

LLM 백엔드를 도메인에 노출하는 단일 인터페이스. 구현체는 GemmaLlmService (flutter_gemma) 와 MockLlmService (테스트).

3. 입력 / 출력

메서드	입력	출력
load()	(구현체 내부에서 path 결정)	void. 모델 메모리 상주
unload()	none	void. 메모리 회수
isLoaded	none	bool
generateStructured(prompt, schema)	prompt string, function calling JSON schema	parsed JSON map

4. 부수효과

• load: 모델 파일 read + 네이티브 메모리 할당.
• unload: 네이티브 메모리 해제.
• generateStructured: 네이티브 추론 호출. prompt 본문은 로그 X (privacy).

5. 인터페이스 계약 (구현체가 반드시 지켜야 할 것)

• load 가 throw 하지 않고 정상 종료하면 isLoaded == true.
• generateStructured 호출 시 !isLoaded → throw StateError("not loaded").
• generateStructured 응답은 schema 의 parameters 와 일치 — 위반 시 throw FormatException.
• unload 는 idempotent. !isLoaded 상태에서 호출해도 noop.
• timeout 은 호출자가 .timeout(...) 로 부여. 본 인터페이스는 별도 타임아웃 처리 X.

6. 추적성

• 인수조건: #215 AC-6 (응답), AC-9 (graceful — throw 종류 명세).
• 관련 ADR: ADR-0003.

---

§B. GemmaLlmService (flutter_gemma 구현체)

1. 시그니처

class GemmaLlmService implements LlmService {
  GemmaLlmService({
    required this.modelPath,
    FlutterGemma? gemma,
  });
  // ...
}

2. 책임 (1줄)

flutter_gemma 를 호출해 Gemma 4 E2B Q4_0 모델을 디스크에서 로드하고 function calling 응답을 받는다.

3. 입력

파라미터	타입	제약/검증	설명
modelPath	String	절대 경로, 파일 존재	ModelLifecycle.checkAvailability 가 ready 일 때만 전달
gemma	FlutterGemma?	nullable (DI 용)	테스트 시 mock 주입 가능

4. 출력

• load: void. 내부 _loaded = true.
• generateStructured: parsed JSON (function calling 의 arguments).
• unload: void. 내부 _loaded = false.

5. 동작 / 알고리즘

load:
  1. if _loaded: return  (idempotent)
  2. gemma = FlutterGemma()
  3. await gemma.init(modelPath: modelPath, backend: 'litert_lm_android')
     - flutter_gemma 의 정확한 API 는 패키지 문서 확정 후 (OQ-1)
  4. _loaded = true
  catch:
    - OOM → throw StateError("OOM during load")
    - File not found → throw FileSystemException
    - 기타 → rethrow

generateStructured(prompt, schema):
  1. if !_loaded: throw StateError("not loaded")
  2. response = await gemma.generateWithFunctionCalling(
       prompt: prompt,
       functions: [
         {"name": "emit_frame_candidates", "parameters": schema},
       ],
     )
  3. if response.functionCall == null:
       throw FormatException("no function call")
  4. return response.functionCall.arguments  // already parsed Map
  catch:
    - FormatException → rethrow (호출자가 결정)

unload:
  1. if !_loaded: return
  2. await gemma.close()
  3. _loaded = false

6. 에러 & 실패 모드

조건	처리	반환/예외
모델 파일 없음	rethrow	FileSystemException
OOM	catch + 변환	StateError("OOM")
init crash (native)	rethrow	Exception (구체 클래스는 flutter_gemma 정의)
function call 없는 응답	throw	FormatException
schema 위반 응답	flutter_gemma 가 거부 + retry → 최종 실패 시 FormatException	(패키지가 처리)

7. 엣지케이스

• 동시에 두 번 load() 호출 → idempotent. 두 번째는 noop.
• load() 진행 중 unload() 호출 → 첫 load 완료 후 unload (Lock 사용 권장).
• 추론 도중 앱 background → flutter_gemma 가 native 측 isolate 로 계속. UI 가 result 받음.
• 추론 도중 unload 호출 → race condition. v1 은 _inferring = true flag 로 unload 지연.

8. 복잡도 / 성능

• load: cold 1–3초 (디스크 → RAM). 1.5GB read.
• generateStructured: cold (모델 첫 호출) 1–2초, warm 0.5–2초.
• unload: < 100ms.
• 메모리: 모델 상주 ≈ 1.5GB.

9. 의존성

• flutter_gemma 패키지 (latest, pubspec.lock 동결).
• dart:async.

10. 테스트 케이스

• 정상 load → generate → unload: dummy 1KB fixture 모델 + mock FlutterGemma 주입.
• !loaded 상태 generateStructured: throw StateError.
• load idempotent: 두 번 호출 → 두 번째 noop, isLoaded == true.
• unload idempotent: 두 번 호출 → 두 번째 noop.
• OOM 시뮬레이션: mock 이 OOM throw → StateError 변환.
• function call 없는 응답: mock 응답 → FormatException.
• schema 일치 응답: mock 응답 → arguments map 반환.

11. 추적성

• 인수조건: #215 AC-6, AC-7, AC-9.
• 관련 ADR: ADR-0003 (flutter_gemma + LiteRT-LM Android).
• Open Question: OQ-1 (모델 URL), OQ-4 (timeout).

---

§C. ModelLifecycle.checkAvailability

1. 시그니처

Future<ModelAvailability> checkAvailability();

enum ModelAvailability { ready, missing, corrupt, downloading }

2. 책임 (1줄)

디스크의 모델 파일 존재 + SHA-256 무결성 + meta_kv 상태를 종합해 가용성을 결정한다.

3. 입력 / 출력

• 입력: none (내부에서 MetaKvDao + path_provider 사용).
• 출력: ModelAvailability enum.

4. 동작 / 알고리즘

1. opt_in = await metaKv.get('ai_opt_in')
   - 'false' or null → return missing (사용자가 끔)

2. state = await metaKv.get('ai_download_state')
   - 'downloading' or 'paused' → return downloading

3. path = await metaKv.get('ai_model_path')
   - null → return missing

4. file = File(path)
   - !exists → return missing (외부 삭제 시나리오)

5. expectedSha = await metaKv.get('ai_model_sha256')
   - null → return corrupt

6. actualSha = sha256.convert(await file.readAsBytes()).toString()
   - != expectedSha → return corrupt

7. return ready

실제 1.5GB 파일 SHA-256 매번 계산은 비용 큼. v1 은 앱 시작 시 1회만 검증 + 결과 캐시. 매번 호출 시 캐시 hit. v1.1 에서 마지막 검증 시각 + invalidation 정책 검토.

5. 에러 & 실패 모드

조건	처리	반환
meta_kv I/O 실패	catch	missing
file read 실패 (권한)	catch	corrupt
SHA 계산 도중 OOM (희박)	catch	corrupt

6. 복잡도 / 성능

• 첫 호출 (해시 계산): 1.5GB read + SHA-256 → 5–15초. 앱 시작 시 백그라운드 isolate 에서 수행.
• 이후 캐시: < 5ms.

7. 의존성

• MetaKvDao (#204), path_provider, crypto (SHA-256), dart:io.

8. 테스트 케이스

• ready: 올바른 path + 일치 SHA → ready.
• missing (opt_out): ai_opt_in = false → missing.
• missing (path null): ai_model_path = null → missing.
• missing (file 없음): path 는 있으나 file 부재 → missing.
• downloading: state = paused → downloading.
• corrupt: SHA mismatch → corrupt.

9. 추적성

• 인수조건: #215 AC-4 (무결성), AC-9 (graceful).

---

§D. ModelLifecycle.download

1. 시그니처

Stream<DownloadProgress> download({String? modelUrl});

class DownloadProgress {
  final int bytesReceived;
  final int totalBytes;       // -1 if unknown
  final DownloadState state;  // downloading | paused | completed | failed
  final String? errorMessage;
}

2. 책임 (1줄)

Gemma 4 E2B Q4_0 모델 파일을 HTTP Range 로 백그라운드 다운로드 + 일시정지/재개 + SHA-256 검증.

3. 입력

파라미터	타입	제약/검증	설명
modelUrl	String?	기본값 = config 상수 (OQ-1)	테스트 / 추후 swap 시 override

4. 출력

• Stream<DownloadProgress> — 진행률 broadcast.
• 부수효과: 디스크 파일 write, meta_kv 4개 키 update.

5. 동작 / 알고리즘

1. tempPath = await pathProvider.getApplicationSupportDirectory() + '/gemma4_e2b_q4.bin.tmp'
2. finalPath = without '.tmp'
3. existingBytes = File(tempPath).existsSync() ? File(tempPath).lengthSync() : 0
4. await metaKv.set('ai_download_state', 'downloading')
5. await metaKv.set('ai_download_bytes', existingBytes.toString())

6. yield DownloadProgress(existingBytes, -1, downloading)

7. response = await http.get(modelUrl, headers: {'Range': 'bytes=$existingBytes-'})
   - 200 (full) or 206 (partial)

8. totalBytes = existingBytes + response.contentLength

9. stream = response.stream
10. for each chunk in stream:
    - if pauseRequested: break (state='paused', save bytes)
    - if cancelRequested: delete tempPath, state='failed', break
    - file.writeAsBytes(chunk, mode: append)
    - existingBytes += chunk.length
    - await metaKv.set('ai_download_bytes', existingBytes.toString())
    - yield DownloadProgress(existingBytes, totalBytes, downloading)

11. if completed:
    - rename tempPath → finalPath
    - actualSha = sha256(finalPath)
    - if actualSha != EXPECTED_SHA:
        - delete finalPath, state='failed', yield failed
        - return
    - await metaKv.set('ai_model_path', finalPath)
    - await metaKv.set('ai_model_sha256', actualSha)
    - await metaKv.set('ai_download_state', 'completed')
    - yield DownloadProgress(totalBytes, totalBytes, completed)

12. catch network error:
    - retry 3회 exponential backoff (1s, 2s, 4s)
    - 최종 실패 → state='paused' (자동 재개 가능), yield failed with message

EXPECTED_SHA 는 모델 파일의 알려진 hash. OQ-1 에서 URL + SHA 함께 확정.

6. 에러 & 실패 모드

조건	처리	반환 (stream emit)
네트워크 끊김	retry 3회 → paused	failed (자동 재개 가능 표시)
디스크 공간 부족	catch IOException	failed ("저장 공간 부족")
SHA mismatch	파일 삭제 + state failed	failed ("다운로드 손상")
HTTP 416 (Range 위반)	0 부터 재시작	downloading from 0
사용자 취소	tempPath 삭제 + meta_kv clear	failed ("취소됨")
사용자 일시정지	tempPath 보존 + state=paused	paused

7. 엣지케이스

• 다운로드 완료 직전 앱 종료 → tempPath 만 존재 (rename 미실행). 재시작 시 checkAvailability = downloading 상태로 인식 → 재개 시 nearly complete.
• 두 번 동시 호출 → v1 은 lock 으로 단일 인스턴스 보장.
• WiFi → cellular 전환 — 본 함수는 신경 X. Settings 의 "WiFi only" 토글이 별도 차단 (OQ-3).

8. 복잡도 / 성능

• 시간: 1.5GB @ 50Mbps = 약 4분. WiFi 200Mbps = 약 1분.
• SHA 검증: 5–15초.
• 메모리: 스트림 chunk 만 (≤ 64KB).

9. 의존성

• http 또는 dio (range request 지원).
• path_provider, crypto, dart:io.
• MetaKvDao.

10. 테스트 케이스

• fresh download (small fixture): mock HTTP server 가 1KB 응답 → completed, file 존재, SHA 매치.
• resume: 512B 다운로드 후 pause → 재개 시 Range=512- 요청 → completed.
• SHA mismatch: mock 이 잘못된 byte 전송 → failed + file 삭제.
• network error → retry → success: mock 이 첫 2번 throw, 3번째 OK → completed.
• cancel: 진행 중 cancel → tempPath 삭제 + meta_kv clear.
• pause + 앱 재시작 시뮬레이션: bytes 보존 → 다시 download() 호출 시 Range header.
• HTTP 416: mock 이 416 → 0부터 재시작.

11. 추적성

• 인수조건: #215 AC-3 (일시정지/재개/취소), AC-4 (무결성).
• Open Question: OQ-1 (URL), OQ-3 (cellular).

---

§E. 통합 점검

• LlmService 인터페이스만 도메인에 노출. 도메인 (suggest_frame.dart) 은 flutter_gemma 를 import 하지 않는다 (I/O ↔ 순수 경계).

• ModelLifecycle.purge (단순 함수, fn 분리 안 함):

  1. await unload() (혹시 로드 중)
  2. path = meta_kv.get('ai_model_path')
  3. if path != null: File(path).delete()  // idempotent
  4. meta_kv.delete(['ai_model_path', 'ai_model_sha256', 'ai_download_state', 'ai_download_bytes'])
  5. return freedBytes
  

• 모든 메서드는 graceful — suggestFrame 호출 흐름에서 모델 로드 실패 / 다운로드 실패 시 throw 하지 않고 호출자가 [] 빈 결과를 반환받도록 한다. UI 가 사용자 메시지 결정 (AC-9 graceful degradation 보장).