Product Spec Search

Workflow / Luồng xử lý

1 NL flow: /search/parse → review parsed filter → /search

NL: gọi /search/parse → xem lại bộ lọc → gọi /search với bộ lọc đã xác nhận

2 Structured flow: /search/structured (single call, no LLM parse needed)

Structured: gọi /search/structured (1 lần, không cần LLM phân tích)

3 PDF flow (2-step): /search/pdf/extract → user edits → /search/structured per spec

PDF (2 bước): /search/pdf/extract → người dùng chỉnh sửa → /search/structured cho mỗi spec

Key Concepts / Khái niệm chính

`must_match`	Hard filter — rows with MISS on these attributes are excluded from results entirely. Other attributes are soft preferences (contribute to ranking only). Bộ lọc cứng — sản phẩm không khớp thuộc tính này sẽ bị loại hoàn toàn. Các thuộc tính khác chỉ ảnh hưởng xếp hạng.
`tolerances`	Percentage thresholds for numeric attributes. Defaults: lumen ±10%, dim ±10%, beam ±15%, watt ±15%. Value `0.1` means ±10%. Customizable per request for all search methods (NL, Structured, PDF). If not provided, defaults are used. Ngưỡng phần trăm cho thuộc tính số. Mặc định: lumen ±10%, dim ±10%, beam ±15%, watt ±15%. Giá trị `0.1` nghĩa là ±10%. Tùy chỉnh được cho tất cả phương thức tìm kiếm (NL, Structured, PDF). Nếu không truyền, dùng mặc định.
`top_k`	Max results per filter/spec. Default: 20. Số kết quả tối đa mỗi bộ lọc/spec. Mặc định: 20.
`notes`	LLM commentary from parse step. Informational only — not used in search logic. Ghi chú từ LLM ở bước phân tích. Chỉ mang tính thông tin — không ảnh hưởng tìm kiếm.
`vocab_version`	Vocabulary version used for this response. Parse cache is keyed by query + version, so vocab updates auto-invalidate stale parses. Phiên bản từ vựng dùng cho response. Cache phân tích được đánh key theo query + version, nên cập nhật vocab tự động vô hiệu cache cũ.

POST /search/parse

Parse natural-language queries into structured filters. Returns parsed filters for review before searching.

Phân tích câu truy vấn tự nhiên thành bộ lọc có cấu trúc. Trả về bộ lọc để xem lại trước khi tìm kiếm.

Request

{
  "queries": [
    "recessed 6W DALI 3000K CRI90"
  ]
}

Response

{
  "vocab_version": 12,
  "parsed": [{
    "watt": 6,
    "dimming": ["DALI"],
    "cct": ["3000K"],
    "cri": ["CRI90"],
    "mounting": ["Recessed"],
    "must_match": ["dimming"]
  }]
}

POST /search

Search with confirmed parsed filters. Supports batch (multiple filters in one request). No LLM cost — uses cached extractions.

Tìm kiếm với bộ lọc đã xác nhận. Hỗ trợ batch (nhiều bộ lọc trong 1 request). Không tốn phí LLM — dùng cache trích xuất. filters[i] tương ứng results[i].

Request

{
  "filters": [{
    "watt": 6,
    "dimming": ["DALI"],
    "cct": ["3000K"],
    "cri": ["CRI90"],
    "mounting": ["Recessed"],
    "must_match": ["dimming"],
    "tolerances": {
      "lumen": 0.1, "dim": 0.1,
      "beam": 0.15, "watt": 0.15
    }
  }],
  "top_k": 20
}

Response

{
  "vocab_version": 12,
  "results": [{
    "matches": [{
      "id": 4521,
      "supplier": "CGD",
      "product_name": "H-Series Downlight",
      "variant_count": 2,
      "variants": [
        {"product_code": "HS06-DALI-CRI90-3000K", "lumen": "540lm", "wattage": "6W", "dimming": "DALI", ...},
        {"product_code": "HS06-DALI-CRI90-4000K", "lumen": "540lm", "wattage": "6W", "dimming": "DALI", ...}
      ],
      "statuses": {
        "lumen": 0, "dim": 0,
        "beam": 0, "watt": 3,
        "ip": 0, "dimming": 3,
        "mounting": 3, "cri": 3,
        "cct": 3
      },
      "closeness": {
        "lumen": null, "dim": null,
        "beam": null, "watt": 0.0
      },
      "extracted": {
        "lumen": {"lumen_lm_min": 540},
        "watt": {"watt_min": 6, "watt_max": 6},
        "dimming": {"dimmings": ["DALI"]},
        "mounting": {"mountings": ["Recessed"]}
      }
    }]
  }]
}

Status codes: 3 = HIT, 2 = WITHIN, 1 = MISS, 0 = UNKNOWN
Mã trạng thái: 3 = Khớp chính xác, 2 = Trong dung sai, 1 = Không khớp, 0 = Không có dữ liệu

POST /search/structured

Search with raw attribute strings (as they appear on spec sheets). No NL parsing — extraction happens server-side. Zero LLM cost when cache is warm.

Tìm kiếm bằng chuỗi thuộc tính thô (đúng như trên spec sheet). Không qua NL — trích xuất phía server. Không tốn phí LLM khi cache đã có.

Request

{
  "lumen": "90lm/w",
  "dimension_size": "Ø104mm x 72mm",
  "beam_angle": "33°",
  "wattage": "6W",
  "mounting": "Recessed",
  "dimming": "DALI",
  "ip_rating": "IP20",
  "cri": "CRI95",
  "cct": "4000K",
  "tolerances": {
    "lumen": 0.1, "dim": 0.1,
    "beam": 0.15, "watt": 0.15
  },
  "top_k": 20
}

Response

{
  "vocab_version": 12,
  "results": [{
    "matches": [{
      "id": 4521,
      "supplier": "CGD",
      "product_name": "H-Series Downlight",
      "variant_count": 2,
      "variants": [
        {"product_code": "HS06-DALI-CRI95-4000K", "lumen": "540lm", "wattage": "6W", ...},
        {"product_code": "HS06-DALI-CRI80-4000K", "lumen": "540lm", "wattage": "6W", ...}
      ],
      "statuses": {
        "lumen": 2, "dim": 3,
        "beam": 3, "watt": 3,
        "ip": 3, "dimming": 3,
        "mounting": 3, "cri": 3,
        "cct": 3
      },
      "closeness": {
        "lumen": 0.05, "dim": 0.0,
        "beam": 0.0, "watt": 0.0
      },
      "extracted": {
        "lumen": {"efficacy_lm_w_min": 90},
        "dim": {"dim_mm_min": 104},
        "beam": {"beam_min": 33},
        "watt": {"watt_min": 6, "watt_max": 6},
        "ip": {"ips": ["IP20"]},
        "dimming": {"dimmings": ["DALI"]},
        "mounting": {"mountings": ["Recessed"]},
        "cri": {"cris": ["CRI95"]},
        "cct": {"ccts": ["4000K"]}
      }
    }]
  }]
}

POST /search/pdf/extract NEW

Extract specs from a PDF without searching. Returns structured fields per luminaire that can be reviewed/edited before calling /search/structured.

Trích xuất thông số từ PDF mà không tìm kiếm. Trả về các trường có cấu trúc cho từng đèn, có thể xem lại/chỉnh sửa trước khi gọi /search/structured.

Request

Content-Type: multipart/form-data

file: <pdf_file>

Response

{
  "specs": [{
    "label": "ND02A",
    "description": "Panel Light 1195x295",
    "lumen": "782lm",
    "wattage": "7.3W",
    "beam_angle": "56°",
    "dimension_size": "Ø125mm H=184mm",
    "ip_rating": "IP54",
    "dimming": "Dimmable",
    "mounting": "Suspended",
    "cri": "CRI80",
    "cct": "3000K"
  }]
}

Cost: ~$0.001 per page (Haiku, parallel). Use with /search/structured for the 2-step Extract → Edit → Search flow.
Chi phí: ~$0.001 mỗi trang (Haiku, song song). Dùng kết hợp với /search/structured cho quy trình 2 bước: Trích xuất → Chỉnh sửa → Tìm kiếm.

POST /search/pdf

Upload a PDF spec sheet. Extracts + searches in one call (no edit step). Kept for backward compatibility.

Tải lên PDF spec sheet. Trích xuất + tìm kiếm trong 1 lần gọi (không có bước chỉnh sửa). Giữ lại để tương thích ngược.

Request

Content-Type: multipart/form-data

file: <pdf_file>
top_k: 20  (optional, default 20)
tolerances: JSON string (optional)
  {"lumen":0.1,"dim":0.1,
   "beam":0.15,"watt":0.15}

Response

{
  "vocab_version": 12,
  "specs_found": 3,
  "results": [{
    "label": "PL01",
    "description": "Panel Light 1195x295",
    "spec": {
      "lumen": "3500lm",
      "wattage": "25W",
      "dimension_size": "1195x295x34mm",
      "beam_angle": "120°",
      "ip_rating": "IP20",
      "dimming": "DALI",
      "mounting": "Recessed",
      "cri": "CRI80",
      "cct": "4000K"
    },
    "matches": [{
      "id": 1023,
      "supplier": "Opple",
      "product_name": "LED Panel RC-SL",
      "product_code": "OP-PL1195-25W",
      "statuses": {
        "lumen": 3, "dim": 3,
        "beam": 3, "watt": 3,
        "ip": 3, "dimming": 3,
        "mounting": 3, "cri": 3,
        "cct": 3
      },
      "closeness": {
        "lumen": 0.02, "dim": 0.0,
        "beam": 0.0, "watt": 0.0
      },
      "extracted": null
    }]
  }]
}

Cost: ~$0.001 per page (Haiku, parallel). Each extracted spec runs structured search (no additional LLM cost).
Chi phí: ~$0.001 mỗi trang (Haiku, song song). Mỗi spec trích xuất được tìm kiếm structured (không tốn thêm phí LLM).

Response Schema Reference / Tham chiếu cấu trúc response

statuses

Per-attribute match quality. Keys: lumen, dim, beam, watt, ip, dimming, mounting, cri, cct

Chất lượng khớp theo từng thuộc tính.

3	HIT	Exact match (categorical in set, numeric at target) Khớp chính xác (phân loại nằm trong tập, số đúng mục tiêu)
2	WITHIN	Within tolerance range (numeric only) Trong khoảng dung sai (chỉ thuộc tính số)
1	MISS	Outside tolerance / not in set Ngoài dung sai / không nằm trong tập hợp
0	UNKNOWN	Product has no data for this attribute Sản phẩm không có dữ liệu cho thuộc tính này

closeness

Numeric attributes only. Relative distance from target: |row - target| / target. Lower is better. null = no data.

Chỉ cho thuộc tính số. Khoảng cách tương đối so với mục tiêu. Càng thấp càng tốt. null = không có dữ liệu.

extracted

Raw extracted values per attribute. Shape varies by type:

Giá trị thô đã trích xuất theo từng thuộc tính. Cấu trúc khác nhau tuỳ loại:

Numeric attributes

"lumen": {
  "lumen_lm_min": 540,
  "lumen_lm_max": 540,
  "efficacy_lm_w_min": null,
  "efficacy_lm_w_max": null
}

"dim": {
  "dim_mm_min": 104,
  "dim_mm_max": 104
}

"beam": {
  "beam_min": 33,
  "beam_max": 33
}

"watt": {
  "watt_min": 6,
  "watt_max": 6
}

Lumen may have lumen_lm_* (absolute) or efficacy_lm_w_* (per-watt). When only efficacy is available, derived lumen = efficacy × wattage.
Lumen có thể là lumen_lm_* (tuyệt đối) hoặc efficacy_lm_w_* (hiệu suất/W). Khi chỉ có efficacy, lumen suy ra = efficacy × wattage.

Categorical attributes

"ip": {
  "ips": ["IP20"]
}

"dimming": {
  "dimmings": ["DALI"]
}

"mounting": {
  "mountings": ["Recessed"]
}

"cri": {
  "cris": ["CRI90"]
}

"cct": {
  "ccts": ["3000K", "4000K"]
}

Always an array — a product can support multiple values (e.g. dual IP rating, multi-CCT).
Luôn là mảng — một sản phẩm có thể có nhiều giá trị (vd: IP kép, nhiều CCT).

Try:

recessed downlight ~6W narrow beam IP20 DALI 3000K CRI90 Ø35mm

pendant light exactly 40W DALI 4000K CRI90

surface mounted around 15W IP44 TRIAC 3000K

1 Extract

2 Review

3 Results

+

Upload Luminaire Spec PDF

Drop a PDF file here. AI will extract specs from each page — you can review and edit before searching.

Try samples:

pdf1 — Luminaire Data

pdf2 — ARUP Data Sheets

pdf3 — Light Collab Specs

Lumen

Dimension Size

Beam Angle

Wattage

Mounting

Dimming

IP Rating

CRI

CCT

or try a sample:

6W Recessed DALI CRI95

6W Surface IP54

25W Surface DALI

2x6W Suspended Non Dim

+

Upload Product XLSX

Drop .xlsx file here or click to browse. Auto-runs vocab refresh after upload.

Eval Build

Build labeled eval set via Oracle (Opus 4.7). ~50 rows per supplier.

Eval Run

Run extraction pipeline against eval set and report accuracy.

Product Spec Search

Workflow / Luồng xử lý

Key Concepts / Khái niệm chính

Response Schema Reference / Tham chiếu cấu trúc response

statuses

closeness

extracted

Review & Edit Specifications

Eval Build

Eval Run

Recent Jobs

Parsed Filter

Results

Workflow / Luồng xử lý

Key Concepts / Khái niệm chính

Response Schema Reference / Tham chiếu cấu trúc response

statuses

closeness

extracted

Review & Edit Specifications

Eval Build

Eval Run

Recent Jobs

Parsed Filter

Results

Variants