Threadline
Overview
Threadline is a local AI shopping copilot built for TikTok TechJam 2026 Track 4. It searches the supplied catalogue of 50,000 products, returns grounded recommendations across multiple conversation turns, asks useful follow-up questions, and adapts when a shopper changes or removes an earlier preference.
The project focuses on a common weakness in conversational shopping systems: outdated preferences can remain in the conversation history and continue influencing later recommendations. For example, a shopper might initially request blue running shoes before changing the colour to black. A system that treats the conversation as one continuously growing prompt may continue giving weight to both colours.
Threadline addresses this problem using a versioned intent ledger. Each preference is stored as active, replaced, or removed. After every message, the search query is rebuilt from active entries only, preventing stale preferences from affecting the next retrieval step.
How Threadline addresses the problem
Threadline supports both Buying and Browsing behaviour.
Specific requests are routed through the Buying path, while exploratory requests use the Browsing path. The same intent ledger is maintained across both paths, allowing the system to accumulate useful information while responding correctly to changes in shopper intent.
The retrieval and decision pipeline contains several stages:
Field-weighted lexical retrieval: SQLite FTS5 with BM25 searches the complete catalogue for strong exact evidence, including product types, colours, brands, materials, and other explicit constraints.
Local semantic reranking: The first 16 candidates are reranked using
nomic-embed-textthrough Ollama. This adds meaning-based similarity without running model inference across all 50,000 products on every turn.Structured constraint ranking: A final ranking pass promotes products that clearly satisfy multiple active requirements. This stage can only reorder grounded candidates and cannot introduce fictional products.
Candidate-aware questioning: The question planner evaluates unanswered attributes by estimating how much they could narrow the current candidate set and improve the Top-10 results.
Correction-aware state management: The intent ledger replaces or removes outdated preferences when the shopper changes direction. The next query is then compiled from the corrected state.
Every recommendation returned by Threadline corresponds to a real parent ASIN from the supplied read-only catalogue.
Verified public results
The verified system achieved the following results on the official 200-session public development set:
| Metric | Result |
|---|---|
| TechnicalScore | 0.809642 |
| Hit Rate@10 | 0.940 |
| MRR | 0.609472 |
| MTTC | 3.16 turns |
| Reported generative token usage | 0 |
Hit Rate@10 measures how often the target product appears in the first ten recommendations. MRR measures how highly the target product is ranked, while MTTC measures the average number of turns required to reach a successful recommendation.
These measurements describe performance on the public development set and do not guarantee the same result on the private evaluation set.
Development tools
- Visual Studio Code for development and code review
- Python 3 for the implementation
- macOS Terminal for local setup, testing, and evaluation
- Git and GitHub for version control and public repository hosting
- Devpost for the final project submission
APIs used
- Ollama local HTTP API for generating embeddings with
nomic-embed-text
Threadline does not use a paid or externally hosted model API. Ollama runs locally, so no API credentials or paid model credits are required after installation.
Libraries and frameworks
- Python standard library for the main agent and supporting utilities
- SQLite FTS5 for full-catalogue lexical retrieval
- BM25 scoring for exact and field-weighted candidate search
- NumPy for the optional full-catalogue dense retrieval experiment
- unittest for automated behaviour and integration tests
- urllib for communication with the local Ollama service
The verified default does not depend on a hosted vector database or heavyweight machine-learning framework.
Datasets and assets used
- Official frozen 50,000-product catalogue supplied for TikTok TechJam 2026 Track 4
- Official 200-session public development dataset
- Product data derived by the organisers from the Amazon Reviews 2023 Clothing, Shoes and Jewelry dataset
- Open-source
nomic-embed-textembedding model, accessed locally through Ollama and distributed under the Apache License 2.0
The product catalogue is treated as strictly read-only. Threadline does not modify catalogue records, insert mock products, or access the private evaluation sessions.
Team contribution
This is a solo submission completed by Er Teng Sheng Elgin. All system design, implementation, experimentation, testing, evaluation, and documentation were completed as part of this submission.
Log in or sign up for Devpost to join the conversation.