epub2anki 0.1.0__tar.gz

epub2anki-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run pre-commit hooks
+        uses: pre-commit/action@v3.0.1
+
+      - name: Run tests with pytest
+        run: uv run pytest

epub2anki-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python package to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/epub2anki
+
+
+    # Required for PyPI Trusted Publisher authentication
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

epub2anki-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.DS_Store
+.env
+.envrc
+.pytest_cache/
+cache/
+books/
+decks/

epub2anki-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-toml
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

epub2anki-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

epub2anki-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: epub2anki
+Version: 0.1.0
+Summary: Convert books and ebooks into Anki flashcards using Anthropic's Claude API.
+Author-email: Matteo Gätzner <matteo.gatzner@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: anthropic>=0.86.0
+Requires-Dist: ebooklib>=0.20
+Requires-Dist: genanki>=0.13.1
+Requires-Dist: instructor>=1.14.5
+Requires-Dist: markdown>=3.10.2
+Requires-Dist: markitdown>=0.1.5
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: tqdm>=4.67.3
+Description-Content-Type: text/markdown
+
+# epub2anki
+
+Convert books and ebooks into Anki flashcards using Anthropic's Claude API.
+
+## Overview
+
+`epub2anki` transforms your EPUB books into Anki decks (`.apkg` files). It parses the table of contents and internal book structure, divides the text into manageable chunks, and requests an LLM (Claude) to generate comprehensive and useful Anki flashcards.
+
+## Features
+
+- **Structural Parsing:** Uses the EPUB's Table of Contents to intelligently split the book into coherent sections.
+- **LLM Flashcard Generation:** Uses Anthropic's API to construct high-quality flashcards summarizing key concepts.
+- **Batch Processing:** Can utilize Anthropic's Batch API for up to 50% cost savings on API calls.
+- **Resilient Coaching & Caching:** Uses SQLite to cache generated notes, meaning if the process is interrupted, you won't be charged twice for previously processed sections!
+- **Direct Anki Export:** Outputs a ready-to-import `.apkg` file.
+
+## Prerequisites
+
+- Python 3.13+
+- An [Anthropic API Key](https://console.anthropic.com/) set as `ANTHROPIC_API_KEY` in your environment.
+
+## Installation
+
+You can install `epub2anki` using `pip` or `uv`:
+
+```bash
+pip install epub2anki
+```
+
+Or using `uv` (recommended):
+
+```bash
+uv tool install epub2anki
+```
+
+## Usage
+
+Basic usage:
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key-here"
+epub2anki path/to/your/book.epub
+```
+
+This will parse the EPUB, split it into chunks of ~50,000 characters, generate flashcards using the `claude-haiku-4-5` model, and finally place a `<book-name>.apkg` file in the `decks/` directory.
+
+### Advanced Usage & Batching
+
+To save 50% on API costs, use the `--batch` flag. This will submit all generation requests to the Anthropic Batch API:
+
+```bash
+epub2anki path/to/your/book.epub --batch
+```
+*Note: The Batch API operates asynchronously and takes 5 minutes to 24 hours to finish. `epub2anki` will submit the batch and return a Batch ID.*
+
+Once your batch is ready (you can check your Anthropic Console), run the script again using `--fetch-batch`:
+
+```bash
+epub2anki path/to/your/book.epub --fetch-batch msgbat_XXXXXXX
+```
+This will retrieve the completed responses from Anthropic, save them into the local cache, and generate your `.apkg` deck.
+
+### Command-Line Arguments
+
+```
+usage: epub2anki [-h] [--batch] [--fetch-batch FETCH_BATCH] [--deck-id DECK_ID]
+                 [--chunk-size CHUNK_SIZE] [--model MODEL] [--retries RETRIES]
+                 [--db-path DB_PATH] [--output-dir OUTPUT_DIR]
+                 [--rate-max-requests RATE_MAX_REQUESTS] [--rate-max-input RATE_MAX_INPUT]
+                 [--rate-max-output RATE_MAX_OUTPUT] [--rate-window RATE_WINDOW]
+                 book_path
+
+Generate Anki flashcards from EPUB books using an LLM.
+
+positional arguments:
+  book_path             Path to the EPUB book.
+
+options:
+  -h, --help            show this help message and exit
+  --batch               Use Anthropic's async Batch API for 50% lower costs.
+  --fetch-batch ID      Fetch an existing batch ID from Anthropic and build the deck.
+  --deck-id DECK_ID     Unique integer ID for the Anki deck.
+  --chunk-size SIZE     Maximum text size per LLM prompt (default: 50000).
+  --model MODEL         Anthropic model (default: claude-haiku-4-5).
+  --output-dir DIR      Directory to save the finished .apkg file (default: decks).
+```
+
+## License
+
+MIT License

epub2anki-0.1.0/README.md

@@ -0,0 +1,90 @@
+# epub2anki
+
+Convert books and ebooks into Anki flashcards using Anthropic's Claude API.
+
+## Overview
+
+`epub2anki` transforms your EPUB books into Anki decks (`.apkg` files). It parses the table of contents and internal book structure, divides the text into manageable chunks, and requests an LLM (Claude) to generate comprehensive and useful Anki flashcards.
+
+## Features
+
+- **Structural Parsing:** Uses the EPUB's Table of Contents to intelligently split the book into coherent sections.
+- **LLM Flashcard Generation:** Uses Anthropic's API to construct high-quality flashcards summarizing key concepts.
+- **Batch Processing:** Can utilize Anthropic's Batch API for up to 50% cost savings on API calls.
+- **Resilient Coaching & Caching:** Uses SQLite to cache generated notes, meaning if the process is interrupted, you won't be charged twice for previously processed sections!
+- **Direct Anki Export:** Outputs a ready-to-import `.apkg` file.
+
+## Prerequisites
+
+- Python 3.13+
+- An [Anthropic API Key](https://console.anthropic.com/) set as `ANTHROPIC_API_KEY` in your environment.
+
+## Installation
+
+You can install `epub2anki` using `pip` or `uv`:
+
+```bash
+pip install epub2anki
+```
+
+Or using `uv` (recommended):
+
+```bash
+uv tool install epub2anki
+```
+
+## Usage
+
+Basic usage:
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key-here"
+epub2anki path/to/your/book.epub
+```
+
+This will parse the EPUB, split it into chunks of ~50,000 characters, generate flashcards using the `claude-haiku-4-5` model, and finally place a `<book-name>.apkg` file in the `decks/` directory.
+
+### Advanced Usage & Batching
+
+To save 50% on API costs, use the `--batch` flag. This will submit all generation requests to the Anthropic Batch API:
+
+```bash
+epub2anki path/to/your/book.epub --batch
+```
+*Note: The Batch API operates asynchronously and takes 5 minutes to 24 hours to finish. `epub2anki` will submit the batch and return a Batch ID.*
+
+Once your batch is ready (you can check your Anthropic Console), run the script again using `--fetch-batch`:
+
+```bash
+epub2anki path/to/your/book.epub --fetch-batch msgbat_XXXXXXX
+```
+This will retrieve the completed responses from Anthropic, save them into the local cache, and generate your `.apkg` deck.
+
+### Command-Line Arguments
+
+```
+usage: epub2anki [-h] [--batch] [--fetch-batch FETCH_BATCH] [--deck-id DECK_ID]
+                 [--chunk-size CHUNK_SIZE] [--model MODEL] [--retries RETRIES]
+                 [--db-path DB_PATH] [--output-dir OUTPUT_DIR]
+                 [--rate-max-requests RATE_MAX_REQUESTS] [--rate-max-input RATE_MAX_INPUT]
+                 [--rate-max-output RATE_MAX_OUTPUT] [--rate-window RATE_WINDOW]
+                 book_path
+
+Generate Anki flashcards from EPUB books using an LLM.
+
+positional arguments:
+  book_path             Path to the EPUB book.
+
+options:
+  -h, --help            show this help message and exit
+  --batch               Use Anthropic's async Batch API for 50% lower costs.
+  --fetch-batch ID      Fetch an existing batch ID from Anthropic and build the deck.
+  --deck-id DECK_ID     Unique integer ID for the Anki deck.
+  --chunk-size SIZE     Maximum text size per LLM prompt (default: 50000).
+  --model MODEL         Anthropic model (default: claude-haiku-4-5).
+  --output-dir DIR      Directory to save the finished .apkg file (default: decks).
+```
+
+## License
+
+MIT License

epub2anki-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "epub2anki"
+version = "0.1.0"
+description = "Convert books and ebooks into Anki flashcards using Anthropic's Claude API."
+authors = [
+    { name = "Matteo Gätzner", email = "matteo.gatzner@gmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "anthropic>=0.86.0",
+    "ebooklib>=0.20",
+    "genanki>=0.13.1",
+    "instructor>=1.14.5",
+    "markdown>=3.10.2",
+    "markitdown>=0.1.5",
+    "pydantic>=2.12.5",
+    "tqdm>=4.67.3",
+]
+[project.scripts]
+epub2anki = "epub2anki.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pdbpp>=0.12.1",
+    "pytest>=9.0.2",
+    "pre-commit>=3.7.1",
+    "ruff>=0.3.4",
+]

epub2anki-0.1.0/src/epub2anki/db.py

@@ -0,0 +1,127 @@
+import json
+import sqlite3
+from functools import cache
+from pathlib import Path
+
+import genanki
+
+ANKI_MODEL_ID = 1847192314
+
+SIMPLE_ANKI_MODEL = genanki.Model(
+    ANKI_MODEL_ID,
+    "Standard Model",
+    fields=[
+        {"name": "Front"},
+        {"name": "Back"},
+    ],
+    templates=[
+        {
+            "name": "Standard Card",
+            "qfmt": "{{Front}}",
+            "afmt": '{{FrontSide}}<hr id="answer">{{Back}}',
+        },
+    ],
+)
+
+
+@cache
+def init_db(db_path: Path) -> sqlite3.Connection:
+    """Initializes the SQLite database and creates required tables.
+
+    Args:
+        db_path (Path): The path to the SQLite database file.
+
+    Returns:
+        sqlite3.Connection: The established database connection.
+    """
+    conn = sqlite3.connect(db_path)
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS generated_notes (
+            book_name TEXT,
+            section_path TEXT,
+            prompt TEXT,
+            notes_json TEXT,
+            model TEXT,
+            PRIMARY KEY (book_name, section_path)
+        )
+    """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS subtrees (
+            href TEXT PRIMARY KEY,
+            html TEXT,
+            size INTEGER
+        )
+    """
+    )
+    conn.commit()
+    return conn
+
+
+def get_cached_notes(
+    conn: sqlite3.Connection, book_name: str, section_path: str
+) -> list[genanki.Note]:
+    """Retrieves generated Anki notes from the database cache for a specific book section.
+
+    Args:
+        conn (sqlite3.Connection): Active database connection.
+        book_name (str): The name of the parsed book.
+        section_path (str): The specific path of the section within the book.
+
+    Returns:
+        list[genanki.Note]: A list of retrieved Anki notes. Returns an empty list if no notes are cached.
+    """
+    cursor = conn.cursor()
+    cursor.execute(
+        "SELECT notes_json FROM generated_notes WHERE book_name = ? AND section_path = ?",
+        (book_name, section_path),
+    )
+    row = cursor.fetchone()
+
+    if not row:
+        return []
+
+    notes_data = json.loads(row[0])
+    notes = []
+    for data in notes_data:
+        note = genanki.Note(
+            model=SIMPLE_ANKI_MODEL,
+            fields=[data["front"], data["back"]],
+            tags=data["tags"],
+        )
+        notes.append(note)
+    return notes
+
+
+def save_notes_to_cache(
+    conn: sqlite3.Connection,
+    book_name: str,
+    section_path: str,
+    prompt: str,
+    model: str,
+    notes: list[genanki.Note],
+):
+    """Saves generated Anki notes to the database cache.
+
+    Args:
+        conn (sqlite3.Connection): Active database connection.
+        book_name (str): The name of the parsed book.
+        section_path (str): The specific path of the section within the book.
+        prompt (str): The LLM prompt used for generation.
+        model (str): The AI model name used for generation.
+        notes (list[genanki.Note]): The list of generated notes to cache.
+    """
+    notes_data = [
+        {"front": note.fields[0], "back": note.fields[1], "tags": note.tags}  # type: ignore
+        for note in notes
+    ]
+    conn.execute(
+        """
+        INSERT OR REPLACE INTO generated_notes (book_name, section_path, prompt, model, notes_json)
+        VALUES (?, ?, ?, ?, ?)
+        """,
+        (book_name, section_path, prompt, model, json.dumps(notes_data)),
+    )
+    conn.commit()