# cisco-ai-defense/model-provenance-kit architecture

> Architecture diagram of the GitHub repository cisco-ai-defense/model-provenance-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cisco-ai-defense/model-provenance-kit
- Repository: https://github.com/cisco-ai-defense/model-provenance-kit

## Overview

Model Provenance Kit is a Python toolkit and CLI that compares two models or scans one model against a bundled reference database. The main flow accepts model identifiers or local paths, extracts metadata, tokenizer, and weight fingerprints, then scores a comparison or performs a staged database lookup and formats ranked results. The README also documents deep-signal fingerprint downloads, caching, and streaming for large models. Source excerpts show the scanner’s cache use and parts of weight extraction; some internal orchestration details are inferred only where the SOURCE INDEX or README supports the relationship.

Main entry points: [`src/provenancekit/core/scanner.py`](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/scanner.py) (Scanner), [`src/provenancekit/cli.py`](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/cli.py) (CLI commands), [`src/provenancekit/core/signals/weight_signals.py`](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/weight_signals.py) (Weight signals), [`src/provenancekit/core/lookup.py`](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/lookup.py) (Three-stage lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and output"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_formatter["Result formatter<br/>[formatters.py]"]
end

subgraph group_analysis["Fingerprint analysis"]
  node_scanner["Scanner<br/>[scanner.py]"]
  node_metadata["Metadata signal<br/>[metadata.py]"]
  node_tokenizer["Tokenizer signals<br/>[tokenizer.py]"]
  node_weights["Weight signals<br/>[weight_signals.py]"]
  node_anchors["Anchor selection<br/>[anchors.py]"]
  node_streamers["Weight streaming<br/>[streamers.py]"]
end

subgraph group_matching["Matching and scoring"]
  node_lookup["Three-stage lookup<br/>[lookup.py]"]
  node_scoring["Pipeline scoring<br/>[scoring.py]"]
end

subgraph group_support["Data and services"]
  node_model_loader["Model loading<br/>[model_loader.py]"]
  node_tensor["Tensor utilities<br/>[tensor.py]"]
  node_cache[("Feature cache<br/>[cache.py]")]
  node_database[("Reference database<br/>[database.py]")]
  node_models["Fingerprint models<br/>[signals.py]"]
  node_download["Fingerprint download<br/>[download.py]"]
end

node_user(("User"))
node_huggingface(("Hugging Face"))

node_user -->|"runs command"| node_cli
node_cli -->|"starts scan or compare"| node_scanner
node_cli -->|"manages fingerprints"| node_download
node_cli -->|"configures cache"| node_cache
node_scanner -->|"reads and writes"| node_cache
node_scanner -->|"extracts metadata"| node_metadata
node_scanner -->|"extracts tokenizer features"| node_tokenizer
node_scanner -->|"extracts weight features"| node_weights
node_weights -->|"uses anchors"| node_anchors
node_weights -->|"streams weights"| node_streamers
node_weights -->|"loads model weights"| node_model_loader
node_weights -->|"uses tensor helpers"| node_tensor
node_scanner -->|"loads model"| node_model_loader
node_scanner -->|"runs database scan"| node_lookup
node_lookup -->|"loads candidates"| node_database
node_lookup -->|"scores candidates"| node_scoring
node_scanner -->|"scores model pair"| node_scoring
node_lookup -->|"validates fingerprints"| node_models
node_scanner -->|"builds fingerprint results"| node_models
node_cli -->|"formats results"| node_formatter
node_download -->|"downloads fingerprints"| node_huggingface
node_huggingface -->|"provides fingerprint files"| node_download
node_user -.->|"hosts dataset"| node_huggingface

click node_cli "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/cli.py"
click node_formatter "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/results/formatters.py"
click node_scanner "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/scanner.py"
click node_metadata "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/metadata.py"
click node_tokenizer "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/tokenizer.py"
click node_weights "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/weight_signals.py"
click node_anchors "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/anchors.py"
click node_streamers "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/streamers.py"
click node_model_loader "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/model_loader.py"
click node_tensor "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/utils/tensor.py"
click node_cache "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/cache.py"
click node_lookup "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/lookup.py"
click node_scoring "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/scoring.py"
click node_database "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/database.py"
click node_models "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/models/signals.py"
click node_download "https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/download.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_formatter,node_user toneBlue
class node_scanner,node_metadata,node_tokenizer,node_weights,node_anchors,node_streamers toneAmber
class node_lookup,node_scoring toneMint
class node_model_loader,node_tensor,node_cache,node_database,node_models,node_download toneRose
class node_huggingface toneIndigo
```

## Components

### CLI and output

- [CLI commands](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/cli.py): `src/provenancekit/cli.py`
- [Result formatter](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/results/formatters.py): `src/provenancekit/core/results/formatters.py`

### Fingerprint analysis

- [Scanner](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/scanner.py): `src/provenancekit/core/scanner.py`
- [Metadata signal](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/metadata.py): `src/provenancekit/core/signals/metadata.py`
- [Tokenizer signals](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/tokenizer.py): `src/provenancekit/core/signals/tokenizer.py`
- [Weight signals](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/weight_signals.py): `src/provenancekit/core/signals/weight_signals.py`
- [Anchor selection](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/anchors.py): `src/provenancekit/core/signals/anchors.py`
- [Weight streaming](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/signals/streamers.py): `src/provenancekit/core/signals/streamers.py`

### Matching and scoring

- [Three-stage lookup](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/lookup.py): `src/provenancekit/core/lookup.py`
- [Pipeline scoring](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/core/scoring.py): `src/provenancekit/core/scoring.py`

### Data and services

- [Model loading](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/model_loader.py): `src/provenancekit/services/model_loader.py`
- [Tensor utilities](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/utils/tensor.py): `src/provenancekit/utils/tensor.py`
- [Feature cache](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/cache.py): `src/provenancekit/services/cache.py`
- [Reference database](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/database.py): `src/provenancekit/services/database.py`
- [Fingerprint models](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/models/signals.py): `src/provenancekit/models/signals.py`
- [Fingerprint download](https://github.com/cisco-ai-defense/model-provenance-kit/blob/main/src/provenancekit/services/download.py): `src/provenancekit/services/download.py`

### Other components

- **User**
- **Hugging Face**

## Connections

- User → CLI commands: runs command (evidence: `README.md`)
- CLI commands → Scanner: starts scan or compare (evidence: `src/provenancekit/cli.py`)
- CLI commands → Fingerprint download: manages fingerprints (evidence: `src/provenancekit/cli.py`)
- CLI commands → Feature cache: configures cache (evidence: `src/provenancekit/cli.py`)
- Scanner → Feature cache: reads and writes (evidence: `src/provenancekit/core/scanner.py`)
- Scanner → Metadata signal: extracts metadata (evidence: `src/provenancekit/core/scanner.py`)
- Scanner → Tokenizer signals: extracts tokenizer features (evidence: `src/provenancekit/core/scanner.py`)
- Scanner → Weight signals: extracts weight features (evidence: `src/provenancekit/core/scanner.py`)
- Weight signals → Anchor selection: uses anchors (evidence: `src/provenancekit/core/signals/weight_signals.py`)
- Weight signals → Weight streaming: streams weights (evidence: `src/provenancekit/core/signals/weight_signals.py`)
- Weight signals → Model loading: loads model weights (evidence: `src/provenancekit/core/signals/weight_signals.py`)
- Weight signals → Tensor utilities: uses tensor helpers (evidence: `src/provenancekit/core/signals/weight_signals.py`)
- Scanner → Model loading: loads model (evidence: `src/provenancekit/core/scanner.py`)
- Scanner → Three-stage lookup: runs database scan (evidence: `src/provenancekit/core/scanner.py`)
- Three-stage lookup → Reference database: loads candidates (evidence: `src/provenancekit/core/lookup.py`)
- Three-stage lookup → Pipeline scoring: scores candidates (evidence: `src/provenancekit/core/lookup.py`)
- Scanner → Pipeline scoring: scores model pair (evidence: `src/provenancekit/core/scanner.py`)
- Three-stage lookup → Fingerprint models: validates fingerprints (evidence: `src/provenancekit/core/lookup.py`)
- Scanner → Fingerprint models: builds fingerprint results (evidence: `src/provenancekit/core/scanner.py`)
- CLI commands → Result formatter: formats results (evidence: `src/provenancekit/cli.py`)
- Fingerprint download → Hugging Face: downloads fingerprints (evidence: `README.md`)
- Hugging Face → Fingerprint download: provides fingerprint files (evidence: `README.md`)
- User → Hugging Face: hosts dataset
