KOAssistant v0.18.1 / v0.18.2

Minor maintenance releases to v0.18.0: new Anthropic models + reasoning updates (v0.18.1), and language auto-detection for non-English users (v0.18.2).

v0.18.0 release notes below.

v0.18.2 — Language auto-detection

Non-English users no longer need to manually configure languages. KOAssistant auto-detects from your KOReader UI language for AI responses, translations, and dictionary. Setup wizard now includes a language step; existing non-English users get a one-time prompt. See #46

Full Changelog: v0.18.1...v0.18.2

v0.18.1 — Anthropic 4.6 + reasoning updates

Claude 4.6 models — Opus 4.6 and Sonnet 4.6 added; older 3.x/4.x removed (4.5 remains; custom entries unaffected)
Adaptive Thinking (4.6+) — Claude decides when/how much to think. Effort: low/medium/high (max for Opus only). Recommended over Extended Thinking.
OpenAI Reasoning toggle (5.1+) — GPT-5.1/5.2 ship with reasoning off; new sub-toggle to opt in. Always-on models (o3, GPT-5) unaffected.
Master toggle now gates all three configurable providers (Anthropic, Gemini 3, OpenAI 5.1+)
Fixes: max effort clamped to high for non-Opus; stale 4096 budget display corrected

Full Changelog: v0.18.0...v0.18.1

KOAssistant v0.18.0 Release Notes

Settings reset recommended. This release includes major changes to actions,
panels, input dialog, settings layout, and KOReader integration. After updating,
go to Settings > Backup & Reset and reset the following to pick up all new
defaults: Quick Actions panel, Quick Settings panel, Input Dialog actions,
Highlight Menu actions, File Browser actions, and KOReader Integration toggles.
Or do a full Reset to get a fresh start.
Custom actions and API keys are not affected by resets.

Major Features

X-Ray Overhaul

The X-Ray feature has been rebuilt from the ground up. It now produces structured JSON output (instead of freeform markdown) organized into typed categories: characters, locations, themes, lexicon/terminology, timeline/argument development, reader engagement, and a status section. Fiction and non-fiction works get different category schemas automatically -- non-fiction works well for articles research papers, etc, making X-Ray a good analysis tool for a wide range of document data. The reader engagement category appears when highlights are shared, analyzing highlight patterns and notable passages, to personalize the X-Ray.

Browsable X-Ray browser. X-Ray results are now navigated through a full-screen menu: category list, item list within each category, and detail view for each entry. Cross-category references are linked and tappable.

Two-track generation. You can now generate X-Ray in two modes:

Incremental (default): Covers only content up to your current reading position. Completely spoiler-free. Updates incrementally as you read further (manually triggered; prompt reminder as you progress) via diff-based merging — the AI sees only new document content and merges it into the existing X-Ray.
Complete: Analyzes the entire document in one pass, including conclusions and resolutions.

Per-item chapter distribution. From any X-Ray entry's detail view, see a bar chart showing mention counts across chapters. Uses union span-merge counting for accurate results across names and aliases, with CJK and multi-word name support.

Chapter analysis. Expanded to all X-Ray categories (not just characters), with a TOC depth selector for choosing analysis granularity.

Hierarchical TOC chapter picker. Mentions now uses a hierarchical chapter picker that reflects the book's actual TOC structure, replacing the flat chapter list.

Prev/next navigation. Detail views now have left/right arrow buttons with a position indicator (e.g., "3/14") for quick browsing — across category items, connections, search results, and Mentions.

Edit Search Terms. A unified dialog to add custom search terms, ignore aliases you don't want tracked, and restore previously ignored terms.

Stale X-Ray notification. When you open an X-Ray that's behind your current reading position by more than 8%, you're prompted to update it.

Spoiler gating. Chapter distribution, mentions, and chapter appearances are gated by X-Ray coverage, not reading position — so incrementally-updated X-Rays show data correctly.

"Chat about this" from X-Ray. From any X-Ray entry's detail view, launch a highlight-context chat pre-populated with the entry's information. Uses a curated action set (Explain, Elaborate, ELI5, Fact Check).

Local X-Ray Lookup. New "Look up in X-Ray" action available from the highlight menu and dictionary popup. Searches your cached X-Ray for the selected text — instant, offline, no API call.

X-Ray (Simple). New artifact action that generates a prose overview of the book based on AI knowledge alone. No text extraction required. Useful as a lightweight alternative when you don't need the full structured X-Ray.

Open Book from file browser. X-Ray features that require an open book (Mentions, Chapter Appearances) are now accessible from the file browser — the book opens automatically and the X-Ray browser reopens once the book is ready.

PDF support. Fixed chapter text extraction for PDF documents in Mentions and Chapter Appearances.

Input Dialog Redesign

The chat/action input dialog has been redesigned:

Top row: Web search toggle, domain selector, and Send button.
Actions in a 2-column grid for better readability.
Per-context action sorting. Four independent action lists: book, book (file browser), highlight, and X-Ray chat. Each can be customized separately via the gear menu.
Gear menu with quick access to Quick Settings, "Choose and Sort Actions" editor, and "More Actions" toggle.
"Show More Actions..." button in the action grid expands to show all remaining enabled actions inline, without opening a separate dialog.

Artifact System

Seven document-level AI results are now cached as reusable "artifacts" stored per-book:

Document Summary — comprehensive summary, also used by Smart actions as a text stand-in.
X-Ray — structured reference guide (see above).
X-Ray (Simple) — prose overview from AI knowledge.
Recap — incremental reading summary with anti-spoiler clauses.
Document Analysis — deep analysis of the full document.
Book Info — overview and metadata from AI knowledge (new, no text extraction needed). Includes a spoiler warning since AI knowledge may extend beyond the reader's current position.
Analyze My Notes — pattern analysis of your highlights and annotations (newly cacheable).

Each artifact stores metadata: which model generated it, when, what data sources were used, whether reasoning or web search was involved. Accessible via an Info popup in the viewer.

Artifact Browser. New top-level browser showing all books that have cached artifacts. Browse by book, see which artifacts exist, and open any of them directly.

Cross-navigation. From any artifact viewer, jump to other artifacts for the same book via the Artifacts button. The X-Ray browser hamburger menu also links to all available artifacts.

Cache progress tracking. Position-relevant artifacts (X-Ray, Recap, X-Ray Simple, Analyze My Notes) track your reading position and show "Update to X%" when you've read further. Position-irrelevant artifacts (Summary, Analysis, Book Info) show "Regenerate" instead.

Artifacts are stored in .sdr/koassistant_cache.lua alongside the book and travel with it when moved.

Privacy Framework

Highlights and annotations now have separate privacy controls (previously they were bundled). This means you can share just your highlighted passages without sharing your notes/annotations.

Annotation degradation. Actions that request annotations will gracefully fall back to highlights-only data when annotation sharing is off but highlight sharing is on. The section label adapts: "My annotations:" vs "My highlights so far:".

Double-gating. Sensitive data (book text, highlights, annotations, notebook, document caches) requires both a global privacy setting AND the per-action flag to be enabled. This prevents accidental data leakage.

Action requirements blocking. Actions that need specific data (like text extraction or highlights) now check prerequisites before executing and show a clear error identifying which setting needs to be enabled, with optional hints suggesting alternatives.

Streaming Improvements

Page-based auto-scroll for e-ink. New streaming mode that fills empty page space instead of continuously scrolling from the bottom. Reduces full-screen refreshes on e-ink devices. Auto-scroll is now enabled by default.

Auto-scroll respects user input. Swiping or pressing page buttons during streaming stops auto-scroll so you can read at your own pace.

Streaming settings sub-menu. All streaming options are now grouped in their own settings section.

Quick Settings and Quick Actions Panel Improvements

TitleBar with gear icon and close button. Both panels now use a proper title bar — gear icon on the left for settings, X on the right to close.

Per-panel left-alignment. Button text can be left-aligned instead of centered, configurable per panel from the gear menu or settings. Enabled by default.

Emoji icons. Optional emoji icons on panel buttons (provider, behavior, chat history, etc.). Controlled by a separate "Emoji Panel Icons" setting.

Text extraction toggle. Quick Settings now includes a one-tap ON/OFF toggle for text extraction.

Browse Artifacts. Quick Settings now includes a shortcut to the Artifact Browser.

Sortable panel items. Both QS and QA panel items can be reordered via dedicated sorting managers. All sorting managers across the plugin now use in-place refresh (no close/reopen flicker), bold selected items, and persistent arrow popups with boundary indicators.

QA panel: merged Notebook button. "View Notebook" and "Edit Notebook" combined into a single "Notebook" button that shows a View/Edit popup (or prompts to create one if none exists). Utility order rebalanced.

Settings Reorganization

The settings menu has been restructured for clarity:

Chat Settings renamed to Chat & Export Settings with streaming moved to its own sub-menu.
Display Settings reorganized into sub-menus: Rendering, Emoji, Panel Alignment, Highlights.
KOReader Integration simplified to 5 master toggles: File Browser, Highlight Menu, Highlight Quick Actions, Dictionary Popup, Gesture Menu.
Temperature promoted to top-level setting (no longer buried in a sub-menu).

Setup Wizard

The old welcome dialog and gesture setup dialog have been combined into a 4-step sequential setup wizard that runs on first launch:

Welcome — Brief introduction.
Emoji Display Test — Shows emoji icons used throughout the plugin. If they render correctly, tap "Yes, enable" to turn on all three emoji features (menu icons, panel icons, data access indicators) at once. Includes a pointer to the README for enabling emoji fonts in KOReader.
Gesture Setup — Offers to auto-assign Quick Settings and Quick Actions panels to tap bottom-right corner, or shows a tip if the slot is already taken.
Getting Started Tips — Pointers to privacy settings and action management.

Web Search Improvements

Web-aware hallucination nudge: actions without explicit web search settings now get a nudge to search when the global web search setting is on.
Pre-thinking text stripped from AI responses when web search is active.
Reasoning and web search indicators shown inline in both the chat viewer and artifact simple viewer.
Web search usage stored in artifact cache metadata for the Info popup.

Gemini 2.5 Thinking Support

Gemini 2.5 models (Flash and Pro) think automatically on every request. The plugin now sends thinkingConfig: { includeThoughts: true } unconditionally for these models to expose thought summaries in streaming and the "Show Reasoning" feature. This is separate from the Gemini 3 reasoning toggle.

Flow-Aware Text Extraction

EPUBs and PDFs with hidden flows (supplementary content, footnotes, backmatter) are now handled correctly. Text extraction and reading progress calculations account for hidden flow pages, preventing incorrect position reporting and extraction errors. A warning is shown when text extraction is triggered from within a hidden flow section. If you want to analyze large works with text extraction, it is wise to use KOReader's hidden flow to remove unnecessary part to save tokens and get focused responses. You can use this to analyze chapters in e.g. reference works and textbooks, because those chapters are often self contained (the book doesn't have one narrative across its chapters).

Text Extraction Limits

Default extraction limits significantly increased: character limit from 1M to 4M (ceiling raised to 10M), page limit from 500 to 2,000 (ceiling raised to 5,000). A new large extraction warning fires before API calls when content exceeds ~500K characters (~125K tokens), with options to Cancel, Continue, or "Don't warn again" (persistent and toggleable from settings). Truncation notifications upgraded from auto-dismissing toasts to blocking dialogs with the same Cancel/Continue pattern.

Browser UI Unification

Chat History, Notebook Manager, and Artifact Browser now share a consistent visual style: same metadata display, cross-navigation between browsers, and hold-action menus. Back-navigation preserves your page position.

Anchored dropdown menus. All hamburger/gear menus across the plugin now use anchored dropdowns that appear below the icon and dismiss on tap-outside, replacing the old centered popup dialogs. Cross-navigation links connect related managers (e.g., Action Manager links to Highlight Menu, QA, File Browser managers; browsers link to each other).

New Actions

Look up in X-Ray — local offline search of cached X-Ray data from highlight menu or dictionary popup.
X-Ray (Simple) — prose overview from AI knowledge, no text extraction needed.
Book Info — now a cacheable artifact with its own viewer (was previously a one-shot query).
Analyze My Notes — now cacheable with progress tracking and Update/Regenerate support.

All built-in actions now have human-readable descriptions visible in the Action Manager detail view.

Action renames. Several actions were renamed for consistency: "Summarize Document" → "Document Summary", "Analyze Document" → "Document Analysis", "Analyze Highlights" → "Analyze My Notes", "New Book Chat/Action" → "Book Chat/Action".

New highlight menu defaults. Fact Check, Elaborate, and Connect With Notes are now included in the default highlight menu actions. Book Info added to default file browser actions.

Author gate removed. Actions no longer require author metadata — books without author info in their sidecar files now fall back to the filename.

Bug Fixes

Fixed artifact caching for closed-book entry points (file browser, chat dialog).
Fixed artifact cache preserved when regenerating/redoing from simple viewer is cancelled.
Fixed emoji rendering in MuPDF — unconditional emojis gated to prevent broken rendering on devices without emoji fonts.
Fixed text extraction using wrong default limit (250K instead of configured 1M).
Fixed highlight sharing flag not being passed to context extractor.
Fixed annotation privacy setting not respected in X-Ray browser and cache.
Fixed "Redo" vs "Update" label in cache popup based on progress threshold.
Fixed TOC chapter picker crash on unread chapters.
Fixed PDF chapter text extraction for Mentions and Chapter Appearances.
Fixed truncated X-Ray caching (partial results no longer saved as complete).
Fixed model misbehaviors: entity name translation (Gemini 3) and description language mismatches (Gemini 2.5 Flash).
Fixed text matching for CJK scripts and multi-word names in X-Ray browser.
Fixed smart action text extraction prerequisite check.
Fixed Action Manager duplicate refresh and hold popup layout.
Fixed file browser row cache invalidation after artifact save.
Fixed calendar-day display (was using elapsed time instead of calendar days).
Fixed auto-scroll not stopping on swipe or device key/page button presses.
Fixed regex search state sync to input dialog.
Fixed missing restart notifications for highlight menu setting changes.
Fixed gesture registrations cleanup (34+ reduced to 11 active registrations).
Fixed reset functions not covering input dialog actions and incomplete key cleanup.
Fixed over-blocking when action requirements were too strict.
Fixed artifact actions (Recap, X-Ray Simple, Document Summary, Document Analysis) opening in full chat viewer instead of their simple viewer after generation.
Fixed Recap viewer missing Update/Redo/Regenerate button and 8 action entry points missing requirements gate checks.
Fixed PDF chapter search crash (regex error handler only existed on EPUB's CreDocument, not PDF's KoptInterface).
Fixed QA gear menu crash when navigating to "Manage Actions" (nil prompts on lazy load).
Fixed surrounding context toggle enabled for non-reader dictionary lookups (AI viewer lookups don't have book context).
Fixed stale highlight menu closure — mid-session changes to action flags and display text now take effect without restart.
Fixed X-Ray browser conclusion category double-nesting and TOC picker selection persistence.
Fixed action requirements blocking not considering trusted providers.
Fixed reasoning config "off" override silently ignored (couldn't disable reasoning per-action).
Fixed web search content lost across multiple sequential searches (Anthropic).
Fixed X-Ray JSON parser failing on multi-line code-fenced responses.
Fixed invisible Unicode characters breaking X-Ray chapter text matching.
Fixed X-Ray browser navigation: distribution back-nav, search return button, item detail close behavior, position indicators, mixed-depth TOC parents in Chapter Appearances, current chapter marker, spoiler gating for complete X-Rays.
Fixed non-numeric HTTP status codes crashing subprocess error formatting.
Fixed shared config mutation in X-Ray "Chat about this" feature.
Fixed auto-updater error handling: honest error message on restore failure, preserve directory creation check.

Model Updates

Gemini defaults reverted to 2.5 series (from 3.x preview) due to output cap issues with Gemini 3 models.
Gemini 2.5 Flash thinking token budget bumped.
Gemini 3 Flash/Pro previews remain available but noted as output-capped (~3K tokens).
X-Ray output token limit increased for more detailed results.

Under the Hood

Unified requires system for pre-flight action blocking with per-action and global gate checks.
Highlights and annotations fully separated in the privacy and context extraction pipeline.
ActionCache.saveCache() serialization: new metadata fields (used_reasoning, web_search_used) properly persisted to disk.
Union span-merge counting algorithm for accurate X-Ray text occurrence matching.
Per-session browser text cache eliminates redundant text extraction across X-Ray features.
Diff-based X-Ray incremental update merge mechanism (name-based entity matching).
3 new test suites: state management (68 tests), X-Ray counting, X-Ray merge.
nextTick used across browsers for snappier transitions (replacing scheduleIn(0.1)).
Setup wizard replaced the old welcome and gesture setup dialogs (see above).
Translate button in highlight menu now uses the interaction language picker.
Local/offline actions (X-Ray Lookup) tagged as "LOCAL" in Action Manager with AI settings disabled.

Full Changelog: v0.17.3...v0.18.0

zeeyado/koassistant.koplugin v0.18.2 on GitHub