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, 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, input_data: str | None = '', output_data: str | None = '', foundational_model: str | None = '', ai_model: AIModel | None = None, bias_analysis: BiasAnalysis | None = None, xai_analysis: ExplainabilityAnalysis | None = None, model_requirements: List | None = None)

Represents an AI model card to document model metadata, analyses, and requirements.

Parameters:

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

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

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

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

  • 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[AIModel]) – An instance of AIModel containing model details.

  • bias_analysis (Optional[BiasAnalysis]) – Instance of BiasAnalysis containing bias metrics.

  • xai_analysis (Optional[ExplainabilityAnalysis]) – Instance of ExplainabilityAnalysis 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"]
)
populate_bias(dataset, true_labels, predicted_labels, sensitive_feature_name, sensitive_feature_data, model)

Calculates and stores fairness metrics.

Parameters:

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

  • true_labels (list) – The ground truth labels.

  • predicted_labels (list) – 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.

Returns:

None

populate_requirements()

Collects package requirements for the model card, excluding specific dependencies.

Returns:

None

populate_xai(train_dataset, column_names, model, n_features=10)

Computes and stores feature importance metrics.

Parameters:

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

  • column_names (list) – Names of the features.

  • model (object) – The model being explained.

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

Returns:

None

save(file_location)

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

Parameters:

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

Returns:

None

submit(patra_server_url)

Validates and submits the model card to the specified Patra server.

Parameters:

patra_server_url (str) – The Patra server URL where the model card should be submitted.

Returns:

The server’s response as a JSON object.

Return type:

dict

validate()

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.