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

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

Installing from an sdist ships no binary — put airom on your PATH (go install github.com/airomhq/airom/cmd/airom@latest, then ensure $(go env GOPATH)/bin is on PATH) or set $AIROM_BINARY.

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). Set AIROM_SKIP_BUNDLE=1 for a pure-Python wheel.

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.6.tar.gz (24.4 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.6-py3-none-win_amd64.whl (5.9 MB view details)

Uploaded Python 3Windows x86-64

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

Uploaded Python 3musllinux: musl 1.2+ x86-64

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

Uploaded Python 3musllinux: musl 1.2+ ARM64

airom-0.3.6-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.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.1 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

airom-0.3.6-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.6.tar.gz.

File metadata

  • Download URL: airom-0.3.6.tar.gz
  • Upload date:
  • Size: 24.4 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.6.tar.gz
Algorithm Hash digest
SHA256 eb52a5e8ce61054f6ba5f742a8db08781d7af534bad4f19a0ef766ebc196223b
MD5 bf54ef85dac4ba931cdb457e7fd3c2fd
BLAKE2b-256 4b0f00d131c4e995f598f75d9f2c735b7aecdd06c2ee7cd6194e356d7df43b92

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.6-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.6-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 db5ed803f5c6f67fe9c9228d9699372cdad445afe4174419a6d15b7a6b00516c
MD5 43bd296d58768a961846a5fbfe296748
BLAKE2b-256 2ab0b4a48997d58125713c773af0a6a9cb5e1354f3119a7c96c180cd213cfe0d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.6-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 6aa6385f14e773784a6228e8c9fa0812935482c6a82c57b9ac9cf830e6cb2ace
MD5 ba7e9391faae0df863fbe7525982ee46
BLAKE2b-256 29aedc45dfb3f4b212953c285661c655c3b2e5ea69c3cd9206348bb80ec78d67

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.6-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 25a0db2605533b35535801e3ac2ca634d1e9259d7793b03114b2ffe29879648e
MD5 025859fbb455ab6c503c50eb40c6e9c0
BLAKE2b-256 aceae7c62fbd083df3dbbce9c2479a8370b1bb6f1680fc94cf3bab5718f60c61

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 58a7a1bd397481e2d0ad49ab9784799bdc971da70a61cff4eb248df5b745f18e
MD5 d678a24f8cba2c6c84e477d2976f7bd7
BLAKE2b-256 3d11104a2e64930d2f44748f5abb2153e5e019f5ff45518de8271cec6ada2d8c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4f42f21a4906a197a6008a91a8255a2fd8adc097f180593540562adb8292bb8b
MD5 f6a09080bf34955c991346b054e813fe
BLAKE2b-256 745c7840718af8dfd7fb299551b0847bd219959a632d3ea1e7838ab5552baa34

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.6-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.6-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 fb782b9c004617d46db62164495ff3a0a22d2569e60520316f484375522ebca6
MD5 7e959f2059125992b53ae5d31725b992
BLAKE2b-256 af5c69c4eeb35156981d32ac318ea3ce09c3fcd8ea28c28f100c8b094dba1023

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.6-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 5c2e6d6e48fb9138f247f40ad01d81ac243d8cd10de41b44588b38f292ceb2c5
MD5 6d7c8a9a12cd489f80d96c6bc0859cc3
BLAKE2b-256 f44992de57ff9bfac5b84769dcf9aa62c29372ebcb52605ce6950b5ea189734f

See more details on using hashes here.

Provenance

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