# factslab/bead architecture

> Architecture diagram of the GitHub repository factslab/bead, 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/factslab/bead
- Repository: https://github.com/factslab/bead

## Overview

bead is a Python framework for building and running large linguistic judgment experiments. Its principal workflow composes configuration and annotation protocols, creates stimuli from lexical resources and templates, constructs items, partitions balanced lists, deploys jsPsych/JATOS studies, and uses collected judgments for evaluation and active-learning training. Separate branches support corpus-to-item processing, simulated annotation, and behavioral analysis. The README documents these capabilities; several subsystem connections below are based on that documented workflow because their implementation was not sampled.

Main entry points: [`bead/active_learning/loop.py`](https://github.com/factslab/bead/blob/main/bead/active_learning/loop.py) (Active-learning loop), [`bead/items`](https://github.com/factslab/bead/tree/main/bead/items) (Experimental items), [`bead/corpus/pipeline.py`](https://github.com/factslab/bead/blob/main/bead/corpus/pipeline.py) (Corpus processing), [`bead/lists`](https://github.com/factslab/bead/tree/main/bead/lists) (Balanced lists)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Experiment design"]
  node_config["Config composition<br/>[loader.py]"]
  node_protocol["Annotation protocols"]
end

subgraph group_stimuli["Stimulus construction"]
  node_resources["Lexical resources"]
  node_templates["Template realization"]
  node_corpus["Corpus processing<br/>[pipeline.py]"]
  node_tokenization["Dependency parsing<br/>[parsers.py]"]
  node_items["Experimental items"]
  node_lists["Balanced lists"]
end

subgraph group_delivery["Study delivery"]
  node_deployment["jsPsych deployment"]
  node_jatos["JATOS integration"]
end

subgraph group_analysis["Judgments and analysis"]
  node_collection["Response collection"]
  node_evaluation["Judgment evaluation"]
  node_behavioral["Behavioral analysis"]
end

subgraph group_learning["Model learning"]
  node_active["Active-learning loop<br/>[loop.py]"]
  node_selection["Uncertainty selection<br/>[selection.py]"]
  node_models["Task models"]
  node_trainers["Model trainers"]
  node_simulation["Judgment simulation"]
end

subgraph group_core["Shared runtime"]
  node_dsl["Constraint DSL"]
  node_storage[("JSONL repositories<br/>[repository.py]")]
end

node_researcher(("Researcher"))
node_annotator(("Study annotator"))
node_external["Model APIs"]

node_researcher -->|"configures"| node_config
node_researcher -->|"defines questions"| node_protocol
node_config -->|"configures"| node_protocol
node_resources -->|"supplies lexicon"| node_templates
node_templates -->|"realizes stimuli"| node_items
node_protocol -->|"defines templates"| node_items
node_corpus -->|"parses records"| node_tokenization
node_tokenization -->|"provides parses"| node_corpus
node_corpus -->|"constructs items"| node_items
node_corpus -->|"filters structure"| node_dsl
node_lists -->|"checks constraints"| node_dsl
node_items -->|"partitions items"| node_lists
node_lists -->|"provides lists"| node_deployment
node_protocol -->|"provides task definitions"| node_deployment
node_deployment -->|"exports study"| node_jatos
node_annotator -->|"completes study"| node_jatos
node_jatos -->|"returns responses"| node_collection
node_collection -->|"supplies judgments"| node_evaluation
node_collection -->|"provides ratings"| node_active
node_evaluation -->|"provides agreement target"| node_active
node_active -->|"requests items"| node_selection
node_active -->|"uses model"| node_models
node_active -->|"trains model"| node_trainers
node_active -->|"checks convergence"| node_evaluation
node_simulation -.->|"demonstrates loop"| node_active
node_collection -->|"supplies behavior data"| node_behavioral
node_resources -.->|"queries providers"| node_external
node_models -.->|"calls model APIs"| node_external
node_items -->|"persists records"| node_storage
node_lists -->|"persists lists"| node_storage

click node_config "https://github.com/factslab/bead/blob/main/bead/config/loader.py"
click node_protocol "https://github.com/factslab/bead/tree/main/bead/protocol"
click node_resources "https://github.com/factslab/bead/tree/main/bead/resources"
click node_templates "https://github.com/factslab/bead/tree/main/bead/templates"
click node_corpus "https://github.com/factslab/bead/blob/main/bead/corpus/pipeline.py"
click node_tokenization "https://github.com/factslab/bead/blob/main/bead/tokenization/parsers.py"
click node_items "https://github.com/factslab/bead/tree/main/bead/items"
click node_dsl "https://github.com/factslab/bead/tree/main/bead/dsl"
click node_lists "https://github.com/factslab/bead/tree/main/bead/lists"
click node_deployment "https://github.com/factslab/bead/tree/main/bead/deployment/jspsych"
click node_jatos "https://github.com/factslab/bead/tree/main/bead/deployment/jatos"
click node_collection "https://github.com/factslab/bead/tree/main/bead/data_collection"
click node_evaluation "https://github.com/factslab/bead/tree/main/bead/evaluation"
click node_behavioral "https://github.com/factslab/bead/tree/main/bead/behavioral"
click node_active "https://github.com/factslab/bead/blob/main/bead/active_learning/loop.py"
click node_selection "https://github.com/factslab/bead/blob/main/bead/active_learning/selection.py"
click node_models "https://github.com/factslab/bead/tree/main/bead/active_learning/models"
click node_trainers "https://github.com/factslab/bead/tree/main/bead/active_learning/trainers"
click node_simulation "https://github.com/factslab/bead/tree/main/bead/simulation"
click node_storage "https://github.com/factslab/bead/blob/main/bead/data/repository.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_config,node_protocol toneBlue
class node_resources,node_templates,node_corpus,node_tokenization,node_items,node_lists toneAmber
class node_deployment,node_jatos,node_external toneMint
class node_collection,node_evaluation,node_behavioral toneRose
class node_active,node_selection,node_models,node_trainers,node_simulation,node_researcher,node_annotator toneIndigo
class node_dsl,node_storage toneTeal
```

## Components

### Experiment design

- [Config composition](https://github.com/factslab/bead/blob/main/bead/config/loader.py): `bead/config/loader.py`
- [Annotation protocols](https://github.com/factslab/bead/tree/main/bead/protocol): `bead/protocol`

### Stimulus construction

- [Lexical resources](https://github.com/factslab/bead/tree/main/bead/resources): `bead/resources`
- [Template realization](https://github.com/factslab/bead/tree/main/bead/templates): `bead/templates`
- [Corpus processing](https://github.com/factslab/bead/blob/main/bead/corpus/pipeline.py): `bead/corpus/pipeline.py`
- [Dependency parsing](https://github.com/factslab/bead/blob/main/bead/tokenization/parsers.py): `bead/tokenization/parsers.py`
- [Experimental items](https://github.com/factslab/bead/tree/main/bead/items): `bead/items`
- [Balanced lists](https://github.com/factslab/bead/tree/main/bead/lists): `bead/lists`

### Study delivery

- [jsPsych deployment](https://github.com/factslab/bead/tree/main/bead/deployment/jspsych): `bead/deployment/jspsych`
- [JATOS integration](https://github.com/factslab/bead/tree/main/bead/deployment/jatos): `bead/deployment/jatos`

### Judgments and analysis

- [Response collection](https://github.com/factslab/bead/tree/main/bead/data_collection): `bead/data_collection`
- [Judgment evaluation](https://github.com/factslab/bead/tree/main/bead/evaluation): `bead/evaluation`
- [Behavioral analysis](https://github.com/factslab/bead/tree/main/bead/behavioral): `bead/behavioral`

### Model learning

- [Active-learning loop](https://github.com/factslab/bead/blob/main/bead/active_learning/loop.py): `bead/active_learning/loop.py`
- [Uncertainty selection](https://github.com/factslab/bead/blob/main/bead/active_learning/selection.py): `bead/active_learning/selection.py`
- [Task models](https://github.com/factslab/bead/tree/main/bead/active_learning/models): `bead/active_learning/models`
- [Model trainers](https://github.com/factslab/bead/tree/main/bead/active_learning/trainers): `bead/active_learning/trainers`
- [Judgment simulation](https://github.com/factslab/bead/tree/main/bead/simulation): `bead/simulation`

### Shared runtime

- [Constraint DSL](https://github.com/factslab/bead/tree/main/bead/dsl): `bead/dsl`
- [JSONL repositories](https://github.com/factslab/bead/blob/main/bead/data/repository.py): `bead/data/repository.py`

### Other components

- **Researcher**
- **Study annotator**
- **Model APIs**

## Connections

- Researcher → Config composition: configures
- Researcher → Annotation protocols: defines questions
- Config composition → Annotation protocols: configures
- Lexical resources → Template realization: supplies lexicon
- Template realization → Experimental items: realizes stimuli
- Annotation protocols → Experimental items: defines templates
- Corpus processing → Dependency parsing: parses records
- Dependency parsing → Corpus processing: provides parses
- Corpus processing → Experimental items: constructs items
- Corpus processing → Constraint DSL: filters structure
- Balanced lists → Constraint DSL: checks constraints
- Experimental items → Balanced lists: partitions items
- Balanced lists → jsPsych deployment: provides lists
- Annotation protocols → jsPsych deployment: provides task definitions
- jsPsych deployment → JATOS integration: exports study
- Study annotator → JATOS integration: completes study
- JATOS integration → Response collection: returns responses
- Response collection → Judgment evaluation: supplies judgments
- Response collection → Active-learning loop: provides ratings
- Judgment evaluation → Active-learning loop: provides agreement target
- Active-learning loop → Uncertainty selection: requests items
- Active-learning loop → Task models: uses model
- Active-learning loop → Model trainers: trains model
- Active-learning loop → Judgment evaluation: checks convergence
- Judgment simulation → Active-learning loop: demonstrates loop
- Response collection → Behavioral analysis: supplies behavior data
- Lexical resources → Model APIs: queries providers
- Task models → Model APIs: calls model APIs
- Experimental items → JSONL repositories: persists records
- Balanced lists → JSONL repositories: persists lists