aissemble-inference-core 1.5.0__py3-none-any.whl

aissemble_inference_core/client/builder/summarization_builder.py

@@ -0,0 +1,213 @@
+###
+# #%L
+# aiSSEMBLE::Open Inference Protocol::Core
+# %%
+# Copyright (C) 2024 Booz Allen Hamilton Inc.
+# %%
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# #L%
+###
+"""Builder for text summarization inference."""
+
+from typing import Any, Generator
+
+from aissemble_inference_core.client.builder.inference_builder import InferenceBuilder
+from aissemble_inference_core.client.predictor import Predictor
+from aissemble_inference_core.client.results.summarization_result import (
+    SummarizationResult,
+)
+from aissemble_inference_core.client.translators.summarization_translator import (
+    DefaultSummarizationTranslator,
+)
+
+
+class SummarizationPredictor(Predictor[str, SummarizationResult]):
+    """Concrete predictor implementation for text summarization."""
+
+    def __init__(
+        self,
+        adapter: Any,
+        translator: DefaultSummarizationTranslator,
+    ):
+        """Initialize the summarization predictor.
+
+        Args:
+            adapter: OIP adapter for communication
+            translator: Translator for preprocessing/postprocessing
+        """
+        self.adapter = adapter
+        self.translator = translator
+
+    def predict(self, text: str) -> SummarizationResult:  # noqa: A003
+        """Perform summarization on the input text.
+
+        Args:
+            text: Text to summarize
+
+        Returns:
+            SummarizationResult with generated summary
+        """
+        request = self.translator.preprocess(text)
+        response = self.adapter.infer(request)
+        return self.translator.postprocess(response)
+
+
+class SummarizationBuilder(InferenceBuilder):
+    """Task-specific builder for text summarization inference.
+
+    Provides a fluent, natural API for text summarization:
+        builder.text("long text...").max_length(100).run()
+
+    Example:
+        client = InferenceClient(adapter, endpoint)
+        result = (client.summarize("bart-large")
+                       .text("Very long article text here...")
+                       .max_length(150)
+                       .min_length(50)
+                       .run())
+        print(result.summary)
+        print(f"Compressed {result.compression_ratio:.1f}x")
+    """
+
+    def __init__(self):
+        """Initialize the summarization builder."""
+        super().__init__()
+        self._text_input: str | None = None
+        self._max_length: int | None = None
+        self._min_length: int | None = None
+
+    def text(self, text: str) -> "SummarizationBuilder":
+        """Set the input text to summarize.
+
+        Args:
+            text: The text to summarize
+
+        Returns:
+            Self for method chaining
+
+        Raises:
+            ValueError: If text is empty or not a string
+        """
+        if not text or not isinstance(text, str):
+            raise ValueError("Text must be a non-empty string")
+        self._text_input = text
+        return self
+
+    def max_length(self, length: int) -> "SummarizationBuilder":
+        """Set maximum summary length.
+
+        Args:
+            length: Maximum length in tokens or characters (model-dependent)
+
+        Returns:
+            Self for method chaining
+
+        Raises:
+            ValueError: If length is not positive
+        """
+        if length <= 0:
+            raise ValueError("Max length must be positive")
+        self._max_length = length
+        return self
+
+    def min_length(self, length: int) -> "SummarizationBuilder":
+        """Set minimum summary length.
+
+        Args:
+            length: Minimum length in tokens or characters (model-dependent)
+
+        Returns:
+            Self for method chaining
+
+        Raises:
+            ValueError: If length is not positive
+        """
+        if length <= 0:
+            raise ValueError("Min length must be positive")
+        self._min_length = length
+        return self
+
+    def run(self) -> SummarizationResult:
+        """Execute the text summarization inference.
+
+        Returns:
+            SummarizationResult with generated summary
+
+        Raises:
+            ValueError: If required inputs are missing or invalid
+        """
+        if self._text_input is None:
+            raise ValueError("Text input is required. Call .text() first.")
+
+        if self._min_length and self._max_length:
+            if self._min_length > self._max_length:
+                raise ValueError(
+                    f"Min length ({self._min_length}) cannot exceed "
+                    f"max length ({self._max_length})"
+                )
+
+        # Add length parameters to request if specified
+        if self._max_length is not None:
+            self._parameters["max_length"] = self._max_length
+        if self._min_length is not None:
+            self._parameters["min_length"] = self._min_length
+
+        predictor = self.build_predictor()
+        return predictor.predict(self._text_input)
+
+    def build_predictor(self) -> Predictor[str, SummarizationResult]:
+        """Build the predictor for summarization.
+
+        Returns:
+            SummarizationPredictor instance
+
+        Raises:
+            ValueError: If adapter is not set
+        """
+        if self.oip_adapter is None:
+            raise ValueError("OipAdapter is required. Call .with_adapter() first.")
+
+        translator = (
+            self.translator
+            if isinstance(self.translator, DefaultSummarizationTranslator)
+            else DefaultSummarizationTranslator()
+        )
+
+        return SummarizationPredictor(
+            adapter=self.oip_adapter,
+            translator=translator,
+        )
+
+    def __iter__(self) -> Generator[SummarizationResult, None, None]:
+        """Streaming iteration for summarization.
+
+        Not currently implemented for summarization tasks.
+
+        Raises:
+            NotImplementedError: Streaming is not yet supported
+        """
+        raise NotImplementedError(
+            "Streaming is not yet supported for summarization tasks"
+        )
+
+    def __next__(self) -> SummarizationResult:
+        """Return the next streaming result.
+
+        Not currently implemented for summarization tasks.
+
+        Raises:
+            NotImplementedError: Streaming is not yet supported
+        """
+        raise NotImplementedError(
+            "Streaming is not yet supported for summarization tasks"
+        )

aissemble_inference_core/client/inference_client.py

@@ -0,0 +1,158 @@
+###
+# #%L
+# aiSSEMBLE::Open Inference Protocol::Core
+# %%
+# Copyright (C) 2024 Booz Allen Hamilton Inc.
+# %%
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# #L%
+###
+from __future__ import annotations
+
+from typing import Dict, List
+
+from aissemble_inference_core.client.builder.object_detection_builder import (
+    ObjectDetectionBuilder,
+)
+from aissemble_inference_core.client.builder.raw_inference_builder import (
+    RawInferenceBuilder,
+)
+from aissemble_inference_core.client.builder.summarization_builder import (
+    SummarizationBuilder,
+)
+from aissemble_inference_core.client.oip_adapter import OipAdapter
+from aissemble_inference_core.client.registry import ModuleRegistry
+
+
+class InferenceClient:
+    """A facade of the entire client library. Supports one-line construction with zero configuration ceremony. It wraps
+    controls invocation of OIP-compliant endpoints.
+
+    ALL task-specific entry points (e.g., detect_object, summarize) are accessible from here.
+
+    The client supports dynamic module discovery via Python entry points. Installed
+    OIP modules (e.g., aissemble-inference-yolo) automatically register their builders,
+    translators, and runtimes.
+
+    Example:
+        from aissemble_inference_core.client import InferenceClient
+
+        client = InferenceClient(adapter, endpoint)
+
+        # List available modules
+        print(client.list_available_modules())
+
+        # Use object detection (uses discovered or built-in builder)
+        result = client.detect_object("yolov8").image("photo.jpg").run()
+    """
+
+    def __init__(self, adapter: OipAdapter, endpoint: str):
+        """Initializes the InferenceClient with the given adapter and endpoint.
+
+        Args:
+            adapter: The OIP adapter to use for inference.
+            endpoint: The endpoint URL for the inference service.
+        """
+        self.adapter = adapter
+        self.endpoint = endpoint
+        self._registry = ModuleRegistry.instance()
+
+    def raw(self, model_name: str) -> RawInferenceBuilder:
+        """Creates a builder for raw inference.
+
+        Args:
+            model_name: The name of the model to use.
+
+        Returns:
+            A RawInferenceBuilder instance.
+        """
+        # TODO: Implement raw inference builder creation
+        pass
+
+    def detect_object(self, model_name: str | None = None) -> ObjectDetectionBuilder:
+        """Creates a builder for object detection inference.
+
+        If a model-specific builder is registered (e.g., from aissemble-inference-yolo),
+        it will be used. Otherwise, falls back to the default ObjectDetectionBuilder.
+
+        Args:
+            model_name: Optional name of the model to use
+
+        Returns:
+            An ObjectDetectionBuilder instance configured for this client
+
+        Example:
+            result = client.detect_object("yolov8").image("photo.jpg").confidence(0.6).run()
+        """
+        builder = ObjectDetectionBuilder()
+        builder = builder.with_adapter(self.adapter)
+        if model_name:
+            builder = builder.with_model(model_name)
+        return builder
+
+    def summarize(self, model_name: str | None = None) -> SummarizationBuilder:
+        """Creates a builder for text summarization inference.
+
+        Args:
+            model_name: Optional name of the summarization model to use
+
+        Returns:
+            A SummarizationBuilder instance configured for this client
+
+        Example:
+            result = client.summarize("bart-large") \
+                .text("Long article text here...") \
+                .max_length(100) \
+                .run()
+            print(result.summary)
+        """
+        builder = SummarizationBuilder()
+        builder = builder.with_adapter(self.adapter)
+        if model_name:
+            builder = builder.with_model(model_name)
+        return builder
+
+    def list_available_modules(self) -> Dict[str, List[str]]:
+        """List all discovered OIP modules.
+
+        Returns:
+            Dictionary mapping category to list of available module names.
+            Categories: runtimes, translators, builders
+
+        Example:
+            modules = client.list_available_modules()
+            # {'runtimes': ['yolo'], 'translators': ['yolo', 'object_detection'], ...}
+        """
+        return self._registry.list_available()
+
+    def get_translator(self, name: str):
+        """Get a translator class by name from the registry.
+
+        Args:
+            name: The registered name of the translator
+
+        Returns:
+            The translator class, or None if not found
+        """
+        return self._registry.get_translator(name)
+
+    def get_runtime(self, name: str):
+        """Get a runtime class by name from the registry.
+
+        Args:
+            name: The registered name of the runtime
+
+        Returns:
+            The runtime class, or None if not found
+        """
+        return self._registry.get_runtime(name)

aissemble_inference_core/client/oip_adapter.py

@@ -0,0 +1,211 @@
+###
+# #%L
+# aiSSEMBLE::Open Inference Protocol::Core
+# %%
+# Copyright (C) 2024 Booz Allen Hamilton Inc.
+# %%
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# #L%
+###
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TensorData:
+    """Represents tensor data in OIP format.
+
+    Attributes:
+        name: Name of the tensor input/output
+        shape: Shape of the tensor as a list of integers
+        datatype: Data type string (e.g., "FP32", "UINT8", "BYTES")
+        data: The actual tensor data (nested list structure)
+        parameters: Optional parameters for this tensor
+    """
+
+    name: str
+    shape: list[int]
+    datatype: str
+    data: list[Any]
+    parameters: dict[str, Any] | None = None
+
+
+@dataclass
+class OipRequest:
+    """Represents an OIP inference request compliant with the Open Inference Protocol specification.
+
+    Attributes:
+        inputs: List of input tensors (required)
+        id: Optional request identifier
+        parameters: Optional inference parameters
+        outputs: Optional list of requested output names
+    """
+
+    inputs: list[TensorData]
+    id: str | None = None  # noqa: A003
+    parameters: dict[str, Any] = field(default_factory=dict)
+    outputs: list[dict[str, Any]] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the request to a dictionary for JSON serialization."""
+        result: dict[str, Any] = {
+            "inputs": [
+                {
+                    "name": inp.name,
+                    "shape": inp.shape,
+                    "datatype": inp.datatype,
+                    "data": inp.data,
+                    **({"parameters": inp.parameters} if inp.parameters else {}),
+                }
+                for inp in self.inputs
+            ]
+        }
+        if self.id:
+            result["id"] = self.id
+        if self.parameters:
+            result["parameters"] = self.parameters
+        if self.outputs:
+            result["outputs"] = self.outputs
+        return result
+
+
+@dataclass
+class OipResponse:
+    """Represents an OIP inference response compliant with the Open Inference Protocol specification.
+
+    Attributes:
+        model_name: Name of the model that produced this response
+        outputs: List of output tensors
+        model_version: Optional version of the model
+        id: Optional request identifier echo
+        parameters: Optional response parameters
+    """
+
+    model_name: str
+    outputs: list[TensorData]
+    model_version: str | None = None
+    id: str | None = None  # noqa: A003
+    parameters: dict[str, Any] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OipResponse":
+        """Create an OipResponse from a dictionary (JSON deserialization)."""
+        outputs = [
+            TensorData(
+                name=out["name"],
+                shape=out["shape"],
+                datatype=out["datatype"],
+                data=out["data"],
+                parameters=out.get("parameters"),
+            )
+            for out in data["outputs"]
+        ]
+        return cls(
+            model_name=data["model_name"],
+            outputs=outputs,
+            model_version=data.get("model_version"),
+            id=data.get("id"),
+            parameters=data.get("parameters"),
+        )
+
+
+@dataclass
+class OipHealthStatus:
+    """Represents the health status of an OIP endpoint.
+
+    Attributes:
+        isLive: Whether the endpoint is alive
+        isReady: Whether the endpoint is ready to serve requests
+    """
+
+    isLive: bool
+    isReady: bool
+
+
+class OipAdapter:
+    """This is the sole class that interacts with OIP endpoints. It is stateless and can be mocked for client testing.
+    Implements appropriate backoff, authentication, and metrics capturing.
+    """
+
+    def infer(self, request: OipRequest) -> OipResponse:
+        """Performs inference using the provided OIP request.
+
+        Args:
+            request: The OipRequest object containing inference parameters.
+
+        Returns:
+            The OipResponse object.
+        """
+        raise NotImplementedError
+
+
+class HttpOipAdapter(OipAdapter):
+    """HTTP-based OIP adapter for communicating with OIP-compliant inference servers.
+
+    This adapter sends inference requests to an OIP endpoint using HTTP POST,
+    compatible with MLServer and other OIP-compliant runtimes.
+    """
+
+    def __init__(self, base_url: str, model_name: str, timeout: float = 30.0):
+        """Initialize the HTTP adapter.
+
+        Args:
+            base_url: Base URL of the inference server (e.g., "http://localhost:8080")
+            model_name: Name of the model to invoke
+            timeout: Request timeout in seconds (default: 30.0)
+        """
+        self.base_url = base_url.rstrip("/")
+        self.model_name = model_name
+        self.timeout = timeout
+
+    @property
+    def inference_url(self) -> str:
+        """Get the full inference URL for this model."""
+        return f"{self.base_url}/v2/models/{self.model_name}/infer"
+
+    def infer(self, request: OipRequest) -> OipResponse:
+        """Perform inference using HTTP POST to the inference server.
+
+        Request parameters are preserved in the response to support stateless translators.
+
+        Args:
+            request: The OipRequest containing inference inputs
+
+        Returns:
+            OipResponse with model outputs and merged request parameters
+
+        Raises:
+            requests.HTTPError: If the server returns an error status
+            requests.Timeout: If the request times out
+        """
+        import requests
+
+        response = requests.post(
+            self.inference_url,
+            json=request.to_dict(),
+            headers={"Content-Type": "application/json"},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+
+        oip_response = OipResponse.from_dict(response.json())
+
+        # Merge request parameters into response for stateless translator support
+        # Server parameters take precedence over request parameters
+        if request.parameters:
+            merged_params = dict(request.parameters)
+            if oip_response.parameters:
+                merged_params.update(oip_response.parameters)
+            oip_response.parameters = merged_params
+
+        return oip_response

aissemble_inference_core/client/predictor.py

@@ -0,0 +1,75 @@
+###
+# #%L
+# aiSSEMBLE::Open Inference Protocol::Core
+# %%
+# Copyright (C) 2024 Booz Allen Hamilton Inc.
+# %%
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# #L%
+###
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+# Input type variable - represents the type of data fed into the model for inference
+T = TypeVar("T")
+
+# Output type variable - represents the type of prediction/result returned by the model
+R = TypeVar("R")
+
+
+class Predictor(Generic[T, R]):
+    """
+    An interface representing a ready-to-use inference wrapper around a specific model endpoint.
+
+    Inspired by the DJL (Deep Java Library) ``Predictor`` abstraction, this interface defines a
+    lightweight, reusable component that encapsulates the invocation of a model while managing
+    underlying resources such as connection pools, retries, timeouts, and authentication.
+
+    Implementations are expected to be thread-safe where appropriate and should maintain internal
+    state (e.g., HTTP clients, gRPC channels, or cached credentials) for efficient repeated use.
+    Typically, one ``Predictor`` instance is created per model endpoint/version and reused across
+    multiple inference calls.
+
+    Example usage::
+
+        predictor: Predictor[Image, Classification] = model.new_predictor()
+        result = predictor.predict(my_image)
+
+    """
+
+    def predict(self, input: T) -> R:  # noqa: A003
+        """
+        Perform inference on the given input and return the model's prediction.
+
+        Parameters
+        ----------
+        input : T
+            The input data in the format expected by the wrapped model. The exact type depends
+            on the model (e.g., ``numpy.ndarray``, ``PIL.Image.Image``, ``dict[str, Any]``, etc.).
+
+        Returns
+        -------
+        R
+            The prediction result. The concrete return type is determined by the model's output
+            schema (e.g., ``Classification``, ``List[float]``, ``dict[str, Any]``, etc.).
+
+        Raises
+        ------
+        InferenceError
+            If the inference request fails after retries are exhausted or due to an unrecoverable
+            error (e.g., malformed input, model endpoint unreachable, timeout).
+        ValueError
+            If the input does not conform to the expected schema or constraints.
+        """
+        raise NotImplementedError("Subclasses must implement predict()")