mosaic-hybrid-retrieval

name	mosaic-hybrid-retrieval
description	Retrieve, compare, and explain source-attributed product candidates through Mosaic's bounded Aurora PostgreSQL hybrid retrieval capability.

Mosaic Hybrid Retrieval

A catalog-read-only product retrieval capability on Aurora PostgreSQL. It generates candidates three ways, enforces eligibility in SQL, fuses with reciprocal rank fusion, reranks the bounded pool, and hands back a receipt that says what it did and what it granted.

This file describes the capability. It does not implement it. The machine-readable contract is db/config/agent_tool_contracts.json, served live at GET /api/tools?surface=skill, and the generated table below is projected from it, so this document cannot drift from what the service enforces.

When to use this

Use it when a caller needs product candidates it can defend: filtered, ranked, attributable, and inspectable. Use it when the caller must be able to answer "why this product" with persisted evidence rather than a model's recollection.

Do not use it as a general agent. It decides nothing about what to ask or what to say. A calling agent chooses which operation to invoke and when.

Start here

1. Call search_products with a retrieval intent and hard eligibility constraints.
2. Keep the returned search_event_id. Use it as retrieval_scope_id for the remaining operations.
3. Use get_product_evidence for source-addressable support and compare_products for a deterministic projection over granted products.
4. Use explain_retrieval to inspect the persisted retrieval event and ranking signals. Treat inspection as diagnostics, never as a wider grant.
5. Hand only granted evidence to the calling application's synthesis step.

The logical arguments below are transport-independent. For this repository's executable path, query, and JSON-body mapping, use references/http-api.md.

What it owns

• lexical candidate retrieval, PostgreSQL full-text search;
• typo-tolerant candidate retrieval, pg_trgm similarity;
• semantic candidate retrieval, pgvector HNSW;
• relational and metadata eligibility, applied inside SQL before any limit;
• a bounded candidate pool;
• unweighted reciprocal rank fusion;
• managed reranking, with exact-SKU preservation;
• retrieval provenance, per arm and per stage;
• scoped access to source-addressable evidence;
• a deterministic grant boundary.

What it does not own

synthesize_cited_answer is not part of this skill. Composing an answer, choosing what to claim, and validating citations belong to the calling application. The skill stops at authorized evidence.

There is no autonomous loop here. The caller orchestrates.

Operations

Operation	Capability	Route	Required arguments	Read-only
search_products	open_retrieval	POST /api/search	query	yes
get_product_evidence	get_product_evidence	POST /api/products/{product_id}/evidence	retrieval_scope_id, product_id, evidence_query	yes
compare_products	compare_products	POST /api/retrieval/events/{search_event_id}/compare	retrieval_scope_id, product_ids	yes
explain_retrieval	explain_retrieval	GET /api/retrieval/events/{search_event_id}	retrieval_scope_id	yes

Inputs

Named as the skill accepts them. The HTTP adapter nests the filter fields under filters; the generated adapter map is the source of truth for that transformation.

Field	Meaning
query	The retrieval intent, or an exact model or SKU string.
domain, category_key, brand	Catalog taxonomy constraints.
availability, in_stock_only	Inventory eligibility constraints.
min_price_cents, max_price_cents, min_rating	Numeric eligibility constraints.
attributes	Domain-specific attribute equality constraints.
limit	How many ranked results to return. 1 to 50.
authorized_limit	How many of those results the caller authorizes for downstream evidence and comparison. Defaults to limit. Never greater than limit.
include_diagnostics	Return per-arm counts, stage timings, and warnings.
rerank	Apply managed reranking to the fused pool.
retrieval_scope_id	The search_event_id returned by search_products. It addresses the retrieval and bounds evidence and comparison.
product_id, product_ids	One granted product for evidence, or two to five granted products for comparison.
evidence_query	The question used to rank evidence for one granted product.

Outputs

Field	Meaning
search_event_id	The retrieval-scope handle. Pass this value as retrieval_scope_id to the scoped operations.
results	Ranked products, each carrying its own rank signals per arm, its fused rank, its rerank score, and its source attribution.
diagnostics	Strategy, rerank status, candidate counts per arm, stage timings, warnings.
applied_filters	The eligibility actually enforced, as SQL received it.
normalized_query	The query text the arms actually matched on.

Scope rules

The retrieval receipt records what happened. authorized_limit records what the caller was granted. They are different, and the second one is the boundary.

• Evidence is served only for products the retrieval granted.
• Comparison is a projection over granted products. It cannot widen the set and issues no retrieval.
• Explanation is addressed by the retrieval scope handle and covers the event's full candidate pool. It does not widen the grant.
• A scope that is unknown, or that predates explicit authorization, grants nothing. There is no inference from a receipt's size.
• A refusal is a 404 with a generic body. It does not report which product fell outside the window, or whether the product exists.

And the distinction the third lab exists to teach:

Retrieving scoped evidence does not by itself authorize that evidence for synthesis. Grant scope and citation authorization are two boundaries. The calling application owns the second one.

Two rank spaces

Inspectable candidate pool          Authorized result window
up to 50 candidates                 1 to `limit`, caller declared
`pre_rerank_rank` lives here        evidence and compare allowed here

These are not the same boundary, and their ranks are not comparable. Subtracting a rank in one from a rank in the other invents movement that did not happen.

Explain can tell you that candidate 27 existed. That does not authorize you to retrieve evidence for candidate 27.

One honest limit: explanation is scope-addressed, not owner-authorized. It also returns the retrieval's session_id and raw query_text, which are not public the way a product record is. The workshop route accepts a valid event UUID without binding it to a principal because each instance is single-attendee and disposable. A shared deployment must bind event replay to its owner. See references/adapting.md for the production boundary.

Behavioral guarantees

• Eligibility is applied inside each arm's SQL, before any limit, so a filter can never be simulated by discarding rows after the fact.
• The candidate pool is bounded, and the bound is declared in the receipt.
• Fusion is unweighted reciprocal rank fusion. The weighted variant exists only as an explicit side-by-side comparison and never serves search.
• Reranking reorders the bounded pool. It cannot introduce a candidate, and it cannot displace an exact catalog-identifier match.
• No operation mutates catalog or business records.
• Every search appends a retrieval event and candidate receipts, so search is not idempotent and the runtime needs write permission, retention, and capacity for observability data.

Non-goal: scope is not identity

search_event_id is a retrieval-capability handle. It bounds which products a scoped read may touch: get_product_evidence and compare_products refuse anything outside the window the search declared.

It is not a synthesis authority. Citation authorization is a separate, turn-local decision made by synthesize_cited_answer, which is not part of this skill and never receives a search_event_id. Holding a scope handle does not authorize any product or record for a cited answer.

It is not an identity, a tenant, or a data-access boundary, and holding one is not authentication. A multi-tenant deployment would have to bind the scope to a principal as well.

Composition

This folder is the portable declaration and operating guidance, not a vendored retrieval runtime. Keep the folder intact when taking it away:

• references/http-api.md maps every logical argument to this deployment's HTTP path or body.
• references/composition.md states the exact HTTP, MCP, A2A, and optional AgentCore status without implying parity that is not implemented.
• references/adapting.md separates reusable invariants from Mosaic-specific schema, language, model, tuning, identity, retention, and evaluation choices.

The calling agent owns decomposition and synthesis. This skill owns one bounded retrieval execution; wrapping it in a second autonomous loop changes the architecture rather than composing it.