### Development Setup with pip

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

Clone the ModelAudit repository and set up the development environment using pip. This command installs in development mode with broad optional extras.

```bash
git clone https://github.com/promptfoo/modelaudit.git
cd modelaudit

pip install -e ".[all]"    # Development mode with broad optional extras
pip install -e .           # Basic installation
```

--------------------------------

### Development Setup with uv

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

Clone the ModelAudit repository and set up the development environment using uv. This command installs broad optional dependencies, excluding TensorFlow and TensorRT.

```bash
git clone https://github.com/promptfoo/modelaudit.git
cd modelaudit

uv sync --extra all    # Broad optional dependencies, excluding TensorFlow/TensorRT
uv sync                # Basic dependencies only
```

--------------------------------

### Install and Test Local Development Version

Source: https://github.com/promptfoo/modelaudit/blob/main/CONTRIBUTING.md

Install the project in editable mode and test the CLI or Python import. Use uv for recommended installation and execution.

```bash
# Option 1: Install in development mode with pip (also requires the Rust toolchain above)
pip install -e .[all]

# Then test the CLI directly (both forms work: "modelaudit <path>" or "modelaudit scan <path>")
modelaudit test_model.pkl

# Option 2: Use uv (recommended)
uv sync --extra all

# Test with uv run (no shell activation needed)
uv run modelaudit test_model.pkl

# Test with Python import
uv run python -c "from modelaudit import scan_file; print(scan_file('test_model.pkl'))"
```

--------------------------------

### Clone and Install ModelAudit

Source: https://github.com/promptfoo/modelaudit/blob/main/CONTRIBUTING.md

Clone the repository and install the project dependencies using uv or pip. The 'all' extra installs all optional dependencies.

```bash
git clone https://github.com/promptfoo/modelaudit.git
cd modelaudit

# Install with uv (recommended)
uv sync --extra all

# Windows (lighter optional set)
uv sync --extra all-ci-windows

# Or with pip (also requires the Rust toolchain above)
pip install -e .[all]
```

--------------------------------

### Install and Scan Models with ModelAudit

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Install ModelAudit with all features and scan a single model file or a directory of models. Ensure Python 3.10-3.13 is installed.

```bash
pip install "modelaudit[all]"

# Scan a file or directory
modelaudit model.pkl
modelaudit ./models/
```

```bash
# Export results for CI/CD
modelaudit model.pkl --format json --output results.json
```

--------------------------------

### Install Targeted Extras for PyTorch Ecosystem

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install the 'pytorch' extra for broader compatibility with the PyTorch ecosystem tooling.

```bash
modelaudit[pytorch]
```

--------------------------------

### Install ModelAudit with uv (Portable Dependencies)

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

Install ModelAudit with uv, including all broad portable dependencies.

```bash
uv sync --extra all
```

--------------------------------

### Example Scanner Skeleton

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/new-scanner-quickstart.md

Provides a basic structure for a new scanner class, including required attributes and methods like `can_handle` and `scan`. Use this as a starting point for implementing custom scanners.

```python
from __future__ import annotations

from typing import Any, ClassVar

from .base import BaseScanner, IssueSeverity, ScanResult


class ExampleScanner(BaseScanner):
    name = "example"
    description = "Scans Example model artifacts for security issues"
    supported_extensions: ClassVar[list[str]] = [".example"]

    @classmethod
    def can_handle(cls, path: str) -> bool:
        # extension + minimal signature checks
        ...

    def scan(self, path: str) -> ScanResult:
        result = self._create_scan_result_after_preflight(path)
        if not result.success:
            return result

        # Add checks here
        result.finish(success=not result.has_errors)
        return result

```

--------------------------------

### Install All Optional Dependencies

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install all optional dependencies for broad portable coverage, including ONNX and TensorFlow for specific Python versions.

```bash
pip install "modelaudit[all]"
```

--------------------------------

### Install Targeted Extras for Dill Compatibility

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install the 'dill' extra for broader compatibility with dill serialized files.

```bash
modelaudit[dill]
```

--------------------------------

### Install modelaudit-picklescan from local checkout

Source: https://github.com/promptfoo/modelaudit/blob/main/packages/modelaudit-picklescan/README.md

Install the package directly from a local source checkout using pip.

```bash
pip install packages/modelaudit-picklescan
```

--------------------------------

### Install modelaudit-picklescan from PyPI

Source: https://github.com/promptfoo/modelaudit/blob/main/packages/modelaudit-picklescan/README.md

Install the package using pip. This command ensures that the Rust extension is built from source.

```bash
# Requires Rust 1.83+ and a working C toolchain
pip install modelaudit-picklescan --no-binary modelaudit-picklescan
```

--------------------------------

### Install Minimal Base

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install only the base ModelAudit package for minimal functionality.

```bash
pip install modelaudit
```

--------------------------------

### Install ModelAudit from Local Wheelhouse

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/offline-air-gapped.md

Install ModelAudit and its dependencies from a local wheelhouse directory in an air-gapped environment. Use --no-index to prevent fetching from PyPI.

```bash
pip install --no-index --find-links wheelhouse "modelaudit[all]"
```

--------------------------------

### Install ModelAudit with uv (Development)

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

Install ModelAudit using uv for development. This command synchronizes dependencies with the TensorFlow, PyTorch, and H5 extras.

```bash
uv sync --extra tensorflow --extra pytorch --extra h5
```

--------------------------------

### Setup and Pre-commit Workflow Commands

Source: https://github.com/promptfoo/modelaudit/blob/main/AGENTS.md

Commands for setting up the development environment and running pre-commit checks. Ensure these are executed before every commit to maintain code quality and consistency.

```bash
# Setup
uv sync --extra all-ci
```

```bash
# Pre-commit workflow (MUST run before every commit)
uv run ruff format modelaudit/ packages/modelaudit-picklescan/src packages/modelaudit-picklescan/tests tests/
uv run ruff check --fix modelaudit/ packages/modelaudit-picklescan/src packages/modelaudit-picklescan/tests tests/
uv run mypy modelaudit/ packages/modelaudit-picklescan/src packages/modelaudit-picklescan/tests tests/
PROMPTFOO_DISABLE_TELEMETRY=1 uv run pytest -n auto -m "not slow and not integration" --maxfail=1
```

--------------------------------

### Quickstart: Scan a pickle file

Source: https://github.com/promptfoo/modelaudit/blob/main/packages/modelaudit-picklescan/README.md

Scan a pickle file or PyTorch ZIP checkpoint for security issues. The report provides a status, verdict, and a list of findings with severity and location.

```python
from modelaudit_picklescan import scan_file

report = scan_file("suspicious_model.pt")  # raw pickle or PyTorch ZIP checkpoint

print(f"status={report.status.value} verdict={report.verdict.value}")
for finding in report.findings:
    print(f"  [{finding.severity.value}] {finding.rule_code}: {finding.message}")
    if finding.location:
        print(f"    at {finding.location}")
```

--------------------------------

### List Installed Package Versions and Licenses

Source: https://github.com/promptfoo/modelaudit/blob/main/THIRD_PARTY_NOTICES.md

Run this command to regenerate the list of installed packages, their versions, and licenses. This is useful for auditing license compatibility.

```bash
uv run python -c "import importlib.metadata as md; [print(f'{d.metadata["Name"]} {d.metadata["Version"]} {d.metadata.get("License","")}') for d in md.distributions()]"
```

--------------------------------

### Install Targeted Extras for H5 Compatibility

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install the 'h5' extra, which is required for Keras H5 file compatibility.

```bash
modelaudit[h5]
```

--------------------------------

### Install modelaudit-picklescan

Source: https://github.com/promptfoo/modelaudit/blob/main/packages/modelaudit-picklescan/README.md

Install the package using pip. Pre-built wheels are available for common platforms and Python versions. For other platforms, a Rust toolchain is required.

```bash
pip install modelaudit-picklescan
```

--------------------------------

### Proto Loading Strategy

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

This outlines the strategy for loading TensorFlow protos. It prioritizes using TensorFlow's native protos if installed, otherwise falls back to vendored protos by adding them to sys.path. This approach prevents conflicts when TensorFlow is installed alongside modelaudit.

```text
1. Import modelaudit.protos
2. Check if TensorFlow is installed
3. If YES → use TensorFlow's native protos (no sys.path changes)
4. If NO → add vendored protos to sys.path
5. Subsequent `from tensorflow.core...` imports resolve correctly
```

--------------------------------

### Create Test Models

Source: https://github.com/promptfoo/modelaudit/blob/main/CONTRIBUTING.md

Generates test model files in PyTorch (.pt) and pickle (.pkl) formats. The pickle example demonstrates creating a potentially malicious file.

```python
# Create test models for specific formats
python -c "import torch; torch.save({'model': 'data'}, 'test.pt')"
python -c "import pickle; pickle.dump({'test': 'malicious'}, open('malicious.pkl', 'wb'))"
```

--------------------------------

### Install Targeted Extras for ONNX Compatibility

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install the 'onnx' extra, which is required for ONNX file compatibility on Python 3.10-3.12.

```bash
modelaudit[onnx]
```

--------------------------------

### ModelAudit Scan Output Example

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

This is an example of the output you might see after running ModelAudit, highlighting critical and warning issues found in a model file.

```text
$ modelaudit suspicious_model.pkl

Files scanned: 1 | Issues found: 2 critical, 1 warning

1. suspicious_model.pkl (pos 28): [CRITICAL] Malicious code execution attempt
   Why: Contains os.system() call that could run arbitrary commands

2. suspicious_model.pkl (pos 52): [WARNING] Dangerous pickle deserialization
   Why: Could execute code when the model loads
```

--------------------------------

### Platform-Agnostic and Environment-Specific Dependency Pinning

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/maintainers/dependency-policy.md

Examples of how to specify version constraints for dependencies. Use `>=X.Y.Z` for minimum versions and environment markers for platform or Python version-specific requirements.

```toml
"onnx>=1.14.0",

```

```toml
"numpy>=1.19.0,<2.0; python_version == '3.10'",
"numpy>=2.4,<2.5; python_version >= '3.11'"

```

--------------------------------

### Install ModelAudit with uv (TensorFlow Runtime)

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

Install ModelAudit with uv, including all broad portable dependencies and the TensorFlow runtime-dependent paths, which are available on Python 3.11-3.12.

```bash
uv sync --extra all --extra tensorflow
```

--------------------------------

### Download ModelAudit Dependencies

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/offline-air-gapped.md

Download all necessary ModelAudit dependencies to a local wheelhouse directory for later installation in an air-gapped environment.

```bash
mkdir -p wheelhouse
pip download "modelaudit[all]" -d wheelhouse
```

--------------------------------

### Install ModelAudit with Specific Frameworks

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Install ModelAudit with support for specific machine learning frameworks like TensorFlow, PyTorch, H5, ONNX, and Safetensors. Note the Python version compatibility for TensorFlow and ONNX.

```bash
pip install "modelaudit[tensorflow,pytorch,h5,onnx,safetensors]"
```

--------------------------------

### Format Markdown, YAML, and JSON Files

Source: https://github.com/promptfoo/modelaudit/blob/main/AGENTS.md

Use this command to format markdown, yaml, and json files according to project standards. Ensure dependencies are installed first.

```bash
npm ci --ignore-scripts && npx prettier --write "**/*.{md,yaml,yml,json}"
```

--------------------------------

### Run ModelAudit Debug Diagnostics

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Execute the debug command to get environment and configuration diagnostics. Use '--json' for JSON output and '--verbose' for more detailed logs.

```bash
modelaudit debug [--json] [--verbose]
```

--------------------------------

### Install ModelAudit with Pip

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/dependencies.md

Install ModelAudit with pip, including optional extras for TensorFlow, PyTorch, and H5. The TensorFlow runtime extra is automatically installed on Python 3.11-3.12.

```bash
pip install "modelaudit[tensorflow,pytorch,h5]"
```

--------------------------------

### Install Targeted Extras for TensorFlow Analysis

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/user/compatibility-matrix.md

Install the 'tensorflow' extra for TensorFlow-dependent checkpoint and weight analysis on Python 3.11-3.12.

```bash
modelaudit[tensorflow]
```

--------------------------------

### Troubleshoot Scanners

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Run this command to list unavailable scanners and missing optional dependencies.

```bash
modelaudit doctor --show-failed
```

--------------------------------

### Install ModelAudit with TensorFlow for Python 3.11-3.12

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

On Python 3.11-3.12, install ModelAudit with all features and explicitly add TensorFlow support when runtime-dependent checkpoint or weight analysis is required.

```bash
pip install "modelaudit[all,tensorflow]"
```

--------------------------------

### Install ModelAudit for CI/CD Environments

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Install ModelAudit with a configuration optimized for Continuous Integration and Continuous Deployment environments. This option includes a comprehensive set of tools for CI/CD pipelines.

```bash
pip install "modelaudit[all-ci]"
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/promptfoo/modelaudit/blob/main/docs/agents/release-process.md

Examples of commit messages following the Conventional Commits specification. Use these formats for all commit messages to ensure consistency and enable automated changelog generation.

```git
feat: add scanner for XYZ format
```

```git
fix: handle corrupt pickle files gracefully
```

```git
fix(modelaudit-picklescan): bound nested pickle expansion
```

--------------------------------

### Enable Telemetry in Development

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

For editable/development installs, telemetry is disabled by default. Set MODELAUDIT_TELEMETRY_DEV=1 to opt in.

```bash
export MODELAUDIT_TELEMETRY_DEV=1
```

--------------------------------

### List All ModelAudit Rules

Source: https://github.com/promptfoo/modelaudit/blob/main/RULES.md

Run this command to list all available ModelAudit rules. This is useful for understanding the scope of security checks.

```bash
modelaudit rules
```

--------------------------------

### Extract Human-Readable Metadata

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Use this command to get a human-readable summary of model metadata. It defaults to safe mode, avoiding model deserialization.

```bash
# Human-readable summary (safe default: no model deserialization)
modelaudit metadata model.safetensors
```

--------------------------------

### Import Core Components

Source: https://github.com/promptfoo/modelaudit/blob/main/packages/modelaudit-picklescan/README.md

Import all necessary components from the modelaudit_picklescan library for scanning and reporting.

```python
from modelaudit_picklescan import (
    PickleScanner,
    ScanOptions,
    scan_file,
    scan_bytes,
    scan_stream,
    shared_source_sensitive_caches,
    PickleReport,
    Finding,
    Notice,
    ScanError,
    Severity,
    ScanStatus,
    SafetyVerdict,
    CoverageSummary,
)
```

--------------------------------

### Run ModelAudit with Selected Scanners

Source: https://github.com/promptfoo/modelaudit/blob/main/README.md

Initiate a scan on specified model paths, running only the 'pickle' and 'tf_savedmodel' scanners. This allows for targeted analysis.

```bash
modelaudit scan ./models --scanners pickle,tf_savedmodel
```

--------------------------------

### Format and Lint Code

Source: https://github.com/promptfoo/modelaudit/blob/main/CONTRIBUTING.md

Applies code formatting using ruff format and checks for linting issues with ruff check, automatically fixing them. Ensure ruff is installed.

```bash
# Format and lint code
uv run ruff format modelaudit/ packages/modelaudit-picklescan/src packages/modelaudit-picklescan/tests tests/
uv run ruff check --fix modelaudit/ packages/modelaudit-picklescan/src packages/modelaudit-picklescan/tests tests/
```