# yuqiannemo/llm-dna architecture

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

- Interactive diagram: https://gitdiagram.com/yuqiannemo/llm-dna
- Repository: https://github.com/yuqiannemo/llm-dna

## Overview

LLM-DNA extracts low-dimensional behavioral signatures from language models by probing them with generated or dataset-backed text, then encoding model responses or hidden-state embeddings into DNA vectors. The primary workflow is exposed through the Python API and CLI, with support for single or parallel model runs, Hugging Face/local and hosted providers, metadata, response caching, and saved signatures. The README also describes comparing models and building evolutionary trees; the sampled files do not establish the implementation or wiring of tree construction.

Main entry points: [`src/llm_dna/core/extraction.py`](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/core/extraction.py) (Extraction core), [`src/llm_dna/api.py`](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py) (Python API), [`src/llm_dna/models/ModelWrapper.py`](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/models/ModelWrapper.py) (Model wrappers), [`src/llm_dna/dna/DNASignature.py`](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/DNASignature.py) (Signatures and metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entrypoints"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["Python API<br/>[api.py]"]
end

subgraph group_workflow["Extraction workflow"]
  node_parallel["Parallel runs<br/>[api.py]"]
  node_extract["Extraction core<br/>[extraction.py]"]
  node_cache["Response and dataset cache<br/>[api.py]"]
  node_output["Saved results<br/>[api.py]"]
end

subgraph group_inputs["Probe and metadata inputs"]
  node_probe["Probe generation<br/>[ProbeGenerator.py]"]
  node_dataset["Dataset loading<br/>[DatasetLoader.py]"]
  node_metadata["Model metadata<br/>[metadata.py]"]
end

subgraph group_models["Model execution"]
  node_model_loader["Model loader<br/>[ModelLoader.py]"]
  node_wrapper["Model wrappers<br/>[ModelWrapper.py]"]
end

subgraph group_signatures["DNA results"]
  node_dna_extractor["DNA extraction<br/>[DNAExtractor.py]"]
  node_embedding["Embedding extraction"]
  node_signature["Signatures and metrics<br/>[DNASignature.py]"]
  node_tree["Evolutionary trees"]
end

node_user(("Researcher"))
node_hf["Hugging Face Hub"]
node_hosted["Hosted model APIs"]
node_filesystem["Local files"]

node_user -->|"invokes"| node_cli
node_user -->|"calls"| node_api
node_cli -->|"dispatches"| node_api
node_api -->|"dispatches"| node_parallel
node_api -->|"runs extraction"| node_extract
node_parallel -->|"runs per model"| node_extract
node_extract -->|"generates probes"| node_probe
node_extract -->|"loads samples"| node_dataset
node_extract -->|"loads metadata"| node_metadata
node_extract -->|"loads model"| node_model_loader
node_model_loader -->|"creates wrapper"| node_wrapper
node_wrapper -->|"loads model"| node_hf
node_wrapper -.->|"sends requests"| node_hosted
node_extract -->|"extracts signature"| node_dna_extractor
node_extract -->|"extracts embeddings"| node_embedding
node_dna_extractor -->|"produces"| node_signature
node_embedding -->|"produces"| node_signature
node_signature -.->|"supports comparison"| node_tree
node_api -->|"reads and writes"| node_cache
node_extract -->|"caches samples"| node_cache
node_api -->|"saves results"| node_output
node_cache -->|"reads and writes"| node_filesystem
node_output -->|"writes"| node_filesystem
node_metadata -.->|"fetches model info"| node_hf

click node_cli "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/cli.py"
click node_api "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py"
click node_parallel "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py"
click node_extract "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/core/extraction.py"
click node_probe "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/data/ProbeGenerator.py"
click node_dataset "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/data/DatasetLoader.py"
click node_metadata "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/utils/metadata.py"
click node_model_loader "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/models/ModelLoader.py"
click node_wrapper "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/models/ModelWrapper.py"
click node_dna_extractor "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/DNAExtractor.py"
click node_embedding "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/EmbeddingDNAExtractor.py"
click node_signature "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/DNASignature.py"
click node_tree "https://github.com/yuqiannemo/llm-dna/tree/main/src/llm_dna/dna"
click node_cache "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py"
click node_output "https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.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_api toneBlue
class node_parallel,node_extract,node_cache,node_output toneAmber
class node_probe,node_dataset,node_metadata,node_hosted toneMint
class node_model_loader,node_wrapper toneRose
class node_dna_extractor,node_embedding,node_signature,node_tree,node_user,node_hf,node_filesystem toneIndigo
```

## Components

### User entrypoints

- [CLI](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/cli.py): `src/llm_dna/cli.py`
- [Python API](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py): `src/llm_dna/api.py`

### Extraction workflow

- [Parallel runs](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py): `src/llm_dna/api.py`
- [Extraction core](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/core/extraction.py): `src/llm_dna/core/extraction.py`
- [Response and dataset cache](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py): `src/llm_dna/api.py`
- [Saved results](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/api.py): `src/llm_dna/api.py`

### Probe and metadata inputs

- [Probe generation](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/data/ProbeGenerator.py): `src/llm_dna/data/ProbeGenerator.py`
- [Dataset loading](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/data/DatasetLoader.py): `src/llm_dna/data/DatasetLoader.py`
- [Model metadata](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/utils/metadata.py): `src/llm_dna/utils/metadata.py`

### Model execution

- [Model loader](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/models/ModelLoader.py): `src/llm_dna/models/ModelLoader.py`
- [Model wrappers](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/models/ModelWrapper.py): `src/llm_dna/models/ModelWrapper.py`

### DNA results

- [DNA extraction](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/DNAExtractor.py): `src/llm_dna/dna/DNAExtractor.py`
- [Embedding extraction](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/EmbeddingDNAExtractor.py): `src/llm_dna/dna/EmbeddingDNAExtractor.py`
- [Signatures and metrics](https://github.com/yuqiannemo/llm-dna/blob/main/src/llm_dna/dna/DNASignature.py): `src/llm_dna/dna/DNASignature.py`
- [Evolutionary trees](https://github.com/yuqiannemo/llm-dna/tree/main/src/llm_dna/dna): `src/llm_dna/dna`

### Other components

- **Researcher**
- **Hugging Face Hub**
- **Hosted model APIs**
- **Local files**

## Connections

- Researcher → CLI: invokes
- Researcher → Python API: calls
- CLI → Python API: dispatches
- Python API → Parallel runs: dispatches
- Python API → Extraction core: runs extraction
- Parallel runs → Extraction core: runs per model
- Extraction core → Probe generation: generates probes
- Extraction core → Dataset loading: loads samples
- Extraction core → Model metadata: loads metadata
- Extraction core → Model loader: loads model
- Model loader → Model wrappers: creates wrapper
- Model wrappers → Hugging Face Hub: loads model
- Model wrappers → Hosted model APIs: sends requests
- Extraction core → DNA extraction: extracts signature
- Extraction core → Embedding extraction: extracts embeddings
- DNA extraction → Signatures and metrics: produces
- Embedding extraction → Signatures and metrics: produces
- Signatures and metrics → Evolutionary trees: supports comparison
- Python API → Response and dataset cache: reads and writes
- Extraction core → Response and dataset cache: caches samples
- Python API → Saved results: saves results
- Response and dataset cache → Local files: reads and writes
- Saved results → Local files: writes
- Model metadata → Hugging Face Hub: fetches model info