Package: mlbomdoc
MLBOMDocMLBOMDOC is a human-readable document generator for an ML-BOM (ML Bill of Materials). MLBOMs document Machine Learning model components
which are typically contained within an SBOM (Software Bill of Materials). MLBOMs are supported forCycloneDX.InstallationTo install use the following command:pip install mlbomdocAlternatively, just clone the repo and install dependencies using the following command:pip install -U -r requirements.txtThe tool requires Python 3 (3.8+). It is recommended to use a virtual python environment especially
if you are using different versions of python.virtualenvis a tool for setting up virtual python environments which
allows you to have all the dependencies for the tool set up in a single environment, or have different environments set
up for testing using different versions of Python.Usageusage: mlbomdoc [-h] [-i INPUT_FILE] [--debug] [-f {console,json,markdown,pdf}] [-o OUTPUT_FILE] [-V]

MLBOMdoc generates documentation for a MLBOM.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Input:
  -i INPUT_FILE, --input-file INPUT_FILE
                        Name of MLBOM file

Output:
  --debug               add debug information
  -f {console,json,markdown,pdf}, --format {console,json,markdown,pdf}
                        Output format (default: output to console)
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        output filename (default: output to stdout)OperationThe--input-fileoption is used to specify the MLBOM to be processed. The format of the SBOM is determined according to
the following filename conventions.SBOMFormatFilename extensionCycloneDXJSON.jsonThe--output-fileoption is used to control the destination of the output generated by the tool. The
default is to report to the console, but it can also be stored in a file (specified using--output-fileoption).ExampleGiven the following MLBOM (test.json), the following output is produced to the console.NOTEthat the data is purely fictitious in order to demonstrate the capability of the tool.{"$schema":"http://cyclonedx.org/schema/bom-1.5.schema.json","bomFormat":"CycloneDX","specVersion":"1.5","serialNumber":"urn:uuid:997191f5-6c2b-4572-9a73-5e0f2d03cedd","version":1,"metadata":{"timestamp":"2024-01-02T11:02:22Z","tools":{"components":[{"name":"lib4sbom","version":"0.6.0","type":"application"}]},"component":{"type":"application","bom-ref":"CDXRef-DOCUMENT","name":"MLApp"}},"components":[{"type":"library","bom-ref":"1-glibc","name":"glibc","version":"2.15","supplier":{"name":"gnu"},"cpe":"cpe:/a:gnu:glibc:2.15","licenses":[{"license":{"id":"GPL-3.0-only","url":"https://www.gnu.org/licenses/gpl-3.0-standalone.html"}}]},{"type":"operating-system","bom-ref":"2-almalinux","name":"almalinux","version":"9.0","supplier":{"name":"alma"},"cpe":"cpe:/o:alma:almalinux:9.0","licenses":[{"license":{"id":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}}]},{"type":"library","bom-ref":"3-glibc","name":"glibc","version":"2.29","supplier":{"name":"gnu"},"cpe":"cpe:/a:gnu:glibc:2.29","licenses":[{"license":{"id":"GPL-3.0-only","url":"https://www.gnu.org/licenses/gpl-3.0-standalone.html"}}],"properties":[{"name":"language","value":"C"}]},{"type":"library","bom-ref":"4-tomcat","name":"tomcat","version":"9.0.46","supplier":{"name":"apache"},"cpe":"cpe:/a:apache:tomcat:9.0.46","licenses":[{"license":{"id":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}}]},{"type":"machine-learning-model","bom-ref":"5-resnet-50","name":"resnet-50","version":"1.5","supplier":{"name":"microsoft"},"description":"ResNet (Residual Network) is a convolutional neural network that democratized the concepts of residual learning and skip connections. This enables to train much deeper models.","licenses":[{"license":{"id":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}}],"modelCard":{"bom-ref":"5-resnet-50-model","modelParameters":{"approach":{"type":"supervised"},"task":"classification","architectureFamily":"Convolutional neural network","modelArchitecture":"ResNet-50","datasets":[{"type":"dataset","name":"ImageNet","contents":{"url":"https://huggingface.co/datasets/imagenet-1k"},"classification":"public","sensitiveData":"no personal data","description":"ILSVRC 2012, commonly known as \"ImageNet\" is an image dataset organized according to the WordNet hierarchy. Each meaningful concept in WordNet, possibly described by multiple words or word phrases, is called a \"synonym set\" or \"synset\". There are more than 100,000 synsets in WordNet, majority of them are nouns (80,000+). ImageNet aims to provide on average 1000 images to illustrate each synset. Images of each concept are quality-controlled and human-annotated.","governance":{"owners":[{"organization":{"name":"microsoft"},"contact":{"email":"sales@microsoft.com"}},{"organization":{"name":"microsoft"},"contact":{"email":"consulting@microsoft.com"}}]}}],"inputs":[{"format":"image"}],"outputs":[{"format":"image class"}]},"quantitativeAnalysis":{"performanceMetrics":[{"type":"CPU","value":"10%","confidenceInterval":{"lowerBound":"8","upperBound":"12"}}],"graphics":{"description":"Test data","collection":[{"name":"cat","image":{"contentType":"text/plain","encoding":"base64","content":"cat.jpg"}},{"name":"dog","image":{"contentType":"text/plain","encoding":"base64","content":"dog.jpg"}}]}},"considerations":{"users":["Researcher"],"technicalLimitations":["To be used in the EU.","To be used in the UK."],"ethicalConsiderations":[{"name":"User from prohibited location","mitigationStrategy":"Use geolocation to validate source of request."}]},"properties":[{"name":"num_channels","value":"3"}]}}]}The following commands will generate a summary of the contents of the MLBOM to the console.mlbomdoc--inputtest.json╭───────────────╮
│MLBOMSummary│
╰───────────────╯
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃Item┃Details┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│MLBOMFile│test.json│
│MLBOMType│cyclonedx│
│Version│1.5│
│Name│MLApp│
│Creator│tool:lib4sbom#0.6.0│
│Created│2024-01-02T11:02:22Z│
└────────────┴──────────────────────────────────────────────────────────────┘

╭───────────────────────────╮
│ModelDetails-resnet-50│
╰───────────────────────────╯
┏━━━━━━━━━━┳━━━━━━━━━━━━┓
┃Item┃Value┃
┡━━━━━━━━━━╇━━━━━━━━━━━━┩
│Version│1.5│
│Supplier│microsoft│
│License│Apache-2.0│
└──────────┴────────────┘
╭──────────────────╮
│ModelParameters│
╰──────────────────╯
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃Parameter┃Value┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│Approach│supervised│
│Task│classification│
│ArchitectureFamily│Convolutionalneuralnetwork│
│ModelArchitecture│ResNet-50│
│Input│image│
│Output│imageclass│
└─────────────────────┴──────────────────────────────┘
╭───────────────╮
│ModelDataset│
╰───────────────╯
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃Parameter┃Value┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│Type│dataset│
│ContentsURL│https://huggingface.co/datasets/imagenet-1k│
│Classification│public│
│SensitiveData│nopersonaldata│
│Description│ILSVRC2012,commonlyknownas"ImageNet"isanimagedatasetorganizedaccordingtotheWordNethierarchy.EachmeaningfulconceptinWordNet,possiblydescribedbymultiplewordsor│
││wordphrases,iscalleda"synonym set"or"synset".Therearemorethan100,000synsetsinWordNet,majorityofthemarenouns(80,000+).ImageNetaimstoprovideonaverage1000│
││imagestoillustrateeachsynset.Imagesofeachconceptarequality-controlledandhuman-annotated.│
└────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╭────────────────────╮
│DatasetGovernance│
╰────────────────────╯
┏━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃Category┃Organization┃Contact┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│Owner│microsoft│sales@microsoft.com│
│Owner│microsoft│consulting@microsoft.com│
└──────────┴──────────────┴──────────────────────────┘
╭───────────────────────╮
│QuantitativeAnalysis│
╰───────────────────────╯
╭─────────────────────╮
│PerformanceMetrics│
╰─────────────────────╯
┏━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃Type┃Value┃Slice┃LowerBOund┃UpperBound┃
┡━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│CPU│10%││8│12│
└──────┴───────┴───────┴─────────────┴─────────────┘
╭──────────────────────╮
│Graphics-Testdata│
╰──────────────────────╯
┏━━━━━━┳━━━━━━━━━┓
┃Name┃Content┃
┡━━━━━━╇━━━━━━━━━┩
│cat│cat.jpg│
│dog│dog.jpg│
└──────┴─────────┘
╭────────────────╮
│Considerations│
╰────────────────╯
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃Category┃Value┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│Users│Researcher│
│TechnicalLimitations│TobeusedintheEU.│
│TechnicalLimitations│TobeusedintheUK.│
│EthicalConsiderations│Userfromprohibitedlocation│
│EthicalConsiderations-MitigationStrategy│Usegeolocationtovalidatesourceofrequest.│
└──────────────────────────────────────────────┴────────────────────────────────────────────────┘
╭────────────╮
│Properties│
╰────────────╯
┏━━━━━━━━━━━━━━┳━━━━━━━┓
┃Name┃Value┃
┡━━━━━━━━━━━━━━╇━━━━━━━┩
│num_channels│3│
└──────────────┴───────┘LicenceLicenced under the Apache 2.0 Licence.LimitationsThe tool has the following limitationsInvalid SBOMs will result in unpredictable results.Feedback and ContributionsBugs and feature requests can be made via GitHub Issues.