anki_generator 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76f0b2892551729509fe0d6568b9e78994ee6b0e4b8001aafe904a76a6fe6418
-  data.tar.gz: b4da700e556de1d07a7ebf8dc82859f2a14644ed18c5f35c0c8a22527e474bd4
+  metadata.gz: c8124d9ca11c2259790dfabfb10f1fab725cfa4889300d6bf91353cce45b9604
+  data.tar.gz: 6be84b8c3d8d430c91ad7c02f0fb063cc3e5ea27c35ee946d2c3ea091aedb994
 SHA512:
-  metadata.gz: c8146c58bf49b3d77a93f739eb2f94669c23c2d66e62370c4dc755541bb087900e2516d331edd9e6b9ae26ff813f56890010f1edf89bfce05131166b95362687
-  data.tar.gz: cbd79503bfd3b4d33b50db4398fbb4ff3d742e355e3f0113a061eacf76fc04d20d22e5402109b8c5c82dccb46864904f3b28a8a055671ff683335023f7007952
+  metadata.gz: 1bae0bd4aad23ab158031ab876385a10660559b5a9acca2be6a4ba932a2851e7c468e5b18d5db33f57724198fe8fda3e6478dfec05718f1a15703fd3a188bf1b
+  data.tar.gz: 25c74048b6dcd2428aab8f879cfebd41b81d7264bd3a5f8e8805530563b7099b9ee72be220e97fe1af070aa44460a084d20fa8010ea658e686a031415c1c2f90

data/README.md

@@ -0,0 +1,428 @@
+# Anki Generator
+
+A Ruby tool to generate Anki .apkg files from YAML definitions with AI-powered content generation using OpenRouter and file attachment support.
+
+## Features
+
+- **AI-Powered Generation**: Create flashcards using OpenRouter API with multiple AI models (GPT, Claude, Llama, etc.)
+- **File Attachment Support**: Attach code files, documentation, or entire directories for context-aware generation
+- **Prompt File Support**: Use text files as prompts for better organization and reusability
+- **Multiple Input Methods**: Generate from YAML files, direct prompts, or file attachments
+- **Intelligent Content Processing**: Automatic text file detection, size limits, and binary file filtering
+- **Direct Prompt-to-Deck Generation**: Create decks in one command without intermediate files
+- **Sync Functionality**: Merge new AI-generated cards with existing decks
+- **Flexible Configuration**: Multiple difficulty levels, context settings, and model selection
+- **Comprehensive CLI**: Full command-line interface with extensive options
+
+## Installation
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   bundle install
+   ```
+
+3. Set up your OpenRouter API key:
+   ```bash
+   cp .env.example .env
+   # Edit .env and add your OpenRouter API key
+   ```
+
+## Usage
+
+### Quick Start - Generate from Prompt
+
+The fastest way to create flashcards is directly from a prompt:
+
+```bash
+# Generate flashcards and create deck in one step
+./bin/anki_generator prompt_to_deck "Ruby programming basics" "Ruby Deck" ruby_deck.apkg --api_key YOUR_API_KEY
+
+# Generate from a prompt file with code attachments
+./bin/anki_generator prompt_to_deck study_prompt.txt "Code Study" code_deck.apkg --prompt-file --attach ./src --api_key YOUR_API_KEY
+
+# Generate just the YAML file first
+./bin/anki_generator generate_yaml "JavaScript fundamentals" js_cards.yaml --api_key YOUR_API_KEY --count 15
+
+# Then create the deck
+./bin/anki_generator generate "JS Deck" js_cards.yaml js_deck.apkg
+```
+
+### Traditional Usage
+
+Generate a deck from a YAML file:
+
+```bash
+./bin/anki_generator generate "My Deck" input/input.yaml my_deck.apkg
+```
+
+### AI-Powered Generation
+
+Create an AI generation template:
+
+```bash
+./bin/anki_generator create_ai_template my_ai_deck.yaml
+```
+
+Generate a deck with AI content:
+
+```bash
+./bin/anki_generator generate "AI Deck" my_ai_deck.yaml ai_deck.apkg --api_key YOUR_API_KEY
+```
+
+### Advanced Options
+
+```bash
+# Use a specific AI model
+./bin/anki_generator prompt_to_deck "Python basics" "Python Deck" python.apkg --model anthropic/claude-3-sonnet
+
+# Set difficulty and count
+./bin/anki_generator generate_yaml "Advanced algorithms" algo.yaml --difficulty hard --count 20
+
+# Add context for better generation
+./bin/anki_generator prompt_to_deck "Machine Learning" "ML Deck" ml.apkg --context "For computer science students" --difficulty medium
+
+# Use prompt from file
+./bin/anki_generator generate_yaml prompt.txt output.yaml --prompt-file
+
+# Attach files for context
+./bin/anki_generator prompt_to_deck "Explain this code" "Code Deck" code.apkg --attach src/main.rb --attach config.yml
+
+# Attach entire directory
+./bin/anki_generator generate_yaml "Create cards about this project" project.yaml --attach ./src --attach ./docs
+
+# Combine file prompt with attachments
+./bin/anki_generator prompt_to_deck prompt.txt "My Deck" deck.apkg --prompt-file --attach ./examples
+
+# Save intermediate YAML file
+./bin/anki_generator prompt_to_deck "React hooks" "React Deck" react.apkg --save-yaml
+
+# Sync with existing deck
+./bin/anki_generator generate "My Deck" input.yaml output.apkg --sync_with existing_deck.yaml
+
+# Test API connection
+./bin/anki_generator test_api --api_key YOUR_API_KEY
+```
+
+## CLI Commands
+
+### `prompt_to_deck` - One-Step Generation
+Generate flashcards from a prompt and create the deck immediately:
+```bash
+anki_generator prompt_to_deck PROMPT DECK_NAME OUTPUT_FILE [options]
+```
+
+**Options:**
+- `--attach FILE_OR_DIR [FILE_OR_DIR...]` - Attach files or directories for context
+- `--prompt-file` - Treat PROMPT as a file path to read from
+- `--save-yaml` - Save intermediate YAML file
+- `--api-key API_KEY` - OpenRouter API key
+- `--model MODEL` - AI model to use
+- `--difficulty LEVEL` - Difficulty level (easy, medium, hard)
+- `--count N` - Number of flashcards to generate
+- `--context TEXT` - Additional context for better generation
+
+### `generate_yaml` - Generate YAML from Prompt
+Create a YAML file from a prompt for later use:
+```bash
+anki_generator generate_yaml PROMPT OUTPUT_YAML [options]
+```
+
+**Options:**
+- `--attach FILE_OR_DIR [FILE_OR_DIR...]` - Attach files or directories for context
+- `--prompt-file` - Treat PROMPT as a file path to read from
+- `--api-key API_KEY` - OpenRouter API key
+- `--model MODEL` - AI model to use
+- `--difficulty LEVEL` - Difficulty level (easy, medium, hard)
+- `--count N` - Number of flashcards to generate
+- `--context TEXT` - Additional context for better generation
+
+### `generate` - Create Deck from YAML
+Generate an Anki deck from an existing YAML file:
+```bash
+anki_generator generate DECK_NAME YAML_FILE OUTPUT_FILE [options]
+```
+
+### `create_ai_template` - Create Template
+Create a template YAML file for AI generation:
+```bash
+anki_generator create_ai_template TEMPLATE_FILE
+```
+
+### `test_api` - Test Connection
+Test your OpenRouter API connection:
+```bash
+anki_generator test_api [options]
+```
+
+## File Attachments
+
+The Anki Generator supports attaching files and directories to provide context for AI generation. This is particularly useful for:
+
+- Creating flashcards about specific code files
+- Generating questions based on documentation
+- Learning from configuration files or data structures
+- Creating study materials from existing project files
+
+### Supported File Types
+
+The tool automatically processes text-based files including:
+- Code files: `.rb`, `.py`, `.js`, `.ts`, `.java`, `.cpp`, `.c`, `.go`, `.rs`, etc.
+- Documentation: `.md`, `.txt`, `.rst`, `.adoc`, `.org`
+- Configuration: `.yaml`, `.yml`, `.json`, `.xml`, `.toml`
+- Web files: `.html`, `.css`, `.scss`
+- Scripts: `.sh`, `.bat`, `.ps1`
+
+### File Size Limits
+
+- Maximum individual file size: 1MB
+- Maximum total attachment size: 5MB
+- Files exceeding limits are automatically skipped with warnings
+
+### Usage Examples
+
+```bash
+# Attach a single file
+./bin/anki_generator prompt_to_deck "Explain this Ruby class" "Ruby Deck" ruby.apkg --attach person.rb
+
+# Attach multiple files
+./bin/anki_generator generate_yaml "Create cards about these configs" config.yaml --attach database.yml --attach routes.rb --attach Gemfile
+
+# Attach entire directories (processes all text files)
+./bin/anki_generator prompt_to_deck "Study this codebase" "Project Deck" project.apkg --attach ./src --attach ./lib
+
+# Combine with prompt files
+./bin/anki_generator generate_yaml study_prompt.txt output.yaml --prompt-file --attach ./examples --attach README.md
+
+# Use context and attachments together
+./bin/anki_generator prompt_to_deck "Advanced Ruby patterns" "Advanced Ruby" advanced.apkg \
+  --attach ./lib --context "Focus on metaprogramming and DSL patterns" --difficulty hard
+```
+
+### How Attachments Work
+
+1. **File Processing**: The tool scans attached files and directories for text-based content
+2. **Content Inclusion**: File contents are included in the AI prompt with clear file boundaries
+3. **Smart Generation**: The AI uses the file content to create more accurate and specific flashcards
+4. **Automatic Filtering**: Binary files and oversized files are automatically skipped
+
+### Best Practices
+
+- **Be Specific**: Attach only relevant files to avoid overwhelming the AI with too much context
+- **Use Descriptive Prompts**: Combine attachments with clear prompts about what you want to learn
+- **Organize Files**: Group related files in directories for easier attachment
+- **Check File Sizes**: Large files will be skipped, so break them down if needed
+
+## YAML Formats
+
+### Traditional Format
+
+```yaml
+- front: "What is Big O notation?"
+  back: "Big O notation describes the limiting behavior of a function..."
+
+- front: "Define a graph"
+  back: "A graph is a collection of vertices connected by edges"
+```
+
+### AI Generation Format
+
+```yaml
+ai_generation:
+  topics:
+    - "Ruby programming fundamentals"
+    - "Object-oriented programming"
+  context: "Beginner-friendly programming concepts"
+  difficulty: "medium"  # easy, medium, hard
+  count: 10
+  save_generated: true
+
+# Optional manual cards
+cards:
+  - front: "Manual question"
+    back: "Manual answer"
+```
+
+## Configuration
+
+### Environment Variables
+
+- `OPENROUTER_API_KEY`: Your OpenRouter API key
+- `OPENROUTER_DEFAULT_MODEL`: Default model to use (optional)
+
+### Supported Models
+
+The tool supports all models available through OpenRouter:
+
+- OpenAI: `openai/gpt-4`, `openai/gpt-3.5-turbo`
+- Anthropic: `anthropic/claude-3-sonnet`, `anthropic/claude-3-haiku`
+- Meta: `meta-llama/llama-3.1-8b-instruct`
+- And many more...
+
+## Examples
+
+### Quick Examples
+
+```bash
+# Generate 10 Python flashcards
+./bin/anki_generator prompt_to_deck "Python data structures" "Python Deck" python.apkg
+
+# Generate 20 hard-level algorithm cards
+./bin/anki_generator generate_yaml "Sorting algorithms" algo.yaml --difficulty hard --count 20
+
+# Create deck with context
+./bin/anki_generator prompt_to_deck "React components" "React Deck" react.apkg --context "For beginners learning React"
+
+# Study a specific code file
+./bin/anki_generator prompt_to_deck "Create flashcards about this Ruby class" "Ruby Class Deck" ruby_class.apkg --attach person.rb
+
+# Learn from project documentation
+./bin/anki_generator generate_yaml "Study this API documentation" api_study.yaml --attach README.md --attach docs/api.md
+
+# Comprehensive project study
+./bin/anki_generator prompt_to_deck "Help me understand this codebase structure and patterns" "Codebase Study" study.apkg \
+  --attach ./src --attach ./lib --attach README.md --context "Focus on architecture and design patterns"
+```
+
+### File Attachment Examples
+
+```bash
+# Study a single Ruby file
+./bin/anki_generator prompt_to_deck "What does this code do?" "Code Analysis" analysis.apkg --attach calculator.rb
+
+# Learn from configuration files
+./bin/anki_generator generate_yaml "Explain these configurations" config_study.yaml --attach config/database.yml --attach config/routes.rb
+
+# Study an entire project
+./bin/anki_generator prompt_to_deck "Create comprehensive study cards for this project" "Project Study" project.apkg \
+  --attach ./app --attach ./lib --attach Gemfile --attach README.md
+
+# Use prompt file with attachments
+echo "Create flashcards focusing on the class structure and methods in the attached files" > study_prompt.txt
+./bin/anki_generator generate_yaml study_prompt.txt class_study.yaml --prompt-file --attach ./models
+
+# Advanced usage with multiple options
+./bin/anki_generator prompt_to_deck prompt_file.txt "Advanced Study" advanced.apkg \
+  --prompt-file --attach ./src --attach ./docs --difficulty hard --count 25 \
+  --context "Focus on advanced patterns and best practices" --save-yaml
+```
+
+### Example YAML Files
+
+See the `input/` directory for example YAML files, or create examples with `rake examples`:
+
+- `examples/study_prompt.txt` - Example prompt file
+- `examples/example_class.rb` - Example Ruby code for attachments
+- `examples/manual_cards.yaml` - Traditional format example
+- `input/ai_generation_example.yaml` - AI generation example
+- `input/algorithms_ai.yaml` - Computer science topics
+- `input/input.yaml.example` - Traditional format
+
+## Development
+
+## Development
+
+### Quick Start for Developers
+
+```bash
+# Clone and setup
+git clone <repository-url>
+cd anki_generator
+rake setup                     # Install dependencies and create examples
+
+# Run tests
+rake test                      # Run all tests
+rake test_file[cli]           # Run specific test
+
+# Try the examples
+rake demo_api                 # Test API connection
+rake examples                 # Create example files
+rake demo_attachments         # Demo with file attachments
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+rake test
+
+# Run specific test file
+rake test_file[cli]              # runs tests/test_cli.rb
+rake test_file[file_processor]   # runs tests/test_file_processor.rb
+
+# Run tests with coverage
+rake test_coverage
+```
+
+### Development Commands
+
+```bash
+# Setup development environment
+rake setup                      # Install deps and create examples
+
+# Build and install
+rake build                      # Build gem
+rake install_local             # Build and install gem locally
+rake clean                     # Clean build artifacts
+
+# Code quality
+rake lint                      # Run RuboCop linter
+rake lint_fix                  # Auto-fix linting issues
+
+# Demos and examples
+rake examples                  # Create example files
+rake demo_prompt              # Demo prompt generation
+rake demo_attachments         # Demo file attachment features
+rake demo_api                 # Test API connection
+
+# Utilities
+rake help                     # Show CLI help
+rake version                  # Show version info
+rake release_prep             # Prepare for release
+```
+
+### Project Structure
+
+```
+├── lib/
+│   ├── anki_generator.rb      # Main generator class
+│   ├── openrouter_client.rb   # OpenRouter API client
+│   ├── anki_cli.rb           # CLI interface
+│   └── file_processor.rb     # File attachment processing
+├── bin/
+│   └── anki_generator         # CLI executable
+├── tests/                     # Test files
+├── input/                     # Example YAML files
+└── README.md
+```
+
+## API Integration
+
+The tool integrates with OpenRouter to provide access to multiple AI models. You can:
+
+1. Generate flashcards on any topic
+2. Specify difficulty levels
+3. Provide context for better generation
+4. Choose from various AI models
+5. Control the number of cards generated
+
+## Sync Functionality
+
+The sync feature allows you to:
+
+- Merge new AI-generated cards with existing manual cards
+- Prevent duplicate cards (based on front text)
+- Maintain version control of your flashcard sets
+- Incrementally build large decks
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.

data/bin/anki_generator

@@ -1,15 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'thor'
-require_relative '../lib/anki_generator'
-
-class AnkiCLI < Thor
-  desc 'generate DECK_NAME YAML_FILE OUTPUT_FILE', 'Generate an Anki .apkg deck from a YAML file'
-  def generate(deck_name, yaml_file, output_file)
-    anki_generator = AnkiGenerator.new(name: deck_name, deck_file: yaml_file)
-    anki_generator.generate_apkg(output_path: output_file)
-    puts "Anki deck '#{deck_name}' has been successfully created as #{output_file}!"
-  end
-end
+require_relative '../lib/anki_cli'
 
 AnkiCLI.start(ARGV)

data/lib/anki_cli.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'dotenv/load'
+require_relative 'anki_generator'
+require_relative 'file_processor'
+
+class AnkiCLI < Thor
+  desc 'generate DECK_NAME YAML_FILE OUTPUT_FILE', 'Generate an Anki .apkg deck from a YAML file'
+  option :api_key, type: :string, desc: 'OpenRouter API key (or set OPENROUTER_API_KEY env var)'
+  option :model, type: :string, default: 'openai/gpt-3.5-turbo', desc: 'AI model to use'
+  option :sync_with, type: :string, desc: 'Existing YAML file to sync with'
+  def generate(deck_name, yaml_file, output_file)
+    anki_generator = AnkiGenerator.new(
+      name: deck_name, 
+      deck_file: yaml_file,
+      api_key: options[:api_key],
+      model: options[:model]
+    )
+    
+    anki_generator.sync_with_existing_deck(options[:sync_with]) if options[:sync_with]
+    anki_generator.generate_apkg(output_path: output_file)
+    
+    puts "Anki deck '#{deck_name}' has been successfully created as #{output_file}!"
+    puts "Total cards: #{anki_generator.cards.length}"
+  end
+
+  desc 'generate_yaml PROMPT OUTPUT_YAML', 'Generate a YAML file from a prompt using AI'
+  option :api_key, type: :string, desc: 'OpenRouter API key (or set OPENROUTER_API_KEY env var)'
+  option :model, type: :string, default: 'openai/gpt-3.5-turbo', desc: 'AI model to use'
+  option :difficulty, type: :string, default: 'medium', desc: 'Difficulty level (easy, medium, hard)'
+  option :count, type: :numeric, default: 10, desc: 'Number of flashcards to generate'
+  option :context, type: :string, desc: 'Additional context for better generation'
+  option :attach, type: :array, desc: 'Attach files or directories for context'
+  option :prompt_file, type: :boolean, default: false, desc: 'Treat PROMPT as a file path to read from'
+  def generate_yaml(prompt, output_yaml)
+    begin
+      require_relative 'openrouter_client'
+      client = OpenRouterClient.new(api_key: options[:api_key], model: options[:model])
+      
+      # Handle prompt from file
+      actual_prompt = if options[:prompt_file]
+        puts "📄 Reading prompt from file: #{prompt}"
+        FileProcessor.read_prompt_from_file(prompt)
+      else
+        prompt
+      end
+      
+      # Process attachments
+      attachments = nil
+      if options[:attach]
+        puts "📎 Processing attachments..."
+        attachments = FileProcessor.process_attachments(options[:attach])
+      end
+      
+      puts "Generating flashcards for: #{actual_prompt[0..100]}#{'...' if actual_prompt.length > 100}"
+      puts "Model: #{client.model}"
+      puts "Difficulty: #{options[:difficulty]}"
+      puts "Count: #{options[:count]}"
+      puts "Attachments: #{attachments&.length || 0} file(s)" if attachments
+      puts "Generating..."
+      
+      # Generate flashcards using the prompt as topics
+      cards = client.generate_multiple_flashcards(
+        topics: [actual_prompt],
+        context: options[:context],
+        difficulty: options[:difficulty],
+        count: options[:count],
+        attachments: attachments
+      )
+      
+      # Create YAML structure
+      yaml_content = {
+        'ai_generation' => {
+          'topics' => [actual_prompt],
+          'context' => options[:context],
+          'difficulty' => options[:difficulty],
+          'count' => options[:count],
+          'save_generated' => false
+        },
+        'cards' => cards
+      }
+      
+      # Write to file
+      File.open(output_yaml, 'w') do |file|
+        file.write(yaml_content.to_yaml)
+      end
+      
+      puts "✅ Generated #{cards.length} flashcards!"
+      puts "YAML file created: #{output_yaml}"
+      puts ""
+      puts "Preview of generated cards:"
+      cards.first(3).each_with_index do |card, index|
+        puts "#{index + 1}. #{card['front']}"
+        puts "   → #{card['back'][0..100]}#{'...' if card['back'].length > 100}"
+        puts ""
+      end
+      
+      puts "To create an Anki deck, run:"
+      puts "  anki_generator generate \"My Deck\" #{output_yaml} my_deck.apkg"
+      
+    rescue => e
+      puts "❌ Error generating flashcards: #{e.message}"
+      exit 1
+    end
+  end
+
+  desc 'prompt_to_deck PROMPT DECK_NAME OUTPUT_FILE', 'Generate flashcards from prompt and create deck in one step'
+  option :api_key, type: :string, desc: 'OpenRouter API key (or set OPENROUTER_API_KEY env var)'
+  option :model, type: :string, default: 'openai/gpt-3.5-turbo', desc: 'AI model to use'
+  option :difficulty, type: :string, default: 'medium', desc: 'Difficulty level (easy, medium, hard)'
+  option :count, type: :numeric, default: 10, desc: 'Number of flashcards to generate'
+  option :context, type: :string, desc: 'Additional context for better generation'
+  option :save_yaml, type: :boolean, default: false, desc: 'Save intermediate YAML file'
+  option :attach, type: :array, desc: 'Attach files or directories for context'
+  option :prompt_file, type: :boolean, default: false, desc: 'Treat PROMPT as a file path to read from'
+  def prompt_to_deck(prompt, deck_name, output_file)
+    begin
+      require_relative 'openrouter_client'
+      client = OpenRouterClient.new(api_key: options[:api_key], model: options[:model])
+      
+      # Handle prompt from file
+      actual_prompt = if options[:prompt_file]
+        puts "📄 Reading prompt from file: #{prompt}"
+        FileProcessor.read_prompt_from_file(prompt)
+      else
+        prompt
+      end
+      
+      # Process attachments
+      attachments = nil
+      if options[:attach]
+        puts "📎 Processing attachments..."
+        attachments = FileProcessor.process_attachments(options[:attach])
+      end
+      
+      puts "🚀 Generating Anki deck from prompt: #{actual_prompt[0..100]}#{'...' if actual_prompt.length > 100}"
+      puts "Model: #{client.model}"
+      puts "Difficulty: #{options[:difficulty]}"
+      puts "Count: #{options[:count]}"
+      puts "Attachments: #{attachments&.length || 0} file(s)" if attachments
+      puts ""
+      
+      # Generate flashcards
+      puts "Generating flashcards..."
+      cards = client.generate_multiple_flashcards(
+        topics: [actual_prompt],
+        context: options[:context],
+        difficulty: options[:difficulty],
+        count: options[:count],
+        attachments: attachments
+      )
+      
+      puts "✅ Generated #{cards.length} flashcards!"
+      
+      # Create temporary YAML file
+      temp_yaml = "temp_#{Time.now.to_i}.yaml"
+      yaml_content = {
+        'ai_generation' => {
+          'topics' => [actual_prompt],
+          'context' => options[:context],
+          'difficulty' => options[:difficulty],
+          'count' => options[:count],
+          'save_generated' => false
+        },
+        'cards' => cards
+      }
+      
+      File.open(temp_yaml, 'w') do |file|
+        file.write(yaml_content.to_yaml)
+      end
+      
+      # Generate Anki deck
+      puts "Creating Anki deck..."
+      anki_generator = AnkiGenerator.new(
+        name: deck_name,
+        deck_file: temp_yaml,
+        api_key: options[:api_key],
+        model: options[:model]
+      )
+      
+      anki_generator.generate_apkg(output_path: output_file)
+      
+      # Clean up or save YAML
+      if options[:save_yaml]
+        yaml_file = output_file.gsub('.apkg', '.yaml')
+        File.rename(temp_yaml, yaml_file)
+        puts "YAML file saved: #{yaml_file}"
+      else
+        File.delete(temp_yaml)
+      end
+      
+      puts "🎉 Anki deck '#{deck_name}' created successfully!"
+      puts "File: #{output_file}"
+      puts "Total cards: #{cards.length}"
+      puts ""
+      puts "Preview of generated cards:"
+      cards.first(3).each_with_index do |card, index|
+        puts "#{index + 1}. #{card['front']}"
+        puts "   → #{card['back'][0..100]}#{'...' if card['back'].length > 100}"
+        puts ""
+      end
+      
+    rescue => e
+      puts "❌ Error: #{e.message}"
+      exit 1
+    end
+  end
+
+  desc 'create_ai_template TEMPLATE_FILE', 'Create a template YAML file for AI generation'
+  def create_ai_template(template_file)
+    template_content = {
+      'ai_generation' => {
+        'topics' => ['Example Topic 1', 'Example Topic 2'],
+        'context' => 'Additional context for generating flashcards',
+        'difficulty' => 'medium',
+        'count' => 5,
+        'save_generated' => true
+      },
+      'cards' => [
+        {
+          'front' => 'Example manual card front',
+          'back' => 'Example manual card back'
+        }
+      ]
+    }
+
+    File.open(template_file, 'w') do |file|
+      file.write(template_content.to_yaml)
+    end
+
+    puts "AI generation template created: #{template_file}"
+    puts "Edit the file and run 'anki_generator generate' to create your deck!"
+  end
+
+  desc 'test_api', 'Test OpenRouter API connection'
+  option :api_key, type: :string, desc: 'OpenRouter API key (or set OPENROUTER_API_KEY env var)'
+  option :model, type: :string, default: 'openai/gpt-3.5-turbo', desc: 'AI model to use'
+  def test_api
+    begin
+      require_relative 'openrouter_client'
+      client = OpenRouterClient.new(api_key: options[:api_key], model: options[:model])
+      
+      puts "Testing OpenRouter API connection..."
+      puts "Model: #{client.model}"
+      
+      card = client.generate_flashcard(topic: 'Ruby programming', difficulty: 'easy')
+      
+      puts "✅ API connection successful!"
+      puts "Sample generated card:"
+      puts "Front: #{card['front']}"
+      puts "Back: #{card['back']}"
+      
+    rescue => e
+      puts "❌ API test failed: #{e.message}"
+      exit 1
+    end
+  end
+end

data/lib/anki_generator.rb

@@ -2,21 +2,87 @@
 
 require 'yaml'
 require 'anki2'
+require_relative 'openrouter_client'
 
 # AnkiGenerator -> Class
 class AnkiGenerator
-  attr_accessor :deck_file, :cards, :name
+  attr_accessor :deck_file, :cards, :name, :openrouter_client
 
-  def initialize(deck_file:, name:)
+  def initialize(deck_file:, name:, api_key: nil, model: 'openai/gpt-3.5-turbo')
     self.deck_file = deck_file
     self.name = name
     self.cards = []
+    self.openrouter_client = OpenRouterClient.new(api_key: api_key, model: model) if api_key || ENV['OPENROUTER_API_KEY']
 
     fill_cards
   end
 
   def fill_cards
-    self.cards = YAML.load_file(deck_file)
+    yaml_content = YAML.load_file(deck_file)
+    
+    # Handle both old format (array of cards) and new format (with ai_generation config)
+    if yaml_content.is_a?(Hash) && yaml_content['ai_generation']
+      process_ai_generation(yaml_content)
+    else
+      self.cards = yaml_content.is_a?(Array) ? yaml_content : []
+    end
+  end
+
+  def process_ai_generation(config, attachments: nil)
+    ai_config = config['ai_generation']
+    existing_cards = config['cards'] || []
+    
+    # Generate AI cards if specified and client is available
+    if ai_config['topics'] && openrouter_client
+      ai_cards = generate_ai_cards(
+        topics: ai_config['topics'],
+        context: ai_config['context'],
+        difficulty: ai_config['difficulty'] || 'medium',
+        count: ai_config['count'] || 5,
+        attachments: attachments
+      )
+      
+      self.cards = existing_cards + ai_cards
+    else
+      self.cards = existing_cards
+    end
+    
+    # Save the generated cards back to YAML for future reference
+    save_generated_cards_to_yaml(config) if ai_config['save_generated'] && openrouter_client
+  end
+
+  def generate_ai_cards(topics:, context: nil, difficulty: 'medium', count: 5, attachments: nil)
+    if topics.is_a?(Array) && topics.length > 1
+      openrouter_client.generate_multiple_flashcards(
+        topics: topics,
+        context: context,
+        difficulty: difficulty,
+        count: count,
+        attachments: attachments
+      )
+    else
+      topic = topics.is_a?(Array) ? topics.first : topics
+      [openrouter_client.generate_flashcard(
+        topic: topic,
+        context: context,
+        difficulty: difficulty,
+        attachments: attachments
+      )]
+    end
+  end
+
+  def save_generated_cards_to_yaml(original_config)
+    output_file = deck_file.gsub('.yaml', '_generated.yaml')
+    
+    updated_config = original_config.dup
+    updated_config['cards'] = cards
+    updated_config['ai_generation']['save_generated'] = false # Prevent recursive generation
+    
+    File.open(output_file, 'w') do |file|
+      file.write(updated_config.to_yaml)
+    end
+    
+    puts "Generated cards saved to: #{output_file}"
   end
 
   def generate_apkg(output_path:)
@@ -28,4 +94,23 @@ class AnkiGenerator
 
     deck.save
   end
+
+  def add_card(front:, back:)
+    cards << { 'front' => front, 'back' => back }
+  end
+
+  def sync_with_existing_deck(existing_yaml_file)
+    return unless File.exist?(existing_yaml_file)
+    
+    existing_cards = YAML.load_file(existing_yaml_file)
+    existing_cards = existing_cards.is_a?(Array) ? existing_cards : existing_cards['cards'] || []
+    
+    # Simple deduplication based on front text
+    existing_fronts = existing_cards.map { |card| card['front'] }
+    new_cards = cards.reject { |card| existing_fronts.include?(card['front']) }
+    
+    self.cards = existing_cards + new_cards
+    
+    puts "Synced #{new_cards.length} new cards with existing deck"
+  end
 end

data/lib/file_processor.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+# FileProcessor -> Handles file and directory processing for attachments
+class FileProcessor
+  # Supported text file extensions
+  TEXT_EXTENSIONS = %w[.txt .md .rb .py .js .ts .java .cpp .c .h .hpp .css .html .xml .json .yaml .yml .sql .sh .bat .ps1 .php .go .rs .swift .kt .scala .clj .hs .elm .ex .exs .erl .pl .r .m .tex .org .rst .adoc].freeze
+  
+  # Maximum file size in bytes (1MB)
+  MAX_FILE_SIZE = 1_048_576
+  
+  # Maximum total content size (5MB)
+  MAX_TOTAL_SIZE = 5_242_880
+
+  def self.process_attachments(paths)
+    return [] if paths.nil? || paths.empty?
+    
+    attachments = []
+    total_size = 0
+    
+    paths.each do |path_str|
+      path = Pathname.new(path_str)
+      
+      unless path.exist?
+        puts "⚠️  Warning: Path does not exist: #{path_str}"
+        next
+      end
+      
+      if path.directory?
+        dir_attachments = process_directory(path)
+        dir_attachments.each do |attachment|
+          if total_size + attachment[:content].bytesize > MAX_TOTAL_SIZE
+            puts "⚠️  Warning: Total attachment size limit reached. Skipping remaining files."
+            break
+          end
+          attachments << attachment
+          total_size += attachment[:content].bytesize
+        end
+      elsif path.file?
+        attachment = process_file(path)
+        if attachment
+          if total_size + attachment[:content].bytesize > MAX_TOTAL_SIZE
+            puts "⚠️  Warning: Total attachment size limit reached. Skipping #{path_str}"
+          else
+            attachments << attachment
+            total_size += attachment[:content].bytesize
+          end
+        end
+      else
+        puts "⚠️  Warning: Path is neither file nor directory: #{path_str}"
+      end
+    end
+    
+    puts "📎 Processed #{attachments.length} file(s) (#{format_size(total_size)})" if attachments.any?
+    attachments
+  end
+
+  def self.process_directory(dir_path)
+    attachments = []
+    
+    # Find all text files in directory (non-recursive for now)
+    dir_path.children.each do |child|
+      next unless child.file?
+      
+      attachment = process_file(child)
+      attachments << attachment if attachment
+    end
+    
+    attachments
+  end
+
+  def self.process_file(file_path)
+    # Check file size
+    if file_path.size > MAX_FILE_SIZE
+      puts "⚠️  Warning: File too large, skipping: #{file_path} (#{format_size(file_path.size)})"
+      return nil
+    end
+    
+    # Check if it's a text file
+    unless text_file?(file_path)
+      puts "⚠️  Warning: Non-text file, skipping: #{file_path}"
+      return nil
+    end
+    
+    begin
+      content = file_path.read(encoding: 'UTF-8')
+      
+      # Truncate if too long
+      if content.bytesize > MAX_FILE_SIZE
+        content = content.byteslice(0, MAX_FILE_SIZE) + "\n... [truncated]"
+      end
+      
+      {
+        filename: file_path.basename.to_s,
+        path: file_path.to_s,
+        content: content
+      }
+    rescue => e
+      puts "⚠️  Warning: Could not read file #{file_path}: #{e.message}"
+      nil
+    end
+  end
+
+  def self.text_file?(file_path)
+    # Check extension
+    ext = file_path.extname.downcase
+    return true if TEXT_EXTENSIONS.include?(ext)
+    
+    # For files without extension, try to detect if it's text
+    return false if file_path.extname.empty? && file_path.basename.to_s !~ /^[A-Z_]+$/
+    
+    # Try to read first few bytes to detect binary files
+    begin
+      sample = file_path.read(512, encoding: 'BINARY')
+      # If it contains null bytes, it's likely binary
+      !sample.include?("\x00")
+    rescue
+      false
+    end
+  end
+
+  def self.format_size(bytes)
+    if bytes < 1024
+      "#{bytes} B"
+    elsif bytes < 1024 * 1024
+      "#{(bytes / 1024.0).round(1)} KB"
+    else
+      "#{(bytes / (1024.0 * 1024)).round(1)} MB"
+    end
+  end
+
+  def self.read_prompt_from_file(file_path)
+    path = Pathname.new(file_path)
+    
+    unless path.exist?
+      raise "Prompt file does not exist: #{file_path}"
+    end
+    
+    unless path.file?
+      raise "Prompt path is not a file: #{file_path}"
+    end
+    
+    begin
+      content = path.read(encoding: 'UTF-8').strip
+      
+      if content.empty?
+        raise "Prompt file is empty: #{file_path}"
+      end
+      
+      content
+    rescue => e
+      raise "Could not read prompt file #{file_path}: #{e.message}"
+    end
+  end
+end

data/lib/openrouter_client.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'dotenv/load'
+
+# OpenRouterClient -> API client for OpenRouter
+class OpenRouterClient
+  BASE_URL = 'https://openrouter.ai/api/v1'
+  
+  attr_reader :api_key, :model
+
+  def initialize(api_key: nil, model: 'openai/gpt-3.5-turbo')
+    @api_key = api_key || ENV['OPENROUTER_API_KEY']
+    @model = model
+    
+    raise ArgumentError, 'API key is required' if @api_key.nil? || @api_key.empty?
+  end
+
+  def generate_flashcard(topic:, context: nil, difficulty: 'medium', attachments: nil)
+    prompt = build_flashcard_prompt(topic: topic, context: context, difficulty: difficulty, attachments: attachments)
+    
+    response = make_request(prompt)
+    parse_flashcard_response(response)
+  end
+
+  def generate_multiple_flashcards(topics:, context: nil, difficulty: 'medium', count: 5, attachments: nil)
+    prompt = build_multiple_flashcards_prompt(
+      topics: topics, 
+      context: context, 
+      difficulty: difficulty, 
+      count: count,
+      attachments: attachments
+    )
+    
+    response = make_request(prompt)
+    parse_multiple_flashcards_response(response)
+  end
+
+  private
+
+  def connection
+    @connection ||= Faraday.new(url: BASE_URL) do |conn|
+      conn.request :json
+      conn.response :json
+      conn.adapter Faraday.default_adapter
+      conn.headers['Authorization'] = "Bearer #{@api_key}"
+      conn.headers['Content-Type'] = 'application/json'
+    end
+  end
+
+  def make_request(prompt)
+    response = connection.post('/chat/completions') do |req|
+      req.body = {
+        model: @model,
+        messages: [
+          {
+            role: 'user',
+            content: prompt
+          }
+        ],
+        temperature: 0.7,
+        max_tokens: 1000
+      }
+    end
+
+    handle_response(response)
+  end
+
+  def handle_response(response)
+    unless response.success?
+      raise "OpenRouter API error: #{response.status} - #{response.body}"
+    end
+
+    response.body.dig('choices', 0, 'message', 'content')
+  end
+
+  def build_flashcard_prompt(topic:, context:, difficulty:, attachments:)
+    base_prompt = <<~PROMPT
+      Create a single flashcard for the topic: "#{topic}"
+      Difficulty level: #{difficulty}
+      #{context ? "Additional context: #{context}" : ''}
+      
+      #{build_attachments_section(attachments) if attachments}
+      
+      Format your response as JSON with exactly this structure:
+      {
+        "front": "Question or prompt",
+        "back": "Answer or explanation"
+      }
+      
+      Make the flashcard educational and appropriate for the #{difficulty} difficulty level.
+      For the back side, provide a clear, concise explanation.
+      #{attachments ? "Use the provided file content to create more accurate and detailed flashcards." : ""}
+    PROMPT
+
+    base_prompt.strip
+  end
+
+  def build_multiple_flashcards_prompt(topics:, context:, difficulty:, count:, attachments:)
+    topics_list = topics.is_a?(Array) ? topics.join(', ') : topics.to_s
+    
+    base_prompt = <<~PROMPT
+      Create #{count} flashcards covering these topics: #{topics_list}
+      Difficulty level: #{difficulty}
+      #{context ? "Additional context: #{context}" : ''}
+      
+      #{build_attachments_section(attachments) if attachments}
+      
+      Format your response as JSON with exactly this structure:
+      [
+        {
+          "front": "Question or prompt 1",
+          "back": "Answer or explanation 1"
+        },
+        {
+          "front": "Question or prompt 2", 
+          "back": "Answer or explanation 2"
+        }
+      ]
+      
+      Make the flashcards educational, diverse, and appropriate for the #{difficulty} difficulty level.
+      Ensure each flashcard covers different aspects of the topics.
+      #{attachments ? "Use the provided file content to create more accurate and detailed flashcards based on the specific information in the files." : ""}
+    PROMPT
+
+    base_prompt.strip
+  end
+
+  def parse_flashcard_response(response)
+    JSON.parse(response)
+  rescue JSON::ParserError => e
+    raise "Failed to parse OpenRouter response as JSON: #{e.message}"
+  end
+
+  def parse_multiple_flashcards_response(response)
+    parsed = JSON.parse(response)
+    
+    # Ensure we return an array
+    parsed.is_a?(Array) ? parsed : [parsed]
+  rescue JSON::ParserError => e
+    raise "Failed to parse OpenRouter response as JSON: #{e.message}"
+  end
+
+  def build_attachments_section(attachments)
+    return "" unless attachments && !attachments.empty?
+    
+    section = "=== ATTACHED FILE CONTENT ===\n\n"
+    
+    attachments.each do |attachment|
+      section += "--- #{attachment[:filename]} ---\n"
+      section += "#{attachment[:content]}\n\n"
+    end
+    
+    section += "=== END ATTACHED CONTENT ===\n"
+    section
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anki_generator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ceb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-03 00:00:00.000000000 Z
+date: 2026-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: anki2
@@ -25,35 +25,108 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.1.2
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.25.1
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.25.1
+        version: '1.2'
 - !ruby/object:Gem::Dependency
-  name: thor
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
-description: AnkiGenerator is a command-line tool to create Anki decks in .apkg format
-  from YAML files.
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A powerful command-line tool that generates Anki flashcard decks (.apkg)
+  from YAML files, direct prompts, or file attachments. Features AI-powered content
+  generation using OpenRouter API with support for multiple models (GPT, Claude, Llama),
+  file and directory attachment processing for context-aware generation, prompt file
+  support, intelligent content filtering, and flexible deck management with sync capabilities.
 email:
 - ceeb.developer@gmail.com
 executables:
@@ -61,12 +134,21 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - bin/anki_generator
+- lib/anki_cli.rb
 - lib/anki_generator.rb
-homepage: ''
+- lib/file_processor.rb
+- lib/openrouter_client.rb
+homepage: https://github.com/pinkfloydsito/anki_generator
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/pinkfloydsito/anki_generator
+  source_code_uri: https://github.com/pinkfloydsito/anki_generator
+  changelog_uri: https://github.com/pinkfloydsito/anki_generator/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/pinkfloydsito/anki_generator/issues
+  documentation_uri: https://github.com/pinkfloydsito/anki_generator/blob/main/README.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -75,7 +157,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -85,5 +167,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: A tool to generate Anki .apkg files from YAML definitions.
+summary: AI-powered Anki flashcard generator with file attachment support
 test_files: []