KOAssistant v0.15.0 Release Notes

Major Release Notice

This is a significant release with extensive changes to actions, menus, gestures, and settings. If you have customizations, you may want to reset certain configurations:

• Highlight Menu - New default actions and ordering. Reset via Settings → KOReader Integration → Reset Highlight Menu
• Dictionary Popup - New default actions. Reset via Settings → KOReader Integration → Reset Dictionary Popup
• Quick Actions Panel - New utility toggles and defaults. Reset via Settings → Quick Actions → Reset
• Gestures - New gesture actions available and changed defaults. Review in KOReader's Gesture Manager
• Built-in Actions - Many actions have been modified with new prompts, flags, and capabilities. If you have duplicated or customized built-in actions, consider reviewing them against the updated originals

Translations - AI-generated translations have been significantly improved. If you use a non-English interface, updating/verifying translations on Weblate is appreciated (marks them as non-fuzzy).

New Features

Document Analysis & Smart Actions

Response Caching System

• X-Ray and Recap responses are now cached per book in .sdr/ folders
• Subsequent runs send only new content since your last read position (incremental updates)
• Massive token savings: ~90% reduction on follow-up queries
• Cache viewer utility: view, copy, export, or delete cached analyses

Smart Actions (new action category)

• Smart actions use cached document summaries (~8K tokens) instead of raw text (~100K tokens)
• New actions: Explain in Context (Smart), Analyze in Context (Smart), Thematic Connection (Smart), Discussion Questions (Smart), Generate Quiz (Smart)
• Auto-prompts to generate summary cache if missing
• Cache placeholders: {xray_analysis_section}, {analyze_analysis_section}, {summary_analysis_section}

Full Document Analysis

• New actions: Analyze Full Document, Summarize Full Document, Extract Insights
• Results can be cached for reuse by Smart actions
• Book text extraction with configurable limits (10K-1M chars, default 250K)

Web Search

• Anthropic: Native web search tool with configurable max searches (1-10)
• Gemini: Google Search grounding for 2.5+ and 3.x models
• OpenRouter: Exa search via :online model suffix (universal)
• Global toggle + per-action override + session toggle in chat viewer
• Streaming indicator: "Searching the web..." during search
• Per-message "[Web search was used]" indicator
• Note: OpenAI and xAI not supported (API limitations)

Per-Book Notebooks

• Markdown notebooks stored in .sdr/ folders (travel with books)
• "Add to Notebook" button in chat viewer saves AI responses
• Three content formats: Response only, Q&A, Full Q&A
• Notebook Manager: browse, view, edit all notebooks
• File browser integration: long-press book → Notebook button
• New placeholder: {notebook_section} for actions
• New action: Connect (With Notes) - uses both annotations and notebook

Quick Actions Menu

• New reader-mode panel for fast access to book actions
• Default actions: X-Ray, Recap, Book Info
• Utility buttons: Translate Page, View/Edit Notebook, Chat History, Summary, View Caches
• Fully customizable: add/remove actions via Action Manager (hold → Add to Quick Actions)
• Alphabetically sorted for consistency

Gesture Menu Integration

• Add any book or general action to KOReader's gesture menu
• Configure via Action Manager (hold action → Add to Gesture Menu)
• [gesture] indicator shown in action list
• Changes require restart to take effect

Quick Settings Redesign

• Renamed from "AI Quick Settings" to "Quick Settings"
• 15+ toggleable controls: Provider, Model, Behavior, Domain, Temperature, Reasoning, Web Search, Languages, and more
• Granular visibility: hide controls you don't use
• Direct access to Chat History, Notebooks, General Chat

Privacy & Data Controls

• New "Privacy & Data" settings section
• Granular toggles: Annotations, Notebook, Reading Progress, Reading Stats
• Double-gating: Sensitive data requires BOTH global consent AND per-action flag
• Trusted Providers: Bypass privacy controls for specific providers (e.g., local Ollama)
• Quick presets: "Minimal Data" and "Full Features" buttons
• Section placeholders gracefully disappear when data types are disabled

KOReader Integration Settings

• New settings section to control plugin presence in KOReader
• Toggle visibility in: File Browser, Highlight Menu, Dictionary Popup
• Individual menu managers for Dictionary and Highlight actions
• Per-menu reset options + Reset All
• Startup behavior: auto-check for updates toggle

Language Settings Overhaul

• Native script dropdown pickers replace free-text input
• 47 pre-loaded languages displayed in native scripts (日本語, Français, etc.)
• 5 classical/scholarly languages: Ancient Greek, Biblical Hebrew, Classical Arabic, Latin, Sanskrit
• Separate "Additional Languages" for translation/dictionary-only targets
• Languages shown in native script throughout the UI

Plain Text View Mode

• New View Mode setting: Markdown vs Plain Text
• Plain Text mode strips markdown to readable text with universal symbols
• Solves MuPDF limitation where e.g. Arabic render properly in markdown
• Auto-switches to Plain Text for RTL languages when detected
• Wikipedia-style hierarchical symbols for headers work in all scripts

RTL & BiDi Support

• Full right-to-left support for Arabic, etc.
• Auto text mode switching for RTL languages in chat viewer and translate view
• BiDi text alignment for mixed RTL/LTR content
• RTL dictionary popup with proper alignment
• Automatic language detection and alignment

Update Checker

• Automatic version checking on startup (configurable)
• Release notes viewer with markdown rendering
• Translate button to view release notes in your translation language
• Clickable links
• Deferred popup during active streaming
• Manual check via Settings → About

Provider-Inspired Behaviors

• Expanded from 8 to 22 built-in behavior styles
• New series: Claude Style, GPT Style, Gemini Style, DeepSeek Style, Grok Style, Perplexity Style
• Mini, Standard, Full variants for each
• Default unchanged (Claude Style - Standard)
• Specialized behaviors (dictionary_direct, translator_direct, etc.) filtered from Quick Settings pickers

Improvements

Actions & Prompts

• New action flags: in_quick_actions, in_gesture_menu, in_reading_features
• Cache flags: cache_as_xray, cache_as_analyze, cache_as_summary
• Utility placeholders: {conciseness_nudge}, {hallucination_nudge}
• {surrounding_context_section} for dictionary-like custom actions (hard-capped 2000 chars)
• Explicit max_tokens limits for highlight actions (4096) and translate (8192)
• Improved prompts for conciseness in highlight/dictionary actions

Chat Storage (v2)

• Chats now stored in DocSettings (.sdr/metadata.lua)
• Automatic file move tracking - chats survive book relocations
• Dedicated storage files for general chats and multi-book chats
• Chat index for fast browsing
• Automatic migration from v1 format (backup preserved)
• Write protection with validation prevents concurrent corruption
• Custom sidecar files (notebooks, caches) tracked and moved with books

Reasoning Support (Anthropic/Gemini)

• Settings redesigned to match actual provider capabilities
• Master toggle now only gates Anthropic and Gemini (where reasoning can be disabled)
• Anthropic budget default raised to 32,000 tokens
• Compound settings dependencies (budget requires both master AND provider toggle)
• Note: OpenAI o-series and DeepSeek reasoner always reason by design
• Fixed non-streaming loading dialog reasoning indicator

Export & Formatting

• Improved export format: simplified Q&A context, highlighted text in Full export
• Save to File feature for chat history and viewer
• Redesigned export directory: central exports folder with book subfolders
• Export settings simplified from 5 options to 3
• Cache export with metadata header (type, book info, date, model, coverage)

UI Polish

• Chat viewer button renames: "Note" → "Save to Note", "NB" → "Add to Notebook"
• Scroll-to-last-message now properly detects follow-ups
• Improved dictionary compact view with action switcher button
• +Note button in compact dictionary view
• Better notebook entry formatting
• Reset Settings redesigned with flat structure and custom reset options
• Welcome and migration dialogs deferred to first user interaction
• Auto-select provider when user adds their first API key

Performance & Architecture

• OpenAI-Compatible Base Class: Reduced ~1,120 lines of duplicate code across 11 providers
• Lazy-loaded update checker for faster startup
• Non-blocking non-streaming requests with cancellation support
• Default max_tokens increased to 16,384 across all providers
• Chat ID increased from 4 to 6 random digits

Bug Fixes

• Fixed X-Ray cache permission check and analysis cache extraction pattern
• Fixed shallow copy bug causing intermittent metadata placeholder failures
• Fixed chat persistence race condition with KOReader's DocSettings
• Fixed spurious chat timestamp updates on book open
• Fixed general chat export showing book metadata from previous session
• Fixed stacked action dialogs when launching General Chat from Quick Settings
• Fixed system prompt debug info disappearing after KOReader restart
• Fixed scroll-to-last-reply skipping first response
• Fixed H.Note button crash in Translate Current Page action
• Fixed quick settings picker dismissal issues
• Fixed multi-book chats not included in backup/restore
• Fixed viewer refresh bug when scrolling to top
• Fixed Gemini web search false positive and thinking truncation
• Fixed cache file vulnerability with dynamic Lua long string delimiters
• Fixed gesture labels and registration (book-only gestures now register to Reader dispatcher only)
• Fixed translate view visibility for full-page translations
• Fixed privacy bug: notebook sharing now correctly uses opt-in pattern

Technical Notes

New Files

• koassistant_backup_manager.lua - Settings backup/restore
• koassistant_update_checker.lua - Version checking
• koassistant_debug_utils.lua - Debug utilities
• koassistant_action_cache.lua - X-Ray/Recap/Analysis caching
• koassistant_api/openai_compatible.lua - Shared base class for OpenAI-compatible providers
• scripts/translate_v2.py - Improved AI translation system

Model Updates

• Full support for latest reasoning models (Claude 4.x, GPT-5.x, Gemini 3.x, o3/o4 series)
• Updated model lists for all 16 built-in providers
• OpenRouter model list expanded from 9 to 48 models
• Tier system: reasoning > flagship > standard > fast > ultrafast

Testing

• Comprehensive test suite: 396+ tests
• New tests for prompt building, privacy gating, constraint utilities
• Provider connectivity tests

Migration Notes

From v0.14.0

1. Chat Storage: Automatic migration to v2 format. Original data backed up to koassistant_chats.backup/

2. Language Settings: Old string format automatically migrated to new picker-based system

3. Privacy Settings: New users get balanced defaults. Existing users retain current behavior (all sharing enabled)

4. Behaviors: Original behaviors renamed (standard.md → Claude Style Standard). Custom behaviors unaffected.

Recommended Resets

If experiencing issues with customized menus:

• Dictionary Popup: Settings → KOReader Integration → Reset Dictionary Popup Actions
• Highlight Menu: Settings → KOReader Integration → Reset Highlight Menu Actions
• Quick Actions: Settings → Quick Actions Panel → Reset Quick Actions
• Gestures: Review in KOReader's Gesture Manager → KOAssistant section

Full Changelog: v0.14.0...v0.15.0