Skip to content

overview.md

Latest commit

 

History

History
351 lines (273 loc) · 14.8 KB

overview.md

File metadata and controls

351 lines (273 loc) · 14.8 KB
Raw

CLI Reference

llammer is a single binary (llammer, version 0.1.0) exposing three subcommands: correct (offline spelling correction), repl (an interactive correction session), and rag (retrieval over an embedded document index). Correction runs entirely locally through the llammer-pipeline crate; the only neural model in the project — a ModernBERT embedder from libgrammstein — runs solely inside rag. This page documents the command surface exactly as built.

Terms used below: REPL = read–eval–print loop; RAG = retrieval-augmented generation (here, embedding-based document retrieval); OOV = out-of-vocabulary (a word absent from the correction dictionary); TSV = tab-separated values.

1. Synopsis

llammer [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]
Command Purpose
correct Correct spelling in a string or a file of sentences.
repl Start an interactive correction REPL (standalone, agent, customer, or rag mode).
rag Build, query, and extend a document retrieval index (init, query, extend).

2. Global options

Global options are accepted before the subcommand. There is no global --language, --models, or --quiet option — language and model directories are per-subcommand flags, and verbosity is controlled through the RUST_LOG environment variable (see §7).

Option Env Default Status
-c, --config <PATH> LLAMMER_CONFIG — Parsed but inert. correct never reads a config file; the RAG and REPL paths load configuration from fixed locations (./llammer.toml, then $XDG_CONFIG_HOME/llammer/config.toml), not from this flag.
-v, --verbose (repeatable: -v, -vv, -vvv) — 0 Parsed but inert. Logging verbosity is driven only by RUST_LOG; this counter is never consulted.
-h, --help — — Print help and exit (provided by clap).
-V, --version — — Print the version and exit (provided by clap).

Logging is written to stdout. llammer initializes tracing with the filter from RUST_LOG, defaulting to llammer=info,libgrammstein=warn,lling_llang=warn when RUST_LOG is unset. Because the formatter writes to stdout, an informational … INFO llammer::cli::commands::…: Loading models... line precedes correction output on stdout — 2>/dev/null will not remove it. Prefix a command with RUST_LOG=off to silence logs when capturing or piping machine-readable output. Every example below that shows exact output uses RUST_LOG=off for that reason.

3. correct

Correct spelling in an inline string or, with --input, in a file processed one line at a time.

llammer correct [OPTIONS] [TEXT]
Flag Default Status / effect
[TEXT] (positional) — The string to correct (single-string mode).
-i, --input <FILE> — Batch mode: read the file and correct one line per row.
-o, --output <FILE> — Write results to a file instead of stdout (batch mode).
-m, --models <DIR> (env LLAMMER_MODELS) — Accepted but ignored — correct loads no external models.
-l, --language <CODE> en-US Copied to config.language but does not change the output: the decoder is language-neutral and correct always uses the embedded English dictionary.
--max-edit-distance <N> 2 Damerau–Levenshtein search radius for candidate words.
--insertion-penalty <F> 3.0 Accepted but ignored — the lattice scores with a single edit_weight, not separate insertion/deletion penalties.
--deletion-penalty <F> 3.0 Accepted but ignored — as above.
--neural-rescore false Maps to the pipeline's enable_lm_rerank, a no-op stub layer: no neural (or LM) rescoring occurs.
--beam-width <N> 100 Stored on the config but not used — correct decodes with exact Viterbi, not beam search.
--format <FMT> text Output format: text, json, or tsv.

correct always uses the embedded 363-word dictionary. It builds its pipeline config from CLI flags with no dictionary path and never reads the config file, and there is no CLI flag to supply a custom dictionary. Consequently many everyday words are OOV (e.g. quick, brown, fox, package, machine), and because tie-breaking has no language model (the LM-rerank layer is a stub), some picks are surprising — for example helo corrects to help, not hello. This is honest as-built behavior; see the pipeline reference and the roadmap for the Planned larger-dictionary and LM-rerank work.

Single-string behavior

With text format, a changed string prints two lines — a dim [original] line and a bold-green [corrected] line; an unchanged string prints just the text:

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

json format prints a pretty-printed object with exactly three keys (alphabetically ordered: changed, corrected, original) — there is no confidence field or corrections array:

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

tsv format prints original<TAB>corrected on one line:

$ RUST_LOG=off llammer correct --format tsv "problm"
problm	problem

Piping to jq/cut works cleanly once logs are silenced:

$ RUST_LOG=off llammer correct --format json "documnet" | jq -r .corrected
document

Batch behavior (--input)

--input FILE corrects each line, driving an indicatif progress bar on stderr. With --output FILE, results are written per line: text writes the corrected sentence only, json writes one compact object {"corrected", "original"} per line (note: no changed key in batch mode), and tsv writes original<TAB>corrected. Without --output, results print to stdout in the same colored per-line form as single-string mode.

Given sentences.txt:

thier problm
custmer servce
wrok on the projcet

$ RUST_LOG=off llammer correct --input sentences.txt --output corrected.txt --format json

produces corrected.txt:

{"corrected":"their problem","original":"thier problm"}
{"corrected":"customer service","original":"custmer servce"}
{"corrected":"work on the project","original":"wrok on the projcet"}

The same run with --format tsv yields:

thier problm	their problem
custmer servce	customer service
wrok on the projcet	work on the project

A verified limitation

The embedded dictionary is small and there is no language model, so correct sometimes picks a near neighbour that is not the intended word. This is expected today:

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

See the roadmap for the Planned dictionary and LM-rerank improvements.

4. repl

Start an interactive session. Non-slash input is auto-corrected and echoed; slash commands control the session. Full per-mode behavior is documented in the REPL component reference.

llammer repl [OPTIONS]
Option Default Status / effect
-m, --mode <MODE> standalone One of standalone, agent, customer, rag.
--models <DIR> (env LLAMMER_MODELS) — Accepted but ignored for model loading.
-l, --language <CODE> en-US Session language.
--address <ADDR> — Stored but never read — the REPL performs no networking.
--index <DIR> — RAG index directory, used only by --mode rag (a placeholder demo).
--history <FILE> — Path used by the /save and /load commands.
--context-window <N> 10 Conversation window in turns (the conversation keeps 2 × N turns).
Mode Description
standalone Single-user correction REPL (default).
agent A local role with agent-styled prompt/banners. Not a server — no networking.
customer A local role with customer-styled prompt/banners. Not a client — no networking.
rag A placeholder demo query loop that reports "No results (index not implemented in demo)".

Agent and customer modes are local, single-process REPLs. They differ only in prompt text, labels, and static "connected/disconnected" banner strings; there are no sockets anywhere in the binary, and --address is never read. A newline-delimited-JSON chat protocol exists in the source but is unused — it is Planned, tracked in the roadmap.

The interactive commands (recognized in every non-RAG mode) are:

Command Effect
/help, /h, /? Show help.
/exit, /quit, /q Exit the REPL.
/clear, /cls Clear the screen (not the conversation).
/history Show the conversation history.
/clearhistory Clear the conversation history.
/autocorrect, /ac Toggle auto-correction (no on/off argument).
/lang <code> Set the session language.
/save <path> Save the conversation as JSON.
/load <path> Load a conversation from JSON.

Anything not beginning with / is treated as input and auto-corrected. When a line changes, the REPL prints the same dim [original] / bold-green [corrected] pair as the correct command, followed by one original → corrected (confidence: N%) line per changed word:

$ llammer repl
> custmer servce
  [original] custmer servce
[corrected] customer service

5. rag

Manage a document retrieval index. Retrieval uses libgrammstein's RagIndex and, for querying, a ModernBERT embedder.

llammer rag <init|query|extend> [OPTIONS]

rag init

Build a new index from a directory of documents.

llammer rag init [OPTIONS]
Option Required Default Status / effect
--documents <DIR> Yes — Directory of documents to index.
-o, --output <DIR> Yes — Output index directory.
-l, --language <CODE> No en-US Accepted but ignored.
-m, --models <DIR> (env LLAMMER_MODELS) No — Accepted but ignored.
--summarize No false Accepted but ignored — synopses are not generated. 
$ llammer rag init --documents ./corpus --output ./index

rag query

Search an existing index. Optionally spell-correct the query first (the only real correction/retrieval integration): a misspelled term is corrected before being embedded so it can still match.

llammer rag query [OPTIONS] <QUERY>
Option Required Default Status / effect
[QUERY] (positional) Yes — The query text.
-i, --index <DIR> Yes — Index directory to search.
-k, --top-k <N> No 10 Number of results to return.
-l, --language <CODE> No en-US Language used when --correct-query is set.
-m, --models <DIR> (env LLAMMER_MODELS) No — Accepted but ignored (the embedder uses its defaults).
--correct-query No false Spell-correct the query before embedding. 
$ RUST_LOG=off llammer rag query "custmer servce" --index ./index --correct-query --top-k 5

There is no --min-score, --topic, or --format option on rag query. The result layout is documented in the RAG component reference.

rag extend

Add documents to an existing index and save the result.

llammer rag extend [OPTIONS]
Option Required Status / effect
--index <DIR> Yes Existing index directory to load.
--documents <DIR> Yes Directory of new documents to add.
-o, --output <DIR> Yes Output index directory (required — there is no in-place mode).
-m, --models <DIR> (env LLAMMER_MODELS) No Accepted but ignored. 
$ llammer rag extend --index ./index --documents ./new-docs --output ./index-v2

6. Output formats

The --format values on correct produce the following shapes. Corrected values shown are from the embedded dictionary.

Format Single string (TEXT) Batch to --output file
text Changed: two lines ( [original] … dim, [corrected] … bold green). Unchanged: the input verbatim. The corrected sentence only, one per line.
json Pretty object { "changed", "corrected", "original" } (keys alphabetical). One compact object {"corrected","original"} per line (no changed).
tsv original<TAB>corrected. original<TAB>corrected per line.

There is no confidence score or per-word corrections array in any correct output format; those richer fields exist on the library's CorrectionResult (see the pipeline reference) but the CLI does not serialize them.

7. Exit behavior and environment

main returns an anyhow::Result, so the process exits 0 on success and with a non-zero status (1) on any error, printing the error (with its context chain) to stderr. There is no finer-grained exit-code scheme. The most common user-facing error is providing no input:

$ llammer correct
Error: No input provided. Use TEXT argument or --input flag.

Environment variables

Variable Effect
RUST_LOG Sets the tracing filter. Unset defaults to llammer=info,libgrammstein=warn,lling_llang=warn; logs are written to stdout. Use RUST_LOG=off for clean machine-readable output.
LLAMMER_CONFIG Populates the global --config flag. Inert — configuration is loaded from fixed paths regardless.
LLAMMER_MODELS Populates each subcommand's --models flag. Accepted but ignored — no external models are loaded for correction, and RAG embedders use their defaults.

There is no LLAMMER_LOG variable; logging is controlled by RUST_LOG only.

See Also