ibm-watsonx-gov 1.3.3__cp313-cp313-macosx_11_0_arm64.whl

ibm_watsonx_gov/entities/ai_experiment.py

@@ -0,0 +1,419 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+
+from typing import Annotated, Dict, List
+from pydantic import BaseModel, Field, validator
+
+from ibm_watsonx_gov.entities.foundation_model import FoundationModelInfo
+
+
+class Node(BaseModel):
+    id: Annotated[
+        str,
+        Field(
+            description="The ID of node for AI Experiemnt.",
+            examples=["node-001"],
+            default="",
+        ),
+    ]
+    name: Annotated[
+        str,
+        Field(
+            description="The name of node for AI Experiment.",
+            examples=["Node_1"],
+            default="",
+        ),
+    ]
+    type: Annotated[
+        str,
+        Field(
+            description="The type of node for AI Experiment.",
+            examples=["tool", "agent"],
+            default="tool",
+        ),
+    ]
+    foundation_models: Annotated[
+        List[FoundationModelInfo],
+        Field(
+            description="The Foundation models invoked by the node",
+            default=[],
+        ),
+    ]
+
+    def to_json(self):
+        """
+        Transform the Node instance to json.
+        """
+        return self.model_dump(mode="json")
+
+    @validator('foundation_models', pre=True, each_item=True)
+    def convert_foundation_models(cls, v):
+        if isinstance(v, dict):
+            return FoundationModelInfo(**v)
+        return v
+
+
+class AIExperimentRun(BaseModel):
+    """
+    The class for AIExperimentRun
+
+    Example:
+    --------
+        .. code-block:: python
+
+            experiment_run_details = AIExperimentRun(
+                                        run_id=str(uuid.uuid4()),
+                                        run_name="",
+                                        test_data={},
+                                        node=[]
+                                        )
+    """
+
+    run_id: Annotated[
+        str, Field(description="The ID of the AI experiment run.",
+                   examples=["run-001"])
+    ]
+    run_name: Annotated[
+        str,
+        Field(
+            description="The name of the AI experiment run.", examples=["Test run 1"]
+        ),
+    ]
+    created_at: Annotated[
+        str,
+        Field(
+            description="The timestamp of the AI experiment run.",
+            examples=["2025-04-01T12:00:00Z"],
+            default="",
+        ),
+    ]
+    created_by: Annotated[
+        str,
+        Field(
+            description="The ID of the user creating AI experiment run.",
+            examples=["user-123"],
+            default="",
+        ),
+    ]
+    test_data: Annotated[
+        dict,
+        Field(description="The test data used for the evaluation run.", default={}),
+    ]
+    tracked: Annotated[
+        bool,
+        Field(
+            description="The experiment run is tracked or not.",
+            examples=[False, True],
+            default=False,
+        ),
+    ]
+    id_deleted: Annotated[
+        bool,
+        Field(
+            description="The experiment run is deleted or not.",
+            examples=[False, True],
+            default=False,
+        ),
+    ]
+    attachment_id: Annotated[
+        str,
+        Field(
+            description="The ID of attachment of evaluation result of the AI experiment run.",
+            examples=["att-456"],
+            default="",
+        ),
+    ]
+    nodes: Annotated[
+        List[Node],
+        Field(
+            description="The list of nodes for AI Experiment run.",
+            examples=[{"id": "node-001", "name": "Node_1", "type": "tool"}],
+            default=[],
+        ),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="The description of AI Experiment run.",
+            examples=["This is the experiment run for AI Experiment"],
+            default="",
+        ),
+    ]
+    source_name: Annotated[
+        str,
+        Field(
+            description="The name of the notebook used to create experiment run",
+            examples=[""],
+            default="",
+        ),
+    ]
+    source_url: Annotated[
+        str,
+        Field(
+            description="The URL of the notebook used to create experiment run",
+            examples=[""],
+            default="",
+        ),
+    ]
+    duration: Annotated[
+        int,
+        Field(
+            description="The time taken to complete the run.",
+            examples=[""],
+            default=None,
+        ),
+    ]
+    custom_tags: Annotated[
+        List[Dict],
+        Field(
+            description="The list of custom tags key value pair.",
+            examples=[""],
+            default=[],
+        ),
+    ]
+    properties: Annotated[
+        Dict,
+        Field(
+            description="Freeform field to store additional metadata related to runs",
+            default={},
+        ),
+    ]
+    agent_method_name: Annotated[
+        str,
+        Field(
+            description="Name of the method which returns the agent.",
+            examples=[""],
+            default="",
+        ),
+    ]
+
+    def to_json(self):
+        """
+        Transform the AIExperimentRun instance to json.
+        """
+        return self.model_dump(mode="json")
+
+
+class AIExperiment(BaseModel):
+    """
+    The class for AIExperiment
+
+    Example:
+    --------
+    Creating instance of AIExperiment
+        .. code-block:: python
+
+            ai_experiment = AIExperiment(name="",
+                             description="",
+                             component_type="agent",
+                             component_name="")
+    """
+
+    container_id: Annotated[
+        str,
+        Field(
+            description="The container ID of the AI Experiment",
+            examples=["proj-001"],
+            default="",
+        ),
+    ]
+    container_type: Annotated[
+        str,
+        Field(
+            description="The container type of the AI Experiment.",
+            examples=["project", "space"],
+            default="",
+        ),
+    ]
+    container_name: Annotated[
+        str,
+        Field(
+            description="The container name of the AI Experiment.",
+            examples=["project_1"],
+            default="",
+        ),
+    ]
+    name: Annotated[
+        str,
+        Field(
+            description="The name of the AI Experiment.",
+            examples=["AI Experiment for Agent 1"],
+            default="AI Experiment for Agent",
+        ),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="The description of the AI Experiment",
+            examples=["AI Experiment asset for Agent governance"],
+            default="",
+        ),
+    ]
+    asset_type: Annotated[
+        str, Field(description="", examples=["ai_experiment"], default="")
+    ]
+    created_at: Annotated[
+        str,
+        Field(
+            description="The timestamp of the AI Experiment creation.",
+            examples=["2025-04-08T10:00:43Z"],
+            default="",
+        ),
+    ]
+    owner_id: Annotated[
+        str,
+        Field(
+            description="The owner of the AI Experiment.",
+            examples=["user-123"],
+            default="",
+        ),
+    ]
+    asset_id: Annotated[
+        str,
+        Field(
+            description="The ID of the AI Experiment.",
+            examples=["ai_experimet-001"],
+            default="",
+        ),
+    ]
+    creator_id: Annotated[
+        str,
+        Field(
+            description="The ID of the user creating AI Experiment.",
+            examples=["user-123"],
+            default="",
+        ),
+    ]
+    component_id: Annotated[
+        str,
+        Field(
+            description="The ID of the component of the AI Experiemnt.",
+            examples=["comp-001"],
+            default="",
+        ),
+    ]
+    component_type: Annotated[
+        str,
+        Field(
+            description="The type of AI component for which the AI Experiment is to be created.",
+            examples=["agent"],
+            default="agent",
+        ),
+    ]
+    component_name: Annotated[
+        str,
+        Field(
+            description="The name of AI component of AI Experiment.",
+            examples=["Test agent"],
+            default="Test agent",
+        ),
+    ]
+    runs: Annotated[
+        List[AIExperimentRun],
+        Field(
+            description="Experiment runs for the AI Experiment",
+            examples=[
+                {
+                    "run_id": "run-001",
+                    "run_name": "Test run 1",
+                    "created_at": "2025-04-01T12:00:00Z",
+                    "created_by": "user-123",
+                    "test_data": {},
+                    "attachment_id": "att-456",
+                    "nodes": [
+                        {
+                            "id": "node-001",
+                            "name": "Node_1",
+                            "type": "example_type",
+                            "foundation_models": [
+                                {
+                                    "type": "chat",
+                                    "model_name": "gpt-4o-mini",
+                                    "provider": "openai"
+                                }
+                            ]
+                        }
+                    ],
+                }
+            ],
+            default=[],
+        ),
+    ]
+
+    def to_json(self):
+        """
+        Transform the AI Experiment instance to json.
+        """
+        return self.model_dump(mode="json")
+
+
+class AIExperimentRunRequest(BaseModel):
+    """ The class for AIExperimentRunRequest
+
+    Example:
+    --------
+    Creating instance of AIExperiment
+        .. code-block:: python
+
+            ai_experiment_run_request = AIExperimentRunRequest(name="",
+                             description="",
+                             source_name="",
+                             source_url="",
+                             custom_tags=[])
+    """
+
+    name: Annotated[
+        str,
+        Field(
+            description="The name of experiment run.",
+            examples=["run_1"],
+            default="run_1",
+        ),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="The description of AI Experiment run.",
+            examples=["This is the experiment run for AI Experiment"],
+            default="",
+        ),
+    ]
+    source_name: Annotated[
+        str,
+        Field(
+            description="The name of the notebook used to create experiment run",
+            examples=[""],
+            default="",
+        ),
+    ]
+    source_url: Annotated[
+        str,
+        Field(
+            description="The URL of the notebook used to create experiment run",
+            examples=[""],
+            default="",
+        ),
+    ]
+    custom_tags: Annotated[
+        List[Dict],
+        Field(
+            description="The list of custom tags key value pair.",
+            examples=[""],
+            default=[],
+        ),
+    ]
+    agent_method_name: Annotated[
+        str,
+        Field(
+            description="Name of the method which returns the agent.",
+            examples=[""],
+            default="",
+        ),
+    ]

ibm_watsonx_gov/entities/base_classes.py

@@ -0,0 +1,134 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, computed_field
+
+from ibm_watsonx_gov.entities.enums import (MetricGroup, MetricType,
+                                            MetricValueType)
+from ibm_watsonx_gov.entities.metric_threshold import MetricThreshold
+
+
+class BaseConfiguration(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True)
+
+    record_id_field: Annotated[str, Field(title="Record id field",
+                                          description="The record identifier field name.",
+                                          examples=["record_id"],
+                                          default="record_id")]
+    record_timestamp_field: Annotated[str, Field(title="Record timestamp field",
+                                                 description="The record timestamp field name.",
+                                                 examples=["record_timestamp"],
+                                                 default="record_timestamp")]
+
+
+class BaseMetric(BaseModel):
+    name: Annotated[str, Field(title="Metric Name",
+                               description="The name of the metric.",
+                               frozen=True,
+                               examples=["answer_relevance",
+                                         "context_relevance"],)]
+    display_name: Annotated[str | None, Field(title="Metric display name",
+                                              description="The display name of the metric.",
+                                              examples=["Answer Relevance",
+                                                        "Context Relevance"],
+                                              default=None)]
+    type_: Annotated[str, Field(title="Metric type",
+                                description="The type of the metric. Indicates whether the metric is ootb or custom.",
+                                serialization_alias="type",
+                                default=MetricType.OOTB.value,
+                                frozen=True,
+                                examples=MetricType.values())]
+    value_type: Annotated[str, Field(title="Metric value type",
+                                     description="The type of the metric value. Indicates whether the metric value is numeric or categorical.",
+                                     serialization_alias="type", default=MetricValueType.NUMERIC.value,
+                                     examples=MetricValueType.values())]
+    _id: Annotated[str, PrivateAttr(default=None)]
+
+    @computed_field(return_type=str)
+    @property
+    def id(self):
+        if self._id is None:
+            self._id = self.name
+        return self._id
+
+
+class BaseMetricGroup(BaseModel):
+    name: Annotated[str, Field(description="The name of the metric group")]
+    _metrics: Annotated[list[BaseMetric], Field(
+        description="Metrics to be computed when selecting this metric group", default=[])]
+
+    @property
+    def metrics(self) -> list[BaseMetric]:
+        return self._metrics
+
+
+class Error(BaseModel):
+    code: Annotated[str, Field(description="The error code")]
+    message_en: Annotated[str, Field(
+        description="The error message in English.")]
+    parameters: Annotated[list[Any], Field(
+        description="The list of parameters to construct the message in a different locale.", default=[])]
+
+
+class BaseMetricResult(BaseModel):
+    name: Annotated[str, Field(title="Metric Name",
+                               description="The name of the metric.",
+                               examples=["answer_relevance",
+                                         "context_relevance"],)]
+    display_name: Annotated[str | None, Field(title="Metric display name",
+                                              description="The display name of the metric.",
+                                              examples=["Answer Relevance",
+                                                        "Context Relevance"],
+                                              default=None)]
+    value_type: Annotated[str, Field(title="Metric value type",
+                                     description="The type of the metric value. Indicates whether the metric value is numeric or categorical.",
+                                     serialization_alias="type", default=MetricValueType.NUMERIC.value,
+                                     examples=MetricValueType.values())]
+    method: Annotated[str | None, Field(title="Method",
+                                        description="The method used to compute this metric result.",
+                                        examples=["token_recall"],
+                                        default=None)]
+    provider: Annotated[str | None, Field(title="Provider",
+                                          description="The provider used to compute this metric result.",
+                                          default=None)]
+    value: Annotated[float | str | bool | dict[str, int] | None, Field(title="Value",
+                                                                       description="The metric value.",
+                                                                       default=None)]
+    label: Annotated[str | None, Field(title="Label",
+                                       description="The string equivalent of the metric value. This is used for metrics with categorical value type.",
+                                       default=None)]
+    errors: Annotated[list[Error] | None, Field(title="Errors",
+                                                description="The list of error messages",
+                                                default=None)]
+    additional_info: Annotated[dict | None, Field(title="Additional Info",
+                                                  description="The additional information about the metric result.",
+                                                  default=None)]
+    explanation: Annotated[str | None, Field(title="Explanation",
+                                             description="The explanation about the metric result.",
+                                             default=None)]
+    group: Annotated[MetricGroup | None, Field(title="Group",
+                                               description="The metric group",
+                                               default=None)]
+    thresholds: Annotated[list[MetricThreshold], Field(title="Thresholds",
+                                                       description="The metric thresholds",
+                                                       default=[])]
+    category_classification: Annotated[dict[str, list[str]], Field(
+        title="Category Classification",
+        description="The category classification of the metrics values.",
+        default={},
+    )]
+    evidences: Annotated[list | None, Field(title="Evidences",
+                                                  description="The evidences for the metric result.",
+                                                  default=None)]
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True, use_enum_values=True)

ibm_watsonx_gov/entities/container.py

@@ -0,0 +1,54 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# OCO Source Materials
+# 5900-A3Q, 5737-H76
+# Copyright IBM Corp. 2025
+# The source code for this program is not published or other-wise divested of its trade
+# secrets, irrespective of what has been deposited with the U.S.Copyright Office.
+# ----------------------------------------------------------------------------------------------------
+
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import Annotated
+
+from ibm_watsonx_gov.entities.enums import ContainerType, EvaluationStage
+from ibm_watsonx_gov.entities.monitor import BaseMonitor
+
+
+class BaseContainer(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True)
+    container_id: Annotated[str, Field(description="Space or project id", examples=[
+                                       "550547b0-1be2-4426-8e62-f3423b0b83dd"])]
+    container_type: Annotated[ContainerType, Field(description="The container type, project or space", examples=[
+                                                   ContainerType.PROJECT, ContainerType.SPACE])]
+    stage: Annotated[EvaluationStage, Field(description="The stage of the container", examples=[
+                                            EvaluationStage.DEVELOPMENT, EvaluationStage.PRODUCTION])]
+    prompt_setup: Annotated[dict[str, Any] | None, Field(
+        default=None, description="The prompt setup details for the container")]
+    monitors: Annotated[list[BaseMonitor] | None, Field(
+        default=None, description="List of monitors to set up for the container")]
+
+
+class ProjectContainer(BaseContainer):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True)
+    container_type: ContainerType = ContainerType.PROJECT
+    stage: EvaluationStage = EvaluationStage.DEVELOPMENT
+
+
+class SpaceContainer(BaseContainer):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True)
+    container_type: ContainerType = ContainerType.SPACE
+    stage: EvaluationStage = EvaluationStage.PRODUCTION
+    serving_name: Annotated[str, Field(
+        description="Serving name of the deployment. This should be unique per space")]
+    base_model_id: Annotated[str, Field(
+        description="The model id of the space deployment base model")]
+    description: Annotated[str, Field(
+        description="Space deployment description")]
+    name: Annotated[str, Field(description="Space deployment name")]
+    version_date: Annotated[str, Field(description="Space deployment version")]