genai-security-project/aibom-generator

1. Purpose and shape of the repo

This is a Python application for generating AI Bills of Materials (AIBOMs) from Hugging Face model repositories. It has two user-facing modes: a CLI for batch/terminal use and a web app for interactive generation and viewing.

2. Top-level entry points

src/main.py is the web runtime entry point, while src/cli.py is the command-line entry point. Both route into the same underlying domain logic, which keeps generation behavior consistent across UI and automation.

3. Controller layer: interface boundary

src/controllers/cli_controller.py and src/controllers/web_controller.py isolate input handling from business logic. They translate CLI arguments or HTTP form/request data into service calls, then return either a generated AIBOM, an error page, or a downloadable result.

4. Core orchestration service

src/models/service.py appears to be the main application service that coordinates the end-to-end workflow: validate input, retrieve model metadata, extract structured fields, compute scoring, and assemble the final AIBOM payload. This is the central business boundary to draw in an architecture diagram.

5. Metadata extraction subsystem

src/models/extractor.py, src/models/model_file_extractors.py, and src/models/gguf_metadata.py handle the model-specific parsing logic. They support extracting metadata from Hugging Face model cards and repository files, including GGUF-related metadata and other model artifacts.

6. Registry and field mapping

src/models/registry.py and src/models/field_registry.json define how raw model metadata maps into the AIBOM field model. This is the normalization layer that converts heterogeneous source metadata into a consistent internal representation.

7. Schema and validation boundary

src/models/schemas.py plus the bundled JSON schema files in src/schemas/ anchor the output format to CycloneDX BOM 1.6/1.7 and SPDX-related schema constraints. The repo is explicitly standards-driven, so schema validation is part of the architecture rather than just an export detail.

8. Scoring and quality feedback

src/models/scoring.py computes AIBOM completeness scores and likely generates improvement recommendations. This is a secondary analysis path over the extracted metadata, used to surface gaps in the generated bill of materials.

9. Utility services and operational controls

src/utils/ contains cross-cutting helpers: validation, formatting, license detection, summarization, cleanup, rate limiting, captcha, and analytics. These are mostly supporting concerns around reliability, output quality, and abuse prevention, especially for the web-facing side.

10. Presentation layer for the web UI

src/templates/ and src/static/ provide a server-rendered HTML interface with CSS and JavaScript enhancements. The web app produces an interactive result page, an error page, and reusable header/footer includes.

11. External dependencies and data sources

The primary external source is Hugging Face model repositories, from which metadata is extracted. Optional AI-assisted features are implied by the --inference and --summarize CLI flags and the utility modules, suggesting the app can enrich metadata through inference-backed or summarization steps when configured.

12. Docs, tests, and delivery pipeline

docs/aibom-field-mapping/ documents the field mapping logic, which is important for understanding the normalization layer. tests/ provides coverage for extraction, scoring, validation, licensing, PURL construction, and service behavior, while .github/workflows/tests.yml indicates CI enforcement. Packaging and dependency management are Python-native via pyproject.toml, requirements.txt, and uv.lock.