AnkiForgeAI

AI-powered vocabulary flashcard pipeline for any language with automatic delivery to Anki. Language-agnostic via configurable YAML profiles (languages/{code}/language.yaml).

Built-in languages: 🇳🇴 Norwegian Bokmål (nb), 🇩🇪 German (de), 🇬🇧 English (en), 🇪🇸 Spanish (es).

What it does

1. Ingest — generates word candidates:
   • by topic via LLM ("20 food-related words, A2")
   • from a URL (web page extraction + LLM parsing)
2. Enrich — adds grammar forms, translation, example sentences.
3. Dedupe — checks duplicates against existing Anki notes and staging DB.
4. Media — generates mp3 audio (edge-tts) and downloads images (pick a provider: Unsplash, Pexels, Pixabay, or key-free Openverse).
5. Review — interactive review of ambiguous candidates (CLI).
6. Push — sends approved cards to Anki via AnkiConnect.

Architecture

Card statuses

pending → review → approved → pushed
              ↓
           skipped / suspended

• pending — just created, not yet enriched
• review — potential duplicates found, needs decision
• approved — ready for push to Anki
• pushed — already in Anki (anki_note_id set)
• skipped — discarded (reason in audit_log)
• suspended — postponed

Supported Languages

Language profiles live in languages/{code}/. Currently supported:

Select the active language with language: <code> in config.yaml, or pick it interactively via ankiforgeai setup.

Adding Your Language

1. Create languages/{code}/language.yaml using nb or de as template:

code: xx              # ISO 639-1
name: Language Name
article: true         # whether nouns have articles
pos_labels:           # POS → target language name
  noun: ...
  verb: ...
forms:                # grammar field schema per POS
  noun:
    - {key: gender, label: "Gender"}
    - {key: ...}
tts:                  # edge-tts voices
  voice_female: xx-XX-NameNeural
anki:
  deck_name: MyDeck
back_labels:          # labels in your native language
  translation: "Translation"

2. Copy prompts: cp prompts/*.md languages/{code}/prompts/
3. Adapt prompts for the target language
4. Minimal setup for a working language: language.yaml + topic_words.md

Installation

Requires Python 3.11+ and Anki desktop + the AnkiConnect addon.

As a tool (end users)

uv tool install ankiforgeai   # or: pipx install ankiforgeai / pip install ankiforgeai
ankiforgeai setup             # writes config.yaml in the current directory
ankiforgeai init              # creates the local DB and the Anki Note Type

config.yaml, data/, and media/ are created in whatever directory you run ankiforgeai from — cd into a project folder first (e.g. mkdir ~/ankiforgeai && cd ~/ankiforgeai).

init is safe to re-run: if the Note Type already exists in Anki, it pushes the current card templates and CSS to it instead of skipping, so re-run it after pulling an update that changes the card design. This also applies if an update renames the Note Type itself (anki.note_type in languages/{code}/language.yaml) — ankiforgeai push will fail with Note Type '...' не найден в Anki until you re-run init to create it.

From source (contributors)

git clone https://github.com/k0bad/AnkiForgeAi.git
cd AnkiForgeAi
uv venv
source .venv/bin/activate     # Linux/macOS
# .venv\Scripts\activate      # Windows
uv pip install -e ".[dev]"

# Configuration
cp .env.example .env
# edit .env — add your API keys

# Initialize (DB + Anki Note Type)
ankiforgeai init

Usage

# Generate 20 food-related words at A2 level
ankiforgeai ingest topic "mat" --count 20 --level A2

# Extract words from a web page
ankiforgeai ingest url "https://example.com/lesson"

# Run interactive review
ankiforgeai review

# Push approved cards to Anki
ankiforgeai push

# Sync Anki → local cache (daily)
ankiforgeai sync

# View stats
ankiforgeai stats

# Consistency check: enrich/images config toggles vs actual card data
ankiforgeai doctor

# Delete cards permanently (frees their id for reuse; irreversible if already pushed)
ankiforgeai delete <id> [<id> ...]

Automated Daily Cycle

# Generate → dedupe (AI-adjudicated)/enrich/media → push (no Telegram notification)
python scripts/daily_topic.py

# Preview what today's topic would be
python scripts/daily_topic.py --dry-run

# Override topic and count
python scripts/daily_topic.py --topic dyr --count 5 --no-push

# Full cycle incl. notifications (config.yaml -> notifications:) — use this for cron
./scripts/daily_topic.sh

daily_topic.py alone does not send notifications — pass --notify (which is what daily_topic.sh does) to fan the report out to every enabled channel in config.yaml -> notifications:. Today that's a generic webhook backend (POST JSON to any URL — n8n, Zapier, a custom bot gateway); see src/ankicards/notify/. Set up daily_topic.sh as a cron job for hands-free daily vocabulary generation with delivery to your configured channel.

Project Structure

src/ankicards/
├── models.py              # Card, POS, Status, Decision (Pydantic)
├── config.py              # config.yaml + language profiles
├── db.py                  # SQLite layer
├── cli.py                 # Typer CLI
├── pipeline.py            # Stage orchestration
├── llm.py                 # LLM client (OpenRouter/Anthropic)
├── dedupe.py              # Exact + fuzzy matching (rapidfuzz)
├── doctor.py              # Consistency check: enrich/images config vs card data
├── migrate_ids.py         # One-time UUID → sequential int id migration
├── ingest/
│   ├── url.py             # trafilatura + LLM
│   └── topic.py           # Topic-based generation
├── enrich/
│   ├── grammar.py         # Grammar forms per POS
│   ├── translation.py     # Translations
│   ├── examples.py        # Example sentences
│   └── pronunciation.py   # Pronunciation hints
├── media/
│   ├── tts.py             # edge-tts audio
│   └── images.py          # Image search: unsplash/pexels/pixabay/openverse
├── anki/
│   ├── connect.py         # HTTP client for AnkiConnect
│   ├── sync.py            # Anki → cache sync
│   └── notetype.py        # Note type definition
├── notify/
│   ├── base.py            # Notifier protocol
│   └── webhook.py         # Generic webhook backend (n8n, Zapier, ...)
└── review/
    ├── interactive.py     # Rich + questionary UI
    └── actions.py         # Non-interactive accept/skip/suspend/resume/edit/delete

languages/                 # Language profiles (YAML + prompts)
prompts/                   # Default prompts
scripts/                   # daily_topic, run_images
tests/
data/                      # DB, logs (gitignored)
media/                     # Audio, images (gitignored)

Roadmap

• Multi-language architecture
• Ingest by topic (LLM)
• Ingest from URL (trafilatura + LLM)
• Dedupe (rapidfuzz)
• Grammar enrichment
• edge-tts audio
• Pluggable image providers (Unsplash / Pexels / Pixabay / Openverse)
• Selectable pronunciation transcription (practical Cyrillic / IPA)
• AnkiConnect push & sync
• Interactive review CLI
• Full auto cycle (cron + dedupe + push + notify)
• Pluggable notification channels (generic webhook: n8n / Zapier / Hermes / any)
• AI-adjudicated dedupe — ambiguous fuzzy matches are judged by the LLM (same word vs. coincidentally similar), not blindly auto-accepted or left for a human by default
• PyPI publication — package and release workflow are ready (see DEVELOPER_GUIDE.md §12), pending one-time trusted-publisher setup on pypi.org

For Developers

See DEVELOPER_GUIDE.md for the full architecture reference, and CONTRIBUTING.md for contribution guidelines.