life-helper/docs/reference/260-in-app-tool-calling.md

# Reference: In-app tool calling (#260, v0.4.0)

> **상태**: 구현 후 동기화 · **추적성** — Redmine #260 · 설계서: [docs/design/260-gemma-tool-calling/](../design/260-gemma-tool-calling/) · ADR-0005 · 태그 `v0.4.0` (commit `7037b9e`)
>
> 본 문서는 v0.4.0 의 **실제 코드 사양**이다. 설계 의도/대안은 설계서·ADR 을 참조. 본 기능은 v0.3.0 의 AI 프레임 제안 ([215-ai-frame-suggest.md](215-ai-frame-suggest.md)) 위에 multi-turn tool calling 을 얹은 것이다.

## 1. 모듈 지도

```
lib/
  ai/tools/
    tool_definition.dart      — ToolDefinition / ToolHandler / ToolDeps
    tool_envelope.dart        — ToolResult sealed (Ok/Err/Cancelled) + encodeToolResult (2KB cap)
    tool_registry.dart        — ToolRegistry.defaults() + 6 tool 모음
    tool_dispatcher.dart      — 라우팅 + JSON-schema 검증 + ConfirmGate 통합
    confirm_gate.dart         — destructive 호출 시 AlertDialog
    catalog_tools.dart        — search_catalog, query_protocol (read-only)
    habit_tools.dart          — add_habit (destructive), list_active_habits
    tracker_tools.dart        — log_tracker_entry (destructive), get_streak
  data/ai/
    llm_service.dart          — LlmChatSession 추상 + LlmChatEvent sealed + MockLlmChatSession
    gemma_llm_service.dart    — _GemmaChatSession (flutter_gemma 0.16.5 + ToolChoice.auto)
  state/
    chat_providers.dart       — ChatSessionController + kChatMaxTurns / kChatSoftHistoryLimit
  ui/screens/
    chat_screen.dart          — AI 코치 화면 + _kToolKoreanLabels
```

## 2. 도메인 모델

### `ToolDefinition` (`lib/ai/tools/tool_definition.dart`)
```dart
class ToolDefinition {
  final String name;                         // 'search_catalog'
  final String description;                  // 모델이 보는 한국어 설명
  final Map<String, dynamic> parametersSchema; // draft-07 JSON Schema Map 리터럴
  final bool isDestructive;                  // true → ConfirmGate 의무
  final ToolHandler handler;                 // Future<ToolResult> Function(args, deps)
  final String Function(Map<String, dynamic>)? summarize; // confirm 모달 본문
}
```

### `ToolResult` (sealed)
```dart
sealed class ToolResult { Map<String, dynamic> toJson(); }
final class ToolOk extends ToolResult { final Map<String, dynamic> data; }
final class ToolErr extends ToolResult { final String code; final String reason; }
final class ToolCancelled extends ToolResult {}
```

`toJson()` 디스크리미네이터:
- ok      → `{'status': 'ok', 'data': {...}}`
- error   → `{'status': 'error', 'code': '...', 'reason': '...'}`
- cancel  → `{'status': 'cancelled', 'reason': 'user did not confirm'}`

### `LlmChatEvent` (sealed)
```dart
sealed class LlmChatEvent {}
final class LlmTextChunk extends LlmChatEvent { final String text; }
final class LlmFunctionCall extends LlmChatEvent {
  final String name;
  final Map<String, dynamic> args;
}
```

## 3. 등록된 도구 6개

| 이름 | 종류 | parametersSchema (required) | 반환 (ok) |
|---|---|---|---|
| `search_catalog` | read-only | `category?`, `keyword?`, `limit?` (1~10) | `{count, items:[{id,title,category,summary}]}` |
| `query_protocol` | read-only | `id` | kind 별 필드 (`protocol` / `break` / `diet`) |
| `list_active_habits` | read-only | — | `{count, build_count, break_count, build_quota_remaining, break_quota_remaining, items[]}` |
| `get_streak` | read-only | `habit_id` | `{current_streak, longest_streak, done_count_30d, done_count_phase42, tier, never_miss_twice_broken}` |
| `add_habit` | **destructive** | `protocol_id`, `frame_level`, `framed_text`, `anchor_when?`, `anchor_after_what?`, `dose_text?` | `{habit_id, title, type, frame_level}` |
| `log_tracker_entry` | **destructive** | `habit_id`, `value`, `date?`, `note?` | `{entry_id, habit_id, date, value}` |

### R 규칙 enforce (핸들러 책임, ADR-0005 §D-2)

| R 규칙 | 위치 | ToolErr code |
|---|---|---|
| R3 (build ≤3 / break ≤1) | `_addHabitHandler` → `judgeActiveHabitQuota` | `r3_quota` |
| R5 (체크 (habit,date) 중복) | `_logTrackerEntryHandler` 핸들러 레벨 dedup | `duplicate` |
| R7 (회피 키워드) | `_addHabitHandler` → `detectAvoidanceKeywords(framePatterns)` | `r7_avoidance` |
| R8 (build XOR break protocol_id) | `HabitDao.insertWithVariants` assert → catch | `r8_xor` |

R1/R2/R4/R6/R9/R10 는 현재 본 surface 의 직접 enforce 범위 아님. R9/R10 (minimum variant) 는 UI 흐름에서 별도 관리 — 후속 이슈.

## 4. 멀티턴 루프

`ChatSessionController.userTurn(text, context)` — `lib/state/chat_providers.dart`.

```
1. 사용자 메시지 append + isStreaming=true
2. (lazy) llm.load() + _session = llm.startChat(tools)
3. nextStream = sendUser(trimmed)
4. for turn in 0..kChatMaxTurns:
     events = nextStream()
     if events.last is LlmTextChunk only:
       모델 자연어 응답 append → return
     if events has LlmFunctionCall(toolCall):
       result = dispatcher.dispatch(toolCall.name, toolCall.args, context, deps)
       messages append ToolCallChatMessage(name, args, result)
       capped = jsonDecode(encodeToolResult(result))         ← AC-9 2KB cap
       nextStream = sendToolResult(name, capped)
5. else: error('도구 호출 루프가 너무 길어 중단했습니다.')
```

- `kChatMaxTurns = 4` (안전 cap, ADR-0005 §C).
- `kChatSoftHistoryLimit = 8` — 사용자 turn 누적 8 회 도달 시 SystemChatMessage 한 줄 추가 ("대화가 길어졌어요").
- `LlmChatSession.sendToolResult` 의 `result` 는 항상 capped Map (`encodeToolResult` round-trip 결과).

## 5. ToolDispatcher 게이트

`lib/ai/tools/tool_dispatcher.dart` — `dispatch` 는 절대 throw 하지 않는다.

```
1. registry.byName → null 이면 ToolErr('unknown_tool')
2. _validateArgs(schema, rawArgs) → 실패 시 ToolErr('validation', ...)
3. tool.isDestructive 라면:
     confirmContext==null → ToolCancelled
     ConfirmGate.show(ctx, tool, rawArgs) == false → ToolCancelled
4. try handler(rawArgs, deps) — 예외 → ToolErr('handler_error', ...)
```

`_validateArgs` 의 지원 타입: `string` / `integer` / `number` / `boolean` / `object` / `array`. 미선언 키는 허용 (모델 환각 허용 — 핸들러가 무시).

## 6. ConfirmGate UI

`lib/ai/tools/confirm_gate.dart` — `showDialog<bool>` 기반 `AlertDialog`.

- 제목: `이 작업을 수행할까요?`
- 본문: `tool.description` + summary box (`tool.summarize?.call(args)` 또는 JSON fallback)
- 액션: `취소` (TextButton, false) / `수행` (FilledButton autofocus, true)
- `barrierDismissible: true` — 바깥 탭 = 취소
- 좁은 화면 대응: content 를 `SingleChildScrollView` 로 감쌈, summary box `width: double.infinity`

## 7. 2KB result cap (ADR-0005 §OQ-2)

`encodeToolResult(ToolResult, {int maxBytes = 2048})` — `lib/ai/tools/tool_envelope.dart`.

- `jsonEncode(result.toJson())` 후 길이가 `maxBytes` 이하면 그대로 반환.
- 초과 + `ToolOk` 이면 payload 를 `{'_truncated': true, '_hint': '... query_protocol 같은 단건 조회 도구를 사용하세요.'}` 로 대체.
- 초과 + 그 외 (방어용) → `substring(0, maxBytes)` hard cut.
- 호출 위치: `chat_providers.dart` `userTurn` 안에서 `jsonDecode(encodeToolResult(result))` 로 round-trip → Map 형태로 `sendToolResult` 전달.

> 주의: `.length` 는 UTF-16 code units. 한글 멀티바이트 utf-8 환산 시 더 작은 바이트 → 2048 cap 은 보수적 (안전 방향).

## 8. LlmChatSession 두 구현

| 구현 | 위치 | 비고 |
|---|---|---|
| `_GemmaChatSession` | `gemma_llm_service.dart` | flutter_gemma 0.16.5 `_chat.addQueryChunk` + `generateChatResponseAsync`. ParallelFunctionCallResponse 는 first 만 yield 후 return. ThinkingResponse skip. |
| `MockLlmChatSession` | `llm_service.dart` | 테스트용. `chatScript` (FIFO `List<List<LlmChatEvent>>`) + `userInputs` + `toolResults` 기록. `lastChat` 으로 마지막 세션 접근. |

`Tool` (flutter_gemma) ↔ `ToolDefinition` 매핑은 `startChat` 안에서 수행 (`name`, `description`, `parameters`).

## 9. UI 진입점

- `HabitListScreen` AppBar 의 🤖 IconButton (Icons.smart_toy_outlined) — `aiSettingsProvider == true` 일 때만 노출.
- 탭 → `ChatScreen` push.
- 새 대화: AppBar refresh 아이콘 (tooltip: `새 대화 (이전 기록 비우기)`) → `controller.clear()`.
- ToolCallChatMessage 라벨은 `_kToolKoreanLabels` 맵 기반 (`add_habit → 습관 추가` 등 6종, 미매핑은 raw name fallback).

## 10. 테스트

| 파일 | 케이스 수 |
|---|---|
| `test/ai/tools/tool_envelope_test.dart` | 6 |
| `test/ai/tools/catalog_tools_test.dart` | 7 |
| `test/ai/tools/habit_tools_test.dart` | 8 |
| `test/ai/tools/tracker_tools_test.dart` | 7 |
| `test/ai/tools/tool_dispatcher_test.dart` | 6 |
| `test/state/chat_session_controller_test.dart` | 8 (huge_dump cap 회귀 포함) |
| `test/ui/chat_screen_test.dart` | 2 (E2E 수행/취소) |

전체 v0.4.0 기준 **154 passed (1 skip)**.

## 11. Known limitations / 후속 이슈 권장

- **`ToolDefinition.koreanLabel` 필드 도입** — 현재 `chat_screen.dart` 의 `_kToolKoreanLabels` hardcoded const. 후속 tool 추가 시 두 위치 동기화 필요.
- **`log_tracker_entry` blank 시 confirm skip** — 현재 `isDestructive: true` 가 done/blank 무차별. R5 의도 "blank = 의도적 공란" 과 차이.
- **`search_catalog` category case-insensitive** — 현재 `DisplayCategory.name` 정확 일치. 모델 환각 대비.
- **R9/R10 minimum variant chat 노출** — Phase 1 dose variants UI 가 chat 진입점에 노출 안 됨. 핸들러는 `isMinimum:false` 고정.
- **KGP deprecation 경고** (빌드 시) — `device_info_plus`, `flutter_gemma`, `large_file_handler`. Future Flutter 빌드 실패 가능.

## 관련 문서

- 설계서: [docs/design/260-gemma-tool-calling/](../design/260-gemma-tool-calling/)
- 결정 기록: [docs/adr/0005-in-app-tool-calling-architecture.md](../adr/0005-in-app-tool-calling-architecture.md)
- 선행 레퍼런스: [docs/reference/215-ai-frame-suggest.md](215-ai-frame-suggest.md)
- 변경 이력: [CHANGELOG.md](../../CHANGELOG.md)