ankinote

AI-powered Anki card generator — vocabulary, phrases, sentences, and STEM concepts

📖 About

ankinote is an automated Anki flashcard generator that uses litellm to support a wide range of AI providers — Gemini, GPT, Claude, DeepSeek, and more — for generating definitions, examples, mnemonics, and images, then syncs directly with Anki through AnkiConnect.

✨ Features

• 🤖 Multi-Provider AI - Powered by litellm, supporting Gemini, GPT, Claude, DeepSeek, and more for text and image generation
• 🔊 Audio Generation - Text-to-Speech using Google Cloud TTS API
• 🖼️ AI Image Generation - Automatic image generation via Google AI (Gemini)
• 🔄 Direct Anki Sync - Seamless integration with Anki through AnkiConnect plugin
• 📝 Dual-Direction Cards - Supports both word→definition and definition→word learning modes
• 🎨 Beautiful Templates - Built-in Light/Dark mode responsive card templates
• ⚡ Batch Processing - Generate multiple cards from word lists efficiently
• 🌐 Multi-Language - Japanese, English (US), and extensible for more languages
• 🧮 STEM Concepts - Math, science, and programming concept cards with MathJax rendering

🚀 Quick Start

Prerequisites

• Python 3.13+
• uv package manager
• Anki with AnkiConnect plugin installed
• An API key for at least one AI provider (see Configuration below)

Installation

# Install from PyPI
uv pip install ankinote-ai

# Or install the CLI as an isolated uv tool
uv tool install ankinote-ai

# Configure API credentials
# Create a .env file in your working directory and add your API keys

Configuration

Create a .env file with your API keys. At minimum, you need one AI provider key and the Google TTS key:

# At least one AI provider (for text and image generation)
DEEPSEEK_API_KEY=your_deepseek_key
# GEMINI_API_KEY=your_gemini_key
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

# Google Cloud TTS (for audio generation)
GOOGLE_TTS_KEY=your_tts_api_key

# AnkiConnect (defaults to http://localhost:8765)
ANKI_CONNECT_URL=http://localhost:8765

ankinote CLI - Usage Guide

Overview

The ankinote CLI is a powerful command-line tool for generating AI-powered Anki flashcards with automatic definitions, examples, pronunciations, audio, and images.

Commands

The CLI currently provides four card types. Run ankinote <type> --help or ankinote <type> <command> --help for the complete, current option list.

Word cards

# Create the word note type and deck in Anki
ankinote word init

# Add one word
ankinote word add serendipity

# Add multiple words, either as arguments or from a file
ankinote word batch serendipity ephemeral eloquent
ankinote word batch --file words.txt

Phrase cards

ankinote phrase init
ankinote phrase add "look after"
ankinote phrase batch "focus on" "call off"
ankinote phrase batch --file phrases.txt

Sentence cards

The sentence argument should be in the native language; the target-language version is generated for the card back.

ankinote sentence init
ankinote sentence add "我今天起晚了。"
ankinote sentence batch --file sentences.txt

STEM cards

ankinote stem init
ankinote stem add "What is a derivative?"
ankinote stem batch --file topics.txt

Common options

Language-learning commands accept --native, --target, and --llm. Batch commands also accept --file and --rpm. STEM commands accept --llm, and can additionally configure diagram generation with --image-model and --image-size.

For example:

ankinote word add serendipity --native English --target 'Chinese(Simplified)'
ankinote word batch --file words.txt --rpm 30
ankinote stem add "State Bayes' theorem" --image-size 1024

Troubleshooting

Error: "AnkiConnect not available"

• Make sure Anki is running
• Check that AnkiConnect add-on is installed
• Verify AnkiConnect is listening on port 8765

Error: "No images found"

• Some STEM topics may not need a generated diagram
• Check the configured image model with ankinote stem add --help

Error: "API key not found"

• Check your configuration file
• Ensure environment variables are set
• Verify API keys are valid

Getting Help

# General help
ankinote --help

# Command-specific help
ankinote word --help
ankinote phrase --help
ankinote sentence --help
ankinote stem --help
ankinote word batch --help

📦 Tech Stack

• Language: Python 3.13+
• Package Manager: uv
• AI/ML: litellm (Gemini, GPT, Claude, DeepSeek, etc.)
• TTS: Google Cloud Text-to-Speech API
• Image Generation: Google AI (Gemini)
• Anki Integration: AnkiConnect
• Card Templates: HTML + CSS

🔧 API Services

AI Provider (via litellm)

• Text generation for definitions, examples, and mnemonics
• Image generation (Gemini) for card visuals
• Supports Gemini, GPT, Claude, DeepSeek, Qwen, and more

Google Cloud TTS

• High-quality audio generation
• Multiple voice options

AnkiConnect

• Direct communication with Anki
• Real-time card creation
• Deck management

📝 Usage Examples

Single Word

from ankinote import CardGenerator

generator = CardGenerator()
card = generator.generate("ephemeral")
generator.add_to_anki(card, deck="Vocabulary")

Batch Processing

words = ["ephemeral", "serendipity", "eloquent"]
for word in words:
    card = generator.generate(word)
    generator.add_to_anki(card)

🛠️ Development

# Clone the repository
git clone https://github.com/ignity21/ankinote-ai.git
cd ankinote-ai

# Install the project and development dependencies
uv sync

# Run tests
make test

# Format code
make format

# Type checking
make check

Documentation

• Note Types
• Skill — for using ankinote with AI coding assistants

📄 License

MIT License - see LICENSE file for details