ladex 0.2.1

A bill of lading for AI.

You already require a bill of lading for physical cargo and an SBOM for software. Ladex is the one for AI — it records what AI is aboard your codebase, from whom, and under what terms, captured at the moment the code is written rather than discovered after the fact.

Ladex is a shift-left AI governance tool for developers. When you write an AI-relevant line of code — importing an agent framework, loading a Hugging Face model, calling an inference API, provisioning a GPU node pool in Terraform — Ladex detects it and answers three questions:

1. What is this?  model / dataset / agent framework / vector store / inference API
2. What does it obligate?  EU AI Act Art. 50 disclosure, Annex III high-risk triggers
3. What's auto-verifiable vs. what needs a human?  CVEs and licenses resolve automatically. Training-data provenance and consent basis can't be derived by any scanner — they're flagged UNDOCUMENTED and require a signed human attestation, never a fake green checkmark.

The output is a CycloneDX ML-BOM committed to your repo, diffable in PRs, with signed attestations for the fields no tool can derive.

Ladex records what's aboard; it does not block attacks.

What it does

detect (Python + Jupyter notebooks + Terraform + Kubernetes)
  → enrich    PyPI licenses · OSV CVEs · Hugging Face model cards   (cached, offline-capable)
  → obligate  EU AI Act (Art. 5 bans · Annex III/Art. 8-15 high-risk · Art. 50 · Art. 53 GPAI)
  → BOM       deterministic CycloneDX ML-BOM that diffs cleanly in PRs
  → attest    in-toto/DSSE signature fills an UNDOCUMENTED gap with a verifiable declaration

surfaces:  CLI   +   VS Code (LSP)   +   GitHub PR check   — one shared engine

Install — which one do you need?

Ladex has three surfaces. Install only the one(s) you'll use — they're independent, and none requires another.

The extension only shows AI inline (read-only). Producing the BOM, signing attestations, and running the gate are CLI actions — so if you want those, install the CLI.

Installing the CLI

uv tool install ladex      # isolated + on your PATH (recommended)
ladex --version            # -> ladex 0.2.1

Tip: install it as a tool (uv tool / pipx), not with a plain global pip install — pip can drop the command in a Scripts/ dir that isn't on your PATH (a common Windows "command not found"), and it clutters your global environment. Tools are isolated and on PATH. pipx install ladex works too; use a project virtualenv only if you specifically want it pinned per-project.

Quickstart

# See every AI component in a repo (silent on non-AI code)
ladex scan path/to/repo

# Add real facts: licenses, CVEs, model cards (cached; --offline works from cache)
ladex scan path/to/repo --enrich

# Declare your EU AI Act classification once (high-risk? GPAI provider? prohibited uses?)
ladex policy init path/to/repo        # writes .ladex/project.yaml to fill in & commit

# What does it obligate under the EU AI Act? (reads .ladex/project.yaml; flags override)
ladex policy check path/to/repo --user-facing

# Produce the committable, deterministic ML-BOM
ladex scan path/to/repo --write-bom aibom.cdx.json

# Sign a human answer for a gap no scanner can fill, then verify it
ladex attest "sentence-transformers/all-MiniLM-L6-v2" \
    --claim provenance --value "Curated public corpora, reviewed 2026-08"
ladex verify

# Gate it (exit non-zero on undocumented provenance / open obligations)
ladex ci path/to/repo --fail-on gaps

Example

app.py
   7:10  inference_api    openai.client       openai.OpenAI (OpenAI)
  12:9   model            openai.model-id     gpt-4o (OpenAI)

infra/main.tf
  20:1   vector_store     iac.tf.vector-store-unencrypted   HIGH   aws_opensearch_domain.vectors
                                                                   - Vector store is not encrypted at rest

Summary: 3 detection(s) across 2 of 2 file(s) scanned.

Commands

Project-fact flags for policy check / ci override .ladex/project.yaml: --user-facing/--not-user-facing, --synthetic-content/--no-synthetic-content.

On your pull requests

The GitHub Action runs the same engine as a merge gate: it detects AI added in a PR, records its EU AI Act obligations, and fails the check on undocumented provenance — with a sticky comment showing exactly which ladex attest command closes each gap.

# .github/workflows/ladex.yml
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
  ladex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: aibhuyan/ladex/apps/github@v0.2.1
        with: { fail-on: gaps }

See apps/github/README.md for all inputs. Locally, the same gate is ladex ci [PATH] --fail-on gaps (exit non-zero on open gaps).

In your editor

The VS Code extension gives inline diagnostics as you type, nothing on non-AI code — and the platform builds bundle the engine, so it's a single install with no separate pip install:

• From the Marketplace — search "Ladex" in the Extensions panel (or open the listing). VS Code automatically installs the build for your OS/CPU.
• From a .vsix — download the one matching your platform from the Releases page (ladex-<version>-{win32-x64,darwin-arm64,linux-x64}.vsix) → Extensions panel → Install from VSIX….

Then open any Python file that uses an AI library. See extensions/vscode/README.md for configuration and development.

Extending Ladex (custom packs)

Ladex loads your project's own rules alongside the built-ins — no fork, no config. Drop YAML into .ladex/packs/ and every surface (CLI, editor, PR check) picks them up:

• ​.ladex/packs/taxonomy/*.yaml — detection rules for your internal frameworks/SDKs (same format as the built-in packs: import / call / attribute / string matches).
• ​.ladex/packs/policy/**/*.yaml — your own obligation bundles (e.g. an internal "every inference API needs a model card" rule), evaluated with the EU AI Act bundles.

# .ladex/packs/taxonomy/acme.yaml
schema_version: 1
name: acme-internal
version: 0.1.0
rules:
  - id: acme.internal-llm
    name: Acme internal LLM SDK
    component_type: inference_api
    provider: Acme
    match: { kind: import, module: acme_llm }

Rule ids must be unique across built-in and custom packs (a clash is rejected loudly).

Design principles

• One engine, three surfaces. The IDE, CLI, and GitHub PR check all call the same Python engine — the editor can never disagree with the gate.
• Ruthless silence. If a line isn't AI-relevant, Ladex says nothing.
• Honest gaps. UNDOCUMENTED is a valid, valuable output. A green checkmark only appears when something was actually verified — or signed by a named human.
• Policy as versioned data. Taxonomy and EU AI Act rules are updatable bundles, not code.

Scope

Python + Jupyter + Terraform + Kubernetes detection. EU AI Act. Three surfaces — CLI, VS Code, and a GitHub PR check. The Postgres-backed evidence graph is the remaining v2 item.

Development

From source (requires uv and Python 3.12):

git clone https://github.com/aibhuyan/ladex
cd ladex
uv sync
uv run ladex --version      # from a checkout, run via `uv run ladex …`

uv run ruff check .
uv run mypy
uv run pytest

Pre-commit (ruff + mypy) runs on every commit; run uv run pre-commit install once. See RELEASING.md for how releases are cut and published.

License

MIT — see LICENSE.