llm-spell 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51c9111bd6a08d766b059d39518f0678021dd1e7b67fb18c9693681a9d6c4dce
+  data.tar.gz: 82298f5be8162f8eb29d031e55974fc566cc586e02d34fa9eead3502a657400a
+SHA512:
+  metadata.gz: 379205906480b491d1436d123a07c5ade826e55be38a0b3681d5deee38107ae80aa8a87e112e817c17ec676019951c9403d45296cdfae4df319384720daff121
+  data.tar.gz: 3d96bc466a4694502406226d4178f8da11eee55100cfb4b59159e89c5b32fa22f7dae0ce79957183a0c6a7b496182637172854c51093d17e43eefacf7dacde64

data/README.md

@@ -0,0 +1,103 @@
+## About
+
+llm-spell is both a library and command-line utility that
+corrects spelling mistakes using a Large Language Model (LLM).
+It is powered by [llm.rb](https://github.com/llmrb/llm).
+
+## Motivation
+
+This project was born while I was working on the documentation
+for a friend's open source project. After realizing how much
+manual effort was involved with traditional spell checkers I
+decided to see if I could leverage LLMs to make the process
+easier and also faster.
+
+Compared to traditional spell checkers like `aspell` and `hunspell`,
+`llm-spell` provides significantly more accurate suggestions with
+far fewer false positives – eliminating the need to manually
+ignore irrelevant corrections, and that often reduces the overall
+time spent on correcting spelling mistakes.
+
+I would call the experiment a success but I also realize this
+approach is not for everyone, or every situation. For example,
+my friend preferred to not use AI for this and instead we opted
+to stick with `hunspell` – even though it meant more
+manual work.
+
+## Features
+
+- ✨ **LLM-powered corrections** – smarter spelling fixes than traditional tools
+- 🤖 **Fewer false positives** – avoids flagging uncommon but valid words
+- 🌐 **Broad provider support** – use OpenAI, Gemini, or xAI (Grok) out of the box
+- 💻 **Offline ready** – run locally with Ollama and LlamaCpp, no cloud required
+- 🔒 **Privacy** – keep sensitive text local with offline models
+- 🛠️ **Easy to use** – provides an easy to use library and command-line utility
+
+## Library
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+require "llm/spell"
+
+##
+# Text
+llm  = LLM.openai(key: ENV["OPENAI_SECRET"])
+text = LLM::Spell::Text.new("Ths is a smple txt with sme speling erors.", llm)
+print "mistakes: ", text.mistakes, "\n"
+print "corrections: ", text.corrections, "\n"
+
+##
+# PDF
+llm  = LLM.openai(key: ENV["OPENAI_SECRET"])
+file = LLM::Spell::Document.new("typos.pdf", llm)
+print "mistakes: ", file.mistakes, "\n"
+print "corrections: ", file.corrections, "\n"
+```
+
+## CLI
+
+#### Configuration
+
+The command line interface can be configured through the configuration file
+located at `$XDG_CONFIG_HOME/llm-spell.yml` or `~/.config/llm-spell.yml`. It
+is also possible to provide the configuration at the command-line, but usually
+it's more convenient to use the configuration file:
+
+```yaml
+# ~/.config/llm-spell.yml
+openai:
+  key: YOURKEY
+gemini:
+  key: YOURKEY
+xai:
+  key: YOURKEY
+ollama:
+  host: localhost
+llamacpp:
+  host: localhost
+```
+
+#### Usage
+
+```sh
+Usage: llm-spell [OPTIONS]
+    -p, --provider NAME              Required. Options: gemini, openai, xai, ollama or llamacpp.
+    -f, --file FILE                  Required. The file to check.
+    -k, --key [KEY]                  Optional. Required by gemini, openai, and xai.
+    -v, --version                    Optional. Print the version and exit.
+```
+
+## Demo
+
+<details>
+  <summary>Start demo</summary>
+  <img src="share/llm-spell/demo.gif" alt="Demo of llm-spell in action" />
+</details>
+
+## License
+
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)
+<br>
+See [LICENSE](./LICENSE)
+

data/bin/llm-spell

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+def wait
+  Process.wait
+rescue Interrupt
+  retry
+end
+
+def libexec
+  File.realpath File.join(__dir__, "..", "libexec", "llm-spell")
+end
+
+def main(argv)
+  Process.spawn File.join(libexec, "check"), *ARGV[0..]
+  Process.wait
+rescue Interrupt
+  wait
+end
+main(ARGV)
+exit $?&.exitstatus || 1

data/lib/llm/spell/cli.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class LLM::Spell
+  class CLI
+    attr_reader :text, :content
+
+    def initialize(text)
+      @text = text
+    end
+
+    def start
+      say "please wait"
+      if text.mistakes.empty?
+        say "no mistakes found"
+      else
+        text.mistakes.each.with_index do |mistake, i|
+          correction = text.corrections[i]
+          print "#{mistake} => #{correction}", "\n"
+          print "Replace? (y/N): "
+          res = $stdin.gets
+          @text.to_s.gsub!(mistake, correction) if res&.strip&.downcase == "y"
+          print "\n"
+        end
+      end
+      @text
+    end
+
+    private
+
+    def say(*messages)
+      print "llm-spell: ", *messages, "\n"
+    end
+  end
+end

data/lib/llm/spell/document.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class LLM::Spell
+  ##
+  # The {LLM::Spell::Document LLM::Spell::Document} class can analyze a given
+  # text file or document, and return any spelling mistakes that were
+  # found – along with suggested corrections.
+  class Document
+    include LLM::Spell::Engine
+
+    ##
+    # @param [File] input
+    #  The file to be analyzed
+    # @param [LLM::Provider] provider
+    #  An instance of LLM::Provider
+    # @return [LLM::Spell::Document]
+    def initialize(input, llm)
+      @input = input
+      @llm = llm
+      @bot = LLM::Bot.new(llm, schema:)
+    end
+  end
+end

data/lib/llm/spell/engine.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class LLM::Spell
+  module Engine
+    ##
+    # @return [Array<String>]
+    #  An array of unique spelling mistakes found in the text
+    def mistakes
+      response["mistakes"].uniq
+    end
+
+    ##
+    # @return [Array<String>]
+    #  An array of unique corrections corresponding to the mistakes
+    def corrections
+      response["corrections"].uniq
+    end
+
+    ##
+    # @return [String]
+    def inspect = "#<#{self.class}:0x#{object_id.to_s(16)} " \
+                  "mistakes=#{mistakes.size} corrections=#{corrections.size}>"
+
+    private
+
+    attr_reader :input, :llm, :bot
+
+    def prompt
+      <<~PROMPT
+        Your task is to find all spelling mistakes in the user's input and provide corrections.
+        Return a JSON object with two arrays:
+        - "mistakes": a list of all detected spelling mistakes.
+        - "corrections": a list of corrections, where each correction is at the same index as its corresponding mistake in the "mistakes" array.
+        Make sure that each mistake and its correction appear at the same index in their respective arrays.
+      PROMPT
+    end
+
+    def schema
+      llm.schema.object(
+        mistakes: llm.schema.array(llm.schema.string.required),
+        corrections: llm.schema.array(llm.schema.string.required)
+      )
+    end
+
+    def response
+      @response ||= begin
+        input = (LLM::Spell::Document === self) ? File.open(@input, "rb") : @input
+        bot.chat prompt, role: :user
+        bot.chat input, role: :user
+        bot.messages.find(&:assistant?).content!
+      end
+    end
+  end
+end

data/lib/llm/spell/text.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class LLM::Spell
+  ##
+  # The {LLM::Spell::Text LLM::Spell::Text} class can analyze a given
+  # piece of text and return any spelling mistakes it found – along
+  # with suggested corrections.
+  class Text
+    include LLM::Spell::Engine
+
+    ##
+    # @param [String] text
+    #  The contents of the Text
+    # @param [LLM::Provider] provider
+    #  An instance of LLM::Provider
+    def initialize(input, llm)
+      @input = input
+      @llm = llm
+      @bot = LLM::Bot.new(llm, schema:)
+    end
+
+    def to_s = input
+    def to_str = input
+  end
+end

data/lib/llm/spell/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LLM
+end unless defined?(LLM)
+
+class LLM::Spell
+  VERSION = "0.1.0"
+end

data/lib/llm/spell.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module LLM
+end unless defined?(LLM)
+
+class LLM::Spell
+  require "llm"
+  require "yaml"
+  require_relative "spell/version"
+  require_relative "spell/engine"
+  require_relative "spell/document"
+  require_relative "spell/text"
+  require_relative "spell/cli"
+
+  ##
+  # The superclass of all LLM::Spell errors
+  Error = Class.new(RuntimeError)
+
+  ##
+  # @param [Hash] options
+  # @return [LLM::Spell]
+  def initialize(options)
+    @options = options
+    @text = Text.new(File.read(@options[:file]), llm)
+  end
+
+  ##
+  # Run in interactive mode
+  # @return [void]
+  def interactive
+    if mime_types.include?(LLM::Mime[file])
+      File.write file, CLI.new(@text).start
+    else
+      raise Error, "In interactive mode, the following mime types " \
+                   "are supported: #{mime_types.join(', ')}"
+    end
+  end
+
+  private
+
+  def options
+    if @options[:key]
+      {key: @options[:key]}
+    elsif File.readable?(config_file)
+      config[provider.to_s].transform_keys(&:to_sym)
+    else
+      raise Error, "No API key available"
+    end
+  end
+
+  def llm = @llm ||= LLM.method(provider).call(**options)
+  def provider = @options[:provider]
+  def config_dir = ENV["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config")
+  def config_file = File.join(config_dir, "llm-spell.yml")
+  def config = @config ||= YAML.load_file(config_file)
+  def file = @options[:file]
+  def mime_types = ["text/plain", "text/markdown"]
+end

data/libexec/llm-spell/check

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+def main(argv)
+  require "optparse"
+  require_relative "../../lib/llm/spell"
+  if argv.include?("-v") || argv.include?("--version")
+    puts LLM::Spell::VERSION
+  else
+    options = {}
+    option_parser.parse(argv, into: options)
+    if argv.empty? || options[:file].nil? || options[:provider].nil?
+      warn option_parser.help
+      throw(:exit, 1)
+    else
+      LLM::Spell.new(options).interactive
+    end
+  end
+end
+
+def option_parser
+  OptionParser.new do |o|
+    o.banner = "Usage: llm-spell [OPTIONS]"
+    o.on("-p PROVIDER", "--provider NAME", "Required. Options: gemini, openai, xai, ollama or llamacpp.", String)
+    o.on("-f FILE", "--file FILE", "Required. The file to check.", String)
+    o.on("-k [KEY]", "--key [KEY]", "Optional. Required by gemini, openai, and xai.", String)
+    o.on("-v", "--version", "Optional. Print the version and exit.")
+  end
+end
+
+excode = catch(:exit) do
+  main(ARGV)
+  0
+rescue => ex
+  warn "#{ex.class}: #{ex.message}"
+  warn ex.backtrace[0..5].join("\n")
+  1
+end
+exit excode

data/llm-spell.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/llm/spell/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "llm-spell"
+  spec.version = LLM::Spell::VERSION
+  spec.authors = ["Antar Azri", "0x1eef"]
+  spec.email = ["azantar@proton.me", "0x1eef@proton.me"]
+
+  spec.summary = "llm-spell is a command-line utility that " \
+                 "can correct spelling mistakes with the help " \
+                 "of a Large Language Model (LLM). Compared to " \
+                 "traditional spell checkers like `aspell` and `hunspell`, " \
+                 "llm-spell often produces fewer false positives and more " \
+                 "accurate suggestions."
+  spec.description = spec.summary
+  spec.homepage = "https://github.com/llmrb/llm-spell"
+  spec.license = "0BSD"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir[
+    "README.md", "LICENSE",
+    "lib/*.rb", "lib/**/*.rb",
+    "libexec/*", "libexec/**/*",
+    "bin/*", "llm-spell.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+  spec.executables = ["llm-spell"]
+  spec.add_dependency "llm.rb", "~> 0.14"
+  spec.add_development_dependency "webmock", "~> 3.24.0"
+  spec.add_development_dependency "yard", "~> 0.9.37"
+  spec.add_development_dependency "kramdown", "~> 2.4"
+  spec.add_development_dependency "webrick", "~> 1.8"
+  spec.add_development_dependency "test-cmd.rb", "~> 0.12.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "standard", "~> 1.40"
+  spec.add_development_dependency "vcr", "~> 6.0"
+  spec.add_development_dependency "dotenv", "~> 2.8"
+end

metadata

@@ -0,0 +1,215 @@
+--- !ruby/object:Gem::Specification
+name: llm-spell
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Antar Azri
+- '0x1eef'
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: llm.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.24.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.24.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: test-cmd.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: llm-spell is a command-line utility that can correct spelling mistakes
+  with the help of a Large Language Model (LLM). Compared to traditional spell checkers
+  like `aspell` and `hunspell`, llm-spell often produces fewer false positives and
+  more accurate suggestions.
+email:
+- azantar@proton.me
+- 0x1eef@proton.me
+executables:
+- llm-spell
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/llm-spell
+- lib/llm/spell.rb
+- lib/llm/spell/cli.rb
+- lib/llm/spell/document.rb
+- lib/llm/spell/engine.rb
+- lib/llm/spell/text.rb
+- lib/llm/spell/version.rb
+- libexec/llm-spell/check
+- llm-spell.gemspec
+homepage: https://github.com/llmrb/llm-spell
+licenses:
+- 0BSD
+metadata:
+  homepage_uri: https://github.com/llmrb/llm-spell
+  source_code_uri: https://github.com/llmrb/llm-spell
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: llm-spell is a command-line utility that can correct spelling mistakes with
+  the help of a Large Language Model (LLM). Compared to traditional spell checkers
+  like `aspell` and `hunspell`, llm-spell often produces fewer false positives and
+  more accurate suggestions.
+test_files: []