• 

  Cover

• 

  Intent Override

• 

  Demo

• 

  System process

• 

  Performance

Evidence-Aware Conversational Shopping Copilot

Ask better. Rank earlier. Adapt when intent changes.

Repository: github.com/vepharix/techjam-conversational-search

A deterministic, offline shopping agent that turns incomplete or changing requests into clear state, focused questions, and evidence-backed Top-10 recommendations from a 50,000-product catalog.

The problem

Track 4 is a sequential recommendation problem over a frozen 50,000-product catalog. On every turn, the agent must either ask one useful clarification or return a ranked product slate. Evaluation rewards the exact target parent_asin entering the Top 10 early and appearing as high as possible, so the system must optimize candidate recall, ranking quality, and turn efficiency together.

The difficult part is that relevance depends on a preference state that changes during the conversation. Buying sessions contain relatively precise constraints; browsing sessions begin with weak signals; intent overrides invalidate earlier preferences; and boundary cases should not trigger unsupported assumptions. A recommender that simply concatenates conversation history or applies every preference as a hard filter will preserve stale constraints, remove useful candidates, and waste turns on low-value questions.

Our solution

We built a deterministic, multi-stage conversational recommender in which state tracking, candidate generation, ranking, and dialogue policy are separate components. This makes ranking behaviour reproducible and allows the system to recover cleanly when the user's intent changes.

1. Mutable preference state. Each turn is parsed into ordered SET, EXCLUDE, REMOVE, ALLOW, or DONTCARE operations. The query is rebuilt from the current state instead of accumulated chat history, while exclusions remain hard constraints and budget is treated as a soft ranking signal.
2. High-recall candidate generation. SQLite FTS5/BM25 retrieves lexical matches, while a category-anchor pool keeps globally relevant products in consideration. After an intent override, bounded query variants are fused with reciprocal-rank fusion to recover candidates suppressed by the previous intent.
3. Evidence-aware ranking. EvidenceRanker scores candidates using exact constraint matches, category support, agreement across retrieval routes, negative constraints, lexical tie-breaking, and soft budget evidence. This converts retrieval pools into a single ranked slate aligned with the active preference state.
4. Adaptive ask-or-recommend policy. Clarifying questions are scored by candidate coverage, entropy, expected candidate reduction, and attribute priors. A slate gate starts with compact recommendations and expands as evidence accumulates, while bounded unseen-candidate rotation prevents repeated exposure to a stagnant candidate set.

Why it stands out

• Clean intent changes. New constraints replace obsolete hard state instead of competing with the past.
• Evidence before confidence. Recommendations are justified by what the catalog actually supports, not by conversational fluency.
• Useful questions, not extra turns. Question scoring combines candidate coverage, entropy, expected reduction, and attribute priors; optional diagnostics expose every decision.

Verified public-set results

We reran the official evaluator on the main branch across all 200 public development sessions. These results are development evidence, not a guarantee of private-set performance.

Verification: 77 automated tests passed with zero failures.

Development tools, APIs, and libraries

Development tools: VS Code, Git/GitHub, the Python command line, unittest, and the official Track 4 evaluator.

APIs: The project implements the official local Python Agent interface through reset() and respond(). It requires no external API, hosted model, vector database, API key, or inference-time network call.

Libraries and frameworks: Python 3.10+ standard-library modules and SQLite FTS5/BM25. The selected main configuration requires no third-party machine-learning framework.

Datasets and assets

The system uses the frozen 50,000-product Clothing, Shoes and Jewelry catalog, 200 public labelled development sessions, and the official evaluator/API contract. The catalog is derived from Amazon Reviews 2023 from McAuley Lab at UC San Diego and joined by parent_asin.

We use text and structured metadata only—no images, private labels, private holdout data, credentials, or undisclosed assets.

Limitations and next steps

The lexical, rule-based design remains vulnerable to unseen paraphrases, misspellings, multilingual requests, and highly implicit intent; it also lacks images, reviews, and live inventory or price signals. Next steps are a semantic parser with deterministic fallback, multilingual stress tests, richer evidence, and user studies of clarification value.

Built With

• bm25
• ftss
• github
• python
• sqlite
• vscode