mlbundle 0.1.0a1__py3-none-any.whl

mlbundle/__init__.py

@@ -0,0 +1,82 @@
+"""Pickle-free model bundles."""
+
+from importlib.metadata import version as _version
+
+from .claims import ModelClaims
+from .contract import (
+    FORMAT_NAME,
+    FORMAT_VERSION,
+    FeatureOrigin,
+    Library,
+    MemberName,
+    ModelKind,
+    SerializationFormat,
+)
+from .environment import OnnxInfo, Opset, TrainingEnvironment
+from .errors import (
+    AdapterNotImplementedError,
+    ClaimMismatchError,
+    IntegrityMismatchError,
+    InvalidContainerError,
+    InvalidJSONError,
+    InvalidManifestError,
+    InvalidModelError,
+    InvalidSamplesError,
+    InvalidSchemaError,
+    LimitExceededError,
+    MissingOptionalDependencyError,
+    MLBundleError,
+    PredictionInputError,
+    UnsupportedFormatVersionError,
+    UnsupportedModelError,
+)
+from .inspection import inspect
+from .integrity import IntegrityRecord
+from .limits import ArchiveLimits
+from .manifest import FeatureInfo, Manifest, MemberReferences, ModelInfo, TargetInfo
+from .model_io import export, load
+from .results import LoadedBundle, MetadataView
+
+__version__ = _version("mlbundle")
+
+__all__ = [
+    "FORMAT_NAME",
+    "FORMAT_VERSION",
+    "AdapterNotImplementedError",
+    "ArchiveLimits",
+    "ClaimMismatchError",
+    "FeatureInfo",
+    "FeatureOrigin",
+    "IntegrityMismatchError",
+    "IntegrityRecord",
+    "InvalidContainerError",
+    "InvalidJSONError",
+    "InvalidManifestError",
+    "InvalidModelError",
+    "InvalidSamplesError",
+    "InvalidSchemaError",
+    "Library",
+    "LimitExceededError",
+    "LoadedBundle",
+    "MLBundleError",
+    "Manifest",
+    "MemberName",
+    "MemberReferences",
+    "MetadataView",
+    "MissingOptionalDependencyError",
+    "ModelClaims",
+    "ModelInfo",
+    "ModelKind",
+    "OnnxInfo",
+    "Opset",
+    "PredictionInputError",
+    "SerializationFormat",
+    "TargetInfo",
+    "TrainingEnvironment",
+    "UnsupportedFormatVersionError",
+    "UnsupportedModelError",
+    "__version__",
+    "export",
+    "inspect",
+    "load",
+]

mlbundle/_base.py

@@ -0,0 +1,19 @@
+"""Shared strict model configuration and bounded field types."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, StringConstraints
+
+ShortString = Annotated[str, StringConstraints(min_length=1, max_length=256)]
+Name = Annotated[str, StringConstraints(min_length=1, max_length=1024)]
+
+
+class ContractModel(BaseModel):
+    model_config = ConfigDict(
+        strict=True,
+        extra="forbid",
+        frozen=True,
+        validate_default=True,
+        hide_input_in_errors=True,
+        allow_inf_nan=False,
+    )

mlbundle/_canonical_work.py

@@ -0,0 +1,67 @@
+"""Linear preflight for the expanded size/depth of native shared JSON containers."""
+
+from typing import Any
+
+from .errors import LimitExceededError
+
+_SCALARS = (str, int, float, bool, type(None))
+_NUMBERS = {int, float, bool, type(None)}
+
+
+def _sequence_cost(item):
+    # C map/set classify flat numeric arrays without Python calls per element.
+    if len(item) >= 64 and set(map(type, item)) <= _NUMBERS:
+        return 1 + 2 * len(item), ()
+    return 1, item
+
+
+def _child_cost(child: Any, measure) -> tuple[int, int]:
+    if type(child) in _SCALARS:
+        return (len(child) + 2 if type(child) is str else 1), 0
+    return measure(child)
+
+
+def _array_cost(value: Any) -> tuple[int, int, Any]:
+    return value.ndim, value.size, value.flat if value.dtype.kind == "O" else ()
+
+
+def bound_work(value: Any, max_bytes: int, max_depth: int) -> None:
+    memo: dict[int, tuple[int, int]] = {}
+    active: set[int] = set()
+
+    def measure(item):
+        array = (
+            type(item).__module__.split(".")[0] == "numpy"
+            and type(item).__name__ == "ndarray"
+        )
+        if not isinstance(item, (dict, list, tuple)) and not array:
+            return (len(item) + 2 if isinstance(item, str) else 1), 0
+        identity = id(item)
+        if identity in active:
+            raise LimitExceededError("Cyclic JSON containers exceed the nesting limit.")
+        if identity in memo:
+            return memo[identity]
+        active.add(identity)
+        depth, size = 1, 1
+        if array:
+            depth, size, children = _array_cost(item)
+        elif isinstance(item, dict):
+            size += sum(len(key) + 3 for key in item if isinstance(key, str))
+            children = item.values()
+        else:
+            size, children = _sequence_cost(item)
+        if size > max_bytes or depth > max_depth:
+            raise LimitExceededError("Expanded JSON size or depth exceeds the limit.")
+        for child in children:
+            child_size, child_depth = _child_cost(child, measure)
+            size += child_size + 1
+            depth = max(depth, child_depth + 1)
+            if size > max_bytes or depth > max_depth:
+                raise LimitExceededError(
+                    "Expanded JSON size or depth exceeds the limit."
+                )
+        active.remove(identity)
+        memo[identity] = size, depth
+        return size, depth
+
+    measure(value)

mlbundle/_catboost/__init__.py

@@ -0,0 +1,159 @@
+"""Native CBM adapter; exact CatBoost wrappers and no reader-side file I/O."""
+
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any, cast
+
+import catboost as cb
+from pydantic import JsonValue
+
+from mlbundle.canonical import canonical_value
+from mlbundle.claims import ClassLabels, ModelClaims
+from mlbundle.contract import Library, MemberName, ModelKind
+from mlbundle.declarations import ExportDeclarations
+from mlbundle.errors import InvalidModelError, MLBundleError, UnsupportedModelError
+
+from .native import decode
+from .prediction import Predictor
+from .scope import CLASSIFIERS, validate
+from .state import commitment, feature_importances, json_value, snapshot
+
+
+class Adapter:
+    library = Library.CATBOOST
+    model_member = MemberName.CBM
+
+    def recognizes(self, model: object) -> bool:
+        return isinstance(model, cb.CatBoost)
+
+    def prepare_export(self, model: Any, declarations: ExportDeclarations) -> object:
+        try:
+            validate(model)
+            if declarations.class_labels is not None:
+                raise UnsupportedModelError(
+                    reason="CatBoost already carries class labels; class_labels is unsupported."
+                )
+            self.extract_claims(model)
+            return model
+        except MLBundleError:
+            raise
+        except Exception:
+            raise UnsupportedModelError(
+                reason="CatBoost export preparation failed."
+            ) from None
+
+    def serialize(self, model: Any) -> bytes:
+        try:
+            validate(model)
+            # Public save_model accepts paths only; export owns this temporary file.
+            with TemporaryDirectory(prefix="mlbundle-catboost-") as directory:
+                path = Path(directory) / "model.cbm"
+                model.save_model(str(path), format="cbm")
+                data = path.read_bytes()
+            decode(data)
+            return data
+        except MLBundleError:
+            raise
+        except Exception:
+            raise UnsupportedModelError(
+                reason="CatBoost CBM serialization failed."
+            ) from None
+
+    def deserialize(self, data: bytes) -> object:
+        try:
+            state = decode(data)
+            cls = (
+                cb.CatBoostClassifier
+                if state.loss in CLASSIFIERS
+                else cb.CatBoostRegressor
+            )
+            # blob loading does not restore _init_params. Poisson's default predict
+            # selects Exponent from that wrapper field, so bind the validated loss.
+            model: Any = cls(loss_function=state.loss)
+            model.load_model(blob=data)
+            model._n_features_in = state.width
+            actual = snapshot(model)
+            if commitment(state) != commitment(actual):
+                raise InvalidModelError(
+                    "CatBoost state does not survive native construction."
+                )
+            validate(model)
+            return model
+        except MLBundleError:
+            raise
+        except Exception:
+            raise InvalidModelError("Invalid CatBoost CBM payload.") from None
+
+    def extract_claims(self, model: Any) -> ModelClaims:
+        try:
+            validate(model)
+            state = snapshot(model)
+            classifier = type(model) is cb.CatBoostClassifier
+            if (
+                classifier != (state.loss in CLASSIFIERS)
+                or model.n_features_in_ not in (0, state.width)
+                or model.tree_count_ != len(state.native["tree_depths"])
+            ):
+                raise InvalidModelError(
+                    "CatBoost wrapper and native dimensions or kind disagree."
+                )
+            labels = (
+                cast(ClassLabels, canonical_value([model.classes_]))
+                if classifier
+                else None
+            )
+            if classifier and (
+                labels is None
+                or len(labels[0])
+                != (state.dimension if state.loss == "MultiClass" else 2)
+            ):
+                raise InvalidModelError(
+                    "CatBoost classes and native dimensions disagree."
+                )
+            loss = model.get_params().get("loss_function")
+            if loss is not None and loss.split(":", 1)[0] != state.loss:
+                raise InvalidModelError("CatBoost wrapper and native loss disagree.")
+            return ModelClaims(
+                estimator_class=type(model).__name__,
+                kind=ModelKind.CLASSIFIER if classifier else ModelKind.REGRESSOR,
+                hyperparameters={
+                    "parameters": canonical_value(model.get_all_params()),
+                    "tree_count": model.tree_count_,
+                    "best_iteration": model.get_best_iteration(),
+                    "scale_and_bias": canonical_value(model.get_scale_and_bias()),
+                    "probability_threshold": model.get_probability_threshold()
+                    if classifier
+                    else None,
+                },
+                state_sha256=commitment(state),
+                n_features=state.width,
+                n_classes=None if labels is None else [len(labels[0])],
+                n_outputs=1,
+                feature_names=model.feature_names_,
+                feature_dtypes=None,
+                class_labels=labels,
+            )
+        except MLBundleError:
+            raise
+        except Exception:
+            raise InvalidModelError("Invalid CatBoost model claims.") from None
+
+    def extract_structure(self, model: Any) -> dict[str, JsonValue]:
+        try:
+            validate(model)
+            state = snapshot(model)
+            return cast(
+                dict[str, JsonValue],
+                {
+                    "family": "catboost",
+                    "native_model": json_value(state.native),
+                    "feature_importances": feature_importances(model, state.width),
+                },
+            )
+        except MLBundleError:
+            raise
+        except Exception:
+            raise InvalidModelError("Invalid CatBoost model structure.") from None
+
+    def predictor(self, model: object) -> Predictor:
+        return Predictor(model, self.extract_claims(model))

mlbundle/_catboost/budget.py

@@ -0,0 +1,22 @@
+"""Bound structure expansion before native parsing or allocating Python lists."""
+
+from typing import Any
+
+from mlbundle.errors import LimitExceededError
+from mlbundle.limits import STRUCTURE_BYTES
+
+
+def structure_budget(native: dict[str, Any]) -> None:
+    # Worst finite binary64 JSON token plus separator is 25 bytes. The bound
+    # intentionally rejects some compact-value models before list allocation.
+    size = 4096
+    for value in native.values():
+        if hasattr(value, "dtype"):
+            size += value.size * (25 if value.dtype.kind == "f" else 12)
+    for feature in native["float_features"]:
+        size += 256 + 6 * len(feature["name"].encode("utf-8"))
+        size += feature["borders"].size * 25
+    if size > STRUCTURE_BYTES:
+        raise LimitExceededError(
+            "CatBoost structure allocation budget exceeds the limit."
+        )

mlbundle/_catboost/flatbuffer.py

@@ -0,0 +1,104 @@
+"""Checked views of the closed CatBoost 1.2.10 CBM FlatBuffer schema."""
+
+import struct
+from typing import Any
+
+import numpy as np
+
+from mlbundle.errors import InvalidModelError
+
+
+class Buffer:
+    def __init__(self, data: memoryview) -> None:
+        self.data = data
+        self.work = 0
+
+    def span(self, position: int, size: int) -> memoryview:
+        if position < 0 or size < 0 or size > len(self.data) - position:
+            raise InvalidModelError("Truncated CatBoost CBM buffer.")
+        return self.data[position : position + size]
+
+    def number(self, position: int, fmt: str) -> Any:
+        return struct.unpack("<" + fmt, self.span(position, struct.calcsize(fmt)))[0]
+
+    def indirect(self, position: int) -> int:
+        offset = self.number(position, "I")
+        if offset < 4:
+            raise InvalidModelError("Invalid CatBoost CBM offset.")
+        target = position + offset
+        self.span(target, 4)
+        return target
+
+    def table(self, position: int, fields: int) -> "Table":
+        self.work += 1
+        if self.work > 200_000:
+            raise InvalidModelError("CatBoost CBM table work exceeds the limit.")
+        return Table(self, position, fields)
+
+    def string(self, position: int, cap: int) -> str:
+        start = self.indirect(position)
+        size = self.number(start, "I")
+        if size > cap or self.number(start + 4 + size, "B") != 0:
+            raise InvalidModelError("Invalid CatBoost CBM string length.")
+        return bytes(self.span(start + 4, size)).decode("utf-8")
+
+
+class Table:
+    def __init__(self, buffer: Buffer, position: int, fields: int) -> None:
+        self.buffer, self.position = buffer, position
+        vtable = position - buffer.number(position, "i")
+        size = buffer.number(vtable, "H")
+        self.size = buffer.number(vtable + 2, "H")
+        if size < 4 or size % 2 or size > 4 + 2 * fields or self.size < 4:
+            raise InvalidModelError("Unknown or invalid CatBoost CBM table fields.")
+        buffer.span(position, self.size)
+        buffer.span(vtable, size)
+        self.offsets = [buffer.number(vtable + i, "H") for i in range(4, size, 2)]
+        if any(offset and not 4 <= offset < self.size for offset in self.offsets):
+            raise InvalidModelError("Invalid CatBoost CBM field offset.")
+
+    def field(self, index: int, size: int = 4) -> int | None:
+        offset = self.offsets[index] if index < len(self.offsets) else 0
+        if not offset:
+            return None
+        if size > self.size - offset:
+            raise InvalidModelError("Invalid CatBoost CBM field size.")
+        return self.position + offset
+
+    def scalar(self, index: int, fmt: str, default: Any = 0) -> Any:
+        position = self.field(index, struct.calcsize(fmt))
+        return default if position is None else self.buffer.number(position, fmt)
+
+    def string(self, index: int, cap: int) -> str:
+        position = self.field(index)
+        return "" if position is None else self.buffer.string(position, cap)
+
+    def child(self, index: int, fields: int) -> "Table":
+        position = self.field(index)
+        if position is None:
+            raise InvalidModelError("Missing CatBoost CBM table.")
+        return self.buffer.table(self.buffer.indirect(position), fields)
+
+    def vector(self, index: int, dtype: str, cap: int) -> np.ndarray:
+        position = self.field(index)
+        kind = np.dtype(dtype)
+        if position is None:
+            return np.empty(0, dtype=kind)
+        start = self.buffer.indirect(position)
+        count = self.buffer.number(start, "I")
+        if count > cap:
+            raise InvalidModelError("CatBoost CBM vector count exceeds the limit.")
+        return np.frombuffer(self.buffer.span(start + 4, count * kind.itemsize), kind)
+
+    def tables(self, index: int, fields: int, cap: int) -> list["Table"]:
+        offsets = self.vector(index, "<u4", cap)
+        if not len(offsets):
+            return []
+        position = self.field(index)
+        if position is None:
+            raise InvalidModelError("Missing CatBoost CBM vector.")
+        start = self.buffer.indirect(position) + 4
+        return [
+            self.buffer.table(self.buffer.indirect(start + 4 * i), fields)
+            for i in range(len(offsets))
+        ]