airom — Python SDK

Python SDK for AIROM, the open-source AI Bill of Materials (AIBOM) scanner. Discover AI assets — models, prompts, datasets, embeddings, vector databases, frameworks, serving infrastructure — across code, containers, and Kubernetes, and get them back as typed Python objects.

pip install airom

This installs both the airom command and the Python library — the wheel ships the scanner binary itself into your environment's bin/, so there is nothing else to install:

$ airom --version
airom 0.4.4

$ airom fs ./my-app -o table          # the CLI, globally

Quick start

import airom

inv = airom.fs("./my-app", min_confidence=0.8)

for c in inv.by_kind(airom.ComponentKind.HOSTED_LLM):
    print(c.name, c.provider.or_default("-"), c.confidence)
    for occ in c.evidence.occurrences:
        print(f"   {occ.location.path}:{occ.location.line}  [{occ.detector_id}]")

gpt-4.1 openai 0.87
   src/rag.py:88  [rules/openai/model-literal]
   src/agent.py:12  [rules/openai/sdk-import]

Every component carries the evidence that justifies it — that is the point of AIROM, and the SDK hands you all of it.

Scanning

airom.scan("./app")                       # auto-detect: path, git URL, or image ref
airom.fs("./app")                         # a directory tree
airom.repo("https://github.com/o/r")      # remote (shallow clone) or a local worktree
airom.image(input="img.tar")              # docker save -o img.tar <ref>
airom.k8s(manifests="./deploy")           # offline: enumerate workload images
airom.version()                           # the underlying binary's ToolInfo

Common keyword args mirror the CLI flags: select, rules, ignore, min_confidence, max_file_size, io_budget, parallel, no_cache, cache_dir, offline, stats, plus binary, timeout, and cwd. None leaves the tool's own default in place — the SDK never invents defaults.

min_confidence=0.8 is the practical high-signal filter: on general-purpose directories, extension-only dataset detection and keyword-only generation-param detection emit low-confidence (0.5–0.6) noise. Note the application root always survives the filter — it is the scan target, not a finding.

select tokens are detector IDs or tags, not languages — "-dataset/file", not "python". Run airom detectors list (or airom.raw(["detectors", "list"])) to see them.

Not wired yet: pulling an image from a live registry/daemon, and live-cluster Kubernetes scanning. Both fail with a clear error. Use image(input=...) / an OCI layout and k8s(manifests=...) today.

Tri-state fields

version, provider, download_location and release_time are tri-state, and the SDK preserves the distinction rather than collapsing it into None:

JSON Meaning Opt
key omitted does not apply Presence.ABSENT
null applies, but undetermined (SPDX NOASSERTION) Presence.UNKNOWN
a value known Presence.KNOWN 
c.version.known           # bool — only True when a real value is present
c.version.or_none()       # value, or None (collapses absent and unknown)
c.version.or_default("-") # value, or your fallback
c.version.presence        # the full distinction, when you need it

Navigating the graph

inv.components                  # sorted, deterministic
inv.by_kind("vector-db", "framework")
inv.get("airom:1f3a9b2c4d5e6f70")
inv.application                 # the scan-root component
inv.edges_from(c.id)            # typed, evidenced relationships
inv.unknowns                    # "looked relevant, could not process" — honesty channel
inv.stats.files_walked          # requires stats=True
len(inv); [c for c in inv]      # Inventory is sized and iterable

CI gating

A fail_on match is a verdict, not an error — the scan succeeded and the AIBOM is complete, so it is reported rather than raised:

res = airom.execute(
    ["fs", "./app"],
    options=airom.ScanOptions(fail_on="hosted-llm&confidence>=0.9", exit_code=7),
)
if res.policy_matched:
    raise SystemExit(res.exit_code)

Often you don't need fail_on at all — you have the whole graph, so gate in Python:

risky = [c for c in inv if c.model and c.model.pickle_risk]
if risky:
    raise SystemExit(f"unsafe pickle globals in: {[c.name for c in risky]}")

Errors

Exception Raised when
BinaryNotFoundError the airom executable could not be located
ScanError a fatal scan failure (exit 2): unreadable target, clone failure, bad flags
OutputError no parseable AIBOM, or an unsupported schemaVersion

Detector errors are not exceptions: they degrade to inv.unknowns records and the scan still succeeds. That is AIROM's degrade-by-default contract, and the SDK preserves it.

The binary

The SDK shells out to the airom binary and decodes its native JSON — the lossless superset every other format (CycloneDX, SARIF, YAML, table) projects from. Resolution order:

  1. the binary= argument
  2. a copy bundled in the wheel (airom/_bin/airom)
  3. $AIROM_BINARY
  4. airom on PATH

Platform wheels bundle the binary as a script, so pip installs it into the environment's bin/ (Scripts\ on Windows): pip install airom gives you a working airom command on PATH and the importable library, with no Python shim in between. In a virtualenv it is on PATH as soon as the venv is active; pipx install airom or pip install --user airom puts it on PATH globally.

The library resolves the binary without relying on PATH at all (it consults the environment's scripts dir directly), so import airom works even from an unactivated venv's interpreter.

Platforms with no wheel

Wheels are published for macOS (Intel + Apple Silicon), Linux (x86-64 + arm64, glibc + musl), and Windows (x86-64 + arm64). Every one is installed and executed on the platform it targets before it is published; see the smoke jobs in release-pypi.yml.

Anywhere else, pip falls back to the sdist, which ships the Python library and no binary — and cannot build one, since it does not contain the Go module. Rather than install successfully and leave you without a scanner, that build now fails and says so. To proceed, either install the binary for your platform from the releases page and put it on your PATH, or take the library alone:

AIROM_SKIP_BUNDLE=1 pip install airom

The second form is the right one when you already run the standalone binary and only want import airom. Resolution then falls through to $AIROM_BINARY or airom on PATH.

Development

cd sdk/python
pip install -e ".[dev]"
pytest            # builds the binary from the checkout and tests against it
mypy && ruff check .

The suite runs against the real binary, not mocks: a wrapper tested only against mocks proves nothing about the contract it wraps.

Building a wheel needs the Go toolchain (the build hook compiles the binary with CGO_ENABLED=0) and fails without it, because a wheel with no binary installs no airom command. Set AIROM_SKIP_BUNDLE=1 for a pure-Python wheel on purpose.

Publishing

Releases are published by .github/workflows/release-pypi.yml using PyPI Trusted Publishing (OIDC): GitHub Actions authenticates to PyPI directly, so there is no API token stored as a secret, and none to leak or rotate.

One-time setup

On pypi.org/manage/account/publishing, add a pending publisher:

Field Value
PyPI project name airom
Owner airomhq
Repository name airom
Workflow name release-pypi.yml
Environment (leave blank)

That is all — no secret is added to GitHub.

Cutting a release

The workflow runs on every push to main that touches the SDK or the scanner, but publishes only when the version is new: PyPI permanently refuses to re-upload a version (even a deleted one), so the workflow compares __version__ against the index and skips cleanly if it is already there.

So a release is exactly one deliberate act:

# sdk/python/src/airom/__init__.py
__version__ = "0.1.0"     # bump, commit, merge to main -> published

Publishing is irreversible: a version number is burned forever once used, and yanking does not free it. Test the whole path first with the manual workflow_dispatch run against TestPyPI (which needs its own pending publisher at test.pypi.org).

License

Apache-2.0, same as AIROM.

Project links

Data verified by PyPI on Aug 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for airom from gravatar.com airom

Credits

Author: AIROM Authors

GitHub Statistics

Data verified by PyPI on Aug 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Tags

ai-bill-of-materials ai-governance ai-security aibom compliance cyclonedx devsecops llm llm-security ml-bom ml-security mlsecops model-scanning nist-ai-rmf owasp sarif sbom security supply-chain-security vulnerability-scanner

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

airom-0.4.4.tar.gz (26.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

airom-0.4.4-py3-none-win_arm64.whl (5.3 MB view details)

Uploaded Python 3Windows ARM64

airom-0.4.4-py3-none-win_amd64.whl (6.0 MB view details)

Uploaded Python 3Windows x86-64

airom-0.4.4-py3-none-musllinux_1_2_x86_64.whl (5.8 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

airom-0.4.4-py3-none-musllinux_1_2_aarch64.whl (5.2 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

airom-0.4.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.8 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

airom-0.4.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

airom-0.4.4-py3-none-macosx_11_0_arm64.whl (5.4 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

airom-0.4.4-py3-none-macosx_10_9_x86_64.whl (5.9 MB view details)

Uploaded Python 3macOS 10.9+ x86-64

File details

Details for the file airom-0.4.4.tar.gz.

File metadata

  • Download URL: airom-0.4.4.tar.gz
  • Upload date:
  • Size: 26.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for airom-0.4.4.tar.gz
Algorithm Hash digest
SHA256 9b1431bacc631cf30deac00d600cbde4306443430d376f98b3052fe1ddefd0a2
MD5 9fa91e4b160bbab2c29b5b589b585733
BLAKE2b-256 61ec1e79fd2d4c67ac51cf8767ee6f0a45bf26a7997647b4c342f34d371b5121

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4.tar.gz:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-win_arm64.whl.

File metadata

  • Download URL: airom-0.4.4-py3-none-win_arm64.whl
  • Upload date:
  • Size: 5.3 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for airom-0.4.4-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 c6c3d3393a2f226c98b303809a2859b71322be9b31838861dd2251e790180814
MD5 e5b75311d60ae57172f2fcf9fc495390
BLAKE2b-256 da6caa5f43e0d126af4ae97b879f294f227e02c7f27ce85a4978db050756985d

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-win_arm64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-win_amd64.whl.

File metadata

  • Download URL: airom-0.4.4-py3-none-win_amd64.whl
  • Upload date:
  • Size: 6.0 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for airom-0.4.4-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 9fc2d374eb7c1955473dbcb2493729e2f3b94b14f53eeeb939987167b24995ad
MD5 868eaecbc3d7d46efaebcbf9ece96763
BLAKE2b-256 742da177289861844b6762deb271a36557c792fbbe19d24b9de68bd5f59b4d5d

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-win_amd64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-musllinux_1_2_x86_64.whl.

File metadata

  • Download URL: airom-0.4.4-py3-none-musllinux_1_2_x86_64.whl
  • Upload date:
  • Size: 5.8 MB
  • Tags: Python 3, musllinux: musl 1.2+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for airom-0.4.4-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 e698f9795270e6be9e59c0ee95afe2076680d9dd0260dfefeb9ba347e9e1be69
MD5 2aa0d471f1cedf563a3e773d3d6e2dbd
BLAKE2b-256 3cab5c7fb4091881883016326a6aea3d1d9bcec95f5fbbefd37d7a28ec137576

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-musllinux_1_2_x86_64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for airom-0.4.4-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 ade2eaaf77ee32fea5f8f87c1a6f0218cae9b99af85b27104ea1ca4e22ba086c
MD5 57968f8dd9bdc5c4782eb7b089305052
BLAKE2b-256 7c20bdf096b26b35e96a8b08d1ea3052ddebc0ce4da9f76f1a7b9893aa62681f

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-musllinux_1_2_aarch64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for airom-0.4.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 916f9d6bb7b7b6cdab96e91fa3ded6321cef405a2b047b8c9551cd7e5a694e8a
MD5 f9fc8e4d5721970a5da4e234ce0e20eb
BLAKE2b-256 dd7e870a75a02bf694a63579404676fe22e0832c72e5db790bc92e5a39caa755

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for airom-0.4.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 12cd88d1aebb172b88968361f0d2dfb2ed75882b115b1bc7432a94754a2baf2d
MD5 575d9c14e32b5b1c44b5d38f12a0a121
BLAKE2b-256 0ceb92641d1547b824f5e3af782a86cbd982cb3e25a08f2b61ea28d1e923d86b

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: airom-0.4.4-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 5.4 MB
  • Tags: Python 3, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for airom-0.4.4-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9a5fb731c186974bde15e26b847870aed49f1a9cd592384dc6e3bd4edd4a10aa
MD5 12c40baf263c64d5e4c3783dc9a85770
BLAKE2b-256 b710274c47b2235c65e3b5798efd5bd0318b2fde1caadfa4d1ce256fe8b9dea2

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-macosx_11_0_arm64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file airom-0.4.4-py3-none-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for airom-0.4.4-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 087a36a62cbf219b71f0dd4cde3ae6857aa71dd327f2930ffb3707382a487041
MD5 9a057f898b00c8cc79b2c35e9b7dcae2
BLAKE2b-256 e1b8bf5fbbc501c41e8c0780e58c604d53650bf2f6f8913872ff7c618028973d

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.4-py3-none-macosx_10_9_x86_64.whl:

Publisher: release-pypi.yml on airomhq/airom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.4.4 This release

9 files

0.4.3

9 files

0.4.2

9 files

0.4.1

9 files

0.4.0

9 files

0.3.9

9 files

0.3.8

9 files

0.3.7

8 files

0.3.6

8 files

0.3.5

8 files

0.3.4

8 files

0.3.3

8 files

0.3.2

8 files

0.3.1

8 files

0.3.0

8 files

0.2.2

8 files

0.2.1

8 files

0.2.0

8 files

0.1.9

8 files

0.1.8

8 files

0.1.7

8 files

0.1.6

8 files

0.1.5

8 files

0.1.4

8 files

0.1.3

8 files

0.1.2

8 files

0.1.1

8 files

0.1.0

8 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page