anki_generator 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8124d9ca11c2259790dfabfb10f1fab725cfa4889300d6bf91353cce45b9604
-  data.tar.gz: 6be84b8c3d8d430c91ad7c02f0fb063cc3e5ea27c35ee946d2c3ea091aedb994
+  metadata.gz: b5a70e0ea5175cfd6c2b76421bf969d170d80cabc73f1a621d781b297d006365
+  data.tar.gz: 35f411b4e13dcf03b6ffe5a674394ed1521618c260e8f12019b6609d85e714c4
 SHA512:
-  metadata.gz: 1bae0bd4aad23ab158031ab876385a10660559b5a9acca2be6a4ba932a2851e7c468e5b18d5db33f57724198fe8fda3e6478dfec05718f1a15703fd3a188bf1b
-  data.tar.gz: 25c74048b6dcd2428aab8f879cfebd41b81d7264bd3a5f8e8805530563b7099b9ee72be220e97fe1af070aa44460a084d20fa8010ea658e686a031415c1c2f90
+  metadata.gz: e960819a79d0870a346234ccb110cb3476a794b6d568f4093ea73a4557290556244b0f4b1510d47865c6119192f8e7c160f9f95a49c63f30c1dcb44e88bd43a1
+  data.tar.gz: 11efe7e80b4fd146ca8ceef017fb6c7f558696dee1f76bad2d18de41f3f2908bf57a2f5497bedf20aa4158d931d7b39c60380139a6e2949a7384c1589ddf965d

data/.gitignore

@@ -0,0 +1,59 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+.env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+#
+input/*.yaml
+*.apkg

data/.rubocop.yml

@@ -0,0 +1,79 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'examples/**/*'
+    - 'scripts/**/*'
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'tests/**/*'
+    # Static Anki data blobs; length is driven by the format, not design.
+    - 'lib/anki_generator/apkg_schema.rb'
+
+Metrics/ClassLength:
+  Max: 150
+  Exclude:
+    - 'tests/**/*'
+    # The server class embeds the single-page UI as one static HTML heredoc;
+    # its size is data, not design.
+    - 'lib/anki_generator/server.rb'
+
+Metrics/BlockLength:
+  Max: 30
+  Exclude:
+    - 'tests/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+
+Metrics/AbcSize:
+  Max: 30
+  Exclude:
+    - 'tests/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+# The schema module is static Anki data (SQL + default JSON blobs); its size is
+# driven by the format, not by design choices.
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/anki_generator/apkg_schema.rb'
+
+# Command initializers take their full option surface as keyword arguments;
+# counting them against the positional-parameter limit is meaningless.
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+# Short parameter names that are unambiguous in this codebase.
+Naming/MethodParameterName:
+  AllowedNames:
+    - ui
+    - io
+    - id
+    - db
+    - e
+
+# WEBrick dispatches to servlets via the camelCase do_GET/do_POST contract.
+Naming/MethodName:
+  Exclude:
+    - 'lib/anki_generator/server.rb'
+
+# Test class names are self-describing.
+Style/Documentation:
+  Exclude:
+    - 'tests/**/*'
+
+# CLI output strings legitimately use double quotes for interpolation.
+Style/StringLiterals:
+  EnforcedStyle: single_quotes

data/.ruby-version

@@ -0,0 +1 @@
+3.3.10

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.10

data/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2026-10-01
+
+### Breaking
+- **Provider-agnostic LLM layer** — the hand-rolled `OpenRouterClient` and `OllamaClient` (Faraday) are replaced by a single `AnkiGenerator::LlmClient` backed by [ruby_llm](https://github.com/crmne/ruby_llm). Gemini is now the default provider (`gemini-3.8-flash`); OpenAI, Anthropic, OpenRouter, and local Ollama (plus any other ruby_llm provider) work through the same client
+- API keys move to provider env vars — `GOOGLE_API_KEY` / `GEMINI_API_KEY` (default), `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `OLLAMA_URL` for local Ollama; `OPENROUTER_API_KEY` alone no longer drives the tool
+- `--provider` is now free-form (any ruby_llm provider name) and defaults to auto-resolution from the model name; `--provider openrouter|ollama` enum is gone
+- `--api-key` now requires an explicit `--provider`
+- `--structured` flag removed — structured output is always on (see below)
+- Dependencies: `faraday` / `faraday-retry` dropped; `ruby_llm ~> 2.0` and `sinatra ~> 4.0` added
+
+### Added
+- **Structured outputs** — card generation now uses ruby_llm/Schematist JSON Schema (`AnkiGenerator::SingleCardSchema` / `MultipleCardsSchema`), so providers validate the card shape at the API level; non-conforming responses raise `ResponseParseError`
+- `GOOGLE_API_KEY` acts as a fallback for the Gemini key when `GEMINI_API_KEY` is unset (bridged into `RubyLLM.configure` by `LlmClient`)
+- `AnkiGenerator::TEMPERATURE` constant (0.7) exposed on the client
+- `anki_generator serve [--provider PROVIDER]` — the web editor can now default to a chosen LLM provider
+
+### Changed
+- **Web server rewritten on Sinatra 4** (was WEBrick servlets + inline HTML heredoc): routes live in `AnkiGenerator::Server`, the UI page moved to `lib/anki_generator/server/public/index.html`, YAML parsing extracted to `AnkiGenerator::Importers::Yaml`, and `.apkg` building to `AnkiGenerator::ApkgExporter` — each concern is now independently testable
+- Default model: `gemini-3.8-flash`
+- `--model` / `ANKI_GENERATOR_MODEL` override the default as before
+- README rewritten for the new provider model
+
+### Technical
+- Test suite: 125 tests, 0 failures, 94% line coverage — server tests moved to rack-test (no real sockets); LLM tests webmock-stub the Gemini `generateContent` endpoint including schema request-body assertions
+- RuboCop zero offenses
+- Note: ruby_llm 2.0 does not auto-detect provider ENV vars — `LlmClient` bridges them
+
+## [1.3.0] - 2026-09-30
+
+### Added
+- **Markdown & CSV importers** (`AnkiGenerator::Importers::Markdown` / `Importers::Csv`) — turn study notes into decks:
+  - Markdown: `Q:`/`A:` pairs, `- **front** — back` bullets, headings become tags
+  - CSV: `front,back[,tags]` (tags pipe-separated)
+  - New command: `anki_generator import DECK_NAME INPUT_FILE OUTPUT_FILE [--reverse]`
+- **Cloze deletion cards** — YAML cards with a `cloze:` key (`cloze: "{{c1::Paris}} is the capital of {{c2::France}}"`) export as a proper Anki cloze note; one card per `{{cN::...}}` ordinal, with a dedicated `AnkiGenerator Cloze` model in the package
+- **Per-card tags** — `tags: [ruby, basics]` in YAML lands in the note's tag column; `--reverse` and importers compose with tags
+- **Reverse cards** — `--reverse` on `generate`/`import` appends a front↔back copy of every basic card (cloze cards are skipped)
+- **Parallel AI generation** — `--jobs N` on `generate` fans one API call per topic out across N threads (Mutex + Queue worker pool)
+- **Ollama provider** — `--provider ollama` talks to a local Ollama server (`OLLAMA_URL`, default `http://localhost:11434`, no API key); provider selection unified behind `AnkiGenerator::ClientFactory`
+- **Automatic retries** — Faraday retry middleware on OpenRouter (3 attempts, exponential backoff, honors `Retry-After` on 429/5xx)
+- **Structured output** — `--structured` requests JSON mode (`response_format: json_object`) from providers that support it
+- **AnkiConnect push** — `anki_generator push DECK_NAME YAML_FILE` sends cards straight into a running Anki (`AnkiConnect` addon, default `http://localhost:8765`), reporting added/duplicate counts
+- **Web UI** — `anki_generator serve [--port]` starts a localhost editor (WEBrick, no build step): paste Markdown/YAML, generate via AI, edit the card table, download `.apkg`
+
+### Changed
+- `--model` now defaults per provider (`OllamaClient::DEFAULT_MODEL` for Ollama, `gpt-4o-mini` for OpenRouter) instead of a single global default
+- OpenRouter client accepts `structured:` and retry configuration; Ollama client mirrors the same interface
+
+### Technical
+- Test suite: 131 tests, 415 assertions, 96.85% line coverage (floor remains 75%)
+- RuboCop zero offenses; `Metrics/ClassLength` / `Naming/MethodName` exclusions documented for the WEBrick servlet contract and the static HTML page heredoc
+- `.apkg` writer uses per-table id sequences (`@note_seq`/`@card_seq`) — fixes a primary-key collision when a cloze note expands into multiple card rows
+
+## [1.2.0] - 2026-09-30
+
+### Breaking
+- All classes are now namespaced under `AnkiGenerator::` (`AnkiGenerator::DeckBuilder`, `AnkiGenerator::OpenRouterClient`, `AnkiGenerator::FileProcessor`, `AnkiGenerator::CLI`)
+- Library API returns `AnkiGenerator::Card` value objects instead of raw hashes (`card.front` / `card.back`)
+- `AnkiGenerator` class renamed to `AnkiGenerator::DeckBuilder`; `sync_with_existing_deck` is now `sync_with`
+- Default model changed from the retired `openai/gpt-3.5-turbo` to `openai/gpt-4o-mini`
+
+### Added
+- Native `.apkg` writer (`AnkiGenerator::ApkgWriter` + `AnkiGenerator::ApkgSchema`) — replaces the unmaintained `anki2` gem and its deprecated sqlite3 bind-param style
+- Error hierarchy: `AnkiGenerator::Error` with `ConfigurationError`, `ApiError`, `ResponseParseError`, `ValidationError`, `FileProcessingError`
+- `AnkiGenerator::UI` presentation boundary — library code no longer writes to `$stdout` directly; commands accept an injectable UI for quiet/testable output
+- `AnkiGenerator::PromptBuilder` — prompt construction extracted from the HTTP client and unit-tested
+- `anki_generator version` command
+- CLI errors are reported as clean messages with exit code 1 instead of raw backtraces
+- Faraday request timeouts (10s open / 120s read)
+- Resilient JSON parsing: markdown fences and model commentary are stripped before parsing
+- `.ruby-version` / `.tool-versions` pinned to Ruby 3.3
+- SimpleCov coverage (line floor 75%) and WebMock-based HTTP tests
+
+### Fixed
+- **API URL bug**: the client posted to `/chat/completions` (leading slash replaced the base path), dropping `/api/v1` — every AI request would have 404'd
+- `prompt_to_deck` no longer sends the prompt through the API a second time when building the deck from generated cards
+- `prompt_to_deck` temp files no longer leak `temp_<timestamp>.yaml` into the working directory (uses `Tempfile`)
+- Deck YAML is loaded with `YAML.safe_load_file` (aliases rejected, typed errors on bad input)
+- Sync deduplication is now case-insensitive and trims whitespace
+- Previously dead test methods (defined outside their test classes) are collected and run — test count 38 → 80
+
+### Technical
+- Thor CLI is now a thin shell over `AnkiGenerator::Commands::*` service objects with dependency injection
+- RuboCop enforced in CI with zero offenses (`rake lint`)
+- HTTP client tested with WebMock against real request shapes
+- Test suite: 80 tests, 284 assertions
+
+## [1.1.0] - 2026-01-01
+
+### Added
+- **File Attachment Support**: Attach individual files or entire directories for context-aware flashcard generation
+- **Prompt File Support**: Use text files as prompts instead of command-line strings
+- **Intelligent File Processing**: Automatic text file detection with support for 20+ file types
+- **File Size Management**: Configurable limits (1MB per file, 5MB total) with automatic filtering
+- **Enhanced CLI Options**: 
+  - `--attach` option for file/directory attachments
+  - `--prompt-file` option to read prompts from files
+- **Comprehensive Test Suite**: Added `test_file_processor.rb` with full coverage
+- **Enhanced Rake Tasks**: 15+ development tasks including demos, examples, and utilities
+- **Developer Experience**: 
+  - `rake examples` - Create example files for testing
+  - `rake demo_attachments` - Demo file attachment features
+  - `rake setup` - Full development environment setup
+
+### Enhanced
+- **OpenRouter Client**: Extended to support file attachments in AI prompts
+- **Anki Generator**: Updated to pass attachments through the generation pipeline
+- **CLI Interface**: Both `generate_yaml` and `prompt_to_deck` commands support new options
+- **Documentation**: Comprehensive README updates with file attachment examples
+- **Error Handling**: Improved file processing with detailed warnings and graceful failures
+
+### Technical
+- Added `FileProcessor` class for robust file and directory handling
+- Enhanced prompt building with attachment content integration
+- Maintained full backward compatibility with existing functionality
+- All tests passing (38 tests, 128 assertions)
+
+## [1.0.0] - 2025-12-XX
+
+### Added
+- **AI-Powered Generation**: OpenRouter API integration with multiple model support
+- **Direct Prompt-to-Deck**: One-command flashcard generation from prompts
+- **Multiple Input Methods**: Support for YAML files and direct prompts
+- **Sync Functionality**: Merge new AI-generated cards with existing decks
+- **Comprehensive CLI**: Full command-line interface with Thor
+- **Model Selection**: Support for GPT, Claude, Llama, and other OpenRouter models
+- **Difficulty Levels**: Easy, medium, hard difficulty settings
+- **Context Support**: Additional context for better AI generation
+- **YAML Formats**: Both traditional and AI-generation YAML formats
+
+### Core Features
+- `prompt_to_deck` - Generate flashcards and create deck in one step
+- `generate_yaml` - Generate YAML from prompts for later use
+- `generate` - Create Anki decks from YAML files
+- `create_ai_template` - Create template files for AI generation
+- `test_api` - Test OpenRouter API connection
+
+### Technical
+- Built with Ruby, Thor, Faraday, and anki2 gem
+- Comprehensive test suite with minitest
+- Environment variable support with dotenv
+- Flexible configuration and error handling
+
+## [0.x.x] - Earlier Versions
+
+### Initial Development
+- Basic YAML to Anki deck conversion
+- Simple flashcard generation
+- Core functionality development
+
+---
+
+## Version Numbering
+
+This project follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible functionality additions  
+- **PATCH** version for backwards-compatible bug fixes
+
+## Contributing
+
+When contributing, please:
+1. Update this changelog with your changes
+2. Follow the existing format and categorization
+3. Add entries under "Unreleased" section
+4. Move entries to versioned section when releasing

data/Gemfile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake', '~> 13.0'
+  gem 'rubocop', '~> 1.60', require: false
+  gem 'ruby-lsp', require: false
+end
+
+group :test do
+  gem 'minitest', '~> 5.20'
+  gem 'rack-test', '~> 2.1'
+  gem 'simplecov', '~> 0.22', require: false
+  gem 'webmock', '~> 3.23'
+end
+
+# Ruby 3.3+ compatibility (faraday dependency)
+gem 'mutex_m' if RUBY_VERSION >= '3.3.0'

data/Makefile

@@ -0,0 +1,20 @@
+RUBY = bundle exec ruby
+RAKE = bundle exec rake
+BUNDLE = bundle
+TEST_FILES = test_*.rb
+
+install:
+	$(BUNDLE) install
+
+test:
+	$(RAKE)
+
+build:
+	$(RUBY) build.rbgenerate_apkg
+
+clean:
+	rm -f *.apkg
+
+all: install test build
+
+.PHONY: install test build clean all