JSTprove 1.0.0__py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

python/core/circuits/errors.py

@@ -0,0 +1,188 @@
+# python/core/utils/exceptions.py
+from __future__ import annotations
+
+from python.core.utils.helper_functions import RunType
+
+
+class CircuitError(Exception):
+    """
+    Base class for all circuit-related errors.
+
+    Attributes:
+        message (str): Human-readable description of the error.
+        details (dict): Optional structured details for debugging or logging.
+    """
+
+    def __init__(
+        self: CircuitError,
+        message: str,
+        details: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+    def __str__(self: CircuitError) -> str:
+        parts = [self.message]
+        if self.details:
+            parts.append(f"Details: {self.details}")
+
+        # Show the chained exception cause if present
+        if self.__cause__ is not None:
+            parts.append(f"Caused by: {self.__cause__}")
+        return " | ".join(parts)
+
+
+class CircuitConfigurationError(CircuitError):
+    """
+    Raised when circuit is not properly configured (missing or invalid attributes).
+
+    Attributes:
+        missing_attributes (list): List of missing attributes (if known).
+    """
+
+    def __init__(
+        self: CircuitConfigurationError,
+        message: str | None = None,
+        missing_attributes: list | None = None,
+        details: dict | None = None,
+    ) -> None:
+        if missing_attributes and not message:
+            message = (
+                "Circuit class (python) is misconfigured."
+                f" Missing required attributes: {', '.join(missing_attributes)}"
+            )
+        elif not message:
+            message = "Circuit is misconfigured."
+        super().__init__(message, details)
+        self.missing_attributes = missing_attributes or []
+
+
+class CircuitInputError(CircuitError):
+    """
+    Raised when input validation fails (missing or invalid values).
+
+    Attributes:
+        parameter (str): Name of the problematic parameter (if known).
+        expected (str): Expected type or value description (optional).
+        actual (any): Actual value encountered (optional).
+    """
+
+    def __init__(  # noqa: PLR0913
+        self: CircuitInputError,
+        message: str | None = None,
+        parameter: str | None = None,
+        expected: str | None = None,
+        actual: any | None = None,
+        details: dict | None = None,
+    ) -> None:
+        if parameter and not message:
+            msg_parts = [f"Issue with parameter '{parameter}'."]
+            if expected:
+                msg_parts.append(f"Expected: {expected}.")
+            if actual is not None:
+                msg_parts.append(f"Got: {actual!r}.")
+            message = " ".join(msg_parts)
+        elif not message:
+            message = "Invalid circuit class (python) input."
+        super().__init__(message, details)
+        self.parameter = parameter
+        self.expected = expected
+        self.actual = actual
+
+
+class CircuitRunError(CircuitError):
+    """
+    Raised when an operation (compile, prove, verify, etc.) fails.
+
+    Attributes:
+        operation (str): Name of the operation that failed (if known).
+    """
+
+    def __init__(
+        self: CircuitRunError,
+        message: str | None = None,
+        operation: RunType | None = None,
+        details: dict | None = None,
+    ) -> None:
+        operations_to_name = {
+            RunType.COMPILE_CIRCUIT: "Compile",
+            RunType.GEN_VERIFY: "Verify",
+            RunType.PROVE_WITNESS: "Prove",
+            RunType.GEN_WITNESS: "Witness",
+        }
+        if operation and not message:
+            message = f"Circuit operation '{operations_to_name.get(operation)}' failed."
+        elif not message:
+            message = "Circuit run failed."
+        super().__init__(message, details)
+        self.operation = operation
+
+
+class CircuitFileError(CircuitError):
+    """
+    Raised when file-related operations fail
+    (e.g., reading, writing, or accessing files).
+
+    Attributes:
+        file_path (str): Path to the problematic file (if known).
+    """
+
+    def __init__(
+        self: CircuitFileError,
+        message: str | None = None,
+        file_path: str | None = None,
+        details: dict | None = None,
+    ) -> None:
+        if file_path and not message:
+            message = f"File operation failed for path: {file_path}"
+        elif not message:
+            message = "Circuit file operation failed."
+        super().__init__(message, details)
+        self.file_path = file_path
+
+
+class CircuitProcessingError(CircuitError):
+    """
+    Raised when data processing operations fail
+    (e.g., tensor operations, scaling, reshaping).
+
+    Attributes:
+        operation (str): Name of the operation that failed (if known).
+        data_type (str): Type of data being processed (if known).
+    """
+
+    def __init__(
+        self: CircuitProcessingError,
+        message: str | None = None,
+        operation: str | None = None,
+        data_type: str | None = None,
+        details: dict | None = None,
+    ) -> None:
+        if operation and not message:
+            message = f"Data processing failed during {operation}."
+        elif not message:
+            message = "Circuit data processing failed."
+        super().__init__(message, details)
+        self.operation = operation
+        self.data_type = data_type
+
+
+class WitnessMatchError(CircuitError):
+    """
+    Raised when input validation fails (missing or invalid values).
+
+    Attributes:
+        parameter (str): Name of the problematic parameter (if known).
+        expected (str): Expected type or value description (optional).
+        actual (any): Actual value encountered (optional).
+    """
+
+    def __init__(
+        self: CircuitInputError,
+        message: str | None = None,
+    ) -> None:
+        common_message = "Witness does not match provided inputs and outputs!"
+        if message:
+            common_message += f" {message}"
+        super().__init__(common_message)

python/core/circuits/zk_model_base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from python.core.circuits.base import Circuit
+from python.core.utils.general_layer_functions import GeneralLayerFunctions
+
+
+class ZKModelBase(GeneralLayerFunctions, Circuit):
+    """
+    Abstract base class for Zero-Knowledge (ZK) ML models.
+
+    This class provides a standard interface for ZK circuit ML models.
+    Instantiates Circuit and GeneralLayerFunctions.
+
+    Subclasses must implement the constructor to define the model's
+    architecture, layers, and circuit details.
+    """
+
+    def __init__(self: ZKModelBase) -> None:
+        """Initialize the ZK model. Must be overridden by subclasses
+
+        Raises:
+            NotImplementedError: If called on the base class directly.
+        """
+        msg = "Must implement __init__"
+        raise NotImplementedError(msg)

python/core/model_processing/converters/base.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import TYPE_CHECKING, Optional, Union
+
+if TYPE_CHECKING:
+    import numpy as np
+    import onnx
+    import torch
+
+
+class ModelType(Enum):
+    ONNX = "ONNX"
+
+
+ONNXLayerDict = dict[
+    str,
+    Union[int, str, list[str], dict[str, list[int]], Optional[list], Optional[dict]],
+]
+
+CircuitParamsDict = dict[str, Union[int, dict[str, bool]]]
+
+
+class ModelConverter(ABC):
+    """
+    Abstract base class for AI model conversion, quantization, and I/O operations.
+
+    This class defines the required interface for implementing a model converter
+    that can handle:
+    - Saving/loading models in various formats
+    - Quantizing models
+    - Extracting model weights
+    - Generating model outputs
+
+    Concrete subclasses must implement all abstract methods to provide
+    model-specific conversion logic.
+    """
+
+    @abstractmethod
+    def save_model(self: ModelConverter, file_path: str) -> None:
+        """Save the current model to the specified file path.
+
+        Args:
+            file_path (str): Path to save the model file.
+        """
+
+    @abstractmethod
+    def load_model(
+        self: ModelConverter,
+        file_path: str,
+        model_type: ModelType | None = None,
+    ) -> onnx.ModelProto:
+        """
+        Load a model from a file.
+
+        Args:
+            file_path (str): Path to the model file.
+            model_type (Optional[ModelType]):
+                Optional identifier for the model format/type.
+                Useful if multiple formats are supported.
+
+        Returns:
+            onnx.ModelProto: The loaded model.
+        """
+
+    @abstractmethod
+    def save_quantized_model(self: ModelConverter, file_path: str) -> None:
+        """Save the quantized version of the model to the specified file path.
+
+        Args:
+            file_path (str): Path to save the quantized model file.
+        """
+
+    @abstractmethod
+    def load_quantized_model(self: ModelConverter, file_path: str) -> None:
+        """Load a quantized model from a file.
+
+        Args:
+            file_path (str): Path to the quantized model file.
+        """
+
+    @abstractmethod
+    def quantize_model(
+        self: ModelConverter,
+        model: onnx.ModelProto,
+        scale_base: int,
+        scale_exponent: int,
+        rescale_config: dict | None = None,
+    ) -> onnx.ModelProto:
+        """Quantize a model with a given scale and optional rescaling configuration.
+
+        Args:
+            model (onnx.ModelProto): The model instance to quantize.
+            scale_base (int): Base for fixed-point scaling (e.g., 2).
+            scale_exponent (int): Quantization scale factor.
+            rescale_config (Optional[dict], optional):
+                Configuration for rescaling layers or weights during quantization.
+                Defaults to None.
+
+        Returns:
+            onnx.ModelProto: The quantized model.
+        """
+
+    @abstractmethod
+    def get_weights(
+        self: ModelConverter,
+    ) -> tuple[
+        dict[str, list[ONNXLayerDict]],
+        dict[str, list[ONNXLayerDict]],
+        CircuitParamsDict,
+    ]:
+        """Retrieve the model's weights.
+
+        Returns:
+            tuple[dict[str, list[ONNXLayerDict]],
+            dict[str, list[ONNXLayerDict]], CircuitParamsDict]:
+                A tuple ``(architecture, weights, circuit_params)``:
+                - ``architecture``: dict with serialized ``architecture`` layers.
+                - ``weights``: dict containing ``w_and_b`` (serialized tensors).
+                - ``circuit_params``: dict containing scaling parameters and
+                  ``rescale_config``.
+        """
+
+    @abstractmethod
+    def get_model_and_quantize(self: ModelConverter) -> None:
+        """Retrieve the model and quantize it in a single operation."""
+
+    @abstractmethod
+    def get_outputs(
+        self: ModelConverter,
+        inputs: np.ndarray | torch.Tensor,
+    ) -> list[np.ndarray]:
+        """
+        Run inference on the given inputs and return model outputs.
+
+        Args:
+            inputs (np.ndarray | torch.Tensor):
+                Input data in the format expected by the model.
+
+        Returns:
+            list[np.ndarray]: Model outputs after processing the inputs.
+        """