nora retrieval

The retrieval command group is the CLI surface for the retrieval subsystem: the layer between agent queries and your knowledge.

Commands

Command	Description
`retrieval search <query>`	Run a search query.
`retrieval diagnose <cluster-id>`	Pin first broken retrieval stage in a failure cluster.
`retrieval presets list/get/upsert/delete`	Retrieval preset CRUD.
`retrieval type-profile show`	Show active typing profile + registry + aimable type ids.
`retrieval type-profile set <id>`	Switch the workspace’s active profile.
`retrieval type-profile backfill`	Re-type existing chunks under the active profile.
`retrieval type-profile custom list/put`	Manage workspace-authored custom profiles.

`retrieval search`

nora retrieval search "how do refunds work" \
  --preset high-precision \
  --k 10 \
  --method hybrid \
  --filters '{"tag": "billing"}'

Runs the query and prints results. Flags:

<query> (positional): the text to search.
--preset <preset-id>: use a saved preset (see below).
--k <n>: top-K to return.
--method vector|keyword|hybrid|kg_rooted: retrieval mode.
--filters <json>: full FiltersBody shape (documentIds / pipelineIds / tags / kgInstanceId / kgOnly / kgScopeNodeId / excludeDocumentIds). @file / @- accepted.
--include-subgraph: include the compact triples subgraph walked from the top KG-rooted hit (requires a bound KG).
--graph-expansion: spreading activation over ontology edges (KG-in-scope required).
--routing-mode pinned|auto: pinned (default, uses --preset) vs auto (router picks presets from query intent).
--target-type <type-id>: aim the hybrid pool at these chunk types (reserved slots + boost, hybrid only). Repeatable. Valid ids come from retrieval type-profile show.
--target-entity <entity>: aim at chunks tagged with these entities. Repeatable.
--expand-window <n>: pull n neighbour chunks around each hit for parent-section context (0 = off).
--reserved-per-type <n>: min reserved top-k slots per target type.

Without --preset, uses the workspace default preset.

`retrieval diagnose`

nora retrieval diagnose cl_billing_misses

For a failure cluster (Signals → cluster), pins the first broken retrieval stage. Answers “where in the retrieval pipeline did this cluster’s failures actually happen?”: filter dropped it? Vector score too low? Reranker demoted it? Grounding rejected it? Output identifies the specific stage and shows evidence per failing trace. Best used as a targeted diagnostic before deciding which retrieval lever to tune.

Presets

Presets bundle retrieval settings (top-K, weights, filters, reranker) so multiple Agents can share one config.

List

nora retrieval presets list

Get

nora retrieval presets get high-precision

Prints the preset’s config as JSON.

Upsert

nora retrieval presets upsert high-precision \
  --name "High Precision" \
  --config '{
    "k": 6,
    "method": "hybrid",
    "vector_weight": 0.6,
    "keyword_weight": 0.4,
    "reranker": true,
    "cutoff": 0.2
  }'

Creates the preset if it doesn’t exist; replaces it if it does. Flags:

<id> (positional, required): the preset’s ID.
--name <n> (required): display name.
--config <json> (required): the full preset config. See Retrieval presets for the field reference.

Delete

nora retrieval presets delete high-precision

Fails if any Agent references the preset. Update those Agents first.

Type-aware retrieval

Chunk typing tags each chunk with a type (heading, table, policy_clause, benefit_table, …) at ingest so retrieval can aim at the right shape of content. The workspace has one active typing profile: either generic (domain-neutral default), a built-in domain profile like insurance, or a custom profile the operator defines.

`type-profile show`

nora retrieval type-profile show

Prints the active profile plus the full profile registry (built-in ∪ custom) plus the active profile’s aimable type ids, the same list the UI type-checkbox and profile selector render from. Feed the type ids into retrieval search --target-type <id>.

`type-profile set`

nora retrieval type-profile set insurance
nora retrieval type-profile set legal      # a custom profile

Switches the active profile. Built-in ids (generic, insurance) work, as do custom ids from custom put. Does not re-type existing chunks. Run backfill right after if you want the current corpus re-classified.

`type-profile backfill`

nora retrieval type-profile backfill

Re-types existing chunks under the active profile. Idempotent: already-typed rows are skipped. Prints {scanned, typed, abstained}.

`type-profile custom`

Custom profiles are for domains that don’t ship built-in (e.g. legal, medical). Built-in profiles are managed in code.

# List workspace-authored profiles (built-ins excluded)
nora retrieval type-profile custom list

# Bulk-replace the whole custom list from JSON
nora retrieval type-profile custom put --file @profiles.json
nora retrieval type-profile custom put --file '[{"id":"legal","types":[...],"rules":{...}}]'

custom put is a bulk replace: the full array is what gets stored, so anything not in the payload is removed. Each item shape:

{
  "id": "legal",
  "label": "Legal",
  "types": [{ "id": "clause", "label": "Clause" }, ...],
  "rules": { "clause": ["shall", "hereby", ...] },
  "entity_suffixes": ["Inc.", "LLC", ...]
}

Validation: id non-empty + unique + must not shadow generic / insurance.

Recipes

Iteratively tune a preset

# Snapshot current
nora retrieval presets get high-precision --json > preset.json

# Edit locally (e.g., bump vector_weight)
jq '.config.vector_weight = 0.7' preset.json > preset-tuned.json

# Re-upsert
nora retrieval presets upsert high-precision \
  --name "$(jq -r '.name' preset-tuned.json)" \
  --config "$(jq -c '.config' preset-tuned.json)"

# Test with a real query
nora retrieval search "sample question" --preset high-precision

Compare two presets side-by-side

diff <(nora retrieval search "refund" --preset old) \
     <(nora retrieval search "refund" --preset new)

Test retrieval isolation between tenants

nora retrieval search "sensitive-question" \
  --filters '{"tenant":"acme"}'
# Should NOT return chunks with tenant="other"

Combine with the app’s isolation-test view for a definitive check.

Attach a preset via `agents sources update`

Once a preset is dialed in, attach it to an Agent’s data source:

nora agents sources update ag_support \
  --kind documents_folder \
  --source-id billing \
  --set-preset high-precision

See nora agents for full source attachment options.

What the CLI does NOT do

Save retrieval results to a dataset use the app’s Trace view for that (search a trace, add the retrieval step to a dataset).
Configure grounding graphs directly grounding is enabled via preset config ({"grounding": {"graph_id": "..."}}), but graph editing is via nora causal.

Debugging queries

Add --json for the raw score breakdown per result.
Try --method vector, then --method keyword separately to see which pass is stronger.
If the right chunk exists but doesn’t rank, retrieval diagnose on a cluster containing similar queries usually explains why.

CLI

SDK

Local App

nora retrieval

Commands

`retrieval search`

`retrieval diagnose`

Presets

List

Get

Upsert

Delete

Type-aware retrieval

`type-profile show`

`type-profile set`

`type-profile backfill`

`type-profile custom`

Recipes

Iteratively tune a preset

Compare two presets side-by-side

Test retrieval isolation between tenants

Attach a preset via `agents sources update`

What the CLI does NOT do

Debugging queries

​Commands

​retrieval search

​retrieval diagnose

​Presets

​List

​Get

​Upsert

​Delete

​Type-aware retrieval

​type-profile show

​type-profile set

​type-profile backfill

​type-profile custom

​Recipes

​Iteratively tune a preset

​Compare two presets side-by-side

​Test retrieval isolation between tenants

​Attach a preset via agents sources update

​What the CLI does NOT do

​Debugging queries

Commands

`retrieval search`

`retrieval diagnose`

Presets

List

Get

Upsert

Delete

Type-aware retrieval

`type-profile show`

`type-profile set`

`type-profile backfill`

`type-profile custom`

Recipes

Iteratively tune a preset

Compare two presets side-by-side

Test retrieval isolation between tenants

Attach a preset via `agents sources update`

What the CLI does NOT do

Debugging queries