🧠 Anki Sentence Miner

AI-powered sentence generation for Anki — Turn your vocabulary cards into natural, contextual sentences using Google's Gemini AI.

Sentence Miner bridges the gap between memorizing isolated words and understanding them in real conversation. It reads your vocabulary deck, identifies which words you know well and which you're still learning, then generates sentences that mix them together — just like how you'd encounter them in the real world.

✨ Features

Two Card Types

You control the mix with a slider (default: 70% cloze / 30% new word).

Smart Word Selection

The add-on doesn't just randomly pick words. It uses several strategies to create better sentences:

• Tag-Aware Sampling — If your vocabulary cards are tagged (e.g., food, travel, JLPT_N3), the generator groups words by topic and creates thematically coherent sentences instead of random word combinations.
• Priority-Weighted New Words — Words you struggle with (high lapse count, low ease factor) or haven't seen yet are prioritized for introduction. This means the sentences focus on words that need the most reinforcement.
• Confidence Threshold — You define what "known" means by setting a minimum review interval (e.g., 7 days). Cards above that interval are considered known; everything below is a candidate for introduction.

Performance Optimized

• In-Memory Cache — Word lists are cached for 5 minutes, so hitting "Generate" multiple times doesn't re-query your entire deck each time.
• Note-Level Deduplication — Fetches each note only once even if it has multiple cards (e.g., forward + reverse cards), preventing duplicate words.
• Background Generation — API calls run in a background thread so Anki's UI stays responsive.

Natural Sentences

The Gemini prompt is carefully crafted to produce sentences that:

• Sound like something a native speaker would actually say
• Fit daily conversation contexts
• Match the learner's current level
• Are NOT awkward combinations of random vocabulary

Natural Grammar & Conjugation

• Context-Aware Conjugation — The AI understands that words in your deck are dictionary forms (lemmas). It automatically conjugates verbs and adjusts nouns/adjectives to fit the sentence context naturally (e.g., changing "go" to "went").
• Smart Cloze Matching — Even when a word is conjugated, the cloze deletion handles it correctly, hiding the actual used form while preserving the underlying concept.
• Optional Grammar Breakdown — Can't figure out why a word changed its ending? Enable "Grammar Breakdown" to get a word-by-word analysis of particles, tense, and sentence structure added to your card notes.

📦 Installation

1. Locate Your Add-ons Folder

In Anki, go to Tools → Add-ons → View Files Folder (or open the folder manually):

2. Copy the Add-on

Copy or symlink the entire anki-sentence-miner folder into addons21/:

addons21/
└── anki-sentence-miner/
    ├── __init__.py
    ├── config.json
    ├── config.md
    ├── manifest.json
    ├── sentence_generator.py
    ├── note_manager.py
    └── ui.py

3. Restart Anki

Close and reopen Anki. You should see a new Sentence Miner submenu under Tools.

🔑 Setting Up Your Gemini API Key (Free)

On first launch, the add-on will prompt you to enter an API key. You can also access this anytime via Tools → Sentence Miner → API Key Setup.

1. Go to Google AI Studio — API Keys
2. Sign in with your Google account
3. Click "Create API Key"
4. Select any Google Cloud project (or create one — it's free, no credit card required)
5. Copy the key and paste it into the add-on dialog
6. Click "Test Key" to verify it works
7. Click "Save"

Free Tier Limits

This is more than enough — generating 5 sentences uses 1 request.

🚀 Usage

Generating Sentences

1. Go to Tools → Sentence Miner → Generate Sentences
2. Configure the settings:

3. Click ⚡ Generate Sentences
4. Review the generated sentences in the preview table
5. Uncheck any sentences you don't want
6. Click ✅ Add Selected to Deck

Settings Are Remembered

All settings are saved automatically and restored next time you open the dialog.

📋 Card Structure

AI Sentence (Basic)

Front shows the sentence with a hint button for new words. Back reveals the translation and word definitions.

AI Sentence Cloze

Front shows the sentence with blanks. Back reveals the hidden words and translation.

Both card types include styled templates with:

• Clean typography (Noto Sans family)
• Dark mode support
• Color-coded new words (orange) and cloze words (blue)

⚙️ Configuration

You can edit the config via Tools → Add-ons → Sentence Miner → Config, or directly in config.json:

{
    "gemini_api_key": "",
    "target_language": "",
    "native_language": "",
    "source_deck": "",
    "sentence_deck": "AI Sentences",
    "known_interval_days": 7,
    "known_word_percentage": 70,
    "cloze_percentage": 70,
    "sentences_per_batch": 5,
    "gemini_model": "gemini-flash-latest"
}

See config.md for detailed explanations of each setting.

🧩 How It Works Under the Hood

Word Classification

Your Vocabulary Deck
        │
        ├── Cards with interval >= threshold ──→ KNOWN WORDS
        │     (e.g., interval >= 7 days)         Used for cloze blanks
        │                                         and sentence scaffolding
        │
        └── Cards with interval < threshold ──→ NEW/WEAK WORDS
              (new, learning, or young cards)     Introduced in context
              Sorted by priority:                 with known-word support
              • High lapses = higher priority
              • Low ease = higher priority
              • Brand new = high priority

Smart Sampling Pipeline

All Known Words (e.g., 3,000)
        │
        ├── Group by Anki tags
        │     food: [rice, fish, cook, ...]
        │     travel: [hotel, ticket, map, ...]
        │     JLPT_N3: [決める, 届ける, ...]
        │
        ├── Pick 1-2 focus tag groups
        │
        ├── Sample 70% from focus groups ──→ Thematic coherence
        └── Sample 30% from others ────────→ Variety
                                                │
                                        50 words to prompt

All New Words (e.g., 500)
        │
        ├── Calculate priority score per word
        │     score = lapses×2 + (3-ease) + new_bonus
        │
        ├── Sort by priority (with jitter)
        │
        └── Sample from top candidates ──→ 20 words to prompt

Generation Flow

[Smart-sampled words] ──→ [Gemini Prompt] ──→ [API Call]
                                                  │
                                           [JSON Response]
                                                  │
                                    ┌─────────────┼─────────────┐
                                    │                           │
                              Cloze Cards               New Word Cards
                           [[word]] → {{c1::word}}    **word** → <b>word</b>
                                    │                           │
                                    └─────────────┬─────────────┘
                                                  │
                                         [Preview Table]
                                                  │
                                    [User accepts/rejects]
                                                  │
                                         [Add to Deck]

🗂️ Project Structure

anki-sentence-miner/
├── __init__.py              # Entry point — menu registration, first-run check
├── config.json              # Default settings
├── config.md                # User-facing config documentation
├── manifest.json            # Anki add-on metadata
├── sentence_generator.py    # Word retrieval, smart sampling, Gemini API
├── note_manager.py          # Deck/note type creation, card templates
├── ui.py                    # PyQt dialogs (API key wizard + generator)
└── README.md                # This file

🤝 Dependencies

• Anki 2.1.55+ (uses modern Qt6/PyQt6 APIs)
• google-genai Python package (auto-installed on first run if missing)
• A free Gemini API key

📝 License

MIT License — feel free to use, modify, and distribute.