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.1

$ 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 22, 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 22, 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.1.tar.gz (26.0 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.1-py3-none-win_arm64.whl (5.2 MB view details)

Uploaded Python 3Windows ARM64

airom-0.4.1-py3-none-win_amd64.whl (5.9 MB view details)

Uploaded Python 3Windows x86-64

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

Uploaded Python 3musllinux: musl 1.2+ x86-64

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

Uploaded Python 3musllinux: musl 1.2+ ARM64

airom-0.4.1-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.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

airom-0.4.1-py3-none-macosx_11_0_arm64.whl (5.3 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

airom-0.4.1-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.1.tar.gz.

File metadata

  • Download URL: airom-0.4.1.tar.gz
  • Upload date:
  • Size: 26.0 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.1.tar.gz
Algorithm Hash digest
SHA256 fd70daf9669de219e57be6e0911ba8670d7c67c1a7059a442fff14efedc87bc1
MD5 e7931e940c853ab614bc89b213c3e28d
BLAKE2b-256 f18ec052157cd08a5b63ca6482bca43ce4c5e7f829e931ea9616f795dd752d20

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1.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.1-py3-none-win_arm64.whl.

File metadata

  • Download URL: airom-0.4.1-py3-none-win_arm64.whl
  • Upload date:
  • Size: 5.2 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.1-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 54d22670cad04bac15b06553f730d885b2a35cee972ae5f035d8d803eb036dd0
MD5 2e935d9424541a50e25bbbb2d8c76253
BLAKE2b-256 10be5bf57738d2843f029b6ae450546bea9d8772634c7bc88be56758fefab0c3

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-win_amd64.whl.

File metadata

  • Download URL: airom-0.4.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 5.9 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.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 f8090e2f425260eee1245bd47635b4afd6abfc6a88a156a6ebd391fd1c4a17cb
MD5 aec4b689da4b50d138e7f49084a68e94
BLAKE2b-256 16d3d755364946ed4bc9263d0c0b7f48f22220c0fb5fd4ff21d744f5bc5e197e

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

  • Download URL: airom-0.4.1-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.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 ca319151e05abee61c24d725109de1a25841a3f77d24c5a171b47d51182187b0
MD5 35a4f43d5c449e7ec0ccd28a2c3d6cdd
BLAKE2b-256 2ed359fafb0e036e7caee08996ebdbfe479bd04a121d24b125dc05efc7575433

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for airom-0.4.1-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 0e928a1b0499963e4428eebfd185ef5d5965da3191c88fceaabc5ec6483fff24
MD5 aedbf7985bf8f54211e76fd895ee7c0a
BLAKE2b-256 360aaa15fb10e5bbe99a2fc212fd2446e24696a622d5eb1775fc0a019ed6e6c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for airom-0.4.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6c8fc0f79e1022285aca28b32dc8ae6d9a64e6d66e36d79d943a49c32dfb6d68
MD5 cf986cd9cf81a0719611116558a21ea4
BLAKE2b-256 11f275029574fd071ce915865f246f3c8f4931e3e98d13f3bb8366f589fba93c

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for airom-0.4.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4b7e46606105cb241b82db92f1246caa8a245be27697f02b45a6affdc3f65dd0
MD5 82ff692f7bfff672ee854957bf7d5ccf
BLAKE2b-256 b1f2814471b6b6ce276b7eaca3bd190354be6b66e991150dc1c9e375a80cf8e1

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: airom-0.4.1-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 5.3 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.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 71fb01e8704a640c2f1c9e5b980d0b96ae2966498780af0fab85b3406748a4b1
MD5 50a1a8b6880ca44a5b77d8e665db20e5
BLAKE2b-256 4858ab0af0ac72f26364383782ca2d2622ed05664d9f9c9b06df280579f4ee19

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1-py3-none-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for airom-0.4.1-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 7365123c23bb0acd48a98e2131be0cfe15adfed9c4d5d22cb0be5fdabfbbd737
MD5 4d59eeec46b60ab5007e78d43c104326
BLAKE2b-256 184a6a509dff98fbb7ececfd1820e5abd8e510ea218ef7b4867b2f5ddb2407c8

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.4.1-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.1 This release

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