andreagrandi / andreagrandi/draftomen
Add optional local AI recommendation narration
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 23m
- Merged PRs (30d)
- 181
Description
## Problem
Draft Omen already computes recommendations and deterministic explanations, but users must still interpret much of the supporting statistical information. The PRD proposes optional, short, conversational explanations without changing how a card is recommended.
## Goal
Let a user explicitly install a small local AI component, independently enable or disable it, and see grounded English narration of the current recommendation without slowing or changing the recommendation. Once installed, inference works offline and sends no draft information to an external LLM.
## Scope
- Bounded engine-fact contract; versioned prompt; fixed quality corpus and output admission policy.
- Evidence-driven model/runtime/quantization selection, supported hardware limits, lifecycle, and latency/memory measurements.
- Pinned, licensed, checksum-verified artifact distribution; explicit installation, progress, safe interruption, removal, compatibility and user-controlled updates.
- Reusable local inference worker; shared-session state; cancellation and stale-output rejection.
- Desktop dialogue and Settings, TUI parity, and explicit pipe-friendly plain-watch support.
- Optional-component packaging, packaged application verification, and user/developer documentation.
- Non-AI fallback, bounded failure behavior, and diagnostic logging throughout.
## Out of scope
Changing ranking or scoring; independently inferring card properties or synergies; cloud inference; accounts/API keys; external knowledge lookup; chatbot or conversations; deck-building advice; autopilot; fine-tuning; extra languages, personas, avatars, selectable models/styles/speeds, or post-draft analysis. No silently downloaded model, bundled model weights, or mutable upstream `latest` artifact.
## Child issues
- [ ] #452 — Publish a bounded recommendation narration fact contract
- [ ] #453 — Define a fixed narration evaluation corpus
- [ ] #454 — Establish local narration feasibility and delivery decisions
- [ ] #455 — Version the narration prompt and output admission policy
- [ ] #456 — Publish a pinned and licensed narration model artifact
- [ ] #457 — Download and verify narration artifacts on explicit request
- [ ] #458 — Manage installed narration models and persisted opt-in
- [ ] #459 — Run bounded local narration in a reusable worker
- [ ] #460 — Coordinate narration through the shared live session
- [ ] #461 — Expose local model controls in desktop Settings
- [ ] #462 — Display progressive recommendation dialogue on desktop
- [ ] #463 — Expose local narration and model controls in the TUI
- [ ] #464 — Support explicit local narration in plain watch
- [ ] #465 — Package the optional local inference component
- [ ] #466 — Document local narration installation and troubleshooting
- [ ] #467 — Verify the complete offline narration release journey
## Acceptance Criteria
- [ ] AC1: A clean installed application produces normal recommendations without installing or loading AI; verified by the packaged baseline journey.
- [ ] AC2: Users explicitly download with size/progress information, enable/disable independently, remove safely, and approve updates; verified by desktop and TUI model-management journeys.
- [ ] AC3: Narration normally contains 1–3 short English prose sentences, preserves supplied facts, and passes the fixed corpus quality gates; verified by the pinned model evaluation report.
- [ ] AC4: Narration never changes the recommended card, score, order, or audit decision identity; verified by enabled/disabled replay comparison.
- [ ] AC5: The recommendation appears immediately and admitted text appears progressively within the agreed hardware/latency limits; verified by instrumented frontend and packaged performance checks.
- [ ] AC6: New recommendations, disable/remove, failures, and shutdown cannot publish obsolete output or obstruct the normal recommendation; verified by the cancellation/failure matrix.
- [ ] AC7: Installed inference works with external networking blocked and no accounts/API keys; verified by the offline release journey.
- [ ] AC8: Distribution, licensing, compatibility, packaging, hardware support, and user/developer documentation match the shipped implementation; verified by the final epic audit after all child implementations merge.
## Epic classification
- **Overall size:** XL
- **Overall orchestration risk:** High
- **Reason:** Optional native inference spans distribution, lifecycle, concurrency, multiple frontends, and packaged offline operation.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.