Image vector to product details

app/api/schemas.py

@@ -138,6 +138,17 @@ class ImageVectorsOut(BaseModel):
     state: str = "unknown"
 
 
+class OcrOut(BaseModel):
+    """Whether POST /api/search/identify can read a label off a photo itself.
+    Reported without loading the engine. `runtime_importable=false` after a
+    deploy means the rapidocr wheel was not installed (requirements-ocr.txt);
+    `onnxruntime_importable=false` means its engine was not."""
+    enabled: bool = True
+    runtime_importable: bool = False
+    onnxruntime_importable: bool = False
+    state: str = "unknown"
+
+
 class HealthOut(BaseModel):
     status: str
     database: bool
@@ -148,6 +159,7 @@ class HealthOut(BaseModel):
     # Defaulted so a client of this schema still validates against a
     # deployment predating the field.
     image_vectors: ImageVectorsOut = Field(default_factory=ImageVectorsOut)
+    ocr: OcrOut = Field(default_factory=OcrOut)
 
 
 # ---------------------------------------------------------------------------
@@ -251,6 +263,16 @@ class ImageVectorSearchRequest(BaseModel):
     top_k: int = Field(IMAGE_SEARCH_DEFAULT_TOP_K, ge=1, le=IMAGE_SEARCH_MAX_TOP_K)
     min_score: float = Field(IMAGE_SEARCH_DEFAULT_MIN_SCORE, ge=-1.0, le=1.0,
                              description="Drop matches with cosine similarity below this")
+    # Opt-in, so a client that never asked for it gets exactly the response
+    # it always did. With it, the route runs the identify ladder: when the
+    # best image score is under IMAGE_IDENTIFY_MIN_IMAGE_SCORE, `text` is
+    # resolved against the catalogue instead, and the response is an
+    # IdentifyOut (ImageSearchOut plus matched_by / fallback_reason / ...).
+    text_fallback: bool = Field(
+        False,
+        description="Fall back to resolving `text` when the image match is below the identify floor; "
+                    "the response then carries the IdentifyOut fields",
+    )
 
     @field_validator("vector")
     @classmethod
@@ -281,6 +303,23 @@ class ImageSearchOut(BaseModel):
     query_text: Optional[str] = None
 
 
+class IdentifyOut(ImageSearchOut):
+    """POST /search/identify: an ImageSearchOut plus which rung answered.
+
+    `matched_by` names the space each result's `score` is in: "image_vector"
+    (cosine of the 1024-d photo embedding) or "text" (cosine of the 384-d
+    MiniLM embedding of the label). `image_top_score` always carries the
+    image side. The answer is confirmed when matched_by is "text", or
+    "image_vector" with no `fallback_reason`; otherwise `fallback_reason`
+    says why the best effort shown is unconfirmed (see product_identify.py).
+    """
+    matched_by: str = "none"                    # "image_vector" | "text" | "none"
+    ocr_text: Optional[str] = None              # the label text the ladder used
+    ocr_source: Optional[str] = None            # "client" | "server"
+    image_top_score: Optional[float] = None
+    fallback_reason: Optional[str] = None
+
+
 # ---------------------------------------------------------------------------
 # RAG chat
 # ---------------------------------------------------------------------------