# 🚀 DONE: Refactor Lead Search Tool

## 📌 Context
- **Status:** ✅ Done

## 🎯 Goal
Replace the OpenAI Embedding logic in `lead_search_tool.py` with the highly optimized NGRAMBF + BITMAP Tags + Stock API architecture from `tag_search_tool.py`, while preserving Lead-specific features like `size` filtering and price relaxation.

## ⚠️ Active Trade-offs
- Skipping: OpenAI Embedding — To reduce latency from >1000ms to <300ms.
- Changing Data Source: Move outfit data from Postgres to local SQLite `123.db` for faster reads.

## 🛠 Impact & Files Touched
| File | Symbol | Change | Blast Radius |
|------|--------|--------|--------------|
| `backend/agent/lead_stage_agent/lead_search_tool.py` | `LeadSearchInput`, `_cascading_search`, etc. | MODIFY | Lead Stage Agent |

**Risk:** Medium

## 📋 Execution Checklist

### Phase 1: Update Schema & Builders
- [x] Task 1.1: Add `tags` field to `LeadSearchInput`. Update `keywords` prompt. Keep `size`.
- [x] Task 1.2: Merge `_build_fixed_clauses`, `_build_tag_clauses`, `_build_search_clause` from Tag Search. Add `size` to `_build_fixed_clauses`.

### Phase 2: Stock API & Outfits
- [x] Task 2.1: Port `_fetch_stock_batch` and `_enrich_with_stock` using `httpx`.
- [x] Task 2.2: Port `_enrich_with_outfit` reading from `123.db`.

### Phase 3: Cascading Search
- [x] Task 3.1: Replace OpenAI embedding in `_cascading_search` with Tag Search's 3 tiers (NGRAMBF, Tags BITMAP, Hard Filters).
- [x] Task 3.2: Re-attach Lead's specific tiers: Drop gender, Price Relaxation 1.5x, 2.0x, Unlimited.
- [x] Task 3.3: Re-attach `suggest_items` and `similar_items` formatting in `_format_products`.

## ✅ Completion Gate
- [x] All tasks [x] | [x] Sub-Doings resolved | [x] Smoke test passed | [x] Trade-offs confirmed

---
_Started: 2026-04-28 | Updated: 2026-04-28_
