instant-bom/docs/backlog.md

Backlog

Done

Ingestion Pipeline

• session/models.py — BomSession, BomRow, NormalizedParams, ComponentCategory, RowState
• ingestion/parser.py — CSV + XLSX + XLS, preamble skip, footer strip, delimiter detection
• ingestion/column_mapper.py — heuristic synonym lookup, AI fallback, synonym persistence
• ingestion/column_synonyms.json — file-backed synonym table, auto-updated on AI discovery
• ingestion/normalizer.py — designator parsing, range expansion, DNP detection, row state
• classification/classifier.py — designator prefix map + value heuristics → ComponentCategory
• classification/param_extractor.py — value parsing, description fallback, package extraction, AI fallback
• classification/package_patterns.json — file-backed regex patterns + known_footprints dict

Bug Fixes

• Double-space header normalization (_normalize_key collapses whitespace) — fixed Ref Des (Multi-4) mismatch
• Comment → part_number disambiguation — passive value sampling prevents pn='100nF'
• Description fallback scanners — extracts values from long strings like "CAP CER 0.1UF 100V X7R 0603"
• \b → (?<![A-Za-z]) lookbehind — fixes underscore-prefixed footprints (Texas_HTSOP-8-1EP)
• HTSOP overcapture fix — suffix pattern (?:-[A-Z0-9]+)* stops at _digit

---

Todo

Ingestion

• Strip Elec_ prefix from package — store "6.3x5.8" not "Elec_6.3x5.8" (change capture group in package_patterns.json)
• Persian-header BOM support — AI column mapping for non-Latin headers (currently returns 0 rows)

LCSC Category Resolution

• suppliers/lcsc/fetch_categories.py — one-time CLI to scrape LCSC category pages → categories.json (1.5s grace period between requests)
• suppliers/lcsc/categories.json — committed static category tree (refresh quarterly)
• suppliers/lcsc/categories.py — load_categories(), get_subcategories_for(internal_cat)
• suppliers/lcsc/category_resolver.py — LLM (Claude Haiku) category inference + category_cache.json persistence
• suppliers/lcsc/category_cache.json — file-backed cache (same pattern as package_patterns.json)

LCSC Search Adapter

• suppliers/base.py — abstract SupplierAdapter(api_token=None) with search(category_id, params, page) interface
• suppliers/lcsc/lcsc.py — scraper mode: CSRF session + POST to lcsc.com/api/products/search; token mode stub for official API

Scouting Loop

• Scouting orchestrator — drive pending rows through scouting → filtering → confirmed
• BomRow state machine transitions wired to category resolver + search adapter
• Retry / re-scout flow when user rejects results or picks a different category

API

• FastAPI app entry point (api/main.py)
• POST /upload — ingest file, return BomSession
• GET /session/{id} — return session state
• GET /session/{id}/row/{row_id}/scout — LLM category inference, return {subcategory, alternatives[]}
• POST /session/{id}/row/{row_id}/confirm-category — lock LCSC subcategory, advance state to filtering
• POST /session/{id}/row/{row_id}/search — search within confirmed category + param filters
• POST /session/{id}/row/{row_id}/confirm — lock part pick, advance state to confirmed
• GET /session/{id}/export — collate confirmed picks → downloadable BOM

Future: Other Suppliers

• DigiKey adapter
• Mouser adapter
• Nexar adapter

Frontend

• React scaffold + build setup
• Upload page
• Row-by-row scouting UI (category dropdown, results grid, confirm/reject)
• Session progress view (rows confirmed vs pending)
• Export button