handler.py

"""
HuggingFace Inference Endpoint Handler for LearningStudio Callout Detection.

This wrapper provides an EMCO-compatible API format for LearningStudio integration,
calling the AWS Lambda-based callout detection pipeline via API Gateway.
"""

from typing import Dict, Any
from inference import inference


class EndpointHandler:
    """
    HuggingFace Inference Endpoint Handler.

    This class provides the interface expected by HuggingFace Inference Endpoints.
    It wraps the callout detection pipeline and transforms outputs to EMCO format.
    """

    def __init__(self, path: str = ""):
        """
        Initialize the endpoint handler.

        Args:
            path: Model path (unused for this wrapper, but required by HF interface)
        """
        # No model to load - this is a wrapper for an external API
        pass

    def __call__(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        Process an inference request.

        Args:
            data: Request data with format:
                {
                    "inputs": "image_url_or_base64",
                    "parameters": {...}  # Optional parameters
                }

        Returns:
            EMCO-compatible response:
            {
                "predictions": [
                    {
                        "id": 1,
                        "label": "callout",
                        "class_id": 0,
                        "confidence": 0.95,
                        "bbox": {"x1": 100, "y1": 200, "x2": 300, "y2": 400}
                    },
                    ...
                ],
                "total_detections": N,
                "image": "base64_encoded_image"
            }
        """
        # Extract input
        inputs = data.get("inputs")
        if inputs is None:
            return {
                "error": "Missing 'inputs' field",
                "predictions": [],
                "total_detections": 0,
                "image": ""
            }

        # Extract optional parameters
        parameters = data.get("parameters", {})

        # Call the inference function
        result = inference(inputs, parameters)

        return result