semantic_search

Semantic search using pre-computed libclang symbol embeddings. Finds symbols by meaning, not by text — matches concepts even when query words don't appear literally in the code. Uses cosine similarity over variable-dimension embeddings generated during fw-context index. Dimensions vary by model: mxbai-embed-large → 1024, qwen3-embedding → 4096.

When to prefer over search_code: When you're describing a concept rather than searching for a known keyword. Examples:

• "parcel locker state" finds door-state and shipment methods even though "parcel" and "locker" don't appear in their names.

• "cell modem" finds _socket_t and ModemMsg* classes.

• "delivery box" finds set_shipment and get_zrtdata.

• "power consumption" finds get_load_power and INA260 class.

When to prefer search_code instead: When you know the exact keyword or symbol name ("fram_write", "cbor encode"). FTS5 is faster and more precise for lexical matches.

Threshold guidance (mxbai-embed-large model):

• 0.50 — exploratory: more results, lower precision

• 0.55 — balanced (~1000 results)

• 0.60 — precise: ~175 avg, high precision (default)

• 0.65 — strict: few results, may miss relevant symbols

Source-aware ranking: the similarity of a project symbol is multiplied by 1.2, and the similarity of every other symbol by 0.85. The index marks each file as project code or not, thus the two tiers are all there are. The multiplied score sets the order. _similarity in the result holds the raw cosine similarity, thus it is on the same scale as threshold and never above 1.0.

Requires [llm] enabled = true, embeddings in the index, and for an Ollama embedding model a running Ollama server at llm.ollama_url. A sentence-transformers or ft:// model embeds the query locally and needs no Ollama. Without one of them, the tool falls back to a lexical search with a warning.

Read-only. No side effects.

Args: query: Natural language description of what you're looking for. Be specific — 5–15 words works best. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. threshold: Minimum cosine similarity (0.0-1.0). Default 0.60. The tool applies it to the raw cosine similarity, before the source boost. limit: Maximum number of results on one page (default 20, max 100). offset: Skip this many results. Reads the next page; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.

Returns: The page notice {total, offset, shown, more, hint} comes before the symbols. total counts every symbol above threshold, as far as one KNN query reaches (4096 vector rows; a symbol of several chunks takes several of them). When the KNN stopped there with its last row still above the threshold, the notice also holds total_capped: True, and total is a lower bound. A page after the last symbol gives one info dict that names the total.

Then a list of dicts, each with: name, qualified_name, kind, file, line,
is_definition, signature, docstring, plus ``_method``
(``"embedding"`` or ``"search_code_fallback"``), ranked in windows
of 200 raw ranks: inside a window by the boosted similarity, then
by the symbol id.  Thus the boost moves a symbol only inside its
window.  The reranker (when
``llm.reranker_model`` is set) reorders the first symbols of a
page, and moves no symbol to another page.  An ``"embedding"``
result also holds ``_similarity``, the raw cosine similarity.  A
symbol also holds ``summary``, ``inputs`` and ``outputs`` when
``fw-context index --analyze`` wrote them — model text, never a
fact to quote — and ``_rerank_score`` when
``llm.reranker_model`` is set.

When the index of the build of the query is not current (for
example, compile_commands.json changed after the last index run),
a leading dict holds ``warning`` and ``index_state``.  The answer
then comes from the last index run.

Fallback: when the LLM is disabled or not running, or the index
holds no embeddings, or the embedding model fails, this tool runs
a plain FTS5 symbol search (the first step of ``search_code``,
with no kind and no relaxation), one page of it.  A leading dict
holds a ``warning`` with the reason, the page notice follows, and
each symbol carries ``_method: "search_code_fallback"``.  A
changed result file or compile_commands.json adds another leading
``warning``.  When the lexical search finds nothing too, the answer
is one ``warning``.

No match above ``threshold`` runs the same lexical fallback, with a
``warning`` that suggests a lower threshold.  When a phase of the
search failed, that ``warning`` gives the error of the phase.  When
the best raw similarity of all matches is below 0.68, the answer is
the page notice and one dict: a ``warning`` that the matches are
likely unrelated, ``_fallback_suggestion: "search_code"``,
``_best_similarity``, and the matches of the page in ``_results``.

One dict with ``error`` means the query failed — check that key
first.