Ruby API reference

The Ruby API is one module, Kotoshu, with a strict two-stage resource model underneath.

参照Reference

Two stages, on purpose

Stage one is Kotoshu.setup — slow, network-bound, explicit. It downloads (or registers local) dictionaries, frequency lists, and models into the cache. Stage two is everything else: correct?, suggest, check resolve resources from cache only.

If the language is not set up, the hot path raises Kotoshu::ResourceNotSetupError. That is intentional, not an accident to catch: no method in the library will ever download on your behalf, so a metered or air-gapped host cannot be surprised. The CLI intercepts the error and offers to run setup interactively. Use Kotoshu.setup?(lang) or Kotoshu.setup?(lang, :model) to ask first.

Facade methods

Checking words

require "kotoshu"

Kotoshu.setup(:en)   # Stage 1 — once per language

# Stage 2 — cache-only, never touches the network
Kotoshu.correct?("hello")  # => true
Kotoshu.correct?("helo")   # => false

# Another language: set it up first, then address it per call
Kotoshu.setup(:de)
Kotoshu.misspelled?("Hallo", language: "de")  # => false

Suggestions

Suggestions come back as a SuggestionSet carrying words, distances, and confidence. Call to_words when you only need the strings.

suggestions = Kotoshu.suggest("helo")
suggestions.to_words  # => ["hello", "help", "held", ...]

Documents and files

result = Kotoshu.check("Hello wrold")
result.errors.map(&:word)  # => ["wrold"]

result = Kotoshu.check_file("README.md")
result.errors.each do |error|
puts "#{error.word} at offset #{error.position}: #{error.top_suggestions(3).join(', ')}"
end

results = Kotoshu.check_files(%w[README.md CHANGELOG.md])
results.select(&:failed?)

Language detection

Kotoshu.detect_language("Bonjour le monde")  # => "fr"

lang, confidence = Kotoshu.detect_language_with_confidence("Hello world")
lang        # => "en"
confidence  # => 0.85

Resources

Kotoshu.setup(:en, want: %i[spelling frequency model])
Kotoshu.setup(:en, :de, :fr)   # several languages, one call

# Local hunspell files instead of downloads (single language)
Kotoshu.setup(:en, aff: "/usr/share/hunspell/en_US.aff",
dic: "/usr/share/hunspell/en_US.dic")
Kotoshu.setup(:en, from: "/usr/share/hunspell/")  # expects en.aff, en.dic

Kotoshu.setup?(:en, :frequency)  # => false unless fetched
Kotoshu.languages_setup         # => ["de", "en"]

Setup is idempotent — re-running it with the same arguments is a no-op unless force: true. Each SetupResult reports per-resource status: :downloaded, :local, :cached, or :unavailable.

Semantic analysis (optional)

The semantic layer reranks Hunspell candidates by context similarity. It requires the optional onnxruntime gem; without it, everything above still works. Guard on ONNX_LOADED.

if Kotoshu::Models::OnnxModel::ONNX_LOADED
Kotoshu.setup(:en, want: %i[spelling model])
model    = Kotoshu::Models::OnnxModel.from_github("en")
analyzer = Kotoshu::Analyzers::SemanticAnalyzer.new(model)

analyzer.analyze(Kotoshu.check("Hello wrold"))

analyzer.suggest_corrections("helo", context: "I said helo to the world")
.map(&:word)  # => ["hello"]
end

全覧Full reference