fiddler-client 2.3.0.dev2__py3-none-any.whl → 2.4.0.dev1__py3-none-any.whl

fiddler3/entities/xai.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import os
+from collections import namedtuple
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Callable
+from uuid import UUID
+
+import pandas as pd
+
+from fiddler3.constants.xai import ExplainMethod
+from fiddler3.decorators import handle_api_error
+from fiddler3.schemas.xai import (
+    DatasetDataSource,
+    EventIdDataSource,
+    RowDataSource,
+    SqlSliceQueryDataSource,
+)
+from fiddler3.utils.helpers import try_series_retype
+
+
+class XaiMixin:
+    id: UUID | None
+    _client: Callable
+
+    @handle_api_error
+    def explain(  # pylint: disable=too-many-arguments
+        self,
+        input_data_source: RowDataSource | EventIdDataSource,
+        ref_data_source: DatasetDataSource | SqlSliceQueryDataSource | None = None,
+        method: ExplainMethod | str = ExplainMethod.FIDDLER_SHAP,
+        num_permutations: int | None = None,
+        ci_level: float | None = None,
+        top_n_class: int | None = None,
+    ) -> tuple:
+        """
+        Get explanation for a single observation.
+
+        :param input_data_source: DataSource for the input data to compute explanation
+            on (RowDataSource, EventIdDataSource)
+        :param ref_data_source: DataSource for the reference data to compute explanation
+            on (DatasetDataSource, SqlSliceQueryDataSource).
+            Only used for non-text models and the following methods:
+            'SHAP', 'FIDDLER_SHAP', 'PERMUTE', 'MEAN_RESET'
+        :param method: Explanation method name. Could be your custom
+            explanation method or one of the following method:
+            'SHAP', 'FIDDLER_SHAP', 'IG', 'PERMUTE', 'MEAN_RESET', 'ZERO_RESET'
+        :param num_permutations: For Fiddler SHAP, that corresponds to the number of
+            coalitions to sample to estimate the Shapley values of each single-reference
+             game. For the permutation algorithms, this corresponds to the number
+            of permutations from the dataset to use for the computation.
+        :param ci_level: The confidence level (between 0 and 1) to use for the
+            confidence intervals in Fiddler SHAP. Not used for other methods.
+        :param top_n_class: For multiclass classification models only, specifying if
+            only the n top classes are computed or all classes (when parameter is None)
+
+        :return: A named tuple with the explanation results.
+        """
+        self._check_id_attributes()
+        payload: dict[str, Any] = {
+            'model_id': self.id,
+            'input_data_source': input_data_source.dict(),
+            'explanation_type': method,
+        }
+        if ref_data_source:
+            payload['ref_data_source'] = ref_data_source.dict()
+        if num_permutations:
+            payload['num_permutations'] = num_permutations
+        if ci_level:
+            payload['ci_level'] = ci_level
+        if top_n_class:
+            payload['top_n_class'] = top_n_class
+
+        response = self._client().post(
+            url='v3/explain',
+            data=payload,
+        )
+
+        return namedtuple('Explain', response.json()['data'])(**response.json()['data'])
+
+    @handle_api_error
+    def get_fairness(
+        self,
+        data_source: DatasetDataSource | SqlSliceQueryDataSource,
+        protected_features: list[str],
+        positive_outcome: str | int | float | bool,
+        score_threshold: float | None = None,
+    ) -> tuple:
+        """
+        Get fairness analysis on a dataset or a slice.
+
+        :param data_source: DataSource for the input dataset to compute
+            fairness on (DatasetDataSource or SqlSliceQueryDataSource)
+        :param protected_features: list of protected attribute names to compute
+            Fairness analysis on
+        :param positive_outcome: name of the positive outcome to compute
+            Fairness analysis on
+        :param score_threshold: Binary threshold value (between 0 and 1). Default to 0.5
+
+        :return: A named tuple with the fairness results.
+        """
+        self._check_id_attributes()
+
+        payload: dict[str, Any] = {
+            'model_id': self.id,
+            'data_source': data_source.dict(),
+            'protected_features': protected_features,
+            'positive_outcome': positive_outcome,
+        }
+        if score_threshold:
+            payload['score_threshold'] = score_threshold
+
+        response = self._client().post(url='/v3/analytics/fairness', data=payload)
+
+        return namedtuple('Fairness', response.json()['data'])(
+            **response.json()['data']
+        )
+
+    @handle_api_error
+    def get_slice(
+        self,
+        query: str,
+        sample: bool = False,
+        max_rows: int | None = None,
+        columns: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """
+        Fetch data with slice query.
+
+        :param query: An SQL query that begins with the keyword 'SELECT'
+        :param columns: Allows caller to explicitly specify list of
+                        columns to select overriding columns selected in the query.
+        :param max_rows: Number of maximum rows to fetch
+        :param sample: Whether rows should be sample or not from the database
+
+        :return: Dataframe of the query output
+        """
+        self._check_id_attributes()
+
+        payload: dict[str, Any] = {
+            'model_id': self.id,
+            'query': query,
+            'sample': sample,
+        }
+        if max_rows:
+            payload['max_rows'] = max_rows
+        if columns:
+            payload['columns'] = columns
+
+        response = self._client().post(
+            url='/v3/slice-query/fetch',
+            data=payload,
+        )
+
+        response_dict = response.json()['data']
+
+        column_names = response_dict['metadata']['columns']
+        dtype_strings = response_dict['metadata']['dtypes']
+        df = pd.DataFrame(response_dict['rows'], columns=column_names)
+        for column_name, dtype in zip(column_names, dtype_strings):
+            df[column_name] = try_series_retype(df[column_name], dtype)
+        return df
+
+    @handle_api_error
+    def download_slice(  # pylint: disable=too-many-arguments
+        self,
+        output_dir: Path | str,
+        query: str,
+        sample: bool = False,
+        max_rows: int | None = None,
+        columns: list[str] | None = None,
+    ) -> None:
+        """
+        Download data with slice query to parquet file.
+
+        :param output_dir: Path to download the file
+        :param query: An SQL query that begins with the keyword 'SELECT'
+        :param columns: Allows caller to explicitly specify list of
+                        columns to select overriding columns selected in the query.
+        :param max_rows: Number of maximum rows to fetch
+        :param sample: Whether rows should be sample or not from the database
+        """
+        self._check_id_attributes()
+        output_dir = Path(output_dir)
+        if output_dir.exists():
+            raise ValueError(f'Output dir already exists {output_dir}')
+        payload: dict[str, Any] = {
+            'model_id': self.id,
+            'query': query,
+            'sample': sample,
+        }
+        if max_rows:
+            payload['max_rows'] = max_rows
+        if columns:
+            payload['columns'] = columns
+
+        os.makedirs(output_dir)
+        file_path = os.path.join(output_dir, 'output.parquet')
+        with self._client().post(url='/v3/slice-query/download', data=payload) as resp:
+            # Download parquet file
+            df = pd.read_parquet(BytesIO(resp.content))
+            df.to_parquet(file_path)
+
+    @handle_api_error
+    def get_mutual_info(
+        self,
+        query: str,
+        column_name: str,
+        num_samples: int | None = None,
+        normalized: bool = False,
+    ) -> dict:
+        """
+        Get mutual information.
+
+        The Mutual information measures the dependency between
+        two random variables. It's a non-negative value. If two random variables are
+        independent MI is equal to zero. Higher MI values means higher dependency.
+
+        :param query: slice query to compute Mutual information on
+        :param column_name: column name to compute mutual information with respect to
+               all the variables in the dataset.
+        :param num_samples: Number of samples to select for computation
+        :param normalized: If set to True, it will compute Normalized Mutual Information
+
+        :return: a dictionary of mutual information w.r.t the given feature
+                 for each column given
+        """
+        self._check_id_attributes()
+
+        payload: dict[str, Any] = {
+            'model_id': self.id,
+            'query': query,
+            'column_name': column_name,
+            'normalized': normalized,
+        }
+        if num_samples:
+            payload['num_samples'] = num_samples
+
+        response = self._client().post(
+            url='/v3/analytics/mutual-info',
+            data=payload,
+        )
+
+        return response.json()['data']
+
+    @handle_api_error
+    def predict(
+        self,
+        df: pd.DataFrame,
+        chunk_size: int | None = None,
+    ) -> pd.DataFrame:
+        """
+        Run model on an input dataframe.
+
+        :param df: Feature dataframe
+        :param chunk_size: Chunk size for fetching predictions
+
+        :return: Dataframe of the predictions
+        """
+        self._check_id_attributes()
+
+        payload: dict[str, Any] = {
+            'model_id': self.id,
+            'data': df.to_dict('records'),
+        }
+        if chunk_size:
+            payload['chunk_size'] = chunk_size
+
+        response = self._client().post(
+            url='/v3/predict',
+            data=payload,
+        )
+        return pd.DataFrame(response.json()['data']['predictions'])
+
+    @handle_api_error
+    def get_precomputed_feature_importance(self) -> tuple:
+        """Get precomputed feature importance for a model"""
+
+        self._check_id_attributes()
+        response = self._client().post(
+            url='/v3/analytics/feature-importance/precomputed',
+            data={'model_id': self.id},
+        )
+
+        return namedtuple('FeatureImportance', response.json()['data'])(
+            **response.json()['data']
+        )
+
+    @handle_api_error
+    def get_precomputed_feature_impact(self) -> tuple:
+        """Get precomputed feature impact for a model"""
+
+        self._check_id_attributes()
+        response = self._client().post(
+            url='/v3/analytics/feature-impact/precomputed',
+            data={'model_id': self.id},
+        )
+
+        return namedtuple('FeatureImpact', response.json()['data'])(
+            **response.json()['data']
+        )
+
+    def _check_id_attributes(self) -> None:
+        if not self.id:
+            raise AttributeError(
+                'This method is available only for model object generated from '
+                'API response.'
+            )

fiddler3/libs/http_client.py

@@ -10,7 +10,12 @@ from requests.adapters import HTTPAdapter
 from requests_toolbelt.multipart.encoder import MultipartEncoder
 
 from fiddler3.constants.common import JSON_CONTENT_TYPE
-from fiddler3.exceptions import ConnectionError, ConnectionTimeout, HttpError
+from fiddler3.exceptions import (  # pylint: disable=redefined-builtin
+    ConnectionError,
+    ConnectionTimeout,
+    HttpError,
+)
+from fiddler3.libs.json_encoder import RequestClientJSONEncoder
 from fiddler3.utils.logger import get_logger
 
 logger = get_logger(__name__)
@@ -24,6 +29,7 @@ class RequestClient:
         verify: bool = True,
         proxies: dict | None = None,
     ) -> None:
+        """Construct a request instance."""
         self.base_url = base_url
         self.proxies = proxies
         self.headers = headers
@@ -43,7 +49,7 @@ class RequestClient:
         url: str,
         params: dict | None = None,
         headers: dict | None = None,
-        data: dict | None = None,
+        data: dict | bytes | None = None,
         timeout: int | None = None,
         files_encoders: dict[str, MultipartEncoder] | None = None,
         **kwargs: Any,
@@ -73,7 +79,7 @@ class RequestClient:
 
         content_type = request_headers.get('Content-Type')
         if data and content_type == JSON_CONTENT_TYPE:
-            data = simplejson.dumps(data, ignore_nan=True)  # type: ignore
+            data = simplejson.dumps(data, ignore_nan=True, cls=RequestClientJSONEncoder)  # type: ignore
 
         kwargs.setdefault('allow_redirects', True)
         # requests is not able to pass the value of self.session.verify to the
@@ -107,16 +113,16 @@ class RequestClient:
                     **kwargs,
                 )
 
-        except requests.Timeout:
-            logger.error(f'{method} call failed with Timeout error for URL {url}')
-            raise ConnectionTimeout()
-        except requests.ConnectionError:
-            logger.error(f'{method} call failed with ConnectionError for URL {url}')
-            raise ConnectionError()
-        except requests.RequestException:
+        except requests.Timeout as exc:
+            logger.error('%s call failed with Timeout error for URL %s', method, url)
+            raise ConnectionTimeout() from exc
+        except requests.ConnectionError as exc:
+            logger.error('%s call failed with ConnectionError for URL %s', method, url)
+            raise ConnectionError() from exc
+        except requests.RequestException as exc:
             # catastrophic error.
-            logger.error(f'{method} call failed with RequestException for URL {url}')
-            raise HttpError()
+            logger.error('%s call failed with RequestException for %s', method, url)
+            raise HttpError() from exc
 
         response.raise_for_status()
         return response
@@ -130,6 +136,7 @@ class RequestClient:
         timeout: int | None = None,
         **kwargs: dict[str, Any],
     ) -> requests.Response:
+        """Construct a get request instance."""
         return self.call(
             method='GET',
             url=url,
@@ -148,6 +155,7 @@ class RequestClient:
         timeout: int | None = None,
         **kwargs: dict[str, Any],
     ) -> requests.Response:
+        """Construct a delete request instance."""
         return self.call(
             method='DELETE',
             url=url,
@@ -164,10 +172,11 @@ class RequestClient:
         params: dict | None = None,
         headers: dict | None = None,
         timeout: int | None = None,
-        data: dict | None = None,
+        data: dict | bytes | None = None,
         files_encoders: dict[str, MultipartEncoder] | None = None,
         **kwargs: dict[str, Any],
     ) -> requests.Response:
+        """Construct a post request instance."""
         return self.call(
             method='POST',
             url=url,
@@ -189,6 +198,7 @@ class RequestClient:
         data: dict | None = None,
         **kwargs: dict[str, Any],
     ) -> requests.Response:
+        """Construct a put request instance."""
         return self.call(
             method='PUT',
             url=url,
@@ -209,6 +219,7 @@ class RequestClient:
         data: dict | None = None,
         **kwargs: dict[str, Any],
     ) -> requests.Response:
+        """Construct a potch request instance."""
         return self.call(
             method='PATCH',
             url=url,

fiddler3/libs/json_encoder.py

@@ -0,0 +1,12 @@
+from typing import Any
+from uuid import UUID
+
+from simplejson import JSONEncoder
+
+
+class RequestClientJSONEncoder(JSONEncoder):
+    def default(self, o: Any) -> Any:
+        """Override JSONEncoder.default to support uuid serialization"""
+        if isinstance(o, UUID):
+            return o.hex
+        return super().default(o)

fiddler3/schemas/__init__.py

@@ -1,5 +1,9 @@
+"""Initialize all schemas."""
 from fiddler3.schemas.custom_features import *  # noqa
+from fiddler3.schemas.dataset import EnvType  # noqa
+from fiddler3.schemas.deployment_params import DeploymentParams  # noqa
 from fiddler3.schemas.model_schema import ModelSchema  # noqa
 from fiddler3.schemas.model_spec import ModelSpec  # noqa
 from fiddler3.schemas.model_task_params import ModelTaskParams  # noqa
+from fiddler3.schemas.xai import *  # noqa
 from fiddler3.schemas.xai_params import XaiParams  # noqa

fiddler3/schemas/baseline.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import Field
+
+from fiddler3.schemas.base import BaseModel
+from fiddler3.schemas.dataset import DatasetCompactResp
+from fiddler3.schemas.model import ModelCompactResp
+from fiddler3.schemas.organization import OrganizationCompactResp
+from fiddler3.schemas.project import ProjectCompactResp
+
+
+class BaselineCompactResp(BaseModel):
+    id: UUID
+    name: str
+
+
+class BaselineResp(BaseModel):
+    """Baseline response pydantic model."""
+
+    id: UUID
+    name: str
+    type: str
+    start_time: Optional[int]
+    end_time: Optional[int]
+    offset: Optional[int]
+    window_size: Optional[int]
+    row_count: Optional[int]
+
+    model: ModelCompactResp
+    project: ProjectCompactResp
+    organization: OrganizationCompactResp
+    dataset: DatasetCompactResp = Field(alias='environment')
+
+    created_at: datetime
+    updated_at: datetime

fiddler3/schemas/custom_features.py

@@ -13,6 +13,7 @@ class CustomFeatureType(str, Enum):
     FROM_VECTOR = 'FROM_VECTOR'
     FROM_TEXT_EMBEDDING = 'FROM_TEXT_EMBEDDING'
     FROM_IMAGE_EMBEDDING = 'FROM_IMAGE_EMBEDDING'
+    ENRICHMENT = 'ENRICHMENT'
 
 
 class CustomFeature(BaseModel):
@@ -20,10 +21,6 @@ class CustomFeature(BaseModel):
     type: CustomFeatureType
     n_clusters: Optional[int] = DEFAULT_NUM_CLUSTERS
     centroids: Optional[List] = None
-    columns: Optional[List[str]] = None
-    column: Optional[str] = None
-    source_column: Optional[str] = None
-    n_tags: Optional[int] = DEFAULT_NUM_TAGS
 
     class Config:
         allow_mutation = False
@@ -49,30 +46,31 @@ class CustomFeature(BaseModel):
             return TextEmbedding.parse_obj(deserialized_json)
         elif feature_type == CustomFeatureType.FROM_IMAGE_EMBEDDING:
             return ImageEmbedding.parse_obj(deserialized_json)
+        elif feature_type == CustomFeatureType.ENRICHMENT:
+            return Enrichment.parse_obj(deserialized_json)
         else:
             raise ValueError(f'Unsupported feature type: {feature_type}')
 
     def to_dict(self) -> Dict[str, Any]:
-        return_dict = {
+        return_dict: Dict[str, Any] = {
             'name': self.name,
             'type': self.type.value,
             'n_clusters': self.n_clusters,
         }
-        if self.type == CustomFeatureType.FROM_COLUMNS:
-            return_dict['columns'] = self.columns  # type: ignore
-        elif self.type == CustomFeatureType.FROM_VECTOR:
+        if isinstance(self, Multivariate):
+            return_dict['columns'] = self.columns
+        elif isinstance(self, VectorFeature):
             return_dict['column'] = self.column
-        elif self.type in (
-            CustomFeatureType.FROM_TEXT_EMBEDDING,
-            CustomFeatureType.FROM_IMAGE_EMBEDDING,
-        ):
-            return_dict['source_column'] = self.source_column
-            return_dict['column'] = self.column
-
-            if self.type == CustomFeatureType.FROM_TEXT_EMBEDDING:
-                return_dict['n_tags'] = self.n_tags
+            if isinstance(self, (ImageEmbedding, TextEmbedding)):
+                return_dict['source_column'] = self.source_column
+                if isinstance(self, TextEmbedding):
+                    return_dict['n_tags'] = self.n_tags
+        elif isinstance(self, Enrichment):
+            return_dict['columns'] = self.columns
+            return_dict['enrichment'] = self.enrichment
+            return_dict['config'] = self.config
         else:
-            raise ValueError(f'Unsupported feature type: {self.type}')
+            raise ValueError(f'Unsupported feature type: {self.type} {type(self)}')
 
         return return_dict
 
@@ -96,3 +94,10 @@ class TextEmbedding(VectorFeature):
 
 class ImageEmbedding(VectorFeature):
     type: CustomFeatureType = CustomFeatureType.FROM_IMAGE_EMBEDDING
+
+
+class Enrichment(CustomFeature):
+    type: CustomFeatureType = CustomFeatureType.ENRICHMENT
+    columns: List[str]
+    enrichment: str
+    config: Dict[str, Any] = {}

fiddler3/schemas/dataset.py

@@ -0,0 +1,27 @@
+from typing import Optional
+from uuid import UUID
+
+from fiddler3.constants.dataset import EnvType
+from fiddler3.schemas.base import BaseModel
+from fiddler3.schemas.model import ModelCompactResp
+from fiddler3.schemas.organization import OrganizationCompactResp
+from fiddler3.schemas.project import ProjectCompactResp
+
+
+class DatasetCompactResp(BaseModel):
+    """Dataset Compact."""
+
+    id: UUID
+    name: str
+    type: EnvType
+
+
+class DatasetResp(BaseModel):
+    """Dataset response pydantic model."""
+
+    id: UUID
+    name: str
+    row_count: Optional[int]
+    model: ModelCompactResp
+    project: ProjectCompactResp
+    organization: OrganizationCompactResp

fiddler3/schemas/deployment_params.py

@@ -0,0 +1,25 @@
+import enum
+from typing import Optional
+
+from fiddler3.schemas.base import BaseModel
+
+
+@enum.unique
+class ArtifactType(str, enum.Enum):
+    SURROGATE = 'SURROGATE'
+    PYTHON_PACKAGE = 'PYTHON_PACKAGE'
+
+
+@enum.unique
+class DeploymentType(str, enum.Enum):
+    BASE_CONTAINER = 'BASE_CONTAINER'
+    MANUAL = 'MANUAL'
+
+
+class DeploymentParams(BaseModel):
+    artifact_type: str = ArtifactType.PYTHON_PACKAGE
+    deployment_type: DeploymentType
+    image_uri: Optional[str]
+    replicas: Optional[int]
+    cpu: Optional[int]
+    memory: Optional[int]

fiddler3/schemas/filter_query.py

@@ -0,0 +1,54 @@
+import enum
+from typing import Any, List, Union
+
+from fiddler3.schemas.base import BaseModel
+
+
+class QueryConditionType(str, enum.Enum):
+    AND = 'AND'
+    OR = 'OR'
+
+
+class QueryRule(BaseModel):
+    field: str
+    operator: str
+    value: Any
+
+
+class QueryCondition(BaseModel):
+    condition: QueryConditionType = QueryConditionType.AND
+
+    rules: List[Union[QueryRule, 'QueryCondition']]
+
+    def add_rule(self, rule: Union[QueryRule, 'QueryCondition']) -> None:
+        """Add a filter rule"""
+        self.rules.append(rule)
+
+    def add_rules(self, rules: List[Union[QueryRule, 'QueryCondition']]) -> None:
+        """Add multiple filter rules"""
+        self.rules.extend(rules)
+
+
+@enum.unique
+class OperatorType(str, enum.Enum):
+    ANY = 'any'
+    EQUAL = 'equal'
+    NOT_EQUAL = 'not_equal'
+    IN = 'in'
+    NOT_IN = 'not_in'
+    LESS = 'less'
+    LESS_OR_EQUAL = 'less_or_equal'
+    GREATER = 'greater'
+    GREATER_OR_EQUAL = 'greater_or_equal'
+    BETWEEN = 'between'
+    NOT_BETWEEN = 'not_between'
+    BEGINS_WITH = 'begins_with'
+    NOT_BEGINS_WITH = 'not_begins_with'
+    CONTAINS = 'contains'
+    NOT_CONTAINS = 'not_contains'
+    ENDS_WITH = 'ends_with'
+    NOT_ENDS_WITH = 'not_ends_with'
+    IS_EMPTY = 'is_empty'
+    IS_NOT_EMPTY = 'is_not_empty'
+    IS_NULL = 'is_null'
+    IS_NOT_NULL = 'is_not_null'

fiddler3/schemas/job.py

@@ -4,12 +4,12 @@ from uuid import UUID
 from fiddler3.schemas.base import BaseModel
 
 
-class JobCompact(BaseModel):
+class JobCompactResp(BaseModel):
     id: UUID
     name: str
 
 
-class JobResponse(BaseModel):
+class JobResp(BaseModel):
     id: UUID
     name: str
     status: str