svsrekha/intentcart

IntentCart — Explainable Multi-Agent Shopping Concierge

IntentCart turns a natural-language shopping request into a safe, catalog-grounded comparison. Eight Google ADK agents extract intent, enforce a budget, retrieve products only through an MCP catalog server, review the returned candidates, and explain final recommendations in a streaming web interface.

Phase 6 upgrades the catalog layer to deterministic SQLite: 60 categories, 36 products per category, and 2,160 total seeded products with product images, features, seller trust, reviews, shipping, and pickup fields.

Capstone Category

IntentCart is best submitted as an Agentic Application / Multi-Agent Tool-Using App. The demo shows a user-facing agent team coordinating intent resolution, budget handling, MCP catalog search, comparison, trust, shipping, and final recommendations. Secondary judging angles are MCP/tool use, safety, explainability, deterministic evaluation, and deployable packaging.

Competition reference: AI Agents: Intensive Vibe Coding Capstone Project.

Live demo: https://svsrekha-intentcart.hf.space/.

Problem

Product search becomes tedious when a shopper has several constraints at once. They must translate a goal into keywords, compare specifications, inspect seller trust and shipping, and keep every option inside a useful price range. Ordinary keyword search also tends to return plausible-looking items even when the requested category is unavailable.

Solution and Value

IntentCart coordinates specialized agents instead of asking one model to perform the entire task. The live LLM is used where language understanding matters: resolving the shopper's intent into category, keywords, and budget. After that, deterministic boundaries surround the model:

• —the catalog is the only source of product inventory;
• —category resolution rejects unsupported requests instead of substituting unrelated products;
• —minimum and maximum budgets are represented explicitly;
• —product review and card selection use local SQLite-backed candidate data;
• —every recommendation must reference a returned catalog candidate;
• —agent explanations and terminal errors use strict schemas before reaching the browser.

The result is a small but complete example of an explainable, security-conscious agentic application rather than a chatbot that invents inventory.

Course Concepts Demonstrated

Architecture

flowchart LR
    U["Shopper"] --> F["Web UI"]
    F -->|"POST /api/shop<br/>NDJSON stream"| G["FastAPI Gateway"]
    G --> C["ADK Coordinator"]
    C --> I["Intent Agent<br/>(LLM-backed)"]
    C --> B["Budget Agent"]
    C --> D["Discovery Agent"]
    D -->|"MCP tools only"| M["FastMCP Catalog Server"]
    M --> S[("SQLite catalog")]
    C --> P["Parallel Product Review<br/>(local candidate data)"]
    P --> CO["Comparison Agent"]
    P --> T["Trust & Review Agent"]
    P --> SH["Shipping Agent"]
    C --> R["Recommendation Agent<br/>(deterministic ranking)"]
    R --> G

Pipeline sequence:

1. 1.The Intent Agent uses the configured ADK/Gemini model to extract category, keywords, and explicit budget values into validated schemas.
2. 2.Unsupported categories stop safely and list supported categories.
3. 3.If a budget is missing, the run pauses and resumes after the user chooses one.
4. 4.Discovery queries the catalog through MCP; agents never read inventory directly.
5. 5.Comparison, trust/review, and shipping agents review the validated SQLite-backed candidates locally.
6. 6.The recommendation agent assigns distinct roles using deterministic price, rating, seller-trust, and range-aware ranking.
7. 7.The gateway streams progress and a single typed terminal result to the UI.

For a bounded range, the UI clearly distinguishes an option inside the range from lower-price alternatives and upgrades above the range. It never silently presents an out-of-range product as an exact budget match.

Catalog

Phase 6 uses a deterministic SQLite catalog generated from mcp_server/catalog_seed.py.

• —60 categories
• —36 products per category
• —2,160 total products
• —Reproducible product images as SVG data URLs
• —Packaged database checked in at mcp_server/catalog.sqlite
• —No catalog JSON file is required at runtime

The repository includes the SQLite database so a zipped source folder, clone, or Docker build has the catalog available. Rebuild it only when changing the deterministic seed:

python scripts/build_catalog_db.py

Test against a temporary database:

python scripts/build_catalog_db.py /tmp/intentcart.sqlite
INTENTCART_CATALOG_DB=/tmp/intentcart.sqlite uvicorn gateway.server:app --port 8123

Local Setup

Prerequisites:

• —Python 3.11 or newer
• —Node.js for the standalone frontend tests
• —Docker Desktop only if using the container workflow

Create an environment and install the development dependencies:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Copy .env.example to .env and set the required values privately on your machine. Never commit .env, paste a credential into source code, or bake it into an image.

Start the application:

.venv/bin/uvicorn gateway.server:app --host 127.0.0.1 --port 8080

Open http://127.0.0.1:8080.

Docker

Build the image:

docker build -t intentcart .

Start it with runtime configuration supplied from a local, uncommitted environment file:

docker run --rm -p 8080:8080 --env-file .env intentcart

Then open http://127.0.0.1:8080. The health endpoint is available at http://127.0.0.1:8080/health.

The Dockerfile copies no .env file, runs as a non-root user, builds mcp_server/catalog.sqlite during image creation, and performs its health check without requiring curl. The SQLite catalog is inside the container filesystem at /app/mcp_server/catalog.sqlite, so the image can run without downloading catalog data.

GitHub Pages Preview

GitHub Pages can host the static frontend, but it cannot run the FastAPI and SQLite backend. Use one of these patterns:

• —Static preview only: open the Pages URL to inspect the UI.
• —Live Pages test: deploy the backend separately, then open https://surekha909.github.io/intentcart/?api=https://your-backend-host.
• —Full local demo: use Docker or Uvicorn locally.

The backend allows GitHub Pages origins through CORS for live frontend testing.

Verification

Automated tests use deterministic model and MCP doubles; they do not call Gemini.

python -m pytest
node frontend/catalogLogic.test.js
node frontend/gatewayLogic.test.js
node frontend/streamParser.test.js
node frontend/adaptiveLayout.test.js
node frontend/a11yExplainability.test.js
git diff --check

The latest Phase 6 verification produced 181 passing Python tests and five passing frontend suites. See the Phase 6 evaluation checklist and the demo procedure.

The current Hugging Face Space deployment was smoke-tested at roughly 4 seconds end-to-end for noise canceling headphones under 150 after product review and recommendation selection were moved to local catalog-grounded logic.

Security Notes

• —Credentials are read at runtime and are excluded from Git and Docker build context.
• —Dynamic text is escaped before HTML rendering.
• —Public gateway errors do not expose stack traces or secret-bearing model output.
• —Recommendation IDs must belong to the MCP candidate set.
• —Explanation evidence is schema-validated and rejects secret-like content.
• —Unsupported categories and empty results are neutral typed outcomes, not fabricated recommendations.

Known Limitations

• —Product data is deterministic seed data rather than live merchant inventory.
• —GitHub Pages requires a separate live backend for real searches.
• —Live intent resolution requires valid private runtime model configuration; catalog review and recommendation selection are local deterministic steps.
• —Known upstream Google ADK, Starlette/FastAPI, and OpenTelemetry deprecation warnings are non-blocking but should be addressed during future dependency upgrades.

Project Documentation

• —Learning journal and phase status
• —Phase 5 evaluation ledger
• —Phase 6 evaluation checklist
• —Five-minute demo procedure
• —Architecture notes
• —Build roadmap
• —Historical implementation plans