AI Tutor Sidebar for Anki

An intelligent AI-powered sidebar for Anki that provides instant explanations of your flashcards using OpenAI API capabilities.

Features • Installation • Usage • Configuration • Contributing

---

🎯 What is AI Tutor Sidebar?

AI Tutor Sidebar transforms your Anki study sessions by adding an intelligent AI assistant that can:

• See and understand images in your flashcards (using GPT-4 Vision)
• Explain complex concepts at an 11th-grade level
• Answer follow-up questions with context awareness
• Track your learning costs with real-time token counting

Think of it as having a patient, knowledgeable tutor sitting beside you, ready to explain anything you don't understand—without judgment, 24/7.

---

✨ Features

🖼️ Vision Support

• Analyzes images in your flashcards using OpenAI's ChatGPT 4.1 (OR GPT 5)
• Automatically detects when cards contain images
• Integrates visual information into explanations
• Supports JPG, PNG, GIF, and WebP formats

🧠 Smart AI Responses

• Concise explanations (2-4 sentences) focused on core concepts
• 11th-grade level understanding—precise but accessible
• Context-aware conversations that remember the current card
• Auto model switching: uses gpt-4o-mini for text, gpt-4o for images

🎨 User Interface

• Persistent dock widget that stays visible across screens
• Clean, modern design that doesn't interfere with Anki's UI
• Token counter showing real-time cost estimates
• Clear chat button to reset conversations
• Keyboard shortcuts for quick access (Ctrl+E, Ctrl+T)

💰 Cost Transparency

• Real-time token tracking with cost estimates
• Efficient model selection to minimize costs
• Typical cost: ~$0.002 per text explanation, ~$0.02 per image explanation

---

🚀 Installation

Prerequisites

• Anki 2.1.50 or newer
• OpenAI API key (Get one here)
• Internet connection for API calls

Quick Install

Option 1: Download Release (Recommended)

1. Download the add-on

   • Go to Releases
   • Download ai_tutor_sidebar.ankiaddon from the latest release
   • Or download directly: releases/ai_tutor_sidebar.ankiaddon

2. Install in Anki

   • Double-click ai_tutor_sidebar.ankiaddon
   • Click "Yes" when Anki asks to install
   • Restart Anki

Option 2: Build from Source

1. Clone the repository

   git clone https://github.com/yourusername/anki-ai-tutor.git
   cd anki-ai-tutor

2. Build the package

   ./build.sh
   # Or manually: zip -r ai_tutor_sidebar.ankiaddon __init__.py tutor_sidebar.py manifest.json config.json

3. Install

   • Double-click releases/ai_tutor_sidebar.ankiaddon
   • Restart Anki

4. Configure your API key

   • In Anki: Tools → Add-ons → AI Tutor Sidebar → Config
   • Paste your OpenAI API key in the api_key field:

     {
       "api_key": "sk-proj-YOUR_KEY_HERE",
       "model": "gpt-4o-mini-2024-07-18",
       "vision_model": "gpt-4o-2024-08-06",
       "auto_use_vision": true,
       "keyboard_shortcut": "Ctrl+E"
     }

   • Click OK and restart Anki

---

📖 Usage

Basic Workflow

1. Start studying any deck in Anki
2. Sidebar appears automatically on the right side
3. Click "✨ Explain" or press Ctrl+E to get an explanation
4. Ask follow-up questions in the chat box
5. Move to next card - conversation resets automatically

Keyboard Shortcuts

Shortcut	Action
Ctrl+E	Explain current card (opens sidebar if hidden)
Ctrl+T	Toggle sidebar visibility
Enter	Send chat message (when input is focused)

Example Interactions

Text Card:

Card: "Explain the Krebs Cycle"

You: [Click "Explain"]

AI: The Krebs cycle is a series of 8 enzymatic reactions in the
mitochondrial matrix that oxidizes acetyl-CoA to produce ATP,
NADH, and FADH2. It's the central metabolic pathway connecting
carbohydrate, fat, and protein metabolism.

Card with Diagram:

Card: [Diagram of heart anatomy]

You: [Click "Explain"] 📷

AI: The diagram shows the four-chambered heart with the right
atrium receiving deoxygenated blood from the vena cava, which
flows through the tricuspid valve to the right ventricle. Notice
how the left ventricle wall is thicker—it needs more muscle to
pump blood throughout the entire systemic circulation.

---

⚙️ Configuration

Access configuration: Tools → Add-ons → AI Tutor Sidebar → Config

For detailed configuration instructions, see docs/config.md.

Configuration Options

{
  "api_key": "",                           // Required: Your OpenAI API key
  "model": "gpt-4o-mini-2024-07-18",      // Model for text-only cards
  "vision_model": "gpt-4o-2024-08-06",    // Model for cards with images
  "api_url": "https://api.openai.com/v1/chat/completions",
  "auto_use_vision": true,                 // Auto-switch to vision model
  "keyboard_shortcut": "Ctrl+E"            // Customizable shortcut
}

Model Options

Model	Use Case	Input Cost	Output Cost	Speed
gpt-4o-mini	Text cards (default)	$0.15/1M tokens	$0.60/1M tokens	Fast
gpt-4o	Image cards	$2.50/1M tokens	$10/1M tokens	Medium
gpt-3.5-turbo	Budget option	$0.50/1M tokens	$1.50/1M tokens	Fastest

---

🏗️ Project Structure

anki-ai-tutor/
├── __init__.py              # Entry point for Anki
├── tutor_sidebar.py         # Main add-on logic
├── manifest.json            # Add-on metadata
├── config.json              # Default configuration
├── README.md                # This file
├── INSTALLATION.md          # Detailed install guide
├── CONTRIBUTING.md          # Contribution guidelines
├── LICENSE                  # MIT License
├── build.sh                 # Build script
├── docs/                    # Documentation
│   ├── config.md            # Configuration guide
│   └── ...                  # Developer docs
└── releases/                # Downloadable packages
    └── ai_tutor_sidebar.ankiaddon

---

🎓 Practical Benefits

For Medical Students

• Visual anatomy explanations - AI analyzes diagrams and relates them to text
• Pathophysiology breakdowns - Complex processes explained simply
• Quick clarifications during late-night study sessions

For Language Learners

• Grammar explanations with examples
• Cultural context for vocabulary
• Pronunciation tips (when applicable)

For STEM Students

• Formula derivations explained step-by-step
• Diagram analysis (circuits, molecules, processes)
• Concept connections between related topics

For Everyone

• Saves time - instant explanations vs. Googling
• Maintains flow - no context switching
• Personalized - adapts to your question style
• Available 24/7 - study whenever you want

---

🔒 Privacy & Security

• API calls are direct to OpenAI (no third-party servers)
• No data storage - conversations are ephemeral
• Local configuration - API key stored locally in Anki
• Open source - audit the code yourself

Important: Never share your API key publicly. Keep it in your local config only.

---

🐛 Troubleshooting

Sidebar doesn't appear

• Ensure you're in review mode (not browsing)
• Check that add-on is enabled: Tools → Add-ons
• Restart Anki

"API key not configured" error

• Go to Tools → Add-ons → AI Tutor Sidebar → Config
• Add your OpenAI API key
• Restart Anki

Vision not working

• Verify auto_use_vision: true in config
• Check image formats (JPG, PNG, GIF, WebP supported)
• Ensure images are in Anki's media folder

High costs

• Use gpt-4o-mini for text cards (default)
• Disable vision: set auto_use_vision: false
• Clear conversations frequently (click 🗑️ button)

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start for Developers

# Clone the repo
git clone https://github.com/yourusername/anki-ai-tutor.git
cd anki-ai-tutor

# Install development dependencies (optional)
pip install black flake8

# Make your changes
# ...

# Test in Anki
zip -r ai_tutor_sidebar.ankiaddon __init__.py tutor_sidebar.py manifest.json config.json

# Submit a pull request

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Built with Anki
• Powered by OpenAI GPT-4
• Inspired by the need for better study tools

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: your.email@example.com

---

Made with ❤️ for better learning

⭐ Star this repo if it helps your studies! ⭐

⬆ Back to Top