feat: enhance AI settings management with local model support and error handling

[VoidX3D]

PixelPlayer AI System

Overview

Complete AI infrastructure for PixelPlayer — multi-provider cloud inference, on-device local models with download management, usage analytics, and a dedicated settings UI.

~4,500 lines of new code, ~1,900 lines removed through refactoring.

---

Cloud Provider System

11 providers supported through a unified client interface:

Client	Providers
GenericOpenAiClient	DeepSeek, Groq, Mistral, NVIDIA, Kimi, GLM, OpenAI, OpenRouter, Ollama — all via OpenAI-compatible /v1/chat/completions
GeminiAiClient	Google Gemini (dedicated REST API)
AnthropicAiClient	Claude (Messages API)

Architecture Components

Component	Responsibility
AiClientFactory	Single creation point; no other class instantiates clients directly
AiProviderEndpoints	Every base URL and default model in one file
AiProviderSupport	Error classification (isRateLimit, isBillingIssue, isApiKeyIssue), provider fallback chain, request wrapping
AiHandler	Main orchestration layer
AiSettingsManager	Reactive settings via suspend fun set(block:) — replaced 20 individual setters
API key validation	Lightweight chat ping (1 token) instead of /v1/models

Refactoring Highlights

• 5 provider-specific client files (DeepSeek, Groq, Mistral, Ollama, LocalMlManager → LocalModelManager) consolidated into GenericOpenAiClient
• Net reduction: −730 lines

---

Local Model System

40+ downloadable models — all ≤16B params, free, no authentication required.

Model Tiers

Tier	RAM Requirement	Example Models
Low-end	≤2GB	Qwen 2.5 0.5B/1.5B, TinyLlama 1.1B, SmolLM2 1.7B, DeepSeek R1 Distill 1.5B
Mid-range	2–4GB	Qwen 2.5 3B/7B, Mistral 7B, Llama 3.2 3B, Phi-3.5 Mini, Granite 8B, Mistral Nemo 12B
High-end	4–8GB+	Qwen 2.5 14B, DeepSeek V2 Lite 16B, StarCoder2 15B

Sources: TheBloke/ and Qwen/ HuggingFace repos only — no login or license acceptance required.

Download Engine (LocalModelManager)

Feature	Implementation
Lifecycle	Persistent CoroutineScope — downloads survive screen navigation
Progress tracking	Average speed tracking + ETA computation
Cancellation	HTTP connection disconnect + coroutine cancellation
Resume support	Auto-resume interrupted downloads via Range header
Retry logic	Exponential backoff (3 attempts: 2s → 4s → 8s)
Retryable errors	Timeout, DNS failure, connection reset
Error messages	Human-readable — e.g., "Connection timed out. Check your network."
Validation	GGUF magic byte validation (GG header)
Result type	ValidationResult sealed class (Ok / Missing / SizeMismatch / Corrupted)
Startup behavior	Auto-detects and validates installed models

---

UI — AiPreferencesScreen

Full-featured settings screen with:

Provider Configuration

• Provider selection dropdown with descriptions
• API key input with show/hide toggle
• Model selection per provider (from AiProvider.models)
• Ollama server configuration

Generation Parameters

• Temperature
• Top-K
• Top-P
• Repetition / frequency / presence penalty
• System prompt editor with reset-to-default

Model Management

Section	Features
Downloaded Models	Shows only installed models; empty state with guidance
Browse Models	Collapsible section — all downloadable models with download/delete/select/use buttons
Progress indicator	Slim 3dp linear progress bar (matches player style)
Speed/ETA	Live download speed (MB/s) and ETA during active downloads
Cancel button	One-tap cancellation during download
Confirmation dialogs	Download ("Are you sure? X MB") and delete
Error display	Card shows descriptive messages instead of generic "Error"

Integration

• SettingsCategoryScreen updated with AI category

---

Notifications (AiNotificationManager)

Notification Channels

Channel	Importance	Purpose
progress	LOW	Download progress updates
completion	DEFAULT	Download finished successfully
error	HIGH	Download failures
info	MIN	General information

Features

• Progress notifications update with speed and ETA
• Completion/error notifications fire automatically via status observer
• BigTextStyle for full message visibility

---

Database

Migration: v41 → v42

New entity: ApiCallRecord

Field	Description
provider	AI provider used
model	Model name
endpoint	API endpoint called
status_code	HTTP response status
response_time	Request duration
token_count	Input + output tokens
cost_estimate	Approximate cost
error_message	Error details if failed

Analytics Queries

• AiUsageDao streamlined with provider-based queries
• Total API calls per provider
• Input/output token counts
• Estimated cost
• Error rates

---

Error Handling (AiErrorHandler)

Automatic Classification

• Rate limit
• Quota exceeded
• Billing issues
• API key issues
• Model unavailable
• Network errors

Fallback Strategy

• Provider fallback chain with recovery model recommendation
• Structured logging through AiLogger
• AiProviderException sealed hierarchy for type-safe handling

---

Supporting Infrastructure

Component	Purpose
AiDeviceCapabilities	Hardware survey — RAM, CPU, GPU, NNAPI, TFLite, networking
AiPromptTemplateEngine	5 prompt templates for music recommendations + jsonArrayOutput helper
AiSystemPromptEngine	Provider-specific system prompts with template variables
AiCacheManager	Response caching with configurable TTL and max entries
AiBehaviorDataCollector	Listening pattern collection for context-aware recommendations

---

Refactoring Summary

Key Changes

Before	After
5 provider clients	1 GenericOpenAiClient
20 AiSettingsManager setters	1 set() method
4 AiLogger methods	1 log(vararg)
GeminiModelService, deprecated AiMetadataSheet	Deleted
AiOrchestrator	→ AiHandler
LocalMlManager	→ LocalModelManager
30 per-provider StateFlows in SettingsViewModel	Removed
XML templates	Compacted
Duplicate constants	Removed

Line Count

Added:   ~2,500 lines
Removed: ~1,900 lines
Net:     +600 lines (after major consolidation)

---

Breaking Changes

Change	Impact
Ollama provider now requires API key + https://ollama.ai/api/v1	No localhost support
LocalMlManager renamed	Update imports to LocalModelManager
AiOrchestrator renamed	Update imports to AiHandler
ModelFormat enum requires explicit extension parameter	Update all usages
LiteRT component removed	Conflicts with TFLite — migrate

---

Files Changed

Added (Key Files)

data/ai/

• AiHandler
• AiSettingsManager
• AiDeviceCapabilities
• AiErrorHandler
• AiCacheManager
• AiLogger
• AiPromptTemplateEngine
• AiSystemPromptEngine
• AiNotificationManager
• AiBehaviorDataCollector
• HuggingFaceClient
• OllamaClient
• AiUsageAnalytics

data/ai/provider/

• AiProvider
• AiProviderEndpoints
• AiClientFactory
• GenericOpenAiClient
• GeminiAiClient
• AnthropicAiClient
• AiProviderSupport

data/ai/local/

• LocalModelConfig
• LocalModelManager

data/database/

• ApiCallRecord

presentation/

• AiPreferencesScreen

Modified

File	Changes
SettingsViewModel.kt	AI state management, download/notification wiring
SettingsCategoryScreen.kt	AI integration
AiPreferencesRepository.kt	Analytics support
AiUsageDao.kt	Streamlined queries
Database.kt	Migration v41→v42

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        AiPreferencesScreen                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  Provider   │  │   Model     │  │   Download Manager      │ │
│  │  Selection  │  │ Management  │  │   (Speed/ETA/Cancel)    │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                          AiHandler                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │AiSettings   │  │AiError      │  │AiCache                  │ │
│  │Manager      │  │Handler      │  │Manager                  │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │GenericOpenAi│  │ GeminiAi    │  │AnthropicAi  │
    │Client       │  │Client       │  │Client       │
    └─────────────┘  └─────────────┘  └─────────────┘
              │               │               │
              ▼               ▼               ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │DeepSeek     │  │   Gemini    │  │   Claude    │
    │Groq         │  │   (REST)    │  │ (Messages)  │
    │Mistral      │  └─────────────┘  └─────────────┘
    │NVIDIA       │
    │Kimi         │
    │GLM          │
    │OpenAI       │
    │OpenRouter   │
    │Ollama       │
    └─────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      Local Model System                          │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                   LocalModelManager                          ││
│  │  • Persistent downloads    • Auto-resume (Range header)     ││
│  │  • Speed/ETA tracking      • Exponential backoff retry      ││
│  │  • GGUF validation         • Coroutine lifecycle            ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

---