anki_generator 1.1.0 → 1.4.0

data/lib/anki_generator/commands/serve.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'webrick'
+require_relative '../server'
+require_relative '../ui'
+
+begin
+  require 'rackup'
+  require 'rackup/handler/webrick'
+rescue LoadError
+  # rackup gem not installed (it is not in the lockfile) — the small adapter
+  # below bridges WEBrick to the Rack app instead.
+end
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator serve` — start the local preview/export web UI.
+    class Serve
+      DEFAULT_PORT = 8787
+
+      def initialize(port: DEFAULT_PORT, provider: nil, ui: UI.new)
+        @port = port
+        @provider = provider
+        @ui = ui
+      end
+
+      # Blocks until the server is stopped (Ctrl+C).
+      def run
+        AnkiGenerator::Server.set(:default_provider, @provider)
+
+        @ui.info("Anki Generator UI available at http://localhost:#{@port}")
+        @ui.info('Press Ctrl+C to stop')
+
+        if defined?(Rackup::Handler::WEBrick)
+          Rackup::Handler::WEBrick.run(
+            AnkiGenerator::Server,
+            Host: '127.0.0.1', Port: @port,
+            AccessLog: [], Logger: WEBrick::Log.new(File::NULL)
+          )
+        else
+          run_webrick
+        end
+      end
+
+      private
+
+      def run_webrick
+        server = WEBrick::HTTPServer.new(
+          BindAddress: '127.0.0.1',
+          Port: @port,
+          Logger: WEBrick::Log.new(File::NULL),
+          AccessLog: []
+        )
+        server.mount('/', RackServlet, AnkiGenerator::Server)
+        trap('INT') { server.shutdown }
+        server.start
+      ensure
+        server&.shutdown
+      end
+
+      # Minimal WEBrick -> Rack bridge used when the rackup gem is unavailable.
+      class RackServlet < WEBrick::HTTPServlet::AbstractServlet
+        def initialize(server, app)
+          super(server)
+          @app = app
+        end
+
+        def service(request, response)
+          status, headers, body = @app.call(rack_env(request))
+          response.status = status
+          headers.each do |key, value|
+            next if key.start_with?('rack.')
+
+            response[key] = value.is_a?(Array) ? value.join(', ') : value.to_s
+          end
+          response.body = +''
+          body.each { |part| response.body << part.to_s }
+          body.close if body.respond_to?(:close)
+        end
+
+        private
+
+        def rack_env(request)
+          env = request.meta_vars
+          env['CONTENT_TYPE'] ||= env.delete('Content-Type')
+          env['CONTENT_LENGTH'] ||= env.delete('Content-Length')
+          env.update(
+            'rack.version' => Rack::RELEASE,
+            'rack.input' => StringIO.new(request.body.to_s),
+            'rack.errors' => $stderr,
+            'rack.url_scheme' => request.ssl? ? 'https' : 'http'
+          )
+          env
+        end
+      end
+    end
+  end
+end

data/lib/anki_generator/commands/test_api.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../client_factory'
+require_relative '../ui'
+
+module AnkiGenerator
+  module Commands
+    # `anki_generator test_api` — verify the LLM connection by generating a
+    # single sample card.
+    class TestApi
+      def initialize(model: LlmClient::DEFAULT_MODEL, client: nil, ui: UI.new)
+        @client = client || ClientFactory.build(model:)
+        @ui = ui
+      end
+
+      def run
+        ui.info('Testing LLM connection...')
+        ui.info("Model: #{client.model}")
+
+        card = client.generate_flashcard(topic: 'Ruby programming', difficulty: 'easy')
+
+        ui.success('API connection successful!')
+        ui.info('Sample generated card:')
+        ui.info("Front: #{card['front']}")
+        ui.info("Back: #{card['back']}")
+      end
+
+      private
+
+      attr_reader :client, :ui
+    end
+  end
+end

data/lib/anki_generator/deck_builder.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'yaml'
+require_relative 'apkg_writer'
+require_relative 'card'
+require_relative 'errors'
+require_relative 'client_factory'
+require_relative 'ui'
+
+module AnkiGenerator
+  # Loads card definitions from YAML, optionally enriches them with AI-generated
+  # cards via an LLM client, and exports the result as an .apkg deck.
+  class DeckBuilder
+    attr_reader :name, :deck_file, :cards
+    attr_accessor :client
+
+    def initialize(name:, deck_file:, client: nil, jobs: 1, ui: UI.new($stderr))
+      @name = name
+      @deck_file = deck_file
+      @client = client
+      @jobs = jobs
+      @ui = ui
+      @cards = []
+      load_cards
+    end
+
+    def load_cards
+      yaml_content = load_yaml(deck_file)
+
+      if yaml_content.is_a?(Hash) && yaml_content['ai_generation']
+        process_ai_generation(yaml_content)
+      else
+        @cards = build_cards(extract_card_list(yaml_content))
+      end
+    end
+
+    def process_ai_generation(config, attachments: nil)
+      ai_config = config['ai_generation']
+      existing_cards = build_cards(config['cards'] || [])
+
+      if ai_config['topics'] && 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:,
+          jobs: ai_config['jobs'] || @jobs
+        )
+        @cards = existing_cards + build_cards(ai_cards)
+      else
+        @cards = existing_cards
+      end
+
+      return unless ai_config['save_generated'] && client
+
+      save_generated_cards_to_yaml(config)
+    end
+
+    # Generates AI cards for the given topics. With jobs > 1 and multiple
+    # topics, each topic is requested in parallel (one API call per topic,
+    # count cards each); with jobs == 1 all topics go in a single batched
+    # request, which is cheaper but may produce less focused cards.
+    def generate_ai_cards(topics:, context: nil, difficulty: 'medium', count: 5, attachments: nil, jobs: 1)
+      topic_list = Array(topics)
+
+      if topic_list.length > 1 && jobs > 1
+        generate_topics_in_parallel(topic_list, context:, difficulty:, count:, attachments:, jobs:)
+      elsif topic_list.length > 1
+        client.generate_multiple_flashcards(
+          topics: topic_list, context:, difficulty:, count:, attachments:
+        )
+      else
+        [client.generate_flashcard(topic: topic_list.first, context:, difficulty:, attachments:)]
+      end
+    end
+
+    # Appends a reversed copy of every basic card (back becomes front) — the
+    # classic "recognition + recall" pattern. Cloze cards are skipped.
+    def add_reverse_cards!
+      originals = cards.dup
+      originals.reject(&:cloze?).each { |card| cards << card.reversed }
+      @ui.info("Added #{cards.length - originals.length} reversed cards")
+      cards
+    end
+
+    def save_generated_cards_to_yaml(original_config)
+      output_file = deck_file.sub(/\.ya?ml\z/, '_generated.yaml')
+
+      updated_config = original_config.dup
+      updated_config['cards'] = cards.map(&:to_h)
+      updated_config['ai_generation']['save_generated'] = false # Prevent recursive generation
+
+      File.write(output_file, updated_config.to_yaml)
+      @ui.info("Generated cards saved to: #{output_file}")
+    end
+
+    def generate_apkg(output_path:)
+      writer = ApkgWriter.new(name:, output_path:)
+      cards.each do |card|
+        if card.cloze?
+          writer.add_card(card.front, card.back, tags: card.tags, cloze: card.front)
+        else
+          writer.add_card(card.front, card.back, tags: card.tags)
+        end
+      end
+      writer.save
+    end
+
+    def add_card(front:, back:, tags: [], cloze: nil)
+      cards << Card.new(front:, back:, tags:, cloze:)
+    end
+
+    # Merges cards from an existing deck YAML, deduplicating on the normalized
+    # front text so re-running generation does not create duplicate cards.
+    def sync_with(existing_yaml_file)
+      unless File.exist?(existing_yaml_file)
+        @ui.warn("Sync file not found, skipping: #{existing_yaml_file}")
+        return
+      end
+
+      existing_cards = build_cards(extract_card_list(load_yaml(existing_yaml_file)))
+      existing_fronts = existing_cards.map { |card| normalize(card.front) }
+      new_cards = cards.reject { |card| existing_fronts.include?(normalize(card.front)) }
+
+      @cards = existing_cards + new_cards
+      @ui.info("Synced #{new_cards.length} new cards with existing deck")
+    end
+
+    private
+
+    def generate_topics_in_parallel(topics, context:, difficulty:, count:, attachments:, jobs:)
+      work = topics.dup
+      lock = Mutex.new
+      results = Queue.new
+
+      threads = [jobs, topics.length].min.times.map do
+        Thread.new do
+          loop do
+            topic = lock.synchronize { work.pop }
+            break if topic.nil?
+
+            client.generate_multiple_flashcards(
+              topics: [topic], context:, difficulty:, count:, attachments:
+            ).each { |card| results << card }
+          end
+        end
+      end
+      threads.each(&:join)
+
+      collected = []
+      collected << results.pop until results.empty?
+      collected
+    end
+
+    def load_yaml(path)
+      YAML.safe_load_file(path, permitted_classes: [Time, Date], aliases: false)
+    rescue Psych::Exception => e
+      raise FileProcessingError, "Invalid YAML in #{path}: #{e.message}"
+    rescue SystemCallError => e
+      raise FileProcessingError, "Cannot read #{path}: #{e.message}"
+    end
+
+    def extract_card_list(content)
+      content.is_a?(Array) ? content : content['cards'] || []
+    end
+
+    def build_cards(raw_cards)
+      Array(raw_cards).map do |raw|
+        next nil unless raw.is_a?(Hash)
+
+        Card.new(front: raw['front'], back: raw['back'], tags: raw['tags'] || [], cloze: raw['cloze'])
+      rescue ValidationError => e
+        @ui.warn("Skipping invalid card: #{e.message}")
+        nil
+      end.compact
+    end
+
+    def normalize(text)
+      text.to_s.strip.downcase
+    end
+  end
+end

data/lib/anki_generator/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AnkiGenerator
+  # Base class for all errors raised by this gem. Rescue this to catch anything
+  # the library raises intentionally.
+  class Error < StandardError; end
+
+  # Raised when required configuration (e.g. API key) is missing or invalid.
+  class ConfigurationError < Error; end
+
+  # Raised when the LLM provider responds with an error status.
+  class ApiError < Error; end
+
+  # Raised when the API response cannot be parsed into flashcards.
+  class ResponseParseError < Error; end
+
+  # Raised when a flashcard definition is invalid (e.g. empty front/back).
+  class ValidationError < Error; end
+
+  # Raised when an input file (deck YAML, prompt file, attachment) cannot be processed.
+  class FileProcessingError < Error; end
+end

data/lib/anki_generator/file_processor.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'errors'
+require_relative 'ui'
+
+module AnkiGenerator
+  # Handles file and directory processing for attachments and prompt files.
+  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
+
+    class << self
+      def process_attachments(paths, ui: UI.new($stderr))
+        return [] if paths.nil? || paths.empty?
+
+        attachments = []
+        total_size = 0
+
+        paths.each do |path_str|
+          candidates = candidates_for(path_str, ui:)
+          attachments, total_size = take_up_to_budget(candidates, attachments, total_size, ui)
+        end
+
+        ui.info("📎 Processed #{attachments.length} file(s) (#{format_size(total_size)})") if attachments.any?
+        attachments
+      end
+
+      # Resolves one CLI path argument to the list of attachments it contributes:
+      # a directory contributes all readable text files inside it, a file
+      # contributes itself. Unusable paths warn and contribute nothing.
+      def candidates_for(path_str, ui:)
+        path = Pathname.new(path_str)
+
+        unless path.exist?
+          ui.warn("Path does not exist: #{path_str}")
+          return []
+        end
+
+        return process_directory(path, ui:) if path.directory?
+
+        if path.file?
+          attachment = process_file(path, ui:)
+          return [attachment].compact
+        end
+
+        ui.warn("Path is neither file nor directory: #{path_str}")
+        []
+      end
+
+      def process_directory(dir_path, ui: UI.new($stderr))
+        dir_path.children.filter_map do |child|
+          process_file(child, ui:) if child.file?
+        end
+      end
+
+      def process_file(file_path, ui: UI.new($stderr))
+        if file_path.size > MAX_FILE_SIZE
+          ui.warn("File too large, skipping: #{file_path} (#{format_size(file_path.size)})")
+          return nil
+        end
+
+        unless text_file?(file_path)
+          ui.warn("Non-text file, skipping: #{file_path}")
+          return nil
+        end
+
+        content = read_content(file_path, ui:)
+        return nil unless content
+
+        {
+          filename: file_path.basename.to_s,
+          path: file_path.to_s,
+          content:
+        }
+      end
+
+      def text_file?(file_path)
+        ext = file_path.extname.downcase
+        return true if TEXT_EXTENSIONS.include?(ext)
+
+        # Files without an extension are treated as text only if the name looks
+        # like a plain-text script (e.g. Gemfile, Rakefile).
+        return false if file_path.extname.empty? && file_path.basename.to_s !~ /^[A-Z_]+$/
+
+        # Fall back to sniffing for null bytes, which indicate binary content.
+        !file_path.read(512, encoding: 'BINARY').include?("\x00")
+      rescue StandardError
+        false
+      end
+
+      def 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 read_prompt_from_file(file_path)
+        path = Pathname.new(file_path)
+        raise FileProcessingError, "Prompt file does not exist: #{file_path}" unless path.exist?
+        raise FileProcessingError, "Prompt path is not a file: #{file_path}" unless path.file?
+
+        content = path.read(encoding: 'UTF-8').strip
+        raise FileProcessingError, "Prompt file is empty: #{file_path}" if content.empty?
+
+        content
+      rescue FileProcessingError
+        raise
+      rescue StandardError => e
+        raise FileProcessingError, "Could not read prompt file #{file_path}: #{e.message}"
+      end
+
+      private
+
+      # Appends candidates to attachments while the total-size budget allows,
+      # warning and stopping once the budget is exhausted.
+      def take_up_to_budget(candidates, attachments, total_size, ui)
+        candidates.each do |attachment|
+          if total_size + attachment[:content].bytesize > MAX_TOTAL_SIZE
+            ui.warn("Total attachment size limit reached. Skipping #{attachment[:filename]}")
+            next
+          end
+
+          attachments << attachment
+          total_size += attachment[:content].bytesize
+        end
+        [attachments, total_size]
+      end
+
+      # NOTE: files larger than MAX_FILE_SIZE never reach this method (they are
+      # rejected in process_file), so no post-read truncation is needed.
+      def read_content(file_path, ui:)
+        file_path.read(encoding: 'UTF-8')
+      rescue StandardError => e
+        ui.warn("Could not read file #{file_path}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/anki_generator/importers/csv.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'csv'
+require_relative '../errors'
+
+module AnkiGenerator
+  module Importers
+    # Parses a CSV file into flashcards.
+    #
+    # Expected columns: front,back — with an optional third column of tags.
+    # A header row (front,back[,tags]) is detected case-insensitively and
+    # skipped. Tags are separated by `|` within the third column.
+    class Csv
+      TAG_SEPARATOR = '|'
+
+      def self.parse(text)
+        new(text).parse
+      end
+
+      def initialize(text)
+        @text = text.to_s
+      end
+
+      # Returns an array of card hashes: { 'front', 'back', 'tags' => [...] }.
+      def parse
+        rows = CSV.parse(@text)
+        rows = rows[1..] if header_row?(rows.first)
+
+        rows.filter_map do |row|
+          front, back, tags = row
+          next nil if front.to_s.strip.empty?
+
+          {
+            'front' => front.to_s.strip,
+            'back' => back.to_s.strip,
+            'tags' => tags.to_s.split(TAG_SEPARATOR).map(&:strip).reject(&:empty?)
+          }
+        end
+      rescue CSV::MalformedCSVError => e
+        raise FileProcessingError, "Invalid CSV: #{e.message}"
+      end
+
+      private
+
+      def header_row?(row)
+        return false unless row
+
+        row[0].to_s.strip.casecmp('front').zero?
+      end
+    end
+  end
+end

data/lib/anki_generator/importers/markdown.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module AnkiGenerator
+  module Importers
+    # Parses study notes written in Markdown into flashcards.
+    #
+    # Supported card syntax:
+    #   Q: What is the capital of France?
+    #   A: Paris
+    #
+    # or, as list items:
+    #   - **What is 2 + 2?** — 4
+    #
+    # Headings (`#`, `##`, ...) are treated as tags for the cards that follow
+    # them, so a file can be organized into sections that become tag groups.
+    class Markdown
+      BULLET_CARD = /^\s*[-*]\s+\*\*(?<front>.+?)\*\*\s*(?:—|--|-|–|:)\s*(?<back>.+?)\s*$/
+      QUESTION_LINE = /^Q:\s*(?<front>.+)$/
+      ANSWER_LINE = /^A:\s*(?<back>.+)$/
+      HEADING_LINE = /^#+\s+(?<title>.+?)\s*#*\s*$/
+
+      def self.parse(text)
+        new(text).parse
+      end
+
+      def initialize(text)
+        @lines = text.to_s.lines.map(&:rstrip)
+      end
+
+      # Returns an array of card hashes: { 'front', 'back', 'tags' => [...] }.
+      def parse
+        @cards = []
+        @tags = []
+        @pending_question = nil
+
+        @lines.each { |line| handle_line(line) }
+
+        @cards
+      end
+
+      private
+
+      def handle_line(line)
+        if (match = HEADING_LINE.match(line))
+          @tags = [match[:title]]
+        elsif (match = QUESTION_LINE.match(line))
+          @pending_question = match[:front].strip
+        elsif (match = ANSWER_LINE.match(line))
+          flush_answer(match[:back].strip)
+        elsif (match = BULLET_CARD.match(line))
+          @cards << card_hash(match[:front].strip, match[:back].strip, @tags)
+        elsif !line.strip.empty?
+          # Any other non-empty line cancels a dangling Q: without its A:.
+          @pending_question = nil
+        end
+      end
+
+      def flush_answer(back)
+        return unless @pending_question
+
+        @cards << card_hash(@pending_question, back, @tags)
+        @pending_question = nil
+      end
+
+      def card_hash(front, back, tags)
+        { 'front' => front, 'back' => back, 'tags' => tags.dup }
+      end
+    end
+  end
+end

data/lib/anki_generator/prompt_builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module AnkiGenerator
+  # Builds the prompts sent to the LLM. Kept separate from the client so the
+  # prompt contract can be tested in isolation.
+  class PromptBuilder
+    def single_card(topic:, context: nil, difficulty: 'medium', attachments: nil)
+      <<~PROMPT.strip
+        Create a single flashcard for the topic: "#{topic}"
+        Difficulty level: #{difficulty}
+        #{context_line(context)}
+        #{attachments_section(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_hint(attachments)}
+      PROMPT
+    end
+
+    def multiple_cards(topics:, context: nil, difficulty: 'medium', count: 5, attachments: nil)
+      topics_list = topics.is_a?(Array) ? topics.join(', ') : topics.to_s
+
+      <<~PROMPT.strip
+        Create #{count} flashcards covering these topics: #{topics_list}
+        Difficulty level: #{difficulty}
+        #{context_line(context)}
+        #{attachments_section(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_hint(attachments)}
+      PROMPT
+    end
+
+    private
+
+    def context_line(context)
+      context ? "Additional context: #{context}" : ''
+    end
+
+    def attachments_hint(attachments)
+      if attachments && !attachments.empty?
+        'Use the provided file content to create more accurate and detailed flashcards.'
+      else
+        ''
+      end
+    end
+
+    def 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
+end