Customizing details for a factsheet (AI Factsheets)

With AI Factsheets, you can programmatically customize the information about a model use case or model to enhance the factsheet that tracks the model lifecycle. For example, programmatically attach files and images to enhance the use case. Use customized factsheets as part of your AI Governance strategy.

Updating a model or model use case programmatically

You might want to update a model use case or model factsheet with additional information. For example, some companies have a standard set of details they want to accompany a model use case or model facts.

Currently, you must update the tenant-level asset types by modifying the user attributes that uses the Watson Data REST API to update the asset.

Updating a custom asset type

Follow these steps to update a custom asset type:

Provide the bss_account_id query parameter for the getcatalogtype method.
Provide asset_type as model_entry_user if you are updating attributes for model_entry. Provide asset_type as modelfacts_user if you are updating attributes for model facts.
Retrieve the current asset type definition by using the getcatalogtype method where asset_type is either modelfacts_user or model_entry_user.
Update the current asset type definition with the custom attributes by adding them to properties JSON object following the schema that is defined in the API documentation. The following types of attributes are supported to view and edit from the user interface of the model use case or model:
- string
- date
- integer
After the JSON is updated with the new properties, start the changes by using the replaceassettype method. Provide the asset_type , bss_account_id, and request payload.

When the update is complete, you can view the custom attributes in the model use case details page and model details page.

Example 1: Retrieving and updating the `model_entry_user` asset type

Note:

This example updates the model use case user data. You can use the same format but substitute modelfacts_user to retrieve and update details for the model factsheet.

This curl command retrieves the asset type model_entry_user:

curl -X GET --header 'Accept: application/json' --header "Authorization: Bearer ${MY_TOKEN}"  'https://api.dataplatform.cloud.ibm.com:443/v2/asset_types/model_entry_user?bss_account_id=<bss_account_id>'

This is a sample response payload for model use case user details:

{
    "description": "The model use case to capture user defined attributes.",
    "fields": [],
    "relationships": [],
    "properties": {},
    "decorates": [{
        "asset_type_name": "model_entry"
    }],
    "global_search_searchable": [],
    "localized_metadata_attributes": {
        "name": {
            "default": "Additional details",
            "en": "Additional details"
        }
    },
    "attribute_only": false,
    "name": "model_entry_user",
    "version": 1,
    "scope": "ACCOUNT"
}

This curl command updates the model_entry_user asset type:

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: Bearer ${MY_TOKEN}"  -d '@requestbody.json' 'https://api.dataplatform.cloud.ibm.com:443/v2/asset_types/model_entry_user?bss_account_id=<bss_account_id>'

The requestbody.json contents look like this:

{
    "description": "The model use case to capture user defined attributes.",
    "fields": [],
    "relationships": [],
    "properties": {
        "user_attribute1": {
            "type": "string",
            "description": "User attribute1",
            "placeholder": "User attribute1",
            "is_array": false,
            "required": true,
            "hidden": false,
            "readonly": false,
            "default_value": "None",
            "label": {
                "default": "User attribute1"
            }
        },
        "user_attribute2": {
            "type": "integer",
            "description": "User attribute2",
            "placeholder": "User attribute2",
            "is_array": false,
            "required": true,
            "hidden": false,
            "readonly": false,
            "label": {
                "default": "User attribute2"
            }
        },
        "user_attribute3": {
            "type": "date",
            "description": "User attribute3",
            "placeholder": "User attribute3",
            "is_array": false,
            "required": true,
            "hidden": false,
            "readonly": false,
            "default_value": "None",
            "label": {
                "default": "User attribute3"
            }
        
    }
    "decorates": [{
        "asset_type_name": "model_entry"
    }],
    "global_search_searchable": [],
    "attribute_only": false,
    "localized_metadata_attributes": {
        "name": {
            "default": "Additional details",
            "en": "Additional details"
        }
    }
}

Updating user details by using the Python client

You can also update and replace an asset type with properties by using a Python script. For details, see fact sheet elements description.

After you update asset type definitions with custom attributes, you can provide values for those attributes from the model use case overview and model details pages. You can also update values to the custom attributes using these Python API client methods:

Capturing cell facts for a model

When a data scientist develops a model in a notebook, they generate visualizations for key model details, such as ROC curve, confusion matrix, panda profiling report, or the output of any cell execution. To capture those facts as part of a model use case, use the 'capture_cell_facts` function in the AI Factsheets Python client library.

Troubleshooting custom fields

After you customize fields and make them available to users, a user trying to update fields in the Additional details section of model details might get this error:

Update failed. To update an asset attribute, you must be a catalog Admin or an asset owner or member with the Editor role. Ask a catalog Admin to update your catalog role or ask an asset member with the Editor role to add you as a member.

If the user already has edit permission on the model and is still getting the error message, follow these steps to resolve.

Invoke the API command for createassetattributenewv2.
Use this payload with the command:
```
{
  "name": "modelfacts_system",
  "entity": {
  }
}
```
where asset_id is the model_id. Enter either project_id or space_id or catalog_id where the model exists.

Learn more

For more information see custom asset types.

Find out about working with a model inventory programmatically, by using the IBM_AIGOV_FACTS_CLIENT documentation.

Parent topic: Managing an inventory of model assets.