class patra_toolkit.patra_model_card.AIModel(name: str, version: str, description: str, owner: str, location: str, license: str, framework: str, model_type: str, test_accuracy: float, inference_labels: str | None = '', model_structure: object | None = <factory>, metrics: ~typing.Dict[str, str] = <factory>)

Represents and stores AI model metadata and its performance metrics.

Parameters:

  • name (str) – The name of the model.

  • version (str) – The version identifier of the model.

  • description (str) – A detailed description of the model.

  • owner (str) – The owner of the model.

  • location (str) – The file path or URL where the model is stored.

  • license (str) – The license under which the model is distributed.

  • framework (str) – The framework used to build the model (e.g., TensorFlow, PyTorch).

  • model_type (str) – The type of model (e.g., classifier, regressor).

  • test_accuracy (str) – The accuracy of the model on a test dataset.

  • model_structure (str) – The structure of the model as a dictionary (optional).

  • metrics (str) – A dictionary storing performance metrics for the model.

Example

ai_model = AIModel(
    name="Model Name",
    version="1.0",
    description="Model description",
    owner="Model owner",
    location="Model location",
    license="Model license",
    framework="Model framework",
    model_type="Model type",
    test_accuracy=0.95,
    model_structure={},
    metrics={"accuracy": "0.95"}
)
add_metric(key: str, value: str) → None

Adds a performance metric to the model’s metrics.

Parameters:

  • key (str) – The name of the metric.

  • value (str) – The value of the metric.

Returns:

None

populate_model_structure(trained_model)

Populates the model_structure attribute from a trained model object.

Parameters:

trained_model (object) – A trained machine learning model object.

Returns:

None

remove_nulls(model_structure)

Recursively removes null values from the model structure.

Parameters:

model_structure (object) – The model structure as a dictionary or list.

Returns:

Model structure with null values removed.

Return type:

object

class patra_toolkit.patra_model_card.BiasAnalysis(demographic_parity_difference: float, equal_odds_difference: float)

Class to store results from bias analysis.

Parameters:

  • demographic_parity_difference (float) – The difference in demographic parity between groups.

  • equal_odds_difference (float) – The difference in equal odds between groups.

class patra_toolkit.patra_model_card.ExplainabilityAnalysis(name: str, metrics: ~typing.List[~patra_toolkit.patra_model_card.Metric] = <factory>)

Class to store explainability metrics.

Parameters:

  • name (str) – Name of the explainability method used.

  • metrics (List[Metric]) – List of metrics related to explainability analysis.

class patra_toolkit.patra_model_card.Metric(key: str, value: str)

Data class for storing metric key-value pairs.

Parameters:

  • key (str) – The name of the metric.

  • value (str) – The value of the metric.

class patra_toolkit.patra_model_card.ModelCard(name: str, version: str, short_description: str, full_description: str, keywords: str, author: str, input_type: str, category: str, citation: str | None = '', input_data: str | None = '', output_data: str | None = '', foundational_model: str | None = '', ai_model: object | None = None, bias_analysis: object | None = None, xai_analysis: object | None = None, model_requirements: List[str] | None = None)

Represents a documented model card containing metadata, analyses, and requirements for an AI model. It includes fields for describing the model, performing bias and explainability analyses, and validating schema compliance.

Parameters:

  • name (str) – The name of the model card.

  • version (str) – The model card’s version.

  • short_description (str) – A brief description of the model card.

  • full_description (str) – A comprehensive description of the model card.

  • keywords (str) – Comma-separated keywords for searchability.

  • author (str) – The model’s creator or owner.

  • input_type (str) – Type of input data (e.g., “Image”, “Text”).

  • category (str) – The category of the model (e.g., “Classification”, “Regression”).

  • input_data (Optional[str]) – Description of the model’s input data.

  • output_data (Optional[str]) – Description of the model’s output data.

  • foundational_model (Optional[str]) – Reference to any foundational model used.

  • ai_model (Optional[object]) – Reference to an AIModel instance containing model details.

  • bias_analysis (Optional[object]) – Reference to a BiasAnalysis instance containing bias metrics.

  • xai_analysis (Optional[object]) – Reference to an ExplainabilityAnalysis instance with interpretability metrics.

  • model_requirements (Optional[List[str]]) – List of required packages and dependencies.

  • id (Optional[str]) – Unique identifier for the model card, generated upon submission.

Example

model_card = ModelCard(
    name="Model Name",
    version="1.0",
    short_description="A brief description",
    full_description="A detailed description of the model's purpose and usage.",
    keywords="classification, AI, image processing",
    author="Author Name",
    input_type="Image",
    category="Classification",
    input_data="Images of size 28x28.",
    output_data="Prediction probabilities for classes.",
    foundational_model="Base Model Reference",
    ai_model=AIModel(
        name="Model Name",
        version="1.0",
        description="Detailed model description",
        owner="Model owner",
        location="Storage location",
        license="MIT",
        framework="TensorFlow",
        model_type="Classifier",
        test_accuracy=0.95,
        model_structure={},
        metrics={"accuracy": "0.95"}
    ),
    bias_analysis=BiasAnalysis(
        demographic_parity_difference=0.05,
        equal_odds_difference=0.1
    ),
    xai_analysis=ExplainabilityAnalysis(
        name="SHAP",
        metrics=[Metric(key="Feature A", value="0.1")]
    ),
    model_requirements=["numpy>=1.19.2", "tensorflow>=2.4.1"]
)
authenticate(username: str, password: str) → str

Authenticates the user using TACC credentials and returns a Tapis access token.

Parameters:

  • username (str) – TACC username.

  • password (str) – TACC password.

Returns:

Access token string if authentication is successful.

Return type:

str

Raises:

Exception – If authentication fails.

populate_bias(dataset, true_labels, predicted_labels, sensitive_feature_name, sensitive_feature_data, model) → None

Calculates and stores fairness metrics for the model.

Parameters:

  • dataset (object) – The dataset used for bias analysis.

  • true_labels (list) – The ground truth labels.

  • predicted_labels (list) – The model’s predictions.

  • sensitive_feature_name (str) – The name of the sensitive attribute.

  • sensitive_feature_data (list) – Values for the sensitive feature.

  • model (object) – The model being analyzed.

populate_requirements() → None

Gathers package requirements for the model card, excluding certain dependencies.

populate_xai(train_dataset, column_names, model, n_features: int = 10) → None

Computes and stores feature importance metrics for explainability.

Parameters:

  • train_dataset (object) – Training dataset used in the analysis.

  • column_names (list) – Names of the features in the dataset.

  • model (object) – The model being explained.

  • n_features (int) – Number of features to analyze. Default is 10.

save(file_location: str) → None

Saves the model card as a JSON file to the specified location.

Parameters:

file_location (str) – Path where the model card JSON file will be saved.

submit(patra_server_url: str, token: str | None = None, model: object | None = None, file_format: str | None = 'h5', model_store: str | None = 'huggingface', inference_labels: str | None = None, artifacts: List[str] | None = None)

Submits the model card to the Patra server, optionally uploading the model and artifacts.

Parameters:

  • patra_server_url (str) – The URL of the Patra server.

  • token (str) – The access token for authentication.

  • model (object) – The trained model to be uploaded.

  • file_format (str) – The format in which the model will be saved (default: “h5”).

  • model_store (str) – The model store to use for uploading the model (default: “huggingface”).

  • inference_labels (str) – The inference labels to be uploaded.

  • artifacts (List[str]) – List of artifacts to be uploaded.

Returns:

“success” if the submission is successful, None otherwise.

Return type:

str

Example

model_card.submit(
    patra_server_url="http://localhost:5002",
    token="access_token",
    model=model,
    file_format="h5",
    model_store="huggingface",
    inference_labels="inference_label.json",
    artifacts=["requirements.txt", "README.md"]
)
validate() → bool

Validates the model card against a predefined JSON schema.

Returns:

True if the model card is valid according to the schema, False otherwise.

Return type:

bool

class patra_toolkit.patra_model_card.ModelCardJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Custom JSON Encoder for ModelCard to handle complex objects.

default()

Serializes non-serializable fields.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)
class patra_toolkit.fairlearn_bias.BiasAnalyzer(dataset, true_labels, predicted_labels, sensitive_feature_name, sensitive_feature_data, model)

Provides automated capture of fairness metrics in a given AI workflow.

calculate_bias_metrics()

Calculate bias metrics.

Parameters:

None

Returns:

A dictionary of bias

Return type:

dict

class patra_toolkit.shap_xai.ExplainabilityAnalyser(train_dataset, column_names, model)

Provides automated capture of xai information in a given AI workflow.