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

aissemble_inference_core/__init__.py

@@ -0,0 +1,19 @@
+###
+# #%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%
+###

aissemble_inference_core/client/__init__.py

@@ -0,0 +1,23 @@
+###
+# #%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 aissemble_inference_core.client.inference_client import InferenceClient
+from aissemble_inference_core.client.registry import ModuleRegistry
+
+__all__ = ["InferenceClient", "ModuleRegistry"]

aissemble_inference_core/client/builder/__init__.py

@@ -0,0 +1,36 @@
+###
+# #%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 aissemble_inference_core.client.builder.inference_builder import InferenceBuilder
+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,
+)
+
+__all__ = [
+    "InferenceBuilder",
+    "ObjectDetectionBuilder",
+    "RawInferenceBuilder",
+    "SummarizationBuilder",
+]

aissemble_inference_core/client/builder/inference_builder.py

@@ -0,0 +1,178 @@
+###
+# #%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 abc import ABC, abstractmethod
+from typing import Dict, Generator, Any
+from collections.abc import Iterator
+
+from aissemble_inference_core.client.oip_adapter import OipAdapter
+from aissemble_inference_core.client.predictor import Predictor
+from aissemble_inference_core.client.translator import Translator
+
+
+class InferenceBuilder(ABC, Iterator[Any]):
+    """Abstract base class for building task-specific inference clients.
+
+    Rather than exposing a generic ``predict`` method, this class encourages the definition
+    of task-oriented inference builders (e.g., object detection, text summarization, translation).
+    Each concrete subclass can provide a natural, fluent API tailored to its task while
+    sharing common configuration state and behavior.
+
+    This design promotes:
+    - Compile-time safety through task-specific method signatures
+    - Reusable shared state (model name, adapter, parameters, etc.)
+    - Consistent access to streaming and iteration capabilities
+    - Alignment with concepts like HuggingFace "tasks"
+
+    Concrete subclasses should implement ``build_predictor`` to return a fully configured
+    :class:`Predictor` instance ready for inference.
+    """
+
+    def __init__(self) -> None:
+        self._model_name: str | None = None
+        self._oip_adapter: OipAdapter | None = None
+        self._translator: Translator | None = None
+        self._parameters: Dict[str, Any] = {}
+        self._streaming: bool = False
+
+    # -------------------------------------------------------------------------
+    # Protected properties (intended for use by subclasses and fluent setters)
+    # -------------------------------------------------------------------------
+
+    @property
+    def model_name(self) -> str | None:
+        """The name or identifier of the model to be used for inference."""
+        return self._model_name
+
+    @property
+    def oip_adapter(self) -> OipAdapter | None:
+        """The OIP adapter responsible for communication with the inference service."""
+        return self._oip_adapter
+
+    @property
+    def translator(self) -> Translator | None:
+        """The translator that handles data format conversion between client and service."""
+        return self._translator
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        """Task-specific or model-specific inference parameters."""
+        return self._parameters
+
+    @property
+    def streaming(self) -> bool:
+        """Whether the inference should be performed in streaming mode."""
+        return self._streaming
+
+    # -------------------------------------------------------------------------
+    # Fluent configuration methods (to be implemented/chained by subclasses)
+    # -------------------------------------------------------------------------
+
+    def with_model(self, model_name: str) -> "InferenceBuilder":
+        """Set the model name/identifier.
+
+        Args:
+            model_name: The identifier of the model to use.
+
+        Returns:
+            Self, for method chaining.
+        """
+        self._model_name = model_name
+        return self
+
+    def with_adapter(self, adapter: OipAdapter) -> "InferenceBuilder":
+        """Set the OIP adapter instance.
+
+        Args:
+            adapter: The adapter handling protocol communication.
+
+        Returns:
+            Self, for method chaining.
+        """
+        self._oip_adapter = adapter
+        return self
+
+    def with_translator(self, translator: Translator) -> "InferenceBuilder":
+        """Set the data translator instance.
+
+        Args:
+            translator: The translator for request/response serialization.
+
+        Returns:
+            Self, for method chaining.
+        """
+        self._translator = translator
+        return self
+
+    def with_parameters(self, **parameters: Any) -> "InferenceBuilder":
+        """Add or update inference parameters.
+
+        Args:
+            **parameters: Arbitrary keyword arguments representing inference parameters.
+
+        Returns:
+            Self, for method chaining.
+        """
+        self._parameters.update(parameters)
+        return self
+
+    # -------------------------------------------------------------------------
+    # Public API required by all task-specific builders
+    # -------------------------------------------------------------------------
+
+    @abstractmethod
+    def build_predictor(self) -> Predictor:
+        """Construct and return a fully configured :class:`Predictor` instance.
+
+        Concrete subclasses must implement this method to assemble the predictor
+        using the configured model name, adapter, translator, parameters, etc.
+
+        Returns:
+            A ready-to-use predictor for the specific task.
+        """
+        raise NotImplementedError
+
+    def stream(self) -> "InferenceBuilder":
+        """Enable streaming mode for subsequent inference calls.
+
+        Returns:
+            Self, for method chaining.
+        """
+        self._streaming = True
+        return self
+
+    # -------------------------------------------------------------------------
+    # Iterator protocol support (for streaming responses)
+    # -------------------------------------------------------------------------
+
+    def __iter__(self) -> Generator[Any, None, None]:
+        """Return a generator that yields streaming results.
+
+        When streaming is enabled, calling ``iter(builder)`` or using the builder
+        in a for-loop should yield incremental results from the inference service.
+
+        The default implementation raises ``NotImplementedError``; concrete
+        task-specific builders that support streaming should override this method.
+
+        Yields:
+            Task-specific streaming chunks (e.g., tokens, bounding boxes, etc.).
+        """
+        raise NotImplementedError(
+            "Streaming iteration is not implemented for this task"
+        )

aissemble_inference_core/client/builder/object_detection_builder.py

@@ -0,0 +1,190 @@
+###
+# #%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 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 import ObjectDetectionResult
+from aissemble_inference_core.client.translators import DefaultObjectDetectionTranslator
+
+
+class ObjectDetectionPredictor(Predictor[Any, ObjectDetectionResult]):
+    """Concrete predictor implementation for object detection."""
+
+    def __init__(
+        self,
+        adapter: Any,
+        translator: DefaultObjectDetectionTranslator,
+    ):
+        """Initialize the object detection predictor.
+
+        Args:
+            adapter: OIP adapter for communication
+            translator: Translator for preprocessing/postprocessing
+        """
+        self.adapter = adapter
+        self.translator = translator
+
+    def predict(self, input_data: Any) -> ObjectDetectionResult:  # noqa: A003
+        """Perform object detection on the input image.
+
+        Args:
+            input_data: Image in various formats (PIL, numpy, path, bytes)
+
+        Returns:
+            ObjectDetectionResult with detected objects
+        """
+        request = self.translator.preprocess(input_data)
+        response = self.adapter.infer(request)
+        return self.translator.postprocess(response)
+
+
+class ObjectDetectionBuilder(InferenceBuilder):
+    """Task-specific builder for object detection inference.
+
+    Provides a fluent, natural API for object detection:
+        builder.image(my_image).confidence(0.5).run()
+
+    Example:
+        client = InferenceClient(adapter, endpoint)
+        result = (client.detect_object()
+                       .with_model("yolov8")
+                       .image("photo.jpg")
+                       .confidence(0.6)
+                       .run())
+    """
+
+    def __init__(self):
+        """Initialize the object detection builder."""
+        super().__init__()
+        self._image_input: Any = None
+        self._confidence_threshold: float = 0.0
+        self._filter_labels: list[str] | None = None
+
+    def image(self, image: Any) -> "ObjectDetectionBuilder":
+        """Set the input image for detection.
+
+        Args:
+            image: Image in various formats (PIL Image, numpy array, file path, bytes)
+
+        Returns:
+            Self for method chaining
+        """
+        self._image_input = image
+        return self
+
+    def confidence(self, threshold: float) -> "ObjectDetectionBuilder":
+        """Set minimum confidence threshold for detections.
+
+        Args:
+            threshold: Minimum confidence score (0-1)
+
+        Returns:
+            Self for method chaining
+        """
+        if not 0 <= threshold <= 1:
+            raise ValueError("Confidence threshold must be between 0 and 1")
+        self._confidence_threshold = threshold
+        return self
+
+    def labels(self, labels: list[str]) -> "ObjectDetectionBuilder":
+        """Filter detections to only include specified labels.
+
+        Args:
+            labels: List of labels to include
+
+        Returns:
+            Self for method chaining
+        """
+        self._filter_labels = labels
+        return self
+
+    def run(self) -> ObjectDetectionResult:
+        """Execute the object detection inference.
+
+        Returns:
+            ObjectDetectionResult with detected objects
+
+        Raises:
+            ValueError: If required inputs are missing
+        """
+        if self._image_input is None:
+            raise ValueError("Image input is required. Call .image() first.")
+
+        predictor = self.build_predictor()
+        result = predictor.predict(self._image_input)
+
+        if self._confidence_threshold > 0:
+            result = result.filter_by_confidence(self._confidence_threshold)
+
+        if self._filter_labels:
+            result = result.filter_by_label(self._filter_labels)
+
+        return result
+
+    def build_predictor(self) -> Predictor[Any, ObjectDetectionResult]:
+        """Build the predictor for object detection.
+
+        Returns:
+            ObjectDetectionPredictor instance
+
+        Raises:
+            ValueError: If adapter or translator 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, DefaultObjectDetectionTranslator)
+            else DefaultObjectDetectionTranslator()
+        )
+
+        return ObjectDetectionPredictor(
+            adapter=self.oip_adapter,
+            translator=translator,
+        )
+
+    def __iter__(self) -> Generator[ObjectDetectionResult, None, None]:
+        """Streaming iteration for object detection.
+
+        Not typically used for object detection but provided for consistency.
+
+        Yields:
+            ObjectDetectionResult instances
+        """
+        raise NotImplementedError(
+            "Streaming is not supported for object detection tasks"
+        )
+
+    def __next__(self) -> ObjectDetectionResult:
+        """Return the next streaming result.
+
+        Not typically used for object detection but provided for Iterator protocol.
+
+        Returns:
+            ObjectDetectionResult instance
+
+        Raises:
+            NotImplementedError: Streaming is not supported for object detection
+        """
+        raise NotImplementedError(
+            "Streaming is not supported for object detection tasks"
+        )

aissemble_inference_core/client/builder/raw_inference_builder.py

@@ -0,0 +1,95 @@
+###
+# #%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 typing import Dict, Any
+
+
+class RawInferenceBuilder:
+    """A minimal, non-fluent interface for directly supplying raw tensors and parameters to an inference request.
+
+    This class is intentionally designed to be "ugly" and low-level compared to higher-level task-specific builders.
+    Its purpose is to support rare cases where pre-defined abstractions do not suffice (e.g., custom model signatures
+    or experimental tasks). Use of this class should be considered a signal that a new, higher-level abstraction
+    specific to the task or model should be contributed upstream or maintained in the project.
+
+    The interface is deliberately non-fluent: each configuration method returns ``None`` rather than ``self``,
+    discouraging method chaining and accidental use in place of more ergonomic APIs.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty raw inference request builder."""
+        self._inputs: Dict[str, Any] = {}
+        self._parameters: Dict[str, Any] = {}
+
+    def inputs(self, tensors: Dict[str, Any]) -> None:
+        """Set the raw input tensors for the inference request.
+
+        Args:
+            tensors: A mapping of input names to tensor objects (or compatible representations such as NumPy arrays,
+                PyTorch tensors, TensorFlow tensors, etc.). The exact type requirements depend on the backend
+                implementation.
+
+        Returns:
+            None. This method intentionally does not support fluent chaining.
+        """
+        if not isinstance(tensors, dict):
+            raise TypeError(
+                "tensors must be a dictionary mapping input names to tensor objects"
+            )
+        self._inputs = tensors.copy()
+
+    def parameters(self, parameters: Dict[str, Any]) -> None:
+        """Set optional inference parameters (e.g., temperature, top_k, etc.).
+
+        Args:
+            parameters: A mapping of parameter names to their values. Meaning and supported keys are model-specific.
+
+        Returns:
+            None. This method intentionally does not support fluent chaining.
+        """
+        if not isinstance(parameters, dict):
+            raise TypeError("parameters must be a dictionary")
+        self._parameters = parameters.copy()
+
+    def run(self) -> Dict[str, Any]:
+        """Execute the inference request using the configured raw inputs and parameters.
+
+        This method delegates to the underlying client/runner implementation (assumed to be available
+        in the broader library context).
+
+        Returns:
+            The raw model outputs, typically a dictionary mapping output names to tensor-like objects.
+
+        Raises:
+            RuntimeError: If the request cannot be executed (e.g., missing client context, network error, etc.).
+            NotImplementedError: Placeholder until the actual execution logic is wired in by the library.
+        """
+        # Placeholder implementation – actual execution will be provided by integration with the client
+        raise NotImplementedError(
+            "RawInferenceBuilder.run() is not yet implemented. "
+            "This method should be overridden or wired to the inference client in the final library."
+        )
+
+    # Optional helper for inspection/debugging
+    def _get_request_payload(self) -> Dict[str, Any]:
+        """Internal helper to retrieve the current payload (used by tests or client integration)."""
+        return {
+            "inputs": self._inputs,
+            "parameters": self._parameters,
+        }