Kindle Zotero Importer

Prototype importer for turning Kindle My Clippings.txt entries into a JSON import plan that Zotero can later write as native annotations.

The project intentionally keeps Zotero writes out of Python. Python parses, matches, and plans. Zotero JavaScript, and eventually a Zotero plugin, will perform annotation creation through Zotero's own APIs.

Current Milestone

Parse Kindle clippings and emit a stable JSON preview:

python -m kindle_zotero_importer parse "/path/to/My Clippings.txt" --output clippings.json

Index Zotero items and PDF/EPUB attachments read-only:

python -m kindle_zotero_importer index-zotero --output zotero-index.json

Match parsed Kindle titles to Zotero items:

python -m kindle_zotero_importer match clippings.json zotero-index.json --overrides match-overrides.json --output matches.json

Generate reusable manual overrides for ambiguous/unmatched titles:

python -m kindle_zotero_importer generate-overrides matches.json --output match-overrides.generated.json --pretty

Generated overrides are designed for batch editing: unresolved titles are sorted by clipping count, unmatched titles default to ignore: true, and already-entered overrides are kept at the end as an audit trail. Replace ignore with a confirmed citation_key, zotero_key, or zotero_item_id to import a title instead of discarding it.

Apply reviewed overrides:

python -m kindle_zotero_importer match clippings.json zotero-index.json --overrides match-overrides.json --output matches.json

Keep confirmed mappings in match-overrides.json. The match-overrides.generated.json file is only a disposable review skeleton and can be regenerated from the current matches.json at any time.

To permanently skip a Kindle title that should not be imported, add an ignore override:

{
  "clipping_title": "Example Kindle Title",
  "resolution": {
    "ignore": true
  }
}

If a matched Zotero item has multiple usable PDF/EPUB attachments, add the selected attachment to the same override entry:

{
  "clipping_title": "Example Kindle Title",
  "resolution": {
    "citation_key": "example2024",
    "attachment_key": "ABC12345"
  }
}

Use either attachment_key or attachment_item_id. Attachment choices are listed in docs/mismatch-review.md when an item is ambiguous.

For cumulative Kindle exports, rerun the whole pipeline against the latest My Clippings.txt. Previously confirmed overrides in match-overrides.json will be applied automatically to old and new clippings.

Review unresolved cases in docs/mismatch-review.md after each run. Prioritize:

1. matched-title-no-attachment: add/link the missing PDF or EPUB in Zotero.
2. unmatched-title: add a confirmed title mapping to match-overrides.json.
3. position failures: improve text/position matching or handle manually.

Regenerate the copy-friendly review report:

python -m kindle_zotero_importer review-mismatches import-plan.positioned.json matches.json --output docs/mismatch-review.md

Each reviewed title includes a YAML-style block with standalone keys such as clipping_title, citation_key, zotero_item_id, zotero_key, and override_entry for easy copying.

Generate a preliminary import plan for matched titles:

python -m kindle_zotero_importer plan clippings.json zotero-index.json matches.json --output import-plan.json --pretty

Position annotations and export the Zotero writer plan:

python -m kindle_zotero_importer position-epub import-plan.json --output import-plan.epub.json --pretty
python -m kindle_zotero_importer position-pdf import-plan.epub.json --output import-plan.positioned.json --pretty
python -m kindle_zotero_importer finalize import-plan.positioned.json --output import-plan.final.json --pretty

PDF positioning uses Poppler tools (pdftotext, pdftohtml, pdfinfo). If a PDF permits viewing but blocks text copying, the importer retries extraction through a temporary qpdf --decrypt copy. The Zotero attachment itself is not modified.

Safety Rule

Do not write directly to zotero.sqlite. Use read-only SQLite access for indexing and Zotero's JavaScript API for writes.