Full-text, fuzzy and semantic search fused in SQL, reranked with Amazon Bedrock, and a Retrieval agent on Amazon Bedrock AgentCore that answers with sources.
The scenario · Labs · Architecture · How it works · Run the workshop · Use it in your project
This repository contains Mosaic, the sample product discovery application for the workshop Build agentic hybrid retrieval with Amazon Aurora PostgreSQL. In three hands-on labs you repair hybrid search in Amazon Aurora PostgreSQL, tune how its results are ranked, and then build and deploy a Retrieval agent with Strands Agents on Amazon Bedrock AgentCore that answers with sources.
The catalog holds 553,911 real products from the Amazon Reviews 2023 dataset, with saved Cohere Embed v4 embeddings. Alex, the shopper in the story, is fictional; every search and answer runs against the real catalog and its source records.
Attending the workshop? Your account, Aurora cluster, application and terminal are already prepared, so there is nothing to install. Follow your Workshop Studio guide and open START_HERE.md in Code Editor.
Alex is a software engineer setting up a home office. He has a desk and a laptop, and needs headphones, a monitor and a chair, with sources behind each recommendation. Each lab takes one part of that request and starts from a failure you can observe: a results page that looks plausible but does not include the product Alex wanted, with no error to explain why.
Each lab follows the same cycle: Broken → Diagnose → Fix → Prove. You trace the failing request, repair the marked code, apply or deploy it, and prove the fix against the same request. Your repairs carry forward from one lab to the next.
| Lab | Question to answer | Where you work |
|---|---|---|
| Lab 1: Retrieve - Debug hybrid search | Can search find Alex's Logitech Zone 900 headphones from a mistyped listing ID? | labs/lab1_retrieve/ |
| Lab 2: Rank and rerank - Tune rank fusion and reranking | Which candidates survive rank fusion, and how does reranking change their order? | labs/lab2_rank/ |
| Lab 3: Reason - Build and deploy the Retrieval agent | Can your Retrieval agent complete Alex's setup, support each choice with sources, and respond when his requirements change? | labs/lab3_reason/ |
Labs 1 and 2 are SQL exercises: you diagnose in psql, repair the marked SQL file and
apply it to Aurora. In Lab 3 you build the Retrieval agent in Python, deploy it to
AgentCore Runtime and check its answers from the terminal. Optional exercises cover
AgentCore Memory, a smaller and faster HNSW index for filtered semantic search, weighted
rank fusion and building your own retrieval tool.
| Component | Role |
|---|---|
| Amazon Aurora PostgreSQL | Stores products, vectors, source records and saved searches. Runs full-text search, fuzzy matching and semantic search, and combines their rankings, all in SQL. |
| Amazon Bedrock | Provides Cohere Embed v4 for query embeddings, Cohere Rerank 3.5 for reranking, and Claude Sonnet 5.5 for the Retrieval agent. |
| Amazon Bedrock AgentCore | Runtime hosts the Retrieval agent and its SQL tools, Gateway exposes the tools over MCP, and Memory holds optional conversation context. Product facts always come from Aurora. |
| Strands Agents | The Python framework the Retrieval agent is built with. |
| Mosaic | A FastAPI service and React interface. Shop runs the same search as the agent's SQL tools without asking the Retrieval agent, Ask Mosaic sends questions to the Retrieval agent, and Playground shows saved searches, rankings, tool calls and sources. |
- Retrieve. Under the same SQL filters, three searches each return a ranked list:
PostgreSQL full-text search (
tsvector) for terms and IDs,pg_trgmfuzzy matching for misspellings, andpgvectorsemantic search (HNSW) for meaning. - Rank. Reciprocal rank fusion (RRF) combines the lists by position, because each search scores on its own scale, and keeps a shortlist.
- Rerank. Cohere Rerank 3.5 compares each shortlisted product with the request and reorders the shortlist. It cannot recover a product that never reached it.
- Reason. The Retrieval agent chooses its searches, reads specifications and reviews, and answers with sources. A citation identifies a source but does not prove the claim, so the application checks every drafted answer: each citation must name a record the agent was given, and every figure a sentence states must appear in the cited record, in the same unit.
Everything search reads or runs lives in one schema, mosaic_search: the
product_listing table with one index per search, the product_listing_view that every
search reads, and the functions the labs repair. Run
\sf mosaic_search.search_hybrid_rrf in psql to print the SQL Aurora runs. Candidate
limits, the RRF constant and other settings are in
db/config/retrieval.yaml, and the
architecture guide covers the design in depth.
The workshop runs in AWS Workshop Studio, which provisions the Aurora cluster, the Mosaic application, Code Editor and model access for each participant.
- Open Getting started in your Workshop Studio guide.
- Open Code Editor beside the guide and follow START_HERE.md.
- Run the catalog readiness check, save Lab 1's failing search, and begin Lab 1 in
psql.
Claude Code in the prepared terminal acts as a coding coach. AGENTS.md, loaded through CLAUDE.md, gives it the lab map, validation commands and exercise boundaries, so it offers hints before answers. The workshop's managed Claude Code settings run it in manual mode, so it asks before it edits a file or runs a command.
The commands you use most:
| Purpose | Command |
|---|---|
| See where each lab stands | uv run python scripts/lab_state.py status |
| Hand off Lab 1 or Lab 2: prove it and prepare the next lab | uv run python scripts/lab_state.py advance --lab 1 |
| Deploy your Retrieval agent (Lab 3) | uv run python scripts/deploy_agentcore.py deploy |
| Ask the deployed Retrieval agent | uv run python scripts/ask_agent.py "QUESTION" |
| Grade your Lab 3 setup run | uv run python scripts/grade_setup_run.py |
| Catch up by installing a lab's reference answer | uv run python scripts/lab_state.py finish --lab N |
A successful deploy or a plausible answer is not completion: each lab ends with the guide's checks against the same request, run on the state you applied or deployed.
To run the workshop outside an AWS event, in an account you own, follow Run Mosaic in your own account.
Connect your agent to the retrieval tools, then add the skill to guide its workflow. In Mosaic, Playground → Use it in your own agent links to the MCP setup and HTTP contracts, the agent skill, and the search SQL with its adaptation guide.
- Adapt the implementation maps the schema, retrieval SQL, ranking, evaluations and citation checks to the files you change.
- The agentic hybrid retrieval skill gives your agent instructions for finding products, comparing them and checking sources. Keep its reference files together and follow the adaptation checklist.
- MCP integration connects another agent host to the catalog tools.
- Build a retrieval tool is an optional extension for applying your own filtering rule.
The skill requires a running Mosaic service or compatible backend, configured with its URL and authentication; a workshop endpoint expires with its event. The catalog tools are read-only, although each search appends an audit record. MCP tool annotations and skill instructions do not grant or restrict database access: the service validates requests and the database role enforces privileges. See the access boundary.
| Path | Contents |
|---|---|
labs/ |
One folder per lab: the file you edit, a short README and the reference answer in solution/ |
db/ |
Schema, search SQL in install order, indexes, retrieval settings and catalog contracts |
service/ |
The FastAPI service: retrieval, agent tools, evidence and citation checks |
ui/ |
The React interface: Shop, Playground and Ask Mosaic |
deploy/ |
AgentCore Runtime entry points, the container image and the host bootstrap |
mcp-server/ |
The MCP adapter for the catalog tools |
skills/mosaic-hybrid-retrieval/ |
A portable agent skill for hybrid product retrieval |
scripts/ |
Participant commands at the top level; maintainer tooling in catalog/, evals/, bench/ and checks/ |
data/ |
Lab missions, evaluation cases and saved benchmark measurements |
docs/ |
Architecture, operations and adaptation guides (documentation map) |
tests/ |
Offline tests and tests that run against Aurora |
To run or change Mosaic outside a workshop event, follow docs/development.md. There is no local database path: development and tests use an Amazon Aurora PostgreSQL cluster with the Mosaic catalog loaded, and the prepared catalog bundle is not stored in this repository. Read AGENTS.md and the house standards before you change code, and see CONTRIBUTING.md to propose a change.
Further reading:
The catalog comes from Amazon Reviews 2023 (McAuley Lab, UC San Diego). Cite it as the publisher asks: Yupeng Hou, Jiacheng Li, Zhankui He, An Yan, Xiusi Chen, and Julian McAuley. 2024. Bridging Language and Items for Retrieval and Recommendation. arXiv:2403.03952. NOTICE.md has the BibTeX entry and the ESCI and WANDS citations and terms used by the evaluations. Product names, brands and trademarks belong to their owners.
See CONTRIBUTING.md for more information. Please report a potential security issue through the AWS vulnerability reporting page, not a public GitHub issue.
This sample is licensed under the MIT-0 License. See the LICENSE file.