cadrumo.application.command_search.index module¶

Lexical command index: per-column BM25 over the command corpus.

Ranks a free-text query against the command corpus so the search meta-tool bridges the operator’s natural vocabulary to a command’s own tokens:

a per-column FTS5 lexical index that weights the command KEY and TOOL NAME above curated OUTCOME ALIASES above the human DESCRIPTION above the per-verb HELP, so a homonym token in a low-value column no longer outranks the correct command whose key carries it (the import mis-rank the review found);
Spanish stemming and diacritics folding on every column, so a morphological or accent variant still recalls its command.

When SQLite FTS5 is unavailable CommandIndex.search() degrades cleanly to a pure-Python token-overlap scorer, so a minimal install always ranks better than a bare substring match and never hard-fails. The index loads no model and reaches no network on any install.

The index is SDK-independent and pure (it takes plain command documents), so it is unit-tested directly without any consuming transport.

class CommandDoc(**data)[source]¶

Bases: BaseModel

One command’s searchable document, split into weighted columns.

The four tiers rank a query hit by WHERE it lands: key_and_name (the command key tokens and tool name) is the most discriminative, aliases carries curated outcome vocabulary for composite verbs, description is the human summary, and help is the per-verb CLI help — the noisiest tier. Each tier becomes its own BM25-weighted FTS5 column; a query token hitting the key ranks above the same token hitting the help.

Parameters:

command_key (str)
tool_name (str)
key_and_name (str)
description (str)
aliases (str)
help (str)

command_key: str¶

tool_name: str¶

key_and_name: str¶

description: str¶

aliases: str¶

help: str¶

property combined_text: str¶: The union of every tier, for the degraded token-overlap fallback.

class CommandHit(**data)[source]¶

Bases: BaseModel

One ranked command match.

Parameters:

command_key (str)
tool_name (str)
rank (Annotated[int, Ge(ge=0)])
score (float)

command_key: str¶

tool_name: str¶

rank: NonNegativeInt¶

score: float¶

class CommandIndex(docs)[source]¶

Bases: object

A lexical searchable index over the command corpus.

Ranks by per-column FTS5 BM25, degrading cleanly to a pure-Python token-overlap scorer when FTS5 is absent, so a minimal install keeps a working search. search() returns ranked CommandHit records for a free-text query.

Parameters:: docs (Sequence[CommandDoc])

search(query, *, limit=20)[source]¶

Return up to limit ranked command hits for query.

A blank query or one with no searchable terms returns no hits. The matching commands are ranked by per-column BM25, or by token overlap when FTS5 is absent. score is the reciprocal of the one-based rank, so it is positive and strictly decreasing across the page on either path (the two paths’ own scales are not comparable, so neither is surfaced raw).

Return type:

tuple[CommandHit, ...]

Parameters:

query (str)
limit (int)

build_command_index(docs)[source]¶

Build a CommandIndex from the command documents.

Return type:: CommandIndex
Parameters:: docs (Iterable[CommandDoc])