Skip to main content

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

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

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.3.9.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.3.9-py3-none-win_arm64.whl (5.2 MB view details)

Uploaded Python 3Windows ARM64

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

Uploaded Python 3Windows x86-64

airom-0.3.9-py3-none-musllinux_1_2_x86_64.whl (5.7 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

airom-0.3.9-py3-none-musllinux_1_2_aarch64.whl (5.1 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

airom-0.3.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

airom-0.3.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.1 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

airom-0.3.9-py3-none-macosx_10_9_x86_64.whl (5.8 MB view details)

Uploaded Python 3macOS 10.9+ x86-64

File details

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

File metadata

  • Download URL: airom-0.3.9.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.3.9.tar.gz
Algorithm Hash digest
SHA256 b421942c92edbf273edee124ae67ad9185728eb8542548d6ea922d0ae716f650
MD5 69470e01e1d466049f9cb5e8fb89c2e3
BLAKE2b-256 5b222fc95f185df50a380ac0ad3c51a79bacb8fde64777ed3488ef96c08eeb41

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.9-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.3.9-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 df1f041abbe5df2db690cc5e1d8c35be9477642cf25f97aaa2128fae418982d5
MD5 82898cfdd599e4f0687fc355a1d9fb6a
BLAKE2b-256 242f076454042ded1b5adffe92f84036be30d3fd682e11943598466470fa0f80

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.9-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.3.9-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 bb3630129ad392b462660edfa4d3637b2c8fe3df7a9281ef2560e893146287c7
MD5 dfe6f13e0932a63212e324987a36c06f
BLAKE2b-256 fd8aa3d728eb77655b13d230e09b5b4676d187b7751d80a7e17a282fa4086992

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.9-py3-none-musllinux_1_2_x86_64.whl
  • Upload date:
  • Size: 5.7 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.3.9-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 59547b394f11c5bb2d81f4a9d2f915db61ed97dcadb6ed60ec0c069db942bd83
MD5 6c5c5e22a09a1114eaeebc77ef5b5fe3
BLAKE2b-256 1f03cc13a135f8e4b43e352ec38c8f8be26f1fa0bec9b5c666a66c329f05226f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.9-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 906b0934c52c4188832d82c22b721869d492b6d180e887cf571bf68bbb522857
MD5 02b740912de892477015af5373bf7461
BLAKE2b-256 8135ee9df962773c50211b1521447507e38479f7b45ed668d4c0b1fe63b54e77

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2b2ba2fcea9cd6bcb65f9e5a45a25b2eab3a88388f49edf99b3e04e377b9ae5d
MD5 d691364617ecf15a8d215a1ec0e1a51d
BLAKE2b-256 d50146f29fa0f03b149156b4260d5cdea9e0a94d56e35f5c245d0e166990663a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4d8922c076c490c029319b81072a11265c33b1614af1023c19d18530f90860f5
MD5 e9ff8b3739040f4bc5fd02d32b795652
BLAKE2b-256 a583159fc56a0a2f554cae22b09f6b3cb5da3a1a7cdb6c4a96333cf6b4140e6b

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.9-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.3.9-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 04c3a4ff7ddc0574db84f316f6aa7f12f9d260cdab33408c93b7e9a99c8ddf00
MD5 85e9374b144a32f48ba2f337ca964e21
BLAKE2b-256 b0a149e8527ea3c1eecbf824a24706489e253aa4514ff5d153fd1bdb2a19bb73

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.9-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 ec33e9611c94d500a06ef7a8e66ece76ffa701bc2eeef95cd7aab0c074eab9e1
MD5 6dc525421033c846b318357c02678466
BLAKE2b-256 d8b147cef953df90e9635b978642791a4b2c2f2271fe08a65beef55001d38956

See more details on using hashes here.

Provenance

The following attestation bundles were made for airom-0.3.9-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.

Supported by

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