maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/learn/contrib/lightgbm/dataset.py

@@ -0,0 +1,153 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.
+
+from typing import List
+
+from .... import opcodes
+from ....core import EntityData
+from ....core.entity.output_types import get_output_types
+from ....core.operator.base import Operator
+from ....core.operator.core import TileableOperatorMixin
+from ....dataframe.core import DATAFRAME_TYPE
+from ....serialization.serializables import BoolField, KeyField, ListField
+from ....serialization.serializables.field import AnyField
+from ....tensor import tensor as astensor
+from ....tensor.core import TENSOR_TYPE
+from ....typing_ import TileableType
+from ...utils import convert_to_tensor_or_dataframe
+
+
+class ToLGBMDataset(Operator, TileableOperatorMixin):
+    _op_type_ = opcodes.TO_LGBM_DATASET
+
+    data = KeyField("data", default=None)
+    label = KeyField("label", default=None)
+    reference = KeyField("reference", default=None)
+    weight = KeyField("weight", default=None)
+    init_score = KeyField("init_score", default=None)
+    group = AnyField("group", default=None)
+    feature_name = ListField("feature_name", default=None)
+    categorical_feature = ListField("categorical_feature", default=None)
+    params = AnyField("params", default=None)
+    free_raw_data = BoolField("free_raw_data", default=None)
+    position = AnyField("position", default=None)
+    # if to collocate the data, label and weight
+    collocate = BoolField("collocate", default=False)
+
+    @property
+    def output_limit(self):
+        if self.collocate:
+            return 1 + sum(bool(x) for x in [self.label, self.weight, self.init_score])
+        return 1
+
+    @classmethod
+    def _set_inputs(cls, op: "ToLGBMDataset", inputs: List[EntityData]):
+        super()._set_inputs(op, inputs)
+        if op.data is not None:
+            op.data = op._inputs[0]
+        has_label = op.label is not None
+        if has_label:
+            op.label = op._inputs[1]
+        if op.weight is not None:
+            i = 1 if not has_label else 2
+            op.weight = op._inputs[i]
+        if op.init_score is not None:
+            op.init_score = op._inputs[-1]
+
+    @staticmethod
+    def _get_kw(obj):
+        if isinstance(obj, TENSOR_TYPE):
+            return {"shape": obj.shape, "dtype": obj.dtype, "order": obj.order}
+        else:
+            return {
+                "shape": obj.shape,
+                "dtypes": obj.dtypes,
+                "index_value": obj.index_value,
+                "columns_value": obj.columns_value,
+            }
+
+    def __call__(self):
+        inputs = [self.data]
+        kw = self._get_kw(self.data)
+        if self.label is not None:
+            inputs.append(self.label)
+        if self.weight is not None:
+            inputs.append(self.weight)
+        if self.init_score is not None:
+            inputs.append(self.init_score)
+
+        return self.new_tileable(inputs, **kw)
+
+
+def check_data(data):
+    data = convert_to_tensor_or_dataframe(data)
+    if data.ndim != 2:
+        raise ValueError(f"Expecting 2-d data, got: {data.ndim}-d")
+
+    return data
+
+
+def check_array_like(y: TileableType, name: str) -> TileableType:
+    if y is None:
+        return
+    y = convert_to_tensor_or_dataframe(y)
+    if isinstance(y, DATAFRAME_TYPE):
+        y = y.iloc[:, 0]
+    return astensor(y)
+
+
+def to_lgbm_dataset(
+    data,
+    label=None,
+    reference=None,
+    weight=None,
+    group=None,
+    init_score=None,
+    feature_name="auto",
+    categorical_feature="auto",
+    params=None,
+    free_raw_data=True,
+    position=None,
+):
+    data = check_data(data)
+    label = check_array_like(label, "label")
+    weight = check_array_like(weight, "weight")
+    init_score = check_array_like(init_score, "init_score")
+
+    if weight is not None and weight.ndim > 1:
+        raise ValueError("weight must be 1-dimensional")
+
+    # If not multiple outputs, try to collect the chunks on same worker into one
+    # to feed the data into LightGBM for training.
+    op = ToLGBMDataset(
+        data=data,
+        label=label,
+        reference=reference,
+        weight=weight,
+        group=group,
+        init_score=init_score,
+        feature_name=None if feature_name == "auto" else feature_name,
+        categorical_feature=None
+        if categorical_feature == "auto"
+        else categorical_feature,
+        params=params,
+        free_raw_data=free_raw_data,
+        position=position,
+        gpu=data.op.gpu,
+        _output_types=get_output_types(data),
+    )
+    return op()
+
+
+Dataset = to_lgbm_dataset

maxframe/learn/contrib/lightgbm/regressor.py

@@ -0,0 +1,29 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.
+
+from ..utils import make_import_error_func
+from .core import LGBMScikitLearnBase
+
+try:
+    import lightgbm
+except ImportError:
+    lightgbm = None
+
+
+if not lightgbm:
+    LGBMRegressor = make_import_error_func("lightgbm")
+else:
+
+    class LGBMRegressor(LGBMScikitLearnBase, lightgbm.LGBMRegressor):
+        _default_objective = "regression"

maxframe/learn/contrib/lightgbm/tests/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.

maxframe/learn/contrib/lightgbm/tests/test_callback.py

@@ -0,0 +1,58 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.
+
+import inspect
+
+import pytest
+
+from ..callback import (
+    EarlyStoppingCallback,
+    LGBMTrainingCallback,
+    early_stopping,
+    reset_parameter,
+)
+
+try:
+    from lightgbm.callback import _EarlyStoppingCallback
+except ImportError:
+    try:
+        from lightgbm.callback import early_stopping as _EarlyStoppingCallback
+    except ImportError:
+        pytestmark = pytest.mark.skip("Need lightgbm to run the test")
+
+
+def test_lgbm_training_callbacks():
+    early_stopping_cb = early_stopping(stopping_rounds=5)
+    assert not early_stopping_cb.has_custom_code()
+
+    local_early_stopping_cb = early_stopping_cb.to_local()
+    if isinstance(_EarlyStoppingCallback, type):
+        assert isinstance(local_early_stopping_cb, _EarlyStoppingCallback)
+        assert local_early_stopping_cb.stopping_rounds == 5
+    else:
+        assert local_early_stopping_cb.__qualname__.startswith(
+            _EarlyStoppingCallback.__name__
+        )
+        cb_vars = inspect.getclosurevars(local_early_stopping_cb).nonlocals
+        assert cb_vars["stopping_rounds"] == 5
+
+    rmt_early_stopping_cb = LGBMTrainingCallback.from_local(local_early_stopping_cb)
+    assert isinstance(rmt_early_stopping_cb, EarlyStoppingCallback)
+    assert rmt_early_stopping_cb.stopping_rounds == 5
+
+    lr_sch_cb = reset_parameter(a=[0.5, 0.4, 0.1])
+    assert not lr_sch_cb.has_custom_code()
+
+    lr_sch_cb = reset_parameter(a=lambda x: x * 0.1)
+    assert lr_sch_cb.has_custom_code()

maxframe/learn/contrib/llm/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.
+
+from . import models, multi_modal, text
+
+del models

maxframe/learn/contrib/llm/core.py

@@ -0,0 +1,105 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.
+
+from typing import Any, Dict
+
+import numpy as np
+import pandas as pd
+
+from ....core.entity.output_types import OutputType
+from ....core.operator.base import Operator
+from ....core.operator.core import TileableOperatorMixin
+from ....dataframe.operators import DataFrameOperatorMixin
+from ....dataframe.utils import parse_index
+from ....serialization.serializables import Int32Field
+from ....serialization.serializables.core import Serializable
+from ....serialization.serializables.field import (
+    AnyField,
+    BoolField,
+    DictField,
+    StringField,
+)
+
+
+class LLM(Serializable):
+    name = StringField("name", default=None)
+
+    def validate_params(self, params: Dict[str, Any]):
+        pass
+
+
+class LLMTaskOperator(Operator, DataFrameOperatorMixin):
+    task = AnyField("task", default=None)
+    model = AnyField("model", default=None)
+    params = DictField("params", default=None)
+    running_options: Dict[str, Any] = DictField("running_options", default=None)
+    timeout = Int32Field("timeout", default=None)
+
+    def __init__(self, output_types=None, **kw):
+        if output_types is None:
+            output_types = [OutputType.dataframe]
+
+        running_options = kw.pop("running_options", {})
+        self._setup_default_gu_quota(running_options)
+
+        super().__init__(
+            _output_types=output_types, running_options=running_options, **kw
+        )
+
+    @staticmethod
+    def _setup_default_gu_quota(running_options):
+        from .... import options
+
+        running_options["gu_quota"] = running_options.get(
+            "gu_quota", options.session.gu_quota_name
+        )
+        if running_options["gu_quota"] is not None and not isinstance(
+            running_options["gu_quota"], str
+        ):
+            raise TypeError("gu_quota must be a string")
+        return running_options
+
+    def get_output_dtypes(self) -> Dict[str, np.dtype]:
+        raise NotImplementedError
+
+    def __call__(self, data, index=None):
+        outputs = self.get_output_dtypes()
+        col_name = list(outputs.keys())
+        columns = parse_index(pd.Index(col_name), store_data=True)
+        out_dtypes = pd.Series(list(outputs.values()), index=col_name)
+        index_value = index or data.index_value
+
+        return self.new_dataframe(
+            inputs=[data],
+            shape=(np.nan, len(col_name)),
+            index_value=index_value,
+            columns_value=columns,
+            dtypes=out_dtypes,
+        )
+
+
+class LLMTextGenOperator(LLMTaskOperator, TileableOperatorMixin):
+    prompt_template = AnyField("prompt_template", default=None)
+
+    def get_output_dtypes(self) -> Dict[str, np.dtype]:
+        return {"response": np.dtype("O"), "success": np.dtype("bool")}
+
+
+class LLMTextEmbeddingOp(LLMTaskOperator, TileableOperatorMixin):
+    dimensions = Int32Field("dimensions", default=None)
+    encoding_format = StringField("encoding_format", default=None)
+    simple_output = BoolField("simple_output", default=False)
+
+    def get_output_dtypes(self) -> Dict[str, np.dtype]:
+        return {"response": np.dtype("O"), "success": np.dtype("bool")}

maxframe/learn/contrib/llm/deploy/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.

maxframe/learn/contrib/llm/deploy/config.py

@@ -0,0 +1,221 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# 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.
+
+from copy import deepcopy
+from typing import Any, Dict, List, Optional, Union
+
+from .....protocol import Serializable
+from .....serialization.serializables import StringField
+from .....serialization.serializables.field import (
+    DictField,
+    EnumField,
+    Int32Field,
+    ListField,
+)
+from .....serialization.serializables.field_type import FieldTypes
+from .framework import InferenceFrameworkEnum
+
+
+class ModelDeploymentConfig(Serializable):
+    """
+    Model deployment configuration for extending MaxFrame with custom models.
+
+    This configuration is designed for users who need to deploy models that are not
+    available within MaxFrame's built-in model offerings. It provides a way to specify
+    custom deployment solutions by informing each MaxFrame worker which framework to use,
+    which model path to load, and how to load it.
+
+    The configuration assumes that models are already set up in the container image or
+    mounted paths, and uses the current deploy_config to load them. Users are responsible
+    for ensuring the runtime environment state and compatibility.
+
+    Parameters
+    ----------
+    model_name: str
+        The name of the model.
+    model_file: str
+        The file path of the model.
+    inference_framework_type: InferenceFrameworkEnum
+        The inference framework of the model.
+    required_resource_files: List[Union[str, Any]]
+        The required resource files of the model.
+    load_params: Dict[str, Any]
+        The load params of the model.
+    required_cpu: int
+        The required cpu of the model.
+    required_memory: int
+        The required memory of the model.
+    required_gu: int
+        The required gu of the model.
+    required_gpu_memory: int
+        The required gpu memory of the model.
+    device: str
+        The device of the model. One of "cpu" or "cuda".
+    properties: Dict[str, Any]
+        The properties of the model.
+    tags: List[str]
+        The tags of the model.
+
+    Notes
+    -----
+    - Preview version for model deployments, all fields could be changed in the future.
+
+    **User Responsibility Notice**: Users must have a complete understanding of what
+    they are computing and ensure they fully comprehend the implications of their
+    configuration choices. You are responsible for:
+
+    * Ensuring model compatibility with the specified inference framework
+    * Verifying that model files exist and are accessible in the runtime environment
+    * Confirming that resource requirements (CPU, memory, GPU) are adequate
+    * Validating that all dependencies and libraries are properly installed
+    * Understanding the computational behavior and characteristics of your chosen model
+
+    Examples
+    --------
+    >>> from maxframe.learn.contrib.llm.deploy.config import ModelDeploymentConfig
+    >>> from maxframe.learn.contrib.llm.deploy.framework import InferenceFrameworkEnum
+    >>> from maxframe.learn.contrib.llm.models.managed import ManagedTextGenLLM
+
+    >>> # Configure model deployment with VLLM framework
+    >>> model_config = ModelDeploymentConfig(
+    ...     # Path to the model files (assumed to be available in container/mount)
+    ...     model_file="/models/Qwen3-4B-Instruct-2507-FP8",
+    ...     # Use VLLM serving framework for text generation
+    ...     inference_framework_type=InferenceFrameworkEnum.VLLM_SERVE_TEXT,
+    ...     # Framework-specific loading parameters
+    ...     load_params={
+    ...         "max_context_tokens": 4096,  # Maximum context length for the model
+    ...         "max_startup_wait_seconds": 600  # Max wait time for model startup
+    ...     },
+    ...     # Target device for inference
+    ...     device="cuda",
+    ...     # Resource requirements (2 GPU units)
+    ...     required_gu=2,
+    ...     # Model tags for capabilities
+    ...     tags=["text-generation"],
+    ... )
+
+    >>> # Create managed LLM instance with the deployment configuration
+    >>> llm = ManagedTextGenLLM(name="my-model", deploy_config=model_config)
+    >>> # Generate text using the deployed model.
+    >>> result_df = llm.generate(
+    ...     df,  # Input DataFrame containing prompts
+    ...     prompt_template=messages,  # Template for formatting prompts
+    ...     running_options={
+    ...         "max_context_tokens": 4096,  # Runtime context limit
+    ...     },
+    ...     params={
+    ...         "temperature": 0.7,  # Sampling temperature
+    ...         "max_tokens": 2048  # Maximum tokens to generate
+    ...     },
+    ... )
+
+    To make this model config working with the ManagedTextGenLLM,
+    you need to provide a custom image with the required dependencies and model files.
+
+    """
+
+    model_name: str = StringField("model_name")
+    model_file: str = StringField("model_file")
+    inference_framework_type: InferenceFrameworkEnum = EnumField(
+        "inference_framework_type", enum_type=InferenceFrameworkEnum
+    )
+    required_resource_files: List[Union[str, Any]] = ListField(
+        "required_resource_files", field_type=FieldTypes.any, default_factory=list
+    )
+    load_params: Dict[str, Any] = DictField(
+        "load_params",
+        key_type=FieldTypes.string,
+        value_type=FieldTypes.any,
+        default_factory=dict,
+    )
+    required_cpu: Optional[int] = Int32Field("required_cpu", default=None)
+    required_memory: Optional[int] = Int32Field("required_memory", default=None)
+    required_gu: Optional[int] = Int32Field("required_gu", default=None)
+    required_gpu_memory: Optional[int] = Int32Field("required_gpu_memory", default=None)
+    device: str = StringField("device")
+    properties: Dict[str, Any] = DictField(
+        "properties",
+        key_type=FieldTypes.string,
+        value_type=FieldTypes.any,
+        default_factory=dict,
+    )
+    tags: List[str] = ListField(
+        "tags",
+        field_type=FieldTypes.string,
+        default_factory=list,
+    )
+
+    def is_reasoning_model(self):
+        if self.properties is None:
+            return False
+        return self.properties.get("reasoning_model", False)
+
+    def copy(self) -> "ModelDeploymentConfig":
+        return deepcopy(self)
+
+    def __eq__(self, other):
+        if not isinstance(other, ModelDeploymentConfig):
+            return False
+
+        return (
+            self.model_name == other.model_name
+            and self.model_file == other.model_file
+            and self.inference_framework_type == other.inference_framework_type
+            and self.required_resource_files == other.required_resource_files
+            and self.load_params == other.load_params
+            and self.required_cpu == other.required_cpu
+            and self.required_memory == other.required_memory
+            and self.required_gu == other.required_gu
+            and self.required_gpu_memory == other.required_gpu_memory
+            and self.device == other.device
+            and self.properties == other.properties
+            and self.tags == other.tags
+        )
+
+    def __hash__(self):
+        return hash(
+            (
+                self.model_name,
+                self.model_file,
+                self.inference_framework_type,
+                self.required_resource_files,
+                self.load_params,
+                self.required_cpu,
+                self.required_memory,
+                self.required_gu,
+                self.required_gpu_memory,
+                self.device,
+                self.properties,
+                self.tags,
+            )
+        )
+
+    def check_validity(self):
+        required_fields = [
+            "model_name",
+            "model_file",
+            "inference_framework_type",
+            "device",
+        ]
+        for field in required_fields:
+            if getattr(self, field) is None:
+                raise ValueError(f"{field} is required")
+
+        one_of_fields = ["required_cpu", "required_gu"]
+        if not any(getattr(self, field) is not None for field in one_of_fields):
+            raise ValueError(f"At least one of {one_of_fields} is required")
+
+        if not self.tags:
+            raise ValueError("tags is required")