Skip to content
ClickHouse Loom
Esc
↑↓navigate↵open⌘Jpreview
On this page

Answer questions about a repository

Use code.search to retrieve source and documentation, and code.ask to produce a cited answer from that evidence. Both can serve a reader who has no local checkout. The repository must be indexed in the code namespace passed to the request.

Calibrate the embedding model

After indexing, run code.calibrate as an administrator for the indexed namespace. Repeat calibration after changing the embedding model and rebuilding its vectors:

curl --fail-with-body -X POST "$LOOM_BASE_URL/v1/code.calibrate" \
  -H "Authorization: Bearer $LOOM_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"org":"example","namespace":"code-example"}'

Similarity scales differ between embedding models. A threshold that admits useful evidence for one model can admit unrelated evidence for another. Check representative questions and questions the repository cannot answer; do not copy a threshold from another deployment. code.search reports calibration_explanation and its abstention reason. See index operations for indexing and calibration, and debugging for retrieval diagnostics.

Configure mixed source and documentation retrieval

The defaults apply a 0.25 multiplier to prose, use the flat chunk-kind prior, and allow synthesis to write up to 900 tokens. The output cap limits cost and answer length. A response that reaches the cap discloses incomplete synthesis.

For a mixed source and documentation workload, compare the defaults with this explicit settings file configuration:

version: 1
settings:
  code_search_prose_penalty: 1.0
  code_search_kind_prior: structural
  llm_max_tokens_overrides: '{"code_answer_synth":4000}'

code_search_kind_prior accepts structural, flat, default, or off. The structural option boosts the kind named by a question, such as a class, without a fixed preference for functions over documentation. flat and default apply fixed kind weights. A kind_prior request overrides the deployment setting through HTTP or an SDK; it remains hidden from the compact MCP tool schema. A model using MCP therefore receives the deployment setting without a source patch.

For a source-only workload, a code_search_prose_penalty below 1.0 can demote prose. Measure that choice against both source and documentation questions. Set LOOM_CODE_ASK_LLM_MODEL to choose a synthesis model supported by the configured provider. The default follows the deployment model; these retrieval settings do not select a paid provider. All settings are listed in the configuration reference.

Check answer completeness and provider availability

code.ask exposes separate signals:

Field Meaning
citations Indexed source ranges supplied as evidence for the answer.
retrieval_confidence Confidence in retrieval, not a grade of the answer.
coverage The synthesizer’s full, partial, or none self-assessment; empty when not assessed, including cached answers. This is not verified correctness.
partial A retrieval or provider limit prevented a complete response.
partial_reason, note The missing retrieval leg, deadline, or synthesis limitation.
abstain, abstain_reason No grounded answer is returned and why.

A failed embedding provider can leave lexical evidence available. Search and answers disclose that limitation rather than presenting lexical-only results as healthy hybrid retrieval. A deliberate lexical-only search is not a provider failure. Provider failures also appear in health diagnostics; successful provider requests clear the failure state.

Synthesis keeps the provider-bounded response without a second character cut. An output-token limit sets partial; filtering or a provider refusal abstains. Failed synthesis returns synthesis_unavailable with the available citations. Answers from failed retrieval legs or interrupted synthesis are not stored in the answer cache, including as negative answers. Fix provider credentials or limits and make a fresh request; no cache purge is needed for those failed responses.

Finding the expected file is a retrieval result. Producing a complete, correct answer is a separate result. Keep both measures when evaluating a repository assistant.

Using retrieval inside a coding agent

For a coding agent, also inspect whether the model requested tools and received useful results. A connected MCP server does not establish tool adoption. Hook-supplied evidence and model-selected lookups are separate paths; report them separately.

See tool-call troubleshooting for discovery, permissions, repository scope, hooks and copyable code and memory policies. Application code can call Loom at defined stages when recall or validation must happen; model instructions guide discretionary investigation.

For issue-resolution comparisons, give both arms the same public issue, historical base, tools for local work, test access and execution budgets. Keep reference fixes and hidden tests outside the agent’s checkout. Count test-gate overhead, backend model usage and failed or unused tools. Zero tool use is a tool-adoption result and must remain in the report. See benchmark methodology.

Was this page helpful?