airom 0.1.0__tar.gz

airom-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+_bin/
+*.egg-info/
+dist/
+.pytest_cache/
+__pycache__/

airom-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: airom
+Version: 0.1.0
+Summary: Python SDK for AIROM — the open-source AI Bill of Materials (AIBOM) scanner
+Project-URL: Homepage, https://github.com/airomhq/airom
+Project-URL: Documentation, https://github.com/airomhq/airom/tree/main/docs-site
+Project-URL: Source, https://github.com/airomhq/airom
+Project-URL: Issues, https://github.com/airomhq/airom/issues
+Author: AIROM Authors
+License-Expression: Apache-2.0
+Keywords: ai,aibom,cyclonedx,sarif,sbom,security,supply-chain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# airom — Python SDK
+
+Python SDK for [AIROM](https://github.com/airomhq/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.
+
+```bash
+pip install airom
+```
+
+## Quick start
+
+```python
+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
+
+```python
+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` |
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```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, so `pip install airom` is self-contained. Installing
+from an sdist does not — put `airom` on your `PATH`
+(`go install github.com/airomhq/airom/cmd/airom@latest`) or set `$AIROM_BINARY`.
+
+## Development
+
+```bash
+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`](../../.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](https://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:
+
+```bash
+# sdk/python/src/airom/__init__.py
+__version__ = "0.1.0"     # bump, commit, merge to main -> published
+```
+
+<!-- Version note: a PEP 440 pre-release suffix (.dev0, rc1, …) is NOT installed by
+     `pip install airom` unless the user passes --pre. Use a plain version for a
+     release people are meant to get by default. -->
+
+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](https://test.pypi.org/manage/account/publishing/)).
+
+## License
+
+Apache-2.0, same as AIROM.

airom-0.1.0/README.md

@@ -0,0 +1,202 @@
+# airom — Python SDK
+
+Python SDK for [AIROM](https://github.com/airomhq/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.
+
+```bash
+pip install airom
+```
+
+## Quick start
+
+```python
+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
+
+```python
+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` |
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```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, so `pip install airom` is self-contained. Installing
+from an sdist does not — put `airom` on your `PATH`
+(`go install github.com/airomhq/airom/cmd/airom@latest`) or set `$AIROM_BINARY`.
+
+## Development
+
+```bash
+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`](../../.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](https://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:
+
+```bash
+# sdk/python/src/airom/__init__.py
+__version__ = "0.1.0"     # bump, commit, merge to main -> published
+```
+
+<!-- Version note: a PEP 440 pre-release suffix (.dev0, rc1, …) is NOT installed by
+     `pip install airom` unless the user passes --pre. Use a plain version for a
+     release people are meant to get by default. -->
+
+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](https://test.pypi.org/manage/account/publishing/)).
+
+## License
+
+Apache-2.0, same as AIROM.

airom-0.1.0/hatch_build.py

@@ -0,0 +1,86 @@
+"""Build hook: compile the ``airom`` binary into the wheel.
+
+Wheels are platform-specific because they carry a compiled Go binary, so this
+hook also stamps the wheel tag. It needs the Go toolchain and the repository
+checkout (the module root is three levels up from this file).
+
+Opt out with ``AIROM_SKIP_BUNDLE=1`` — the resulting wheel is pure-Python and
+falls back to ``$AIROM_BINARY`` or ``airom`` on ``PATH`` at runtime.
+
+Cross-compile by setting ``GOOS``/``GOARCH`` (both are forwarded to ``go
+build``); set ``AIROM_WHEEL_TAG`` to override the platform tag when doing so.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import sysconfig
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+HERE = Path(__file__).parent
+# sdk/python/hatch_build.py -> sdk/python -> sdk -> <repo root>
+REPO_ROOT = HERE.parent.parent
+BIN_DIR = HERE / "src" / "airom" / "_bin"
+
+
+def _exe_name() -> str:
+    goos = os.environ.get("GOOS") or sys.platform
+    return "airom.exe" if goos in ("win32", "windows") else "airom"
+
+
+def _wheel_tag() -> str:
+    if tag := os.environ.get("AIROM_WHEEL_TAG"):
+        return tag
+    # Not pure-Python, but ABI-independent: the payload is a standalone binary,
+    # so the wheel works on any CPython for this platform.
+    plat = sysconfig.get_platform().replace("-", "_").replace(".", "_")
+    return f"py3-none-{plat}"
+
+
+class AiromBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        if self.target_name != "wheel":
+            return
+
+        if os.environ.get("AIROM_SKIP_BUNDLE"):
+            self.app.display_waiting("AIROM_SKIP_BUNDLE set — building a pure-Python wheel")
+            return
+
+        if not (REPO_ROOT / "go.mod").is_file():
+            self.app.display_warning(
+                f"no go.mod under {REPO_ROOT} — building without a bundled binary "
+                "(the SDK will fall back to $AIROM_BINARY or PATH)"
+            )
+            return
+
+        if shutil.which("go") is None:
+            self.app.display_warning(
+                "the Go toolchain was not found — building without a bundled binary "
+                "(set AIROM_SKIP_BUNDLE=1 to silence this)"
+            )
+            return
+
+        BIN_DIR.mkdir(parents=True, exist_ok=True)
+        out = BIN_DIR / _exe_name()
+
+        env = dict(os.environ)
+        env["CGO_ENABLED"] = "0"  # invariant P8: the release binary is always static
+
+        cmd = ["go", "build", "-trimpath", "-ldflags", "-s -w", "-o", str(out), "./cmd/airom"]
+        self.app.display_info(f"bundling airom: {' '.join(cmd)} (in {REPO_ROOT})")
+        try:
+            subprocess.run(cmd, cwd=REPO_ROOT, env=env, check=True)
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(f"failed to build the airom binary: {e}") from e
+
+        out.chmod(0o755)
+        build_data["pure_python"] = False
+        build_data["tag"] = _wheel_tag()
+        build_data["artifacts"].append("src/airom/_bin/*")

airom-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "airom"
+dynamic = ["version"]
+description = "Python SDK for AIROM — the open-source AI Bill of Materials (AIBOM) scanner"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "AIROM Authors" }]
+keywords = ["aibom", "sbom", "ai", "security", "cyclonedx", "sarif", "supply-chain"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+# Deliberately dependency-free: the SDK is a typed wrapper over a static binary.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/airomhq/airom"
+Documentation = "https://github.com/airomhq/airom/tree/main/docs-site"
+Source = "https://github.com/airomhq/airom"
+Issues = "https://github.com/airomhq/airom/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "mypy>=1.8", "ruff>=0.5"]
+
+[tool.hatch.version]
+path = "src/airom/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/airom"]
+# The bundled binary is produced by hatch_build.py; ship it if it is there.
+artifacts = ["src/airom/_bin/*"]
+
+[tool.hatch.build.targets.sdist]
+# The sdist carries no binary — installing from it falls back to $AIROM_BINARY
+# or `airom` on PATH.
+exclude = ["src/airom/_bin"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+packages = ["airom"]
+mypy_path = "src"
+strict = true
+warn_unused_ignores = false