Module: Kotoshu

Defined in:
lib/kotoshu/embeddings.rb,
lib/kotoshu.rb,
lib/kotoshu.rb,
lib/kotoshu/cli.rb,
lib/kotoshu/core.rb,
lib/kotoshu/data.rb,
lib/kotoshu/typo.rb,
lib/kotoshu/cache.rb,
lib/kotoshu/paths.rb,
lib/kotoshu/rspec.rb,
lib/kotoshu/checks.rb,
lib/kotoshu/jekyll.rb,
lib/kotoshu/models.rb,
lib/kotoshu/native.rb,
lib/kotoshu/grammar.rb,
lib/kotoshu/plugins.rb,
lib/kotoshu/readers.rb,
lib/kotoshu/results.rb,
lib/kotoshu/version.rb,
lib/kotoshu/baseline.rb,
lib/kotoshu/defaults.rb,
lib/kotoshu/keyboard.rb,
lib/kotoshu/language.rb,
lib/kotoshu/analyzers.rb,
lib/kotoshu/documents.rb,
lib/kotoshu/integrity.rb,
lib/kotoshu/languages.rb,
lib/kotoshu/algorithms.rb,
lib/kotoshu/cli/errors.rb,
lib/kotoshu/components.rb,
lib/kotoshu/debug_mode.rb,
lib/kotoshu/dictionary.rb,
lib/kotoshu/validators.rb,
lib/kotoshu/cache/cache.rb,
lib/kotoshu/checks/base.rb,
lib/kotoshu/suggestions.rb,
lib/kotoshu/typo/engine.rb,
lib/kotoshu/debug_logger.rb,
lib/kotoshu/dictionaries.rb,
lib/kotoshu/grammar/rule.rb,
lib/kotoshu/spellchecker.rb,
lib/kotoshu/configuration.rb,
lib/kotoshu/baseline/entry.rb,
lib/kotoshu/baseline/store.rb,
lib/kotoshu/checks/finding.rb,
lib/kotoshu/cli/auto_setup.rb,
lib/kotoshu/core/trie/node.rb,
lib/kotoshu/core/trie/trie.rb,
lib/kotoshu/fluent_checker.rb,
lib/kotoshu/language/suika.rb,
lib/kotoshu/metrics_module.rb,
lib/kotoshu/models/context.rb,
lib/kotoshu/native_backend.rb,
lib/kotoshu/plugins/plugin.rb,
lib/kotoshu/project_config.rb,
lib/kotoshu/results/result.rb,
lib/kotoshu/string_metrics.rb,
lib/kotoshu/checks/registry.rb,
lib/kotoshu/core/exceptions.rb,
lib/kotoshu/data_structures.rb,
lib/kotoshu/dictionary/base.rb,
lib/kotoshu/keyboard/layout.rb,
lib/kotoshu/language/script.rb,
lib/kotoshu/resource_bundle.rb,
lib/kotoshu/source_registry.rb,
lib/kotoshu/cache/base_cache.rb,
lib/kotoshu/cli/dict_command.rb,
lib/kotoshu/core/models/word.rb,
lib/kotoshu/plugins/registry.rb,
lib/kotoshu/readers/aff_data.rb,
lib/kotoshu/resource_manager.rb,
lib/kotoshu/tasks/check_task.rb,
lib/kotoshu/algorithms/lookup.rb,
lib/kotoshu/cache/model_cache.rb,
lib/kotoshu/cli/cache_command.rb,
lib/kotoshu/cli/status_report.rb,
lib/kotoshu/core/trie/builder.rb,
lib/kotoshu/data/frozen_kelly.rb,
lib/kotoshu/dictionary/cspell.rb,
lib/kotoshu/dictionary/custom.rb,
lib/kotoshu/embeddings/search.rb,
lib/kotoshu/keyboard/registry.rb,
lib/kotoshu/language/detector.rb,
lib/kotoshu/language/registry.rb,
lib/kotoshu/metrics_collector.rb,
lib/kotoshu/models/onnx_model.rb,
lib/kotoshu/models/suggestion.rb,
lib/kotoshu/algorithms/soundex.rb,
lib/kotoshu/algorithms/suggest.rb,
lib/kotoshu/cache/lookup_cache.rb,
lib/kotoshu/cli/batch_reporter.rb,
lib/kotoshu/cli/ignore_matcher.rb,
lib/kotoshu/conformance_runner.rb,
lib/kotoshu/dictionary/unified.rb,
lib/kotoshu/documents/document.rb,
lib/kotoshu/integrity/manifest.rb,
lib/kotoshu/integrity/net_http.rb,
lib/kotoshu/language/segmenter.rb,
lib/kotoshu/readers/aff_reader.rb,
lib/kotoshu/readers/dic_reader.rb,
lib/kotoshu/cli/directory_check.rb,
lib/kotoshu/dictionary/hunspell.rb,
lib/kotoshu/documents/text_node.rb,
lib/kotoshu/embeddings/protocol.rb,
lib/kotoshu/embeddings/registry.rb,
lib/kotoshu/grammar/rule_engine.rb,
lib/kotoshu/grammar/rule_loader.rb,
lib/kotoshu/integrity/audit_log.rb,
lib/kotoshu/language/identifier.rb,
lib/kotoshu/personal_dictionary.rb,
lib/kotoshu/readers/file_reader.rb,
lib/kotoshu/suggestions/context.rb,
lib/kotoshu/baseline/application.rb,
lib/kotoshu/cache/language_cache.rb,
lib/kotoshu/cache/model_registry.rb,
lib/kotoshu/checks/grammar_check.rb,
lib/kotoshu/cli/baseline_command.rb,
lib/kotoshu/cli/directory_walker.rb,
lib/kotoshu/cli/personal_command.rb,
lib/kotoshu/components/tokenizer.rb,
lib/kotoshu/conformance_exporter.rb,
lib/kotoshu/dictionaries/catalog.rb,
lib/kotoshu/embeddings/lru_cache.rb,
lib/kotoshu/languages/latin_base.rb,
lib/kotoshu/suggestions/pipeline.rb,
lib/kotoshu/cache/eviction_policy.rb,
lib/kotoshu/cache/frequency_cache.rb,
lib/kotoshu/checks/spelling_check.rb,
lib/kotoshu/cli/display_formatter.rb,
lib/kotoshu/cli/language_resolver.rb,
lib/kotoshu/cli/progress_reporter.rb,
lib/kotoshu/components/pos_tagger.rb,
lib/kotoshu/configuration/builder.rb,
lib/kotoshu/dictionary/plain_text.rb,
lib/kotoshu/dictionary/repository.rb,
lib/kotoshu/dictionary/unix_words.rb,
lib/kotoshu/embeddings/vocabulary.rb,
lib/kotoshu/keyboard/layouts/hrsl.rb,
lib/kotoshu/language/lid_detector.rb,
lib/kotoshu/languages/ar/language.rb,
lib/kotoshu/languages/bg/language.rb,
lib/kotoshu/languages/ca/language.rb,
lib/kotoshu/languages/cs/language.rb,
lib/kotoshu/languages/da/language.rb,
lib/kotoshu/languages/de/language.rb,
lib/kotoshu/languages/el/language.rb,
lib/kotoshu/languages/en/language.rb,
lib/kotoshu/languages/es/language.rb,
lib/kotoshu/languages/et/language.rb,
lib/kotoshu/languages/fa/language.rb,
lib/kotoshu/languages/fr/language.rb,
lib/kotoshu/languages/he/language.rb,
lib/kotoshu/languages/hr/language.rb,
lib/kotoshu/languages/hu/language.rb,
lib/kotoshu/languages/id/language.rb,
lib/kotoshu/languages/it/language.rb,
lib/kotoshu/languages/ja/language.rb,
lib/kotoshu/languages/ko/language.rb,
lib/kotoshu/languages/lt/language.rb,
lib/kotoshu/languages/lv/language.rb,
lib/kotoshu/languages/nb/language.rb,
lib/kotoshu/languages/ne/language.rb,
lib/kotoshu/languages/nl/language.rb,
lib/kotoshu/languages/nn/language.rb,
lib/kotoshu/languages/pl/language.rb,
lib/kotoshu/languages/pt/language.rb,
lib/kotoshu/languages/ro/language.rb,
lib/kotoshu/languages/ru/language.rb,
lib/kotoshu/languages/sk/language.rb,
lib/kotoshu/languages/sl/language.rb,
lib/kotoshu/languages/sr/language.rb,
lib/kotoshu/languages/sv/language.rb,
lib/kotoshu/languages/tr/language.rb,
lib/kotoshu/languages/uk/language.rb,
lib/kotoshu/languages/vi/language.rb,
lib/kotoshu/models/fasttext_model.rb,
lib/kotoshu/models/semantic_error.rb,
lib/kotoshu/models/word_embedding.rb,
lib/kotoshu/suggestions/generator.rb,
lib/kotoshu/cache/staged_languages.rb,
lib/kotoshu/cache/suggestion_cache.rb,
lib/kotoshu/cli/navigation_manager.rb,
lib/kotoshu/components/synthesizer.rb,
lib/kotoshu/configuration/resolver.rb,
lib/kotoshu/core/models/affix_rule.rb,
lib/kotoshu/documents/source_range.rb,
lib/kotoshu/documents/suppressions.rb,
lib/kotoshu/keyboard/layouts/greek.rb,
lib/kotoshu/keyboard/layouts/latin.rb,
lib/kotoshu/models/embedding_model.rb,
lib/kotoshu/multi_language_checker.rb,
lib/kotoshu/readers/lookup_builder.rb,
lib/kotoshu/suggestions/suggestion.rb,
lib/kotoshu/suggestions/typo_merge.rb,
lib/kotoshu/algorithms/permutations.rb,
lib/kotoshu/cli/completions_command.rb,
lib/kotoshu/core/indexed_dictionary.rb,
lib/kotoshu/keyboard/layouts/arabic.rb,
lib/kotoshu/keyboard/layouts/azerty.rb,
lib/kotoshu/keyboard/layouts/dvorak.rb,
lib/kotoshu/keyboard/layouts/hebrew.rb,
lib/kotoshu/keyboard/layouts/jcuken.rb,
lib/kotoshu/keyboard/layouts/qwerty.rb,
lib/kotoshu/keyboard/layouts/qwertz.rb,
lib/kotoshu/language/languages/base.rb,
lib/kotoshu/language/tokenizer/base.rb,
lib/kotoshu/models/nearest_neighbor.rb,
lib/kotoshu/suggestions/sweep_index.rb,
lib/kotoshu/algorithms/edit_distance.rb,
lib/kotoshu/algorithms/ngram_suggest.rb,
lib/kotoshu/cli/interactive_reviewer.rb,
lib/kotoshu/components/spell_checker.rb,
lib/kotoshu/data/common_words_loader.rb,
lib/kotoshu/keyboard/layouts/persian.rb,
lib/kotoshu/keyboard/layouts/serbian.rb,
lib/kotoshu/language/normalizer/base.rb,
lib/kotoshu/algorithms/capitalization.rb,
lib/kotoshu/algorithms/phonet_suggest.rb,
lib/kotoshu/documents/source_position.rb,
lib/kotoshu/integrity/rotation_policy.rb,
lib/kotoshu/language/normalizer/greek.rb,
lib/kotoshu/readers/condition_checker.rb,
lib/kotoshu/suggestions/confusion_set.rb,
lib/kotoshu/keyboard/layouts/bulgarian.rb,
lib/kotoshu/keyboard/layouts/dubeolsik.rb,
lib/kotoshu/keyboard/layouts/turkish_q.rb,
lib/kotoshu/keyboard/layouts/ukrainian.rb,
lib/kotoshu/language/normalizer/arabic.rb,
lib/kotoshu/language/normalizer/hebrew.rb,
lib/kotoshu/languages/sr-Latn/language.rb,
lib/kotoshu/suggestions/suggestion_set.rb,
lib/kotoshu/analyzers/semantic_analyzer.rb,
lib/kotoshu/language/normalizer/persian.rb,
lib/kotoshu/language/normalizer/turkish.rb,
lib/kotoshu/algorithms/lookup/affix_form.rb,
lib/kotoshu/data_structures/bloom_filter.rb,
lib/kotoshu/embeddings/similarity_engine.rb,
lib/kotoshu/embeddings/similarity_search.rb,
lib/kotoshu/keyboard/layouts/chinese_ime.rb,
lib/kotoshu/suggestions/semantic_cascade.rb,
lib/kotoshu/documents/plain_text_document.rb,
lib/kotoshu/embeddings/embedding_pipeline.rb,
lib/kotoshu/embeddings/onnx_runtime_model.rb,
lib/kotoshu/spellchecker/parallel_checker.rb,
lib/kotoshu/validators/spelling_validator.rb,
lib/kotoshu/core/models/result/word_result.rb,
lib/kotoshu/documents/suppressions/scanner.rb,
lib/kotoshu/suggestions/frequency_provider.rb,
lib/kotoshu/algorithms/lookup/compound_form.rb,
lib/kotoshu/components/whitespace_tokenizer.rb,
lib/kotoshu/algorithms/lookup/compound_checks.rb,
lib/kotoshu/suggestions/strategies/word_index.rb,
lib/kotoshu/core/models/result/document_result.rb,
lib/kotoshu/documents/suppressions/suppression.rb,
lib/kotoshu/language/tokenizer/greek_tokenizer.rb,
lib/kotoshu/language/tokenizer/latin_tokenizer.rb,
lib/kotoshu/language/tokenizer/french_tokenizer.rb,
lib/kotoshu/language/tokenizer/german_tokenizer.rb,
lib/kotoshu/language/tokenizer/hangul_tokenizer.rb,
lib/kotoshu/language/tokenizer/script_tokenizer.rb,
lib/kotoshu/components/passthrough_spell_checker.rb,
lib/kotoshu/keyboard/layouts/devanagari_inscript.rb,
lib/kotoshu/language/tokenizer/russian_tokenizer.rb,
lib/kotoshu/language/tokenizer/spanish_tokenizer.rb,
lib/kotoshu/suggestions/strategies/base_strategy.rb,
lib/kotoshu/grammar/pattern_matchers/base_matcher.rb,
lib/kotoshu/language/tokenizer/cyrillic_tokenizer.rb,
lib/kotoshu/language/tokenizer/japanese_tokenizer.rb,
lib/kotoshu/suggestions/strategies/ngram_strategy.rb,
lib/kotoshu/grammar/pattern_matchers/phrase_matcher.rb,
lib/kotoshu/language/tokenizer/devanagari_tokenizer.rb,
lib/kotoshu/language/tokenizer/portuguese_tokenizer.rb,
lib/kotoshu/suggestions/strategies/phonetic_strategy.rb,
lib/kotoshu/suggestions/strategies/semantic_strategy.rb,
lib/kotoshu/suggestions/strategies/symspell_strategy.rb,
lib/kotoshu/suggestions/strategies/composite_strategy.rb,
lib/kotoshu/grammar/pattern_matchers/word_list_matcher.rb,
lib/kotoshu/grammar/pattern_matchers/vowel_sound_matcher.rb,
lib/kotoshu/suggestions/strategies/edit_distance_strategy.rb,
lib/kotoshu/suggestions/strategies/typo_retrieval_strategy.rb,
lib/kotoshu/grammar/pattern_matchers/sentence_start_matcher.rb,
lib/kotoshu/grammar/pattern_matchers/double_negative_matcher.rb,
lib/kotoshu/suggestions/strategies/keyboard_proximity_strategy.rb,
lib/kotoshu/grammar/pattern_matchers/possessive_context_matcher.rb,
lib/kotoshu/grammar/pattern_matchers/possessive_contraction_matcher.rb,
sig/kotoshu.rbs

Overview

frozen_string: true

Defined Under Namespace

Modules: Algorithms, Analyzers, Baseline, Cache, Checks, Cli, Components, Core, Data, DataStructures, Debug, Defaults, Dictionaries, Dictionary, Documents, Embeddings, Grammar, Integrity, Jekyll, Keyboard, Language, Languages, Metrics, Models, Native, Paths, Plugins, Readers, Results, Rspec, StringMetrics, Suggestions, Tasks, Typo, Validators Classes: AffixRuleError, Configuration, ConfigurationError, ConformanceExporter, ConformanceRunner, DictionaryNotFoundError, Error, InputFileNotFoundError, IntegrityError, InvalidDictionaryFormatError, MultiLanguageChecker, NativeBackend, PersonalDictionary, ProjectConfig, ResourceBundle, ResourceManager, ResourceNotCachedError, ResourceNotSetupError, ResourceResolutionError, SourceRegistry, SpellcheckError, Spellchecker, SuikaUnavailable

Constant Summary collapse

VERSION =

Returns:

  • (String) 
'1.0.8'

Class Method Summary collapse

Class Method Details

.check(text, language: nil, suggestions_filter: nil, **_options) ⇒ Models::Result::DocumentResult

Check text for spelling errors. Hot path.

Examples:

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

Parameters:

  • text (String) —

    The text to check

  • language (String, Symbol, nil) (defaults to: nil) —

    Language code; if nil, uses configured default

  • _options (Hash) —

    Accepted and ignored — kept so call sites can pass extra options without breaking

Returns:

Raises:



329
330
331
332
 
# File 'lib/kotoshu.rb', line 329

def self.check(text, language: nil, suggestions_filter: nil, **_options)
  checker = language ? spellchecker_for(language) : spellchecker
  checker.check(text, suggestions_filter: suggestions_filter)
end

.check_file(path, language: nil, **_options) ⇒ Models::Result::DocumentResult

Check a file for spelling errors. Hot path.

Examples:

Kotoshu.setup(:en)
result = Kotoshu.check_file("README.md")
result.success?  # => false

Parameters:

  • path (String) —

    The file path

  • language (String, Symbol, nil) (defaults to: nil) —

    Language code

  • _options (Hash) —

    Accepted and ignored — kept so call sites can pass extra options without breaking

Returns:

Raises:



347
348
349
350
 
# File 'lib/kotoshu.rb', line 347

def self.check_file(path, language: nil, **_options)
  checker = language ? spellchecker_for(language) : spellchecker
  checker.check_file(path)
end

.check_files(paths, **options) ⇒ Array<Models::Result::DocumentResult>

Check multiple files for spelling errors.

Examples:

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

Parameters:

  • paths (Array<String>) —

    The file paths

  • options (Hash) —

    Options

Returns:



361
362
363
 
# File 'lib/kotoshu.rb', line 361

def self.check_files(paths, **options)
  paths.map { |path| check_file(path, **options) }
end

.configuration ⇒ Configuration

Get the global configuration.

Examples:

config = Kotoshu.configuration

Returns:



107
108
109
 
# File 'lib/kotoshu.rb', line 107

def self.configuration
  Configuration.instance
end

.configuration=(config) ⇒ Configuration

Replace the global configuration. Useful for tests and for embedding kotoshu in a larger application that wants to share a Configuration across multiple Spellcheckers without each one independently touching the singleton.

The argument must be a Configuration instance (type-checked so a typo doesn't silently flip the global to nil and break every downstream lookup).

Examples:

Inject a test-only configuration

Kotoshu.configuration = Configuration.new.tap { |c| c.cache_ttl = 1 }

Parameters:

Returns:

Raises:

  • (ArgumentError) 


125
126
127
128
129
 
# File 'lib/kotoshu.rb', line 125

def self.configuration=(config)
  raise ArgumentError, "configuration must be a Configuration instance" unless config.is_a?(Configuration)

  Configuration.instance = config
end

.configure {|configuration| ... } ⇒ Configuration

Global configuration instance.

Examples:

Kotoshu.configure do |config|
  config.dictionary_path = "/usr/share/dict/words"
  config.language = "en-US"
end

Yields:

Returns:



96
97
98
99
 
# File 'lib/kotoshu.rb', line 96

def self.configure
  yield configuration if block_given?
  configuration
end

.correct?(word, language: nil) ⇒ Boolean

Check if a word is spelled correctly. Hot path — cache-only, raises if language not set up.

Examples:

Kotoshu.setup(:en)
Kotoshu.correct?("hello")            # => true
Kotoshu.correct?("Hallo", language: "de")  # requires Kotoshu.setup(:de) first

Parameters:

  • word (String) —

    The word to check

  • language (String, Symbol, nil) (defaults to: nil) —

    Language code; if nil, uses configured default

Returns:

  • (Boolean) —

    True if the word is correct

Raises:



284
285
286
287
 
# File 'lib/kotoshu.rb', line 284

def self.correct?(word, language: nil)
  checker = language ? spellchecker_for(language) : spellchecker
  checker.correct?(word)
end

.detect_language(text) ⇒ Language::Detection

Detect language of text.

Native LID when available (plan 106): the Rust extension scoring the kotoshu://models/lid/lid-176 artifact pair over 176 languages, after a one-time setup_lid. Falls back to the Kotoshu::Language::Detector heuristic when the extension is absent, KOTOSHU_BACKEND=ruby, or the model is not set up — so pure-Ruby installs keep the previous behavior.

Examples:

Kotoshu.setup_lid
Kotoshu.detect_language("Bonjour le monde").code  # => "fr"
Kotoshu.detect_language("こんにちは").score        # => 0.99

Parameters:

  • text (String) —

    Text to analyze

Returns:

  • (Language::Detection) —

    code (String, or nil when the heuristic is uncertain) and score (Float in [0, 1]); interpolation yields the code



463
464
465
 
# File 'lib/kotoshu.rb', line 463

def self.detect_language(text)
  Language::LidDetector.detect(text)
end

.detect_language_with_confidence(text) ⇒ Array<String, Float>

Detect language with confidence score.

Same engine selection as detect_language, returned as the historical [code, confidence] pair.

Examples:

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

Parameters:

  • text (String) —

    Text to analyze

Returns:

  • (Array<String, Float>) —

    Language code and confidence



479
480
481
482
 
# File 'lib/kotoshu.rb', line 479

def self.detect_language_with_confidence(text)
  detection = Language::LidDetector.detect(text)
  [detection.code, detection.score]
end

.dictionary(source = nil) ⇒ Core::IndexedDictionary

Convenience method for creating an indexed dictionary.

Parameters:

  • source (Array<String>, Hash, nil) (defaults to: nil) —

    Words or file path

Returns:



369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'lib/kotoshu.rb', line 369

def self.dictionary(source = nil)
  case source
  when Array
    Core::IndexedDictionary.new(source)
  when String
    Core::IndexedDictionary.from_file(source)
  when nil, Hash
    Core::IndexedDictionary.new
  else
    raise ArgumentError, "Invalid dictionary source: #{source.inspect}"
  end
end

.get_language(code) ⇒ Class?

Get language class by code.

Examples:

Kotoshu.get_language("en-US")

Parameters:

  • code (String) —

    Language code (e.g., "en-US", "de-DE")

Returns:

  • (Class, nil) —

    Language class or nil



517
518
519
 
# File 'lib/kotoshu.rb', line 517

def self.get_language(code)
  Language.get(code)
end

.language ⇒ Module

Access the language module.

Examples:

Kotoshu::Language.detect("Hello world")  # => "en"

Returns:

  • (Module) —

    The Language module



441
442
443
 
# File 'lib/kotoshu.rb', line 441

def self.language
  Language
end

.language_registered?(code) ⇒ Boolean

Check if a language is registered.

Examples:

Kotoshu.language_registered?("en-US")  # => true or false

Parameters:

  • code (String) —

    Language code

Returns:

  • (Boolean) —

    True if registered



528
529
530
 
# File 'lib/kotoshu.rb', line 528

def self.language_registered?(code)
  Language.registered?(code)
end

.languages_setup ⇒ Array<String>

List languages that have been set up.

Examples:

Kotoshu.languages_setup  # => ["de", "en", "fr"]

Returns:

  • (Array<String>) —

    Sorted array of language codes with cached spelling



255
256
257
 
# File 'lib/kotoshu.rb', line 255

def self.languages_setup
  ResourceManager.languages_setup
end

.misspelled?(word, language: nil) ⇒ Boolean

Check if a word is misspelled. Hot path.

Parameters:

  • word (String) —

    The word to check

  • language (String, Symbol, nil) (defaults to: nil) —

    Language code

Returns:

  • (Boolean) —

    True if the word is misspelled

Raises:



295
296
297
 
# File 'lib/kotoshu.rb', line 295

def self.misspelled?(word, language: nil)
  !correct?(word, language: language)
end

.register_dictionary_type(type, klass) ⇒ Object

Register a custom dictionary type.

Examples:

Kotoshu.register_dictionary_type(:my_custom, MyDictionary)

Parameters:

  • type (Symbol) —

    The type key

  • klass (Class) —

    The dictionary class



420
421
422
 
# File 'lib/kotoshu.rb', line 420

def self.register_dictionary_type(type, klass)
  Dictionary.register_type(type, klass)
end

.register_suggestion_algorithm(name, klass) ⇒ Object

Register a custom suggestion algorithm.

Examples:

Kotoshu.register_suggestion_algorithm(:my_custom, MyStrategy)

Parameters:

  • name (Symbol) —

    The algorithm name

  • klass (Class) —

    The algorithm class



431
432
433
 
# File 'lib/kotoshu.rb', line 431

def self.register_suggestion_algorithm(name, klass)
  Suggestions::Strategies::BaseStrategy.register_type(name, klass)
end

.reset_spellchecker ⇒ Object

Reset the spellchecker cache. The next call to spellchecker or spellchecker_for re-resolves from the current configuration.

Does NOT eagerly reload — clearing the cache is enough. This makes the method safe to call between tests even when no language is set up yet (the next call will raise ResourceNotSetupError per the strict two-stage contract).



266
267
268
269
270
 
# File 'lib/kotoshu.rb', line 266

def self.reset_spellchecker
  @spellchecker = nil
  @spellcheckers = nil
  nil
end

.resolve(language: nil, want: nil, tier: nil) ⇒ ResourceBundle

Resolve language resources from the cache (no download).

Examples:

Kotoshu.setup(:en)
bundle = Kotoshu.resolve(language: "en")
bundle.dictionary  # => #<Dictionary::Hunspell ...>

Parameters:

  • language (String, Symbol, nil) (defaults to: nil) —

    Language code; if nil, uses default

  • want (Array<Symbol>) (defaults to: nil) —

    Resource types (default: [:spelling])

  • tier (Symbol, nil) (defaults to: nil) —

    Model tier to resolve (:full default, :fluency, :mini, or :any for "the single cached tier")

Returns:

Raises:



177
178
179
180
181
182
183
 
# File 'lib/kotoshu.rb', line 177

def self.resolve(language: nil, want: nil, tier: nil)
  lang = language || configuration.default_language
  raise ResourceNotSetupError.new(lang || "default", "spelling") if lang.nil?

  want_param = want || ResourceManager::DEFAULT_WANT
  ResourceManager.resolve(language: lang, want: want_param, tier: tier)
end

.setup(*languages, want: nil, **opts) ⇒ SetupResult+

Set up resources for one or more languages (download or register local files). Idempotent: re-running with the same args is a no-op unless force: true.

Examples:

Download from kotoshu/dictionaries

Kotoshu.setup(:en)                                 # spelling only
Kotoshu.setup(:en, want: %i[spelling frequency])   # spelling + frequency
Kotoshu.setup(:en, want: %i[model], tier: :mini)   # mini-tier model
Kotoshu.setup(:en, :de, :fr)                       # multiple languages

Register local files (user already has hunspell dicts)

Kotoshu.setup(:en, aff: "/usr/share/hunspell/en_US.aff",
                    dic: "/usr/share/hunspell/en_US.dic")

Register local files from a directory

Kotoshu.setup(:en, from: "/usr/share/hunspell/")  # looks for en.aff, en.dic

Parameters:

  • languages (String, Symbol, Array<String, Symbol>) —

    One or more language codes

  • want (Array<Symbol>) (defaults to: nil) —

    Resource types to fetch (default: [:spelling])

  • opts (Hash) —

    Additional keyword options, all forwarded to ResourceManager.setup

Options Hash (**opts):

  • :force (Boolean) —

    Re-fetch even if already cached

  • :strict (Boolean) —

    Re-raise on optional-resource failure

  • :tier (Symbol, String) —

    Model tier when want includes :model (:full default, :fluency, :mini)

  • :aff (String, nil) —

    Path to local .aff file (single-language only)

  • :dic (String, nil) —

    Path to local .dic file (single-language only)

  • :from (String, nil) —

    Directory containing local .aff/.dic (single-language only)

  • :frequency (String, nil) —

    Path to local frequency.json (single-language only)

Returns:

  • (SetupResult, Array<SetupResult>) —

    Result or results (array if multiple languages)

Raises:

  • (ArgumentError) 


218
219
220
221
222
223
224
225
226
227
 
# File 'lib/kotoshu.rb', line 218

def self.setup(*languages, want: nil, **opts)
  raise ArgumentError, "Kotoshu.setup requires at least one language" if languages.empty?

  want_param = want || ResourceManager::DEFAULT_WANT
  if languages.size == 1
    ResourceManager.setup(languages.first, want: want_param, **opts)
  else
    languages.map { |lang| ResourceManager.setup(lang, want: want_param, **opts) }
  end
end

.setup?(language, resource = nil, tier: nil, **options) ⇒ Boolean

Check if a language (or a specific resource for that language) is set up.

Examples:

Kotoshu.setup(:en)
Kotoshu.setup?(:en)              # => true
Kotoshu.setup?(:en, :spelling)   # => true
Kotoshu.setup?(:en, :frequency)  # => false (not set up)
Kotoshu.setup?(:en, resource: :model, tier: :mini)  # => false

Parameters:

  • language (String, Symbol) —

    Language code

  • resource (Symbol, nil) (defaults to: nil) —

    :spelling, :frequency, :model, or nil for any

  • tier (Symbol, nil) (defaults to: nil) —

    Model tier to check (:full, :fluency, :mini, or :any for "any tier cached"); only meaningful with resource: :model

Returns:

  • (Boolean) —

    True if the resource is cached and available



243
244
245
246
247
 
# File 'lib/kotoshu.rb', line 243

def self.setup?(language, resource = nil, tier: nil, **options)
  # The resource may be given positionally (legacy) or as a keyword.
  resource = options.fetch(:resource, resource)
  ResourceManager.setup?(language, resource: resource, tier: tier)
end

.setup_lid(force: false) ⇒ Hash

Set up the language-identification model: downloads the lid.176.onnx + vocab.json pair from the models registry into the model cache (stage one of the two-stage model — detect_language never downloads implicitly). Idempotent; force re-downloads.

Examples:

Kotoshu.setup_lid
Kotoshu.setup_lid?  # => true

Parameters:

  • force (Boolean) (defaults to: false) —

    Re-fetch even if already cached

Returns:

  • (Hash) —

    { onnx_path:, vocab_path:, metadata }

Raises:

  • (Kotoshu::Error) —

    registry unreachable while offline with no cached registry (KOTOSHU_OFFLINE=1), or no registry entry

  • (Kotoshu::IntegrityError) —

    downloaded bytes fail the registry checksum



499
500
501
 
# File 'lib/kotoshu.rb', line 499

def self.setup_lid(force: false)
  Language::LidDetector.setup(config: configuration, force: force)
end

.setup_lid? ⇒ Boolean

Whether the language-identification model is cached (cache-only).

Returns:

  • (Boolean) 


506
507
508
 
# File 'lib/kotoshu.rb', line 506

def self.setup_lid?
  Language::LidDetector.setup?(config: configuration)
end

.setup_typo(language, configuration: Kotoshu.configuration, force: false) ⇒ Hash

The setup half of the two-stage model (plan 131): download the typo bi-encoder pair and the language's full tier with its vocab sibling, so Engine.for can resolve cache-only at suggest time. Raises the same errors Kotoshu::Cache::ModelCache#download_typo_biencoder and Kotoshu::Cache::ModelCache#download_tiered_model raise — setup callers report, they do not degrade.

Parameters:

  • language (String) —

    ISO 639-1 code

  • configuration (Configuration) (defaults to: Kotoshu.configuration)
  • force (Boolean) (defaults to: false) —

    re-fetch the registry first

Returns:

  • (Hash) —

    { typo: vocab_path, tier: vocab_path? }



144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/kotoshu/typo/engine.rb', line 144

def self.setup_typo(language, configuration: Kotoshu.configuration, force: false)
  cache = Cache::ModelCache.new(cache_path: configuration.cache_path)
  typo = cache.download_typo_biencoder(force: force)
  tier = cache.download_tiered_model(language, tier: :full, force_download: force)
  # Plan 136: the prebuilt matrix makes arming instant. Best-effort
  # only - a language without one arms by deriving (the fallback),
  # and the fetch must never fail the setup that already succeeded.
  matrix = begin
    cache.download_typo_matrix(language, force: force)
  rescue Kotoshu::Error, StandardError
    nil
  end
  { typo: typo, tier: tier, matrix: matrix }
end

.spellchecker ⇒ Spellchecker

Default spellchecker (singleton). Uses the configured default language. Cache-only — raises ResourceNotSetupError if the default language hasn't been set up via Kotoshu.setup.

Returns:

Raises:



137
138
139
140
141
142
143
144
 
# File 'lib/kotoshu.rb', line 137

def self.spellchecker
  return @spellchecker if @spellchecker

  lang = configuration.default_language
  raise ResourceNotSetupError.new(lang || "default", "spelling") if lang.nil? || lang.to_s.empty?

  @spellchecker = spellchecker_for(lang)
end

.spellchecker_for(language) ⇒ Spellchecker

Get a spellchecker for a specific language (cache-only, raises on miss).

Examples:

Kotoshu.setup(:de)
Kotoshu.spellchecker_for("de").correct?("Hallo")  # => true

Parameters:

  • language (String, Symbol) —

    Language code (e.g., "en", "de", "fr")

Returns:

  • (Spellchecker) —

    Spellchecker using a ResourceManager-resolved bundle

Raises:



155
156
157
158
159
160
161
162
 
# File 'lib/kotoshu.rb', line 155

def self.spellchecker_for(language)
  key = language.to_s
  @spellcheckers ||= {}
  @spellcheckers[key] ||= begin
    bundle = ResourceManager.resolve(language: language)
    Spellchecker.new(resource_bundle: bundle, config: configuration)
  end
end

.suggest(word, language: nil, **options) ⇒ Suggestions::SuggestionSet

Get spelling suggestions for a word. Hot path.

Examples:

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

Parameters:

  • word (String) —

    The misspelled word

  • language (String, Symbol, nil) (defaults to: nil) —

    Language code

  • options (Hash) —

    Options (max_suggestions, etc.)

Returns:

Raises:



311
312
313
314
 
# File 'lib/kotoshu.rb', line 311

def self.suggest(word, language: nil, **options)
  checker = language ? spellchecker_for(language) : spellchecker
  checker.suggest(word, **options)
end

.suggestion_pipeline(*strategies) ⇒ Suggestions::Strategies::CompositeStrategy

Convenience method for creating a suggestion pipeline.

Parameters:

  • strategies (Array) —

    Optional strategies to add

Returns:



407
408
409
410
411
 
# File 'lib/kotoshu.rb', line 407

def self.suggestion_pipeline(*strategies)
  pipeline = Suggestions::Strategies::CompositeStrategy.new(name: :default)
  strategies.each { |s| pipeline.add(s) }
  pipeline
end

.supported_languages ⇒ Array<String>

Get all supported language codes.

Examples:

Kotoshu.supported_languages  # => ["de-DE", "en-US", "fr-FR", ...]

Returns:

  • (Array<String>) —

    List of language codes



538
539
540
 
# File 'lib/kotoshu.rb', line 538

def self.supported_languages
  Language.supported_codes
end

.trie(source = nil) ⇒ Core::Trie::Trie

Convenience method for creating a trie.

Parameters:

  • source (Array<String>, String, nil) (defaults to: nil) —

    Words or file path

Returns:



386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/kotoshu.rb', line 386

def self.trie(source = nil)
  case source
  when Array
    Core::Trie::Builder.from_array(source)
  when String
    if File.exist?(source)
      Core::Trie::Builder.from_file(source)
    else
      Core::Trie::Builder.from_string(source)
    end
  when nil
    Core::Trie::Trie.new
  else
    raise ArgumentError, "Invalid trie source: #{source.inspect}"
  end
end