Skip to content

README.md

Latest commit

 

History

History
128 lines (84 loc) · 10.2 KB

README.md

File metadata and controls

128 lines (84 loc) · 10.2 KB
Raw

llammer Documentation

llammer is a command-line tool for grammatical and spelling correction with an optional Retrieval-Augmented Generation (RAG) search mode. This hub is the entry point to the full documentation set — architecture, theory, per-component references, configuration, worked examples, integration notes, and the roadmap. Every document describes llammer as built; anything not yet wired to a live code path is labelled Planned and collected in the roadmap.

llammer architecture layers: CLI → application → library → foundation

What is llammer?

llammer is a thin, clap-based CLI shell over two independent library stacks. Keeping them separate is the single most important thing to understand about the system:

  • Correction stack — all spelling/grammar correction is performed by the sibling crate llammer-pipeline. It builds a weighted finite-state transducer (WFST) lattice whose candidate words come from a dictionary-constrained Damerau–Levenshtein automaton (via liblevenshtein), and decodes the lattice with the Viterbi algorithm over the tropical (min-plus) semiring (via lling-llang). An optional phonetic layer reweights sound-alike candidates. No neural network runs here.
  • Retrieval stack — the rag subcommand (and the query-correction inside it) uses libgrammstein for ModernBERT sentence embeddings and a cosine-similarity RagIndex. libgrammstein is the only place a neural model executes, and it is used only by RAG.

Accuracy note. Earlier drafts of these docs claimed the WFST correction engine lived in libgrammstein and that ModernBERT rescored corrections. Neither is true in the shipped code: correction is llammer-pipeline (→ lling-llang + liblevenshtein), and libgrammstein is RAG/embedding only. The documentation you are reading now reflects the real design.

liblevenshtein (fuzzy dictionary automata) and lling-llang (WFST lattice, layer pipeline, Viterbi, semiring) are foundation crates that reach llammer transitively through llammer-pipeline. The binary uses #[tokio::main], but there is no real concurrency or networking today.

How correction works

Each input is tokenized (whitespace split, punctuation peeled into a prefix/suffix, case pattern recorded). For every token that is out of vocabulary, the pipeline adds one lattice edge per Damerau–Levenshtein candidate found within the maximum edit distance, weighting each edge by its distance; the original (uncorrected) token is added at a deliberately high weight so any genuine correction outranks keeping the typo. Viterbi then selects the minimum-total-weight path through the lattice:

$$\hat{p} \;=\; \operatorname*{arg\,min}_{p \,\in\, \mathrm{paths}(\mathcal{L})} \; \sum_{e \,\in\, p} w(e) \qquad\text{with}\qquad w(e) \;=\; d(e) \times \texttt{edit\_weight}$$

Here $\mathcal{L}$ is the lattice, an edge $e$ is one candidate for one token, $d(e)$ is that candidate's Damerau–Levenshtein distance (adjacent transpositions cost $1$, so thier → their), and edit_weight defaults to 0.3. Because weights are costs on the tropical semiring, lower is better and Viterbi finds the cheapest path. There is deliberately no probabilistic language-model term today — the lm_weight / LM-rerank machinery is scaffolding for a Planned layer, so ties between equally-close candidates are resolved without context. The correction-model theory and pipeline component docs develop this in full.

Quick start

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

$ cargo build --release

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

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

correct always uses the compact 363-word dictionary embedded in llammer-pipeline; there is no flag to substitute a larger word list on this path, so out-of-vocabulary words pass through or map to a near neighbour (see the roadmap for the Planned larger-dictionary and LM-rerank work). See Basic Correction for the single-string and file workflows, REPL Modes for the interactive session, and RAG Workflow for indexing and search.

Commands

llammer exposes exactly three subcommands (rag has three subcommands of its own). This is the complete surface — there is no config subcommand, and rag has no info/export/import.

Command Purpose Key options
correct Correct a single string or a file (one sentence per line) --format text|json|tsv, --input <FILE>, --output <FILE>, --max-edit-distance <N>
repl Interactive correction session --mode standalone|agent|customer|rag, --language <CODE>, --context-window <N>
rag init Build a RAG index from a directory of documents --documents <DIR> (required), --output <DIR> (required)
rag query Search an index, optionally spell-correcting the query first --index <DIR> (required), --top-k <N>, --correct-query
rag extend Add documents to an existing index --index <DIR>, --documents <DIR>, --output <DIR>

The full argument reference — including flags that are accepted but currently ignored (--models, --insertion-penalty, --deletion-penalty, --beam-width, repl --address, rag init --summarize) — is in the CLI component overview.

Documentation index

Architecture

  • Overview — the CLI → application → library → foundation layer stack, the crate dependency DAG, and the two-stack design.
  • Data Flow — end-to-end flow of correct (single + batch), rag init/query, and the REPL loop.

Theory

  • Correction Model — Damerau–Levenshtein distance, Levenshtein automata, the tropical semiring, and Viterbi decoding, with references.

Components

  • CLI — every subcommand, argument, default, and the consumed-versus-inert status of each flag.
  • Pipeline — Overview — the LatticeCorrectionPipeline: tokenize → expand → (phonetic) rescore → Viterbi → reconstruct.
  • Pipeline — Contextual — LatticeContextualCorrector, the library-only confidence-reweighting API (CLI wiring is Planned).
  • REPL — the BaseRepl driver, the ReplRole strategy, the three roles, and the RAG placeholder mode.
  • RAG — index construction, ModernBERT embedding, cosine query, and optional query correction.

Configuration

  • Overview — the llammer.toml schema, the load order, and which keys are live versus reserved.

Examples

  • Basic Correction — single-string and file correction, output formats, and exit behavior.
  • Batch Processing — --input/--output file workflows and scripting with RUST_LOG=off.
  • RAG Workflow — building, querying, and extending an index.
  • REPL Modes — standalone, agent, customer, and the RAG placeholder mode.

Integration

  • llammer-pipeline — how llammer consumes the correction crate and its re-exported pipeline/context/language modules.
  • libgrammstein — how the rag subcommand consumes the retrieval crate and ModernBERT embeddings.

Roadmap

  • Planned / Not Yet Implemented — the honest tier list of Implemented / Partial / Planned features, each with the code that exists and the wiring it needs.

Diagrams

  • Diagram index — every figure is authored in PlantUML (*.puml) and committed alongside its rendered *.svg; the Markdown docs embed the SVGs. There is no Mermaid in this repository.

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 — correction (WFST lattice, tokenizer, conversation context, language tags; brings in lling-llang and liblevenshtein transitively).
    • ../libgrammstein — RAG indexing and ModernBERT embeddings.

See Also

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. Schulz, K. U., & Mihov, S. (2002). Fast string correction with Levenshtein automata. International Journal on Document Analysis and Recognition, 5(1), 67–85. https://doi.org/10.1007/s10032-002-0082-8
  3. 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
  4. 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
  5. Warner, B., et al. (2024). Smarter, better, faster, longer: A modern bidirectional encoder (ModernBERT). arXiv. https://arxiv.org/abs/2412.13663
  6. Lewis, P., et al. (2020). Retrieval-augmented generation for knowledge-intensive NLP tasks. Advances in Neural Information Processing Systems (NeurIPS). https://arxiv.org/abs/2005.11401