updates on catalog search and suggestions in backend

app/api/schemas.py

@@ -126,8 +126,34 @@ class AllProductsOut(BaseModel):
 
 class SearchOut(BaseModel):
     query: str
+    # Echoes the *request* param, as it always has. The brand inferred from the
+    # query text goes in `detected_brand` instead - repurposing this field would
+    # break any consumer reading it as "the filter I sent".
     brand: Optional[str] = None
     results: List[SourceProductOut]
+    # Exact in brand_catalog mode. None in hybrid mode: the merge happens in
+    # Python across N brand tables after per-table LIMITs, so there is no cheap
+    # exact count and inventing one would misreport how much was found.
+    total: Optional[int] = None
+    limit: int = 0
+    offset: int = 0
+    match_mode: str = "hybrid"          # "brand_catalog" | "hybrid"
+    detected_brand: Optional[str] = None
+    detected_category: Optional[str] = None
+
+
+class SuggestionOut(BaseModel):
+    """One row in the search box's autocomplete dropdown."""
+    type: str                           # "brand" | "category"
+    value: str                          # what the search box / filter should use
+    label: str                          # display text
+    sublabel: Optional[str] = None      # e.g. "128 products"
+    score: float = 0.0
+
+
+class SuggestOut(BaseModel):
+    query: str
+    suggestions: List[SuggestionOut]
 
 
 # ---------------------------------------------------------------------------