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

$ 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.7.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.7-py3-none-win_amd64.whl (5.9 MB view details)

Uploaded Python 3Windows x86-64

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

Uploaded Python 3musllinux: musl 1.2+ x86-64

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

Uploaded Python 3musllinux: musl 1.2+ ARM64

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

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

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

File metadata

  • Download URL: airom-0.3.7.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.7.tar.gz
Algorithm Hash digest
SHA256 341ef53f3b2e7527e7e8725ec10deed214cf3309d5d8d1e7c446d28b01f84859
MD5 2a893d9a20ca04ba42d8df109a6ee41e
BLAKE2b-256 dc23d0bc913b53bd7e1ba0d0b5830280dc68135ed54dd0ca72693925c44bdd42

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.7-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.7-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 a80b4049ea33bfd709b0fba2c1430782100664002b7fee41ee8a4a1681a68147
MD5 4242bea20281614d0a382fd4d19f86f4
BLAKE2b-256 6c7ecfc19b8e4b47f1542773f3037460e90eebf04727c1656bc02e2d137c385e

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.7-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.7-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 18140b89dd55301513df677b22d963775a56b6aa6fa27dc961cf91fa654e9c07
MD5 ecf1589589e4718543ecf781a0476102
BLAKE2b-256 b11b100beb9490128e97b0e2b4ded554e36629543b52f886c5911469c0216c3b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.7-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 419b514164a5c4c12eafdb16c1c9b05879e811aeef64fc80119767bf105f78ba
MD5 1cf38dbffa6fcb1fd22f361b02ad5930
BLAKE2b-256 c80faf2506dc354a7e9c6ace7cf7efab915a88084811e27cbd607ed42d4fdf20

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.7-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 38115860814d401e9add2165a99f40f0b5fbaf65c89f04bef7083b5c976a37ad
MD5 9993a909319902cf773cc954e846900d
BLAKE2b-256 30b93498f2587928eea1545df949dce9b58ce6c8bbaca979b1eaf670dd21ddcd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.7-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ef32f9206c140af3556cba02b7448fdc1c6d911413bd16daf62aa8be5ab8f931
MD5 a434200bd5b3b996d537d512e9ab3f5d
BLAKE2b-256 89fb89e7cf597736ed9113bc3e3aef2dacc0d8fdd4e543696bb9ed2274139da4

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: airom-0.3.7-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.7-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8eeac775a45c9e4c0c06623912138b07de4bee7b9139c36e4e89d2a0646b255d
MD5 9b641363e2370b8500aeac66bb390a40
BLAKE2b-256 083c602cb5f2f4d2b8869aa36679a34ead1be56774b952963a132261f8483a4d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for airom-0.3.7-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 79f0a86ec0c46140213fe8d69d0048a7250081c9e4c1986ff07820d83578bd0c
MD5 1526895bc2c876a5b2b6d343226b656f
BLAKE2b-256 f52ed739712e658c3e94c363a224e04fb447507406f3776f587bd706825cc7a2

See more details on using hashes here.

Provenance

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