Metadata-Version: 2.4
Name: ai-bom-generator
Version: 0.1.2
Summary: Local AI/ML bill-of-materials generator
Author: 0disoft
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/0disoft/ai-bom-generator
Project-URL: Repository, https://github.com/0disoft/ai-bom-generator
Project-URL: Issues, https://github.com/0disoft/ai-bom-generator/issues
Project-URL: Changelog, https://github.com/0disoft/ai-bom-generator/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/0disoft/ai-bom-generator/releases
Keywords: ai,ai-bom,bill-of-materials,bom,cyclonedx,machine-learning,ml-bom,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5,>=4.25
Dynamic: license-file

# AI-BOM Generator

Status: Draft
Scope: data
Repository Type: cli-tool
Addons: github-action

AI-BOM Generator is a small CLI and optional GitHub Action for producing an AI
bill of materials from a model project directory.

The tool records declared model metadata, discovered `MODEL_CARD.md` paths,
model or checkpoint digests, training-code references, dependency lockfiles,
dataset references, prompt templates, and eval artifact references, then exports
them to CycloneDX JSON 1.7.

It is a generator and evidence reporter. It is not a model registry, scanner,
legal compliance engine, dataset auditor, or AI governance platform.

## Source Files

- AGENTS.md: agent working rules
- CHECKLIST.md: checklist router
- VALIDATION.md: validation names and reporting requirements
- .agents/context-map.md: agent route map
- docs/product/02-spec.md: product source of truth
- docs/cli/command-contract.md: CLI contract source
- docs/github-action/action-contract.md: GitHub Action contract source
- docs/data/pipeline-contract.md: artifact collection and export contract
- docs/: design, operations, architecture, and engineering standards

## Repository Shape Notes

- cli-tool: This repository type owns command behavior, arguments, flags, config loading, exit codes, terminal output, JSON output, runtime compatibility, and shell integration contracts.
- github-action: This repository type owns action inputs, outputs, permissions, token handling, and runner compatibility.

## MVP Direction

- accept one model directory as input;
- discover in-root `MODEL_CARD.md` paths without copying model-card contents;
- compute SHA-256 digests for model artifacts and checkpoints;
- collect dependency and training-code references from known lockfile or config locations;
- read dataset, prompt, and eval references from explicit config;
- export one initial standards-backed BOM format;
- report missing metadata as warnings without pretending the BOM is complete.

## Quickstart

The current public patch release is `v0.1.2`. It is distributed as a GitHub
repository, GitHub Action, and Python package.

Install the released package from PyPI:

```powershell
python -m pip install ai-bom-generator
ai-bom --help
```

Try the bundled minimal project from a checkout:

```powershell
uv sync --locked
$out = Join-Path ([System.IO.Path]::GetTempPath()) ("ai-bom-example-" + [System.Guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $out | Out-Null
uv run --python 3.12 ai-bom generate examples/minimal-model-project --config examples/minimal-model-project/aibom.toml --format cyclonedx-json-1.7 --output (Join-Path $out "bom.cdx.json") --warning-report (Join-Path $out "warnings.json") --summary (Join-Path $out "summary.json")
Get-ChildItem -LiteralPath $out
```

The same command shape works for your own model project as long as generated
output paths resolve outside the target model directory.

Example `aibom.toml` from `examples/minimal-model-project`:

```toml
schema_version = "1"

[output]
format = "cyclonedx-json-1.7"

[model]
name = "example-model"
version = "0.1.0"
model_card = "MODEL_CARD.md"
license_declared = "NOASSERTION"

[artifacts]
include = ["models/*.safetensors"]

[[dependencies]]
path = "requirements.lock"
type = "pip"

[[datasets]]
name = "example-dataset"
license_declared = "NOASSERTION"
```

The CLI writes a BOM, a warning report, a JSON summary, and a generation
manifest. The manifest is the commit marker for the output set and records path,
size, and SHA-256 entries for the generated JSON files. Missing optional
metadata is reported as machine-readable warnings. Unreadable required files,
invalid config, unsupported exporters, unsafe paths, and invalid generated BOM
output fail with non-zero exit codes. Generated output paths must resolve
outside the target model project directory.

## Current CLI Smoke

```text
ai-bom generate <model-directory> --config <path> --format cyclonedx-json-1.7 --output <bom.json> --warning-report <warnings.json> --summary <summary.json> [--manifest <manifest.json>]
```

## Current GitHub Action Smoke

```yaml
- uses: actions/checkout@v7

- uses: actions/setup-python@v6
  with:
    python-version: "3.12"

- uses: astral-sh/setup-uv@v8.3.1

- id: ai-bom
  uses: 0disoft/ai-bom-generator@v0.1.2
  with:
    model-directory: .
    config: aibom.toml
    warnings: allow

- name: Verify AI-BOM outputs
  shell: bash
  run: |
    set -euo pipefail
    test -s "${{ steps.ai-bom.outputs.bom-path }}"
    test -s "${{ steps.ai-bom.outputs.warning-report-path }}"
    test -s "${{ steps.ai-bom.outputs.summary-path }}"
    test "${{ steps.ai-bom.outputs.status }}" = "success"
```

The action invokes the packaged CLI with `uv run --project`, so consuming
workflows must make Python 3.12 and `uv` available before this action runs. When
`format` or `warnings` inputs are omitted, the action lets the CLI use the
explicit config values and CLI defaults. Generated files are written to explicit
paths when provided, or to a run-unique directory under `RUNNER_TEMP`.
Summary-derived action outputs are published only when the generation manifest
matches the BOM, warning report, and summary files from the current run.

The current implementation validates explicit `aibom.toml` config files against
AI-BOM config schema v1, validates generated CycloneDX JSON 1.7 output against
the vendored official schema, and validates AI-BOM summary/warning contracts in
tests.

## Non-Goals

- no automatic legal license judgment;
- no training-data audit guarantee;
- no vulnerability scanner;
- no model serving runtime;
- no hosted registry;
- no broad "all ML frameworks" promise until fixtures prove it.

## Repository Hygiene

.editorconfig, .gitattributes, and .gitignore are generated to keep line endings,
binary diffs, local files, build outputs, caches, and secret files under control.

## Scope Notes

Runtime floor is Python 3.12, the initial CLI adapter is `argparse`, package
metadata lives in `pyproject.toml`, JSON Schema validation uses `jsonschema`,
the project lockfile is `uv.lock`, explicit config files use `aibom.toml`, the
first exporter is CycloneDX JSON 1.7, strict redaction is the default, and the
repository license is Apache-2.0. The first public MVP release uses immutable
GitHub tags, with `v0.1.2` as the current smoke-tested patch tag and first PyPI
package release. Mutable major action tags, GitHub Marketplace registration,
second exporter priority, automatic config discovery, and model artifact
discovery defaults remain deferred until the repository owner records them in
the source-of-truth documents.
