Customizing details for a use case or factsheet

You can programmatically customize the information that is collected in factsheets for AI use cases. Use customized factsheets as part of your AI Governance strategy.

Updating a model or AI use case programmatically

You might want to update a use case or 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 Data and AI Common Core API to update the asset.

Updating a custom asset type

Follow these steps to update a custom asset type:

  1. Provide the bss_account_id query parameter for the getcatalogtype method.

  2. 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.

  3. Retrieve the current asset type definition by using the getcatalogtype method where asset_type is either modelfacts_user or model_entry_user.

  4. 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
  5. 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 AI use case details page and model details page.

Example 1: Retrieving and updating the model_entry_user asset type

Note:

This example updates the 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: ZenApiKey ${MY_TOKEN}"  'https://api.dataplatform.cloud.ibm.com:443/v2/asset_types/model_entry_user?bss_account_id=<bss_account_id>'

This snippet 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: ZenApiKey ${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"
        }
    }
}

Assigning a display order for custom facts

The field Order in the "Create Custom Facts Definition" method, lets you assign a display order for a custom fact. This gives you greater control over the organization of facts on a factsheet.

Follow these steps to assign an order to a custom facts.

  1. Edit the custom facts definition file and add an Order field with an assigned integer to control the order. For example: Assigning an order for a custom field using Python
  2. Load the definition file using this method:
facts_client.assets.create_custom_facts_definitions("Asset_type_definition.csv", overwrite=True)

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 that use 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 it.

  1. Invoke the API command for createassetattributenewv2.

  2. 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

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