cyclonedx.model.model_card

This set of classes represents the model card types in the CycloneDX standard.

Note

Introduced in CycloneDX v1.5. Environmental considerations were added in v1.6.

Note

See the CycloneDX Schema for model cards:

• XML: https://cyclonedx.org/docs/1.7/xml/#type_modelCardType

• JSON: https://cyclonedx.org/docs/1.7/json/#components_items_modelCard

Classes

MachineLearningApproach	Enumeration for machineLearningApproachType.
Approach	Container for the approach element within modelParameters.
InputOutputMLParameters	Definition for items under modelParameters.inputs[] and outputs[].
ModelParameters	modelParameters block within modelCard.
ConfidenceInterval	Confidence interval with lower/upper bounds.
PerformanceMetric	A single performance metric entry.
Graphic	Graphic entry with optional name and image (AttachedText).
GraphicsCollection	A collection of graphics with optional description.
QuantitativeAnalysis	quantitativeAnalysis block within modelCard.
EthicalConsideration	Entry in ethicalConsiderations with name and mitigation strategy.
FairnessAssessment	Entry in fairnessAssessments.
EnvironmentalConsiderations	Environmental considerations (1.6+). Energy consumptions and properties.
EnergyActivity	Enumeration for lifecycle activity in energyConsumption.activity (1.6+).
EnergyMeasure	A measure of energy. Schema energyMeasure (1.6+): value + unit (kWh).
Co2Measure	A measure of CO2. Schema co2Measure (1.6+): value + unit (tCO2eq).
EnergySource	Enumeration for provider energySource (1.6+).
EnergyProvider	Energy provider per schema energyProvider (1.6+).
EnergyConsumption	Energy consumption entry. Matches schema energyConsumption (1.6+).
Considerations	considerations block within modelCard.
ModelCard	Internal representation of CycloneDX modelCardType.

Module Contents

class cyclonedx.model.model_card.MachineLearningApproach

Bases: str, enum.Enum

Enumeration for machineLearningApproachType.

Values are stable across 1.5–1.7.

SUPERVISED = 'supervised'

UNSUPERVISED = 'unsupervised'

REINFORCEMENT_LEARNING = 'reinforcement-learning'

SEMI_SUPERVISED = 'semi-supervised'

SELF_SUPERVISED = 'self-supervised'

class cyclonedx.model.model_card.Approach(*, type: MachineLearningApproach | None = None)

Container for the approach element within modelParameters.

property type: MachineLearningApproach | None

class cyclonedx.model.model_card.InputOutputMLParameters(*, format: str)

Definition for items under modelParameters.inputs[] and outputs[].

property format: str

class cyclonedx.model.model_card.ModelParameters(*, approach: Approach | None = None, task: str | None = None, architecture_family: str | None = None, model_architecture: str | None = None, datasets: collections.abc.Iterable[Any] | None = None, inputs: collections.abc.Iterable[InputOutputMLParameters] | None = None, outputs: collections.abc.Iterable[InputOutputMLParameters] | None = None)

modelParameters block within modelCard.

property approach: Approach | None

property task: str | None

property architecture_family: str | None

property model_architecture: str | None

property inputs: SortedSet[InputOutputMLParameters]

property outputs: SortedSet[InputOutputMLParameters]

class cyclonedx.model.model_card.ConfidenceInterval(*, lower_bound: str | None = None, upper_bound: str | None = None)

Confidence interval with lower/upper bounds.

property lower_bound: str | None

property upper_bound: str | None

class cyclonedx.model.model_card.PerformanceMetric(*, type: str | None = None, value: str | None = None, slice: str | None = None, confidence_interval: ConfidenceInterval | None = None)

A single performance metric entry.

property type: str | None

property value: str | None

property slice: str | None

property confidence_interval: ConfidenceInterval | None

class cyclonedx.model.model_card.Graphic(*, name: str | None = None, image: cyclonedx.model.AttachedText | None = None)

Graphic entry with optional name and image (AttachedText).

property name: str | None

property image: cyclonedx.model.AttachedText | None

class cyclonedx.model.model_card.GraphicsCollection(*, description: str | None = None, collection: collections.abc.Iterable[Graphic] | None = None)

A collection of graphics with optional description.

property description: str | None

property collection: SortedSet[Graphic]

class cyclonedx.model.model_card.QuantitativeAnalysis(*, performance_metrics: collections.abc.Iterable[PerformanceMetric] | None = None, graphics: GraphicsCollection | None = None)

quantitativeAnalysis block within modelCard.

property performance_metrics: SortedSet[PerformanceMetric]

property graphics: GraphicsCollection | None

class cyclonedx.model.model_card.EthicalConsideration(*, name: str | None = None, mitigation_strategy: str | None = None)

Entry in ethicalConsiderations with name and mitigation strategy.

property name: str | None

property mitigation_strategy: str | None

class cyclonedx.model.model_card.FairnessAssessment(*, group_at_risk: str | None = None, benefits: str | None = None, harms: str | None = None, mitigation_strategy: str | None = None)

Entry in fairnessAssessments.

property group_at_risk: str | None

property benefits: str | None

property harms: str | None

property mitigation_strategy: str | None

class cyclonedx.model.model_card.EnvironmentalConsiderations(*, energy_consumptions: collections.abc.Iterable[EnergyConsumption] | None = None, properties: collections.abc.Iterable[cyclonedx.model.Property] | None = None)

Environmental considerations (1.6+). Energy consumptions and properties.

NOTE: Prior revisions kept energy_consumptions opaque. This has been replaced by concrete types that match CycloneDX 1.6+/1.7 schema: EnergyConsumption, EnergyMeasure, Co2Measure, EnergyProvider, and enumerations for activity and energySource.

property energy_consumptions: SortedSet[EnergyConsumption]

property properties: SortedSet[Property]

class cyclonedx.model.model_card.EnergyActivity

Bases: str, enum.Enum

Enumeration for lifecycle activity in energyConsumption.activity (1.6+).

DESIGN = 'design'

DATA_COLLECTION = 'data-collection'

DATA_PREPARATION = 'data-preparation'

TRAINING = 'training'

FINE_TUNING = 'fine-tuning'

VALIDATION = 'validation'

DEPLOYMENT = 'deployment'

INFERENCE = 'inference'

OTHER = 'other'

class cyclonedx.model.model_card.EnergyMeasure(*, value: float, unit: str = 'kWh')

A measure of energy. Schema energyMeasure (1.6+): value + unit (kWh).

property value: float

property unit: str

class cyclonedx.model.model_card.Co2Measure(*, value: float, unit: str = 'tCO2eq')

A measure of CO2. Schema co2Measure (1.6+): value + unit (tCO2eq).

property value: float

property unit: str

class cyclonedx.model.model_card.EnergySource

Bases: str, enum.Enum

Enumeration for provider energySource (1.6+).

COAL = 'coal'

OIL = 'oil'

NATURAL_GAS = 'natural-gas'

NUCLEAR = 'nuclear'

WIND = 'wind'

SOLAR = 'solar'

GEOTHERMAL = 'geothermal'

HYDROPOWER = 'hydropower'

BIOFUEL = 'biofuel'

UNKNOWN = 'unknown'

OTHER = 'other'

class cyclonedx.model.model_card.EnergyProvider(*, organization: cyclonedx.model.contact.OrganizationalEntity, energy_source: EnergySource, energy_provided: EnergyMeasure, bom_ref: str | cyclonedx.model.bom_ref.BomRef | None = None, description: str | None = None, external_references: collections.abc.Iterable[cyclonedx.model.ExternalReference] | None = None)

Energy provider per schema energyProvider (1.6+).

property description: str | None

property organization: cyclonedx.model.contact.OrganizationalEntity

property energy_source: EnergySource

property energy_provided: EnergyMeasure

property external_references: SortedSet[ExternalReference]

property bom_ref: cyclonedx.model.bom_ref.BomRef

class cyclonedx.model.model_card.EnergyConsumption(*, activity: EnergyActivity, energy_providers: collections.abc.Iterable[EnergyProvider], activity_energy_cost: EnergyMeasure, co2_cost_equivalent: Co2Measure | None = None, co2_cost_offset: Co2Measure | None = None, properties: collections.abc.Iterable[cyclonedx.model.Property] | None = None)

Energy consumption entry. Matches schema energyConsumption (1.6+).

property activity: EnergyActivity

property energy_providers: SortedSet[EnergyProvider]

property activity_energy_cost: EnergyMeasure

property co2_cost_equivalent: Co2Measure | None

property co2_cost_offset: Co2Measure | None

property properties: SortedSet[Property]

class cyclonedx.model.model_card.Considerations(*, users: collections.abc.Iterable[str] | None = None, use_cases: collections.abc.Iterable[str] | None = None, technical_limitations: collections.abc.Iterable[str] | None = None, performance_tradeoffs: collections.abc.Iterable[str] | None = None, ethical_considerations: collections.abc.Iterable[EthicalConsideration] | None = None, environmental_considerations: EnvironmentalConsiderations | None = None, fairness_assessments: collections.abc.Iterable[FairnessAssessment] | None = None)

considerations block within modelCard.

property users: SortedSet[str]

property use_cases: SortedSet[str]

property technical_limitations: SortedSet[str]

property performance_tradeoffs: SortedSet[str]

property ethical_considerations: SortedSet[EthicalConsideration]

property environmental_considerations: EnvironmentalConsiderations | None

property fairness_assessments: SortedSet[FairnessAssessment]

class cyclonedx.model.model_card.ModelCard(*, bom_ref: str | cyclonedx.model.bom_ref.BomRef | None = None, model_parameters: ModelParameters | None = None, quantitative_analysis: QuantitativeAnalysis | None = None, considerations: Considerations | None = None, properties: collections.abc.Iterable[cyclonedx.model.Property] | None = None)

Internal representation of CycloneDX modelCardType.

Version gating: - Introduced in schema 1.5 - Unchanged structurally in 1.6 except for additional nested environmental considerations inside considerations - 1.7 retains 1.6 structure (additions in nested types only)

property model_parameters: ModelParameters | None

property quantitative_analysis: QuantitativeAnalysis | None

property considerations: Considerations | None

property properties: SortedSet[Property]

Provides the ability to document properties in a key/value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions.

Return:

Set of Property

property bom_ref: cyclonedx.model.bom_ref.BomRef