DEEPBOM

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, Training IR, Snapshot 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. The artifact metadata route retains deepbom.provenance_ir.v1 and its provenance_ir selector. The additive Snapshot workflow uses typed deepbom.provenance_ir.v2 references for native states, dataset releases and configurations. Existing document hashes are preserved; retired names remain unsupported. See the migration rules.

For model-change reviews, use the synthetic two-population example and browser evidence review. Web, CLI, Node/Python SDK and local MCP use the same checks. External measurements remain external evidence; criteria satisfaction does not establish clinical suitability.

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.5.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.5.0 integrate codex

npx -y deepbom@2.5.0 integrate codex --apply npx -y deepbom@2.5.0 integrate claude-code npx -y deepbom@2.5.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:

npx -y deepbom@2.5.0 mcp

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

For code-first model development, start with the Python candidate loop. It uses the shipped native APIs and distinguishes trainable-model workflows from the browser Structure IDE's source-bound graph proposals.

Verified 2.4.0 release channels expose the same analysis implementation. npm and the Linux x86-64 release wheel below are published; other native platforms and registry channels require their own release verification.

npx deepbom@2.5.0 audit model.onnx --format cyclonedx

npx deepbom@2.5.0 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 @ https://github.com/JunHwan-Kwon/deepbom/releases/download/channels-v2.4.0/deepbom-2.4.0-py3-none-linux_x86_64.whl' 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