llammer

llammer is a command-line tool for grammatical and spelling correction. It corrects text with a weighted finite-state transducer (WFST) lattice of dictionary-constrained Damerau–Levenshtein candidates, decoded by the Viterbi algorithm over the tropical (min-plus) semiring, with an optional phonetic rescoring layer — and it can retrieve documents with Retrieval-Augmented Generation (RAG) using ModernBERT embeddings and cosine search. Correction runs entirely on the sibling llammer-pipeline crate (WFST + Levenshtein automata); retrieval runs on libgrammstein, which is the only place a neural model executes.

Status at a glance

llammer is v0.1.0, an early release. This matrix is honest about what runs today versus what is scaffolded. Statuses use one vocabulary throughout the documentation:

• ● Implemented — runs today on the primary code path.
• ◐ Partial — present and reachable, but a flag/toggle is accepted-and-ignored or wired to a stub.
• ○ Planned — code or configuration exists but is not connected to any live path; see the roadmap.

Capability	Status	Notes
correct — single string + batch (text/json/tsv)	● Implemented	Lattice + Damerau–Levenshtein + Viterbi via llammer-pipeline.
Damerau–Levenshtein candidates + Viterbi decode (tropical semiring)	● Implemented	Adjacent transpositions cost 1; lower weight = better path.
Phonetic rescoring layer	● Implemented	On by default (phonetic-rescore feature); reweights sound-alike candidates.
Case-preserving, punctuation-aware, Unicode-safe tokenizer	● Implemented	Mixed case and non-ASCII words survive correction.
repl — standalone / agent / customer modes	● Implemented	Local, single-process; auto-correct + slash commands + JSON history.
rag init / query / extend	● Implemented	ModernBERT embeddings + cosine RagIndex (via libgrammstein).
rag query --correct-query	● Implemented	Spell-corrects the query before embedding so misspelled terms still retrieve.
TOML configuration file	◐ Partial	Consumed by the rag and repl --mode rag paths; a subset of keys is live. correct does not read it. See configuration.
--neural-rescore / LM-rerank / CFG-filter layers	◐ Partial	Flags accepted; the layers are stubs that add no effect today.
Context-aware REPL correction	◐ Partial	LatticeContextualCorrector exists as a library API but is not wired into the CLI.
Agent/customer networking + wire protocol	○ Planned	No sockets; --address and protocol.rs are inert. Banners are static text.
repl --mode rag live search	○ Planned	A placeholder demo that prints "No results (index not implemented in demo)".
REPL tab-completion + syntax highlighting	○ Planned	ReplCompleter / ReplHighlighter exist but are not attached to the editor.
Selectable color schemes	○ Planned	Colors::minimal / high_contrast exist but no flag selects them.

The full breakdown — every stub, inert flag, and unwired module, with the code that exists and the wiring it needs — is in docs/roadmap.md.

Installation

llammer is a Cargo binary. Build it from a checkout, or install it onto your PATH.

$ cargo build --release        # produces target/release/llammer
$ cargo install --path .       # installs the `llammer` binary

Quick start

llammer writes an informational Loading models... line to stdout at info level by default. Prefix any command with RUST_LOG=off to silence it — this is required when piping machine-readable output into jq, cut, or a file. Every example below is verbatim.

Correct text

correct corrects a single string (or, with --input, a file of one sentence per line):

$ RUST_LOG=off llammer correct "thier problm"
  [original] thier problm
[corrected] their problem

$ RUST_LOG=off llammer correct "custmer servce"
  [original] custmer servce
[corrected] customer service

correct always uses the compact 363-word embedded dictionary shipped in llammer-pipeline; there is no flag or config key to substitute a larger word list on this path. Out-of-vocabulary words are therefore left unchanged or mapped to their nearest in-dictionary neighbour, and because ties are broken without a language model (the LM-rerank layer is a stub — see the roadmap), some picks are surprising:

$ RUST_LOG=off llammer correct "helo"
  [original] helo
[corrected] help

Machine-readable output is available with --format json or --format tsv; keep RUST_LOG=off when piping:

$ RUST_LOG=off llammer correct --format json "custmer"
{
  "changed": true,
  "corrected": "customer",
  "original": "custmer"
}

Interactive REPL

$ llammer repl
llammer - Grammatical Correction REPL
Language: en-US
Type /help for commands, /exit to quit

> thier problm
  [original] thier problm
[corrected] their problem

  thier → their (confidence: 67%)
  problm → problem (confidence: 67%)

> /exit
Goodbye!

RAG retrieval

Build an index from a directory of documents, then query it (the query can be spell-corrected first with --correct-query):

$ llammer rag init --documents ./corpus --output ./index
$ llammer rag query "machine learning" --index ./index --top-k 5
$ llammer rag extend --index ./index --documents ./more-docs --output ./index-v2

Prerequisites

• Rust — a stable toolchain; llammer targets Rust edition 2021.
• Sibling path crates — llammer depends on two crates by relative path, so they must sit alongside this repository:
  • ../llammer-pipeline — the correction stack (WFST lattice, tokenizer, conversation context, language tags; pulls in lling-llang and liblevenshtein transitively).
  • ../libgrammstein — RAG indexing and ModernBERT embeddings.

parent-directory/
├── llammer/            ← this repository
├── llammer-pipeline/   ← required sibling (correction)
└── libgrammstein/      ← required sibling (RAG / embeddings)

Documentation

The complete documentation set — architecture, theory, per-component references, configuration, worked examples, integration notes, and the roadmap — lives under docs/.

• Documentation hub
• Architecture overview
• Roadmap — Planned / Not Yet Implemented

License

Licensed under either of MIT or Apache-2.0 at your option (MIT OR Apache-2.0).

References

1. Damerau, F. J. (1964). A technique for computer detection and correction of spelling errors. Communications of the ACM, 7(3), 171–176. https://doi.org/10.1145/363958.363994
2. Viterbi, A. J. (1967). Error bounds for convolutional codes and an asymptotically optimum decoding algorithm. IEEE Transactions on Information Theory, 13(2), 260–269. https://doi.org/10.1109/TIT.1967.1054010
3. Mohri, M., Pereira, F., & Riley, M. (2002). Weighted finite-state transducers in speech recognition. Computer Speech & Language, 16(1), 69–88. https://doi.org/10.1006/csla.2001.0184
4. Warner, B., et al. (2024). Smarter, better, faster, longer: A modern bidirectional encoder (ModernBERT). arXiv. https://arxiv.org/abs/2412.13663