cyclonedx.model.model_card ========================== .. py:module:: cyclonedx.model.model_card .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: cyclonedx.model.model_card.MachineLearningApproach cyclonedx.model.model_card.Approach cyclonedx.model.model_card.InputOutputMLParameters cyclonedx.model.model_card.ModelParameters cyclonedx.model.model_card.ConfidenceInterval cyclonedx.model.model_card.PerformanceMetric cyclonedx.model.model_card.Graphic cyclonedx.model.model_card.GraphicsCollection cyclonedx.model.model_card.QuantitativeAnalysis cyclonedx.model.model_card.EthicalConsideration cyclonedx.model.model_card.FairnessAssessment cyclonedx.model.model_card.EnvironmentalConsiderations cyclonedx.model.model_card.EnergyActivity cyclonedx.model.model_card.EnergyMeasure cyclonedx.model.model_card.Co2Measure cyclonedx.model.model_card.EnergySource cyclonedx.model.model_card.EnergyProvider cyclonedx.model.model_card.EnergyConsumption cyclonedx.model.model_card.Considerations cyclonedx.model.model_card.ModelCard Module Contents --------------- .. py:class:: MachineLearningApproach Bases: :py:obj:`str`, :py:obj:`enum.Enum` Enumeration for `machineLearningApproachType`. Values are stable across 1.5–1.7. .. py:attribute:: SUPERVISED :value: 'supervised' .. py:attribute:: UNSUPERVISED :value: 'unsupervised' .. py:attribute:: REINFORCEMENT_LEARNING :value: 'reinforcement-learning' .. py:attribute:: SEMI_SUPERVISED :value: 'semi-supervised' .. py:attribute:: SELF_SUPERVISED :value: 'self-supervised' .. py:class:: Approach(*, type: Optional[MachineLearningApproach] = None) Container for the `approach` element within `modelParameters`. .. py:property:: type :type: Optional[MachineLearningApproach] .. py:class:: InputOutputMLParameters(*, format: str) Definition for items under `modelParameters.inputs[]` and `outputs[]`. .. py:property:: format :type: str .. py:class:: ModelParameters(*, approach: Optional[Approach] = None, task: Optional[str] = None, architecture_family: Optional[str] = None, model_architecture: Optional[str] = None, datasets: Optional[collections.abc.Iterable[Any]] = None, inputs: Optional[collections.abc.Iterable[InputOutputMLParameters]] = None, outputs: Optional[collections.abc.Iterable[InputOutputMLParameters]] = None) `modelParameters` block within `modelCard`. .. py:property:: approach :type: Optional[Approach] .. py:property:: task :type: Optional[str] .. py:property:: architecture_family :type: Optional[str] .. py:property:: model_architecture :type: Optional[str] .. py:property:: inputs :type: SortedSet[InputOutputMLParameters] .. py:property:: outputs :type: SortedSet[InputOutputMLParameters] .. py:class:: ConfidenceInterval(*, lower_bound: Optional[str] = None, upper_bound: Optional[str] = None) Confidence interval with lower/upper bounds. .. py:property:: lower_bound :type: Optional[str] .. py:property:: upper_bound :type: Optional[str] .. py:class:: PerformanceMetric(*, type: Optional[str] = None, value: Optional[str] = None, slice: Optional[str] = None, confidence_interval: Optional[ConfidenceInterval] = None) A single performance metric entry. .. py:property:: type :type: Optional[str] .. py:property:: value :type: Optional[str] .. py:property:: slice :type: Optional[str] .. py:property:: confidence_interval :type: Optional[ConfidenceInterval] .. py:class:: Graphic(*, name: Optional[str] = None, image: Optional[cyclonedx.model.AttachedText] = None) Graphic entry with optional name and image (AttachedText). .. py:property:: name :type: Optional[str] .. py:property:: image :type: Optional[cyclonedx.model.AttachedText] .. py:class:: GraphicsCollection(*, description: Optional[str] = None, collection: Optional[collections.abc.Iterable[Graphic]] = None) A collection of graphics with optional description. .. py:property:: description :type: Optional[str] .. py:property:: collection :type: SortedSet[Graphic] .. py:class:: QuantitativeAnalysis(*, performance_metrics: Optional[collections.abc.Iterable[PerformanceMetric]] = None, graphics: Optional[GraphicsCollection] = None) `quantitativeAnalysis` block within `modelCard`. .. py:property:: performance_metrics :type: SortedSet[PerformanceMetric] .. py:property:: graphics :type: Optional[GraphicsCollection] .. py:class:: EthicalConsideration(*, name: Optional[str] = None, mitigation_strategy: Optional[str] = None) Entry in `ethicalConsiderations` with name and mitigation strategy. .. py:property:: name :type: Optional[str] .. py:property:: mitigation_strategy :type: Optional[str] .. py:class:: FairnessAssessment(*, group_at_risk: Optional[str] = None, benefits: Optional[str] = None, harms: Optional[str] = None, mitigation_strategy: Optional[str] = None) Entry in `fairnessAssessments`. .. py:property:: group_at_risk :type: Optional[str] .. py:property:: benefits :type: Optional[str] .. py:property:: harms :type: Optional[str] .. py:property:: mitigation_strategy :type: Optional[str] .. py:class:: EnvironmentalConsiderations(*, energy_consumptions: Optional[collections.abc.Iterable[EnergyConsumption]] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = 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`. .. py:property:: energy_consumptions :type: SortedSet[EnergyConsumption] .. py:property:: properties :type: SortedSet[Property] .. py:class:: EnergyActivity Bases: :py:obj:`str`, :py:obj:`enum.Enum` Enumeration for lifecycle activity in `energyConsumption.activity` (1.6+). .. py:attribute:: DESIGN :value: 'design' .. py:attribute:: DATA_COLLECTION :value: 'data-collection' .. py:attribute:: DATA_PREPARATION :value: 'data-preparation' .. py:attribute:: TRAINING :value: 'training' .. py:attribute:: FINE_TUNING :value: 'fine-tuning' .. py:attribute:: VALIDATION :value: 'validation' .. py:attribute:: DEPLOYMENT :value: 'deployment' .. py:attribute:: INFERENCE :value: 'inference' .. py:attribute:: OTHER :value: 'other' .. py:class:: EnergyMeasure(*, value: float, unit: str = 'kWh') A measure of energy. Schema `energyMeasure` (1.6+): value + unit (kWh). .. py:property:: value :type: float .. py:property:: unit :type: str .. py:class:: Co2Measure(*, value: float, unit: str = 'tCO2eq') A measure of CO2. Schema `co2Measure` (1.6+): value + unit (tCO2eq). .. py:property:: value :type: float .. py:property:: unit :type: str .. py:class:: EnergySource Bases: :py:obj:`str`, :py:obj:`enum.Enum` Enumeration for provider `energySource` (1.6+). .. py:attribute:: COAL :value: 'coal' .. py:attribute:: OIL :value: 'oil' .. py:attribute:: NATURAL_GAS :value: 'natural-gas' .. py:attribute:: NUCLEAR :value: 'nuclear' .. py:attribute:: WIND :value: 'wind' .. py:attribute:: SOLAR :value: 'solar' .. py:attribute:: GEOTHERMAL :value: 'geothermal' .. py:attribute:: HYDROPOWER :value: 'hydropower' .. py:attribute:: BIOFUEL :value: 'biofuel' .. py:attribute:: UNKNOWN :value: 'unknown' .. py:attribute:: OTHER :value: 'other' .. py:class:: EnergyProvider(*, organization: cyclonedx.model.contact.OrganizationalEntity, energy_source: EnergySource, energy_provided: EnergyMeasure, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, description: Optional[str] = None, external_references: Optional[collections.abc.Iterable[cyclonedx.model.ExternalReference]] = None) Energy provider per schema `energyProvider` (1.6+). .. py:property:: description :type: Optional[str] .. py:property:: organization :type: cyclonedx.model.contact.OrganizationalEntity .. py:property:: energy_source :type: EnergySource .. py:property:: energy_provided :type: EnergyMeasure .. py:property:: external_references :type: SortedSet[ExternalReference] .. py:property:: bom_ref :type: cyclonedx.model.bom_ref.BomRef .. py:class:: EnergyConsumption(*, activity: EnergyActivity, energy_providers: collections.abc.Iterable[EnergyProvider], activity_energy_cost: EnergyMeasure, co2_cost_equivalent: Optional[Co2Measure] = None, co2_cost_offset: Optional[Co2Measure] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = None) Energy consumption entry. Matches schema `energyConsumption` (1.6+). .. py:property:: activity :type: EnergyActivity .. py:property:: energy_providers :type: SortedSet[EnergyProvider] .. py:property:: activity_energy_cost :type: EnergyMeasure .. py:property:: co2_cost_equivalent :type: Optional[Co2Measure] .. py:property:: co2_cost_offset :type: Optional[Co2Measure] .. py:property:: properties :type: SortedSet[Property] .. py:class:: Considerations(*, users: Optional[collections.abc.Iterable[str]] = None, use_cases: Optional[collections.abc.Iterable[str]] = None, technical_limitations: Optional[collections.abc.Iterable[str]] = None, performance_tradeoffs: Optional[collections.abc.Iterable[str]] = None, ethical_considerations: Optional[collections.abc.Iterable[EthicalConsideration]] = None, environmental_considerations: Optional[EnvironmentalConsiderations] = None, fairness_assessments: Optional[collections.abc.Iterable[FairnessAssessment]] = None) `considerations` block within `modelCard`. .. py:property:: users :type: SortedSet[str] .. py:property:: use_cases :type: SortedSet[str] .. py:property:: technical_limitations :type: SortedSet[str] .. py:property:: performance_tradeoffs :type: SortedSet[str] .. py:property:: ethical_considerations :type: SortedSet[EthicalConsideration] .. py:property:: environmental_considerations :type: Optional[EnvironmentalConsiderations] .. py:property:: fairness_assessments :type: SortedSet[FairnessAssessment] .. py:class:: ModelCard(*, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, model_parameters: Optional[ModelParameters] = None, quantitative_analysis: Optional[QuantitativeAnalysis] = None, considerations: Optional[Considerations] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = 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) .. py:property:: model_parameters :type: Optional[ModelParameters] .. py:property:: quantitative_analysis :type: Optional[QuantitativeAnalysis] .. py:property:: considerations :type: Optional[Considerations] .. py:property:: properties :type: 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` .. py:property:: bom_ref :type: cyclonedx.model.bom_ref.BomRef