# promptadvisers/unlock architecture

> Architecture diagram of the GitHub repository promptadvisers/unlock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/promptadvisers/unlock
- Repository: https://github.com/promptadvisers/unlock

## Overview

Unlock is an assistant-invoked skill and Python tooling for safely editing a local language model, then comparing the untouched original with a saved copy. The main journey checks the machine, prepares dependencies and model files, runs the experiment, reloads both models for matched prompts, fingerprints the changes, and produces a shareable report. Recipes and clarification scoring support the edit; the README documents these capabilities, while the sampled run.py excerpt does not expose all stage dispatches, so those links are shown as unverified where necessary.

Main entry points: [`scripts/run.py`](https://github.com/promptadvisers/unlock/blob/main/scripts/run.py) (Experiment runner), [`scripts/setup.py`](https://github.com/promptadvisers/unlock/blob/main/scripts/setup.py) (Environment setup), [`scripts/report.py`](https://github.com/promptadvisers/unlock/blob/main/scripts/report.py) (Run report), [`scripts/prepare.py`](https://github.com/promptadvisers/unlock/blob/main/scripts/prepare.py) (Recipe preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Assistant entry"]
  node_assistant["Coding assistant"]
  node_skill["Skill instructions<br/>[SKILL.md]"]
end

subgraph group_preparation["Machine and setup"]
  node_doctor["Machine check<br/>[doctor.py]"]
  node_setup["Environment setup<br/>[setup.py]"]
  node_model[("Base model")]
end

subgraph group_experiment["Edit and compare"]
  node_heretic["Heretic editor"]
  node_recipes["Edit recipes"]
  node_prepare["Recipe preparation<br/>[prepare.py]"]
  node_run["Experiment runner<br/>[run.py]"]
  node_clarification["Clarification scorer"]
  node_mpoa["MPOA modifier"]
  node_compare["Model comparison<br/>[compare.py]"]
end

subgraph group_evidence["Receipts and reporting"]
  node_freeze["Model fingerprinting<br/>[freeze.py]"]
  node_common["Shared safeguards<br/>[unlock_common.py]"]
  node_report["Run report<br/>[report.py]"]
end

node_user(("User"))
node_huggingface[("Model repository")]

node_user -->|"requests edit"| node_assistant
node_assistant -->|"follows instructions"| node_skill
node_assistant -->|"checks machine"| node_doctor
node_assistant -->|"sets up"| node_setup
node_setup -->|"installs pinned"| node_heretic
node_setup -->|"downloads model"| node_huggingface
node_huggingface -.->|"provides weights"| node_model
node_assistant -->|"runs experiment"| node_run
node_run -.->|"prepares recipe"| node_prepare
node_recipes -->|"supplies configuration"| node_prepare
node_prepare -->|"prepares invocation"| node_heretic
node_clarification -->|"scores responses"| node_heretic
node_mpoa -->|"sets edit parameters"| node_heretic
node_run -.->|"drives edit"| node_heretic
node_run -.->|"runs comparisons"| node_compare
node_compare -->|"loads and queries"| node_model
node_run -.->|"freezes copy"| node_freeze
node_freeze -->|"uses hashing helpers"| node_common
node_run -->|"uses shared safeguards"| node_common
node_run -.->|"produces run data"| node_report
node_report -->|"uses shared helpers"| node_common
node_report -->|"presents findings"| node_assistant

click node_skill "https://github.com/promptadvisers/unlock/blob/main/SKILL.md"
click node_doctor "https://github.com/promptadvisers/unlock/blob/main/scripts/doctor.py"
click node_setup "https://github.com/promptadvisers/unlock/blob/main/scripts/setup.py"
click node_recipes "https://github.com/promptadvisers/unlock/tree/main/assets"
click node_prepare "https://github.com/promptadvisers/unlock/blob/main/scripts/prepare.py"
click node_run "https://github.com/promptadvisers/unlock/blob/main/scripts/run.py"
click node_clarification "https://github.com/promptadvisers/unlock/blob/main/scripts/clarification_objective.py"
click node_mpoa "https://github.com/promptadvisers/unlock/blob/main/scripts/clarification_mpoa.py"
click node_compare "https://github.com/promptadvisers/unlock/blob/main/scripts/compare.py"
click node_freeze "https://github.com/promptadvisers/unlock/blob/main/scripts/freeze.py"
click node_common "https://github.com/promptadvisers/unlock/blob/main/scripts/unlock_common.py"
click node_report "https://github.com/promptadvisers/unlock/blob/main/scripts/report.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_assistant,node_skill,node_user toneBlue
class node_doctor,node_setup,node_model,node_huggingface toneAmber
class node_heretic,node_recipes,node_prepare,node_run,node_clarification,node_mpoa,node_compare toneMint
class node_freeze,node_common,node_report toneRose
```

## Components

### Assistant entry

- **Coding assistant**
- [Skill instructions](https://github.com/promptadvisers/unlock/blob/main/SKILL.md): `SKILL.md`

### Machine and setup

- [Machine check](https://github.com/promptadvisers/unlock/blob/main/scripts/doctor.py): `scripts/doctor.py`
- [Environment setup](https://github.com/promptadvisers/unlock/blob/main/scripts/setup.py): `scripts/setup.py`
- **Base model**

### Edit and compare

- **Heretic editor**
- [Edit recipes](https://github.com/promptadvisers/unlock/tree/main/assets): `assets`
- [Recipe preparation](https://github.com/promptadvisers/unlock/blob/main/scripts/prepare.py): `scripts/prepare.py`
- [Experiment runner](https://github.com/promptadvisers/unlock/blob/main/scripts/run.py): `scripts/run.py`
- [Clarification scorer](https://github.com/promptadvisers/unlock/blob/main/scripts/clarification_objective.py): `scripts/clarification_objective.py`
- [MPOA modifier](https://github.com/promptadvisers/unlock/blob/main/scripts/clarification_mpoa.py): `scripts/clarification_mpoa.py`
- [Model comparison](https://github.com/promptadvisers/unlock/blob/main/scripts/compare.py): `scripts/compare.py`

### Receipts and reporting

- [Model fingerprinting](https://github.com/promptadvisers/unlock/blob/main/scripts/freeze.py): `scripts/freeze.py`
- [Shared safeguards](https://github.com/promptadvisers/unlock/blob/main/scripts/unlock_common.py): `scripts/unlock_common.py`
- [Run report](https://github.com/promptadvisers/unlock/blob/main/scripts/report.py): `scripts/report.py`

### Other components

- **User**
- **Model repository**

## Connections

- User → Coding assistant: requests edit (evidence: `README.md`)
- Coding assistant → Skill instructions: follows instructions (evidence: `README.md`)
- Coding assistant → Machine check: checks machine (evidence: `README.md`)
- Coding assistant → Environment setup: sets up (evidence: `README.md`)
- Environment setup → Heretic editor: installs pinned (evidence: `scripts/setup.py`)
- Environment setup → Model repository: downloads model (evidence: `scripts/setup.py`)
- Model repository → Base model: provides weights
- Coding assistant → Experiment runner: runs experiment (evidence: `README.md`)
- Experiment runner → Recipe preparation: prepares recipe
- Edit recipes → Recipe preparation: supplies configuration (evidence: `scripts/prepare.py`)
- Recipe preparation → Heretic editor: prepares invocation (evidence: `scripts/prepare.py`)
- Clarification scorer → Heretic editor: scores responses (evidence: `scripts/clarification_objective.py`)
- MPOA modifier → Heretic editor: sets edit parameters (evidence: `scripts/clarification_mpoa.py`)
- Experiment runner → Heretic editor: drives edit
- Experiment runner → Model comparison: runs comparisons
- Model comparison → Base model: loads and queries (evidence: `scripts/compare.py`)
- Experiment runner → Model fingerprinting: freezes copy
- Model fingerprinting → Shared safeguards: uses hashing helpers (evidence: `scripts/freeze.py`)
- Experiment runner → Shared safeguards: uses shared safeguards (evidence: `scripts/run.py`)
- Experiment runner → Run report: produces run data
- Run report → Shared safeguards: uses shared helpers (evidence: `scripts/report.py`)
- Run report → Coding assistant: presents findings (evidence: `README.md`)
