DEEPBOM
DEEPBOM is a local static analyzer for deployed AI model artifacts. It audits
serialized graph, tensor, quantization, memory, compatibility, and ML-BOM
evidence without uploading model bytes.
It is a multi-format artifact-evidence producer, an external-interface contract
verifier, and a bounded BOM-to-artifact reconciliation tool. It is not an
official reference implementation, a complete BOM validator, or a regulatory
compliance verifier.
The public source distribution covers TFLite, ONNX, GGUF, SafeTensors, Core ML,
and bounded ExecuTorch artifacts. Findings distinguish observed and derived
artifact facts from predicted compatibility, imported runtime evidence, and
values that cannot be assessed statically.
Evidence IR
DEEPBOM Evidence IR is the common representation
family: Artifact IR, Model IR, optional Weight IR, Activation IR and Provenance
IR. The draft specification includes a generated schema catalog,
compatibility checks and
public maintenance rules.
Search input → IR → output mappings
or inspect the same versioned catalog on GitHub.
It is a DEEPBOM-maintained specification, not an endorsed external standard.
Provenance IR uses deepbom.provenance_ir.v1 and the sole CLI/MCP selector
provenance_ir. The released 2.0.0 contract does not accept
retired names. See the migration rules.
Quick start
For export pipelines, experiment tracking and release checks, see the new
Node/TypeScript and Python SDK contract and
three executable integration examples.
The supported SDK begins with DEEPBOM 2.1.0; earlier npm 2.0.0 packages do not
include this entry point. Install it with npm install deepbom@2.1.0.
Run the published CLI without cloning the repository (Node.js 20 or newer):
npx deepbom audit "https://raw.githubusercontent.com/JunHwan-Kwon/deepbom/main/web/samples/gpu_partition_probe.onnx#sha256=82a2feef00eb6ab03d82f2b30cd17f4d826e2d8307cb059eccd6a0f3120059b2"
The pinned expected values and independent verifier are in
examples/expected-output. Source builds
require Rust and, for the Python channel, Python 3.9 or newer; maintainer setup
is documented separately below.
Assistant integration
Install the repository-local Agent Skill after previewing the managed files:
npx -y deepbom@2.1.0 integrate codex
npx -y deepbom@2.1.0 integrate codex --apply
npx -y deepbom@2.1.0 integrate claude-code
npx -y deepbom@2.1.0 integrate claude-code --apply
The Skill lets a local agent select a contract-compatible analyzer for a
supported deployment-artifact question. It does not create or call a hosted
analysis server. See the agent setup guide,
the machine-readable capability contract,
and the independent engine/Agent/evidence version policy.
The installed Skill first checks DEEPBOM_BIN, its package-bundled analyzer,
and a deepbom already on PATH. It accepts a runtime only after the declared
deepbom.agent_contract.v2 and evidence contract match and its self-test binds
the exact observed engine version. The verifier does not contact npm unless
--allow-download is explicitly supplied. This keeps a blocked registry lookup
from being mistaken for a failed artifact analysis.
For persistent tool-call access, run the same local analyzer as an MCP server
over stdio:
It exposes deepbom_capabilities, deepbom_audit, deepbom_diff, and
deepbom_explain_rule without uploading artifact bytes or using a hosted
analysis endpoint. Audit calls default to a bounded human summary; detailed
formats and large-model scan depth are explicit. Local paths are restricted to
the launch directory unless DEEPBOM_MCP_ALLOWED_ROOTS is configured.
Agent-facing usage guidance is in the DEEPBOM skill.
Claude Desktop users can instead install the version-matched
deepbom-2.1.0.mcpb asset from the corresponding GitHub Release. The bundle
contains the same CLI and WASM bytes as the npm channel and asks the user to
select the only local directory it may read.
For a single attachment in ChatGPT, connect the separately bounded Streamable
HTTP endpoint at https://deepbom.org/mcp. Its browser component performs the
analysis in the ChatGPT sandbox and returns a bounded, hash-bound result; the
DEEPBOM service does not fetch or retain model bytes. This path is ready for
developer-mode review, while public ChatGPT discovery remains subject to
OpenAI review. See the ChatGPT integration guide.
Use the local CLI or stdio MCP for confidential or large artifacts, package and
sidecar closure, complete exports, and repeated automation.
For private testing on a Claude host that supports remote MCP Apps, add the
separate https://deepbom.org/mcp/claude connector. It opens an explicit file
picker inside the MCP App; it does not automatically read Claude attachments.
The selected bytes remain in the browser sandbox while a bounded result is
returned to the conversation. Public Claude discovery remains subject to
Anthropic review. See the Claude integration guide
and use the local MCPB or CLI when derived model facts must also remain local.
The repository root is also a portable Agent Plugins package: plugin.json
identifies the Skill and mcp.json declares the bounded ChatGPT attachment
endpoint. The compatibility manifest under .codex-plugin/ carries the same
identity for clients that have not moved to the portable format. These files
prepare installation and review; they do not imply a public directory listing
or platform approval.
Account-owned ChatGPT, Claude, Codex, and search-indexing steps are kept in the
agent distribution operations checklist.
Verified release channels expose the same analysis implementation:
npx deepbom audit model.onnx --format cyclonedx
npx deepbom audit model.onnx --format sarif --output deepbom.sarif --gate defects
deepbom capabilities --compact
deepbom self-test
deepbom audit model.onnx --list-sections --compact
deepbom audit model.onnx --section quantization,memory --compact
deepbom explain-rule onnx.conv.output-shape
python -m pip install deepbom
cargo install deepbom
deepbom audit model.gguf --compact
deepbom verify model.tflite --contract production-interface.json
deepbom verify model.onnx --bom supplied.cdx.json --render markdown
deepbom contract capture model.onnx -o baseline.interface-contract.json
deepbom diff baseline.gguf candidate.gguf --tensors --render markdown
deepbom capabilities --format agent-text
deepbom explore model.tflite
deepbom placement model.tflite --profiles xnnpack_cpu,tflite_coreml_delegate,litert_qualcomm_qnn
deepbom graph model.onnx --format json --output artifact-graph.json
deepbom audit model.onnx --section model_ir --compact
deepbom visualize model.onnx --view all --orientation portrait -o model-views.zip
deepbom model-summary model.onnx --format table
deepbom model-summary model.gguf --level storage --format markdown
deepbom audit model.onnx --conversion-receipt conversion-receipt.json --format cyclonedx
The default is a terminal-sized evidence summary. --json and --compact
expose complete format evidence; --format envelope provides the canonical
cross-format contract; CycloneDX 1.7 and OASIS SARIF 2.1.0 are standard
projections. --policy-output records a hash-bound gate result when --fail-on
is selected. --review-policy adds identity-scoped, expiring exceptions and
keeps execution, coverage, and finding-policy states independent. See
docs/CLI_AUTOMATION.md. The complete
option inventory is generated from the executable in
docs/CLI_REFERENCE.md.
CycloneDX 1.7 consumers should read the analyzed model from
metadata.component and additional inventory members from components[].
DEEPBOM does not duplicate the BOM root into the additional-components array.
The graph JSON output includes the evidence-preserving
deepbom.artifact_ir.v2 ledger and a deterministic deepbom.graph_ir.v1
visualization compatibility projection. Serialized graph, storage topology,
architecture grouping, scoped quantization, static placement, and imported
runtime evidence remain separate. Method 2.2.0 also preserves an optional,
output-bound conversion receipt without promoting declared converter execution
to observed evidence. It materializes exactly decoded
TFLite subgraphs, ONNX nested graphs/local functions, and ExecuTorch primary
plans without flattening conditional scopes. Runtime-node fusion is reconciled
only from artifact-bound subject references or primary native op indices;
names are never guessed. graph_ir.v1 remains primary-scope-only for legacy
consumers. The v2 JSON Schema is published at
docs/schemas/deepbom-artifact-ir-v2.schema.json
and at https://deepbom.org/schemas/deepbom-artifact-ir-v2.schema.json.
The conversion receipt schema is published at
docs/schemas/deepbom-conversion-receipt-v1.schema.json.
The additive preview deepbom.model_ir.v1 projects those frozen artifact facts
into a format-neutral program, logical-value, storage, binding, quantization,
architecture, and static/runtime evidence vocabulary. It preserves source,
dependency, deterministic display, and observed runtime order as different
fields. visualize consumes only this IR and creates deterministic monochrome
ISO A4 SVG pages, 300-DPI black-and-white PNG derivatives, caption sidecars,
and a Word insertion manifest. These are traceable engineering documents, not
standard-conformance or regulatory-approval determinations. See
docs/MODEL_IR_V1.md.
model-summary is the shared Keras-summary-like projection for every supported
adapter. It emits operation rows when a serialized program exists, storage rows
for graphless weight containers, and an explicit identity-only result for safe
envelopes. It never relabels serialized constants as trainable parameters or a
deterministic display order as observed runtime. JSON consumers can use
deepbom.model_summary.v1, published in
docs/schemas/deepbom-model-summary-v1.schema.json.
Public product output uses CycloneDX 1.7.
verify compares the serialized external tensor ABI with a supplied,
artifact-bound production declaration. diff uses the canonical deterministic
multi-target TFLite deployment-delta ledger, and explore exposes the existing
WASM redesign Pareto search without claiming trained-model accuracy. A strict
custom TFLite target can be bound with --target-profile profile.json; the CLI
records both the source-file SHA-256 and the resolved Rust profile SHA-256.
Accelerator evidence is separate from that CPU cost profile. Source-pinned
TFLite Core ML and LiteRT Qualcomm QNN profiles, Core ML MLComputePlan, Edge TPU
and Qualcomm compiler reports, TensorRT parser/engine evidence, and NVIDIA host
profiles use a shared staged binding without promoting static or compiled
evidence to observed execution. placement compares any available profiles
over one conserved graph ledger without inventing backend priority.
The Cargo launcher downloads only the engine matching its exact package version
and platform from the corresponding immutable GitHub Release. It validates the
release matrix, byte lengths, and SHA-256 digests before caching or execution.
Build the npm, standalone, Python, and Cargo launcher channels:
npm run build:channels
npm run check:public-package-boundary
npm run check:channels -- --no-build
Run the public correctness gates:
npm run check:cli
npm run check:cli-docs
npm run check:cli-automation
npm run check:formats
npm run check:rust
The browser workbench is available at deepbom.org.
Evidence scope
Accepted extensions do not imply equal analytical depth. TFLite and ONNX have
stable executable-graph contracts. GGUF and SafeTensors have stable container,
storage, and architecture contracts but do not serialize an executable graph.
Core ML and ExecuTorch analysis remains preview and fixture-bounded. The exact
parser, graph, quantization, and placement status for every format is available
from deepbom capabilities --compact under public_product_contracts.
| Format | Public static evidence |
|---|
| TFLite | FlatBuffer graph and tensor contracts, quantization arithmetic, weight integrity, memory projections, accumulator proofs, redesign candidates, and source-bounded delegation predictions |
| ONNX | Protobuf graph, initializer and external-data contracts, symbolic shape inference, operation cost, Q/DQ and affine quantization, and provider-compatible evidence envelopes |
| GGUF | Container and tensor-directory integrity, quantization encoding inventory, architecture metadata, and bounded LLM memory scenarios |
| SafeTensors | Tensor-directory and sharding integrity, configuration-bound architecture contracts, AWQ/GPTQ/HQQ/compressed-tensors metadata, and bounded LLM memory scenarios |
| Core ML | NeuralNetwork and ML Program serialized graphs, tensor/weight encodings, deployment floor, and imported compute-plan evidence boundaries |
| ExecuTorch | Bounded ET12/FT01 plans, source-bound portable calls and processed payload identities, plus optional selected-build/backend/operator/binary attestation; execution remains external |
| GraphDef / SavedModel | Bounded serialized nodes, data/control dependencies, first-MetaGraph SignatureDef tensor contracts, and hash-bound package membership; no graph execution |
| Keras / PT2 | Bounded declarative config/JSON dependency graphs without object construction, pickle loading, lowering, native code, or runtime-order claims |
| HDF5 / PyTorch checkpoint | Safe-envelope, archive, storage-member, and pickle-risk inventory only; no object graph or executable-model claim |
Static compatibility does not establish observed execution-provider assignment,
device latency, task accuracy, clinical validity, or release readiness. Runtime
claims require an identity-bound runtime capture.
The detailed format and accelerator boundary is maintained in
docs/SUPPORT_MATRIX.md. Bugs can be reported without
sharing model bytes using
docs/MODEL_FREE_BUG_REPORTING.md.
Distribution boundary
This repository is generated from an exact reviewed allowlist. Private
rulepack generators, hosted-service infrastructure, and unreleased research
modules are not included. The enforceable boundary and export verification
method are documented in
docs/PUBLIC_PRIVATE_BOUNDARY.md.
License and citation
The public source and release-channel packages are licensed under the Apache
License 2.0. Third-party model artifacts retain their declared licenses.
Please cite:
Kwon, J. (2026). DEEPBOM: Browser-Native Static Analysis of On-Device Neural
Network Deployment Artifacts [Computer software]. Zenodo.
https://doi.org/10.5281/zenodo.21834508
After inspecting a model, create a model-bound input with deepbom audit model.onnx --metadata-template omop -o metadata.json. Fill the selected OMOP 5.4/5.5 CDM_SOURCE row and institution/release identifiers, then use --metadata metadata.json --evidence-files ./evidence --section provenance_ir --json. A generic template connects non-OMOP datasets, cohorts, code, runs and reports through the same IR.
The Web Metadata workspace provides import, record creation, an interactive relationship diagram and JSON/CycloneDX downloads. Local MCP deepbom_audit accepts metadata_template, metadata and evidence_files; ChatGPT/Claude widgets share only explicitly requested counts and digests. Connections remain declarations: file hashes and reference consistency do not authenticate lineage or clinical suitability. See the OMOP guide and common IR contract.