Skip to content

README.md

Latest commit

 

History

History
78 lines (63 loc) · 3.73 KB

README.md

File metadata and controls

78 lines (63 loc) · 3.73 KB
Raw

Assistant Extractor

An "Extractor" plugin for AnnotationSync.koplugin, built against the design proposed in AnnotationSync.koplugin#93. It reads assistant.koplugin's notebook markdown files and turns new entries into Extractor Records — data AnnotationSync (once its side of this interface exists) can sync across devices.

See ARCHITECTURE.md for how this actually works internally, the module map, and the design decisions behind it — in particular why this one is structurally simpler than the companion VocabDeck extractor.

Status

Working today: the full round trip — finding assistant.koplugin's notebook files, parsing entries out of their markdown format, pushing to AnnotationSync, and appending merged entries from other devices back into the real notebook file. Verified end-to-end across two real, independently-editing KOReader instances — see ARCHITECTURE.md for what's been tested and how.

Finds both general notebooks and per-book notebooks (which default to sitting next to their book, wherever that is — no default_folder_for_logs setup required). The per-book search is cached for speed, so a newly-added book's notebook needs one "Rescan for notebooks" tap to be picked up — see ARCHITECTURE.md for why.

Installation

  1. Download or clone this repository.
  2. Copy the folder named assistantextractor.koplugin into KOReader's plugins directory.
  3. Restart KOReader.
  4. Requires assistant.koplugin to already have some notebook entries saved — this plugin only reads its data files, it doesn't need assistant.koplugin's own plugin to be running.

Debug menu (Tools > Assistant Extractor)

  • Extract now (debug) — runs the real extraction pipeline, shows how many new entries were found per notebook file.
  • Rescan for notebooks (debug) — forces a fresh filesystem search for per-book notebooks, picking up any added since the last scan.
  • Dump extraction to file (debug) — writes the full extracted record set to <KOReader data dir>/assistantextractor_dump.lua as a plain Lua table literal, for inspection while there's no real downstream consumer yet.
  • Push to AnnotationSync — currently a placeholder; shows a message explaining what's pending.

Roadmap

Same plan as vocabdeckextractor.koplugin: this is meant to eventually fold into a single installed "suite" plugin that auto-detects which source plugins are present and activates the matching extractor internally, rather than a separate install per source. This repo stays standalone until that suite's shared core exists — see ARCHITECTURE.md for what's already shareable versus what's still duplicated on purpose.

Contributing

Issues and pull requests are welcome — this is early and still evolving alongside AnnotationSync's own design work on the Extractor interface (see AnnotationSync.koplugin#93), so it's worth reading ARCHITECTURE.md first to see what's settled versus still in flux, and worth opening an issue before a large change so the approach can be agreed on first. Small fixes and clarifications don't need that — just open a PR.

License

GPLv3 (see LICENSE) — matching assistant.koplugin's own license.