anki_generator 1.1.0 → 1.4.0

data/lib/anki_generator/cli.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'dotenv/load'
+require_relative 'version'
+require_relative 'errors'
+require_relative 'ui'
+require_relative 'client_factory'
+require_relative 'commands/create_ai_template'
+require_relative 'commands/generate_deck'
+require_relative 'commands/generate_yaml'
+require_relative 'commands/import'
+require_relative 'commands/prompt_to_deck'
+require_relative 'commands/push'
+require_relative 'commands/serve'
+require_relative 'commands/test_api'
+
+module AnkiGenerator
+  # Command-line interface. This class is intentionally thin: it parses
+  # arguments with Thor and delegates to command objects in
+  # AnkiGenerator::Commands, which hold the actual behaviour.
+  class CLI < Thor
+    DEFAULT_MODEL = LlmClient::DEFAULT_MODEL
+
+    def self.exit_on_failure?
+      true
+    end
+
+    class_option :provider,
+                 type: :string, default: nil,
+                 desc: 'LLM provider (e.g. gemini, openai, anthropic, openrouter, ollama); ' \
+                       'auto-resolved from the model when omitted'
+
+    desc 'generate DECK_NAME YAML_FILE OUTPUT_FILE', 'Generate an Anki .apkg deck from a YAML file'
+    option :api_key, type: :string, desc: 'Provider API key (defaults to the provider env var, e.g. GEMINI_API_KEY)'
+    option :model, type: :string, desc: 'AI model to use (provider default if omitted)'
+    option :sync_with, type: :string, desc: 'Existing YAML file to sync with'
+    option :reverse, type: :boolean, default: false, desc: 'Add reversed copy of each basic card'
+    option :jobs, type: :numeric, default: 1, desc: 'Parallel API calls for multi-topic generation'
+    def generate(deck_name, yaml_file, output_file)
+      run_command Commands::GenerateDeck,
+                  deck_name:,
+                  yaml_file:,
+                  output_file:,
+                  model: option_model,
+                  sync_with: options[:sync_with],
+                  reverse: options[:reverse],
+                  jobs: options[:jobs],
+                  client: build_client(required: false)
+    end
+
+    desc 'generate_yaml PROMPT OUTPUT_YAML', 'Generate a YAML file from a prompt using AI'
+    option :api_key, type: :string, desc: 'Provider API key (defaults to the provider env var, e.g. GEMINI_API_KEY)'
+    option :model, type: :string, desc: 'AI model to use (provider default if omitted)'
+    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)
+      run_command Commands::GenerateYaml,
+                  prompt:,
+                  output_yaml:,
+                  model: option_model,
+                  difficulty: options[:difficulty],
+                  count: options[:count],
+                  context: options[:context],
+                  attach: options[:attach],
+                  prompt_file: options[:prompt_file],
+                  client: build_client
+    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: 'Provider API key (defaults to the provider env var, e.g. GEMINI_API_KEY)'
+    option :model, type: :string, desc: 'AI model to use (provider default if omitted)'
+    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)
+      run_command Commands::PromptToDeck,
+                  prompt:,
+                  deck_name:,
+                  output_file:,
+                  model: option_model,
+                  difficulty: options[:difficulty],
+                  count: options[:count],
+                  context: options[:context],
+                  save_yaml: options[:save_yaml],
+                  attach: options[:attach],
+                  prompt_file: options[:prompt_file],
+                  client: build_client
+    end
+
+    desc 'import DECK_NAME INPUT_FILE OUTPUT_FILE', 'Build a deck from Markdown or CSV study notes'
+    option :reverse, type: :boolean, default: false, desc: 'Add reversed copy of each basic card'
+    long_desc 'Supported inputs: Markdown (.md, Q:/A: pairs or "- **Q** — A" bullets, headings become tags) ' \
+              'and CSV (front,back[,tags]).'
+    def import(deck_name, input_file, output_file)
+      run_command Commands::Import,
+                  deck_name:,
+                  input_file:,
+                  output_file:,
+                  reverse: options[:reverse]
+    end
+
+    desc 'push DECK_NAME YAML_FILE', 'Push a YAML card file into a running Anki via AnkiConnect'
+    option :url, type: :string, default: AnkiConnectClient::DEFAULT_URL, desc: 'AnkiConnect URL'
+    long_desc 'Requires Anki running with the AnkiConnect add-on. Cards are added to the Basic note type; ' \
+              'duplicates are skipped.'
+    def push(deck_name, yaml_file)
+      run_command Commands::Push,
+                  deck_name:,
+                  yaml_file:,
+                  url: options[:url]
+    end
+
+    desc 'serve', 'Start a local web UI to preview, edit, and export decks'
+    option :port, type: :numeric, default: Commands::Serve::DEFAULT_PORT, desc: 'Port to listen on'
+    long_desc 'Opens a browser UI at http://localhost:<port>: paste Markdown notes or generate cards with AI, ' \
+              'edit the result, and download an .apkg.'
+    def serve
+      run_command Commands::Serve,
+                  port: options[:port],
+                  provider: options[:provider]
+    end
+
+    desc 'create_ai_template TEMPLATE_FILE', 'Create a template YAML file for AI generation'
+    def create_ai_template(template_file)
+      run_command Commands::CreateAiTemplate, template_file:
+    end
+
+    desc 'test_api', 'Test the LLM API connection'
+    option :api_key, type: :string, desc: 'Provider API key (defaults to the provider env var, e.g. GEMINI_API_KEY)'
+    option :model, type: :string, desc: 'AI model to use (provider default if omitted)'
+    def test_api
+      run_command Commands::TestApi, model: option_model, client: build_client
+    end
+
+    desc 'version', 'Show the gem version'
+    def version
+      say "anki_generator #{AnkiGenerator::VERSION}"
+    end
+
+    private
+
+    # All AnkiGenerator errors are reported as a clean message + exit 1;
+    # unexpected errors still raise with a full backtrace.
+    def run_command(command_class, **args)
+      command_class.new(**args, ui: UI.new).run
+    rescue AnkiGenerator::Error => e
+      UI.new.error("Error: #{e.message}")
+      exit 1
+    end
+
+    def option_model
+      options[:model] || DEFAULT_MODEL
+    end
+
+    # The API key comes from --api_key; otherwise the standard provider env
+    # vars (GEMINI_API_KEY, OPENAI_API_KEY, ...) are picked up by LlmClient
+    # itself. With required: false and no key anywhere, yields nil (commands
+    # then skip AI generation instead of failing).
+    def build_client(required: true)
+      api_key = options[:api_key]
+      if api_key && !api_key.empty?
+        return ClientFactory.build(provider: options[:provider], model: option_model, api_key:)
+      end
+
+      return ClientFactory.build(provider: options[:provider], model: option_model) if !required || llm_configured?
+
+      raise ConfigurationError,
+            'An LLM API key is required (use --api_key or set an env var such as GOOGLE_API_KEY)'
+    end
+
+    def llm_configured?
+      (LlmClient::ENV_KEY_VARS + ['GOOGLE_API_KEY']).any? { |name| !(ENV.fetch(name, nil) || '').empty? } ||
+        !(ENV.fetch('OLLAMA_URL', nil) || '').empty?
+    end
+  end
+end

data/lib/anki_generator/client_factory.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'llm_client'
+
+module AnkiGenerator
+  # Builds the unified ruby_llm-backed client. Any provider ruby_llm
+  # supports (gemini, openai, anthropic, openrouter, ollama, ...) is valid;
+  # pass provider: nil to auto-resolve from the model name.
+  module ClientFactory
+    module_function
+
+    def build(model: nil, provider: nil, api_key: nil)
+      LlmClient.new(
+        model: model || LlmClient::DEFAULT_MODEL,
+        provider:,
+        api_key:
+      )
+    end
+  end
+end

data/lib/anki_generator/commands/create_ai_template.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator create_ai_template` — write a starter YAML file users can
+    # edit and feed back into `generate`.
+    class CreateAiTemplate
+      TEMPLATE = {
+        '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'
+          }
+        ]
+      }.freeze
+
+      def initialize(template_file:, ui: UI.new)
+        @template_file = template_file
+        @ui = ui
+      end
+
+      def run
+        File.write(@template_file, TEMPLATE.to_yaml)
+
+        @ui.info("AI generation template created: #{@template_file}")
+        @ui.info("Edit the file and run 'anki_generator generate' to create your deck!")
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/generate_deck.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../deck_builder'
+require_relative '../client_factory'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator generate` — build an .apkg deck from a YAML card file.
+    class GenerateDeck
+      def initialize(deck_name:, yaml_file:, output_file:, model: LlmClient::DEFAULT_MODEL,
+                     sync_with: nil, reverse: false, jobs: 1, client: nil, ui: UI.new)
+        @deck_name = deck_name
+        @yaml_file = yaml_file
+        @output_file = output_file
+        @sync_with = sync_with
+        @reverse = reverse
+        @jobs = jobs
+        @client = client || build_client(model)
+        @ui = ui
+      end
+
+      def run
+        builder = DeckBuilder.new(name: @deck_name, deck_file: @yaml_file, client: @client, jobs: @jobs, ui: @ui)
+        builder.sync_with(@sync_with) if @sync_with
+        builder.add_reverse_cards! if @reverse
+        builder.generate_apkg(output_path: @output_file)
+
+        @ui.success("Anki deck '#{@deck_name}' has been successfully created as #{@output_file}!")
+        @ui.info("Total cards: #{builder.cards.length}")
+      end
+
+      private
+
+      def build_client(model)
+        # DeckBuilder only calls the client when the YAML has an
+        # ai_generation section, so building unconditionally is safe — plain
+        # card files never touch the network.
+        ClientFactory.build(model:)
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/generate_yaml.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'prompt_based'
+require_relative '../client_factory'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator generate_yaml` — generate a YAML card file from a prompt.
+    class GenerateYaml
+      include PromptBased
+
+      def initialize(prompt:, output_yaml:, model: LlmClient::DEFAULT_MODEL, difficulty: 'medium',
+                     count: 10, context: nil, attach: nil, prompt_file: false,
+                     client: nil, ui: UI.new)
+        @prompt = prompt
+        @output_yaml = output_yaml
+        @difficulty = difficulty
+        @count = count
+        @context = context
+        @attach = attach
+        @prompt_file = prompt_file
+        @client = client || ClientFactory.build(model:)
+        @ui = ui
+      end
+
+      def run
+        actual_prompt = resolve_prompt(@prompt, @prompt_file)
+        attachments = resolve_attachments(@attach)
+
+        announce(prompt: actual_prompt, difficulty: @difficulty, count: @count, attachments:)
+        cards = generate_cards(
+          prompt: actual_prompt, difficulty: @difficulty, count: @count,
+          context: @context, attachments:
+        )
+
+        File.write(@output_yaml, yaml_document(actual_prompt, cards).to_yaml)
+
+        @ui.success("Generated #{cards.length} flashcards!")
+        @ui.info("YAML file created: #{@output_yaml}")
+        preview_cards(cards)
+
+        @ui.info('To create an Anki deck, run:')
+        @ui.info("  anki_generator generate \"My Deck\" #{@output_yaml} my_deck.apkg")
+      end
+
+      private
+
+      def yaml_document(prompt, cards)
+        {
+          'ai_generation' => {
+            'topics' => [prompt],
+            'context' => @context,
+            'difficulty' => @difficulty,
+            'count' => @count,
+            'save_generated' => false
+          },
+          'cards' => cards
+        }
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/import.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require_relative '../deck_builder'
+require_relative '../errors'
+require_relative '../importers/csv'
+require_relative '../importers/markdown'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator import` — build a deck straight from study notes
+    # (Markdown or CSV) without a YAML intermediate.
+    class Import
+      EXTENSION_IMPORTERS = {
+        '.md' => Importers::Markdown,
+        '.markdown' => Importers::Markdown,
+        '.csv' => Importers::Csv
+      }.freeze
+
+      def self.importer_for(path)
+        EXTENSION_IMPORTERS.fetch(File.extname(path).downcase, nil)
+      end
+
+      def initialize(deck_name:, input_file:, output_file:, reverse: false, ui: UI.new)
+        @deck_name = deck_name
+        @input_file = input_file
+        @output_file = output_file
+        @reverse = reverse
+        @ui = ui
+      end
+
+      def run
+        cards = import_cards
+
+        with_temp_deck(cards) do |deck_file|
+          builder = DeckBuilder.new(name: @deck_name, deck_file:, ui: @ui)
+          builder.add_reverse_cards! if @reverse
+          builder.generate_apkg(output_path: @output_file)
+          @ui.success("Anki deck '#{@deck_name}' has been successfully created as #{@output_file}!")
+          @ui.info("Total cards: #{builder.cards.length}")
+        end
+      end
+
+      private
+
+      def import_cards
+        importer = self.class.importer_for(@input_file)
+        unless importer
+          supported = EXTENSION_IMPORTERS.keys.join(', ')
+          raise FileProcessingError, "Unsupported input file #{@input_file} (supported: #{supported})"
+        end
+
+        @ui.info("Importing #{@input_file}...")
+        cards = importer.parse(File.read(@input_file, encoding: 'UTF-8'))
+        raise FileProcessingError, "No cards found in #{@input_file}" if cards.empty?
+
+        @ui.info("Parsed #{cards.length} card(s)")
+        cards
+      rescue SystemCallError => e
+        raise FileProcessingError, "Cannot read #{@input_file}: #{e.message}"
+      end
+
+      # DeckBuilder loads from a YAML path, so stage the imported cards in a
+      # temp file rather than duplicating export logic.
+      def with_temp_deck(cards)
+        Tempfile.create(['anki_generator_import', '.yaml']) do |file|
+          file.write({ 'cards' => cards }.to_yaml)
+          file.flush
+          yield file.path
+        end
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/prompt_based.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../file_processor'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # Shared behaviour for commands that turn a prompt (+ optional attachments)
+    # into flashcards via the configured LLM provider.
+    module PromptBased
+      attr_reader :client, :ui
+
+      def resolve_prompt(prompt, prompt_file)
+        return prompt unless prompt_file
+
+        ui.info("📄 Reading prompt from file: #{prompt}")
+        FileProcessor.read_prompt_from_file(prompt)
+      end
+
+      def resolve_attachments(attach)
+        return nil unless attach
+
+        ui.info('📎 Processing attachments...')
+        FileProcessor.process_attachments(attach, ui:)
+      end
+
+      def announce(prompt:, difficulty:, count:, attachments:)
+        preview = truncate(prompt)
+        ui.info("Generating flashcards for: #{preview}")
+        announce_parameters(difficulty:, count:, attachments:)
+      end
+
+      # Deck-flavored announcement used by prompt_to_deck.
+      def announce_deck(prompt:, difficulty:, count:, attachments:)
+        ui.info("🚀 Generating Anki deck from prompt: #{truncate(prompt)}")
+        announce_parameters(difficulty:, count:, attachments:)
+        ui.info('')
+      end
+
+      def generate_cards(prompt:, difficulty:, count:, context:, attachments:)
+        ui.info('Generating...')
+        client.generate_multiple_flashcards(
+          topics: [prompt],
+          context:,
+          difficulty:,
+          count:,
+          attachments:
+        )
+      end
+
+      def truncate(text)
+        text.length > 100 ? "#{text[0..100]}..." : text
+      end
+
+      def announce_parameters(difficulty:, count:, attachments:)
+        ui.info("Model: #{client.model}")
+        ui.info("Difficulty: #{difficulty}")
+        ui.info("Count: #{count}")
+        ui.info("Attachments: #{attachments&.length || 0} file(s)") if attachments
+      end
+
+      def preview_cards(cards, limit: 3)
+        ui.info('')
+        ui.info('Preview of generated cards:')
+        cards.first(limit).each_with_index do |card, index|
+          back = card['back'].length > 100 ? "#{card['back'][0..100]}..." : card['back']
+          ui.info("#{index + 1}. #{card['front']}")
+          ui.info("   → #{back}")
+          ui.info('')
+        end
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/prompt_to_deck.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require_relative 'prompt_based'
+require_relative '../deck_builder'
+require_relative '../client_factory'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator prompt_to_deck` — generate cards from a prompt and build
+    # the .apkg deck in one step, via a temporary YAML file that is always
+    # cleaned up (or persisted when --save-yaml is passed).
+    class PromptToDeck
+      include PromptBased
+
+      def initialize(prompt:, deck_name:, output_file:, model: LlmClient::DEFAULT_MODEL,
+                     difficulty: 'medium', count: 10, context: nil, save_yaml: false,
+                     attach: nil, prompt_file: false, client: nil, ui: UI.new)
+        @prompt = prompt
+        @deck_name = deck_name
+        @output_file = output_file
+        @difficulty = difficulty
+        @count = count
+        @context = context
+        @save_yaml = save_yaml
+        @attach = attach
+        @prompt_file = prompt_file
+        @client = client || ClientFactory.build(model:)
+        @ui = ui
+      end
+
+      def run
+        actual_prompt = resolve_prompt(@prompt, @prompt_file)
+        attachments = resolve_attachments(@attach)
+
+        announce_deck(prompt: actual_prompt, difficulty: @difficulty, count: @count, attachments:)
+
+        cards = generate_cards(
+          prompt: actual_prompt, difficulty: @difficulty, count: @count,
+          context: @context, attachments:
+        )
+        ui.success("Generated #{cards.length} flashcards!")
+
+        export_deck(cards)
+
+        ui.success("Anki deck '#{@deck_name}' created successfully!")
+        ui.info("File: #{@output_file}")
+        ui.info("Total cards: #{cards.length}")
+        preview_cards(cards)
+      end
+
+      private
+
+      def export_deck(cards)
+        deck_document = build_deck_document(cards)
+
+        Tempfile.create(['anki_generator', '.yaml']) do |file|
+          file.write(deck_document.to_yaml)
+          file.flush
+          ui.info('Creating Anki deck...')
+          DeckBuilder.new(name: @deck_name, deck_file: file.path, client:, ui:)
+                     .generate_apkg(output_path: @output_file)
+        end
+
+        persist_yaml(deck_document) if @save_yaml
+      end
+
+      def persist_yaml(deck_document)
+        yaml_path = @output_file.sub(/\.apkg\z/, '.yaml')
+        File.write(yaml_path, deck_document.to_yaml)
+        ui.info("YAML file saved: #{yaml_path}")
+      end
+
+      def build_deck_document(cards)
+        # The cards are already generated at this point, so the intermediate
+        # document is plain card data. Including the ai_generation section here
+        # would make DeckBuilder send the prompt back through the API a second
+        # time instead of using the cards we already have.
+        { 'cards' => cards }
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/push.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../anki_connect_client'
+require_relative '../deck_builder'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator push` — send a YAML card file straight into a running
+    # Anki via the AnkiConnect add-on, skipping the .apkg import step.
+    class Push
+      def initialize(deck_name:, yaml_file:, url: AnkiConnectClient::DEFAULT_URL,
+                     anki_connect: nil, ui: UI.new)
+        @deck_name = deck_name
+        @yaml_file = yaml_file
+        @anki_connect = anki_connect || AnkiConnectClient.new(base_url: url)
+        @ui = ui
+      end
+
+      def run
+        builder = DeckBuilder.new(name: @deck_name, deck_file: @yaml_file, ui: @ui)
+        raise FileProcessingError, "No cards found in #{@yaml_file}" if builder.cards.empty?
+
+        @ui.info("Pushing #{builder.cards.length} card(s) to deck '#{@deck_name}' via AnkiConnect...")
+        result = @anki_connect.push_deck(deck_name: @deck_name, cards: builder.cards)
+
+        @ui.success("Pushed #{result[:added]} card(s) to Anki!")
+        @ui.info("Skipped #{result[:duplicate]} duplicate(s)") if result[:duplicate].positive?
+      end
+    end
+  end
+end