# eaminc/nips2027 architecture

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

- Interactive diagram: https://gitdiagram.com/eaminc/nips2027
- Repository: https://github.com/eaminc/nips2027

## Overview

abhack is a Python toolkit for simulating A/B experiments where sticky versus freshly randomized traffic assignments interact with honest versus score-peeking agents. Its main workflow configures a study, generates a stable user population and scores, simulates rounds, and reports AB/AA gains and theory bounds. A separate run workflow writes and checks user, bucket, and score CSVs. The README documents additional score processes and experiment modes; their implementation details are represented at subsystem level where source excerpts are limited.

Main entry points: [`exp/run.py`](https://github.com/eaminc/nips2027/blob/main/exp/run.py) (Run workflow), [`src/abhack/study/core.py`](https://github.com/eaminc/nips2027/blob/main/src/abhack/study/core.py) (Study simulation), [`exp/study.py`](https://github.com/eaminc/nips2027/blob/main/exp/study.py) (Study workflow), [`src/abhack/utils/distributions.py`](https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/distributions.py) (Score distributions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration and runs"]
  node_run_config["Run config<br/>[spec.py]"]
  node_study_config["Study config<br/>[spec.py]"]
  node_run_cli["Run workflow<br/>[run.py]"]
  node_study_cli["Study workflow<br/>[study.py]"]
end

subgraph group_data["Population and artifacts"]
  node_users["User IDs<br/>[core.py]"]
  node_user_csv["User CSV I/O<br/>[io.py]"]
  node_layer_csv["Bucket CSV I/O<br/>[io.py]"]
  node_layer_logic["Bucket assignment<br/>[core.py]"]
  node_hashing["Stable hashing<br/>[hash.py]"]
  node_score_csv["Score CSV I/O<br/>[io.py]"]
  node_outputs["Experiment outputs"]
end

subgraph group_simulation["Experiment simulation"]
  node_distributions["Score distributions<br/>[distributions.py]"]
  node_processes["Score processes<br/>[core.py]"]
  node_strategies["System and agents<br/>[core.py]"]
  node_study_engine["Study simulation<br/>[core.py]"]
end

subgraph group_analysis["Metrics and reporting"]
  node_score_logic["Score checks<br/>[core.py]"]
  node_evaluation["Gain and bounds<br/>[core.py]"]
  node_terminal["Terminal reports<br/>[term.py]"]
end

node_experimenter(("Experimenter"))

node_experimenter -->|"runs config"| node_run_cli
node_experimenter -->|"runs study"| node_study_cli
node_run_cli -->|"loads config"| node_run_config
node_study_cli -->|"loads config"| node_study_config
node_run_cli -->|"writes users"| node_user_csv
node_user_csv -->|"generates IDs"| node_users
node_run_cli -->|"writes and checks"| node_layer_csv
node_layer_csv -->|"reads IDs"| node_user_csv
node_layer_csv -->|"assigns buckets"| node_layer_logic
node_layer_logic -->|"hashes IDs"| node_hashing
node_run_cli -->|"writes and checks"| node_score_csv
node_score_csv -->|"reads IDs"| node_user_csv
node_score_csv -->|"draws scores"| node_distributions
node_score_csv -->|"checks scores"| node_score_logic
node_run_config -->|"builds distributions"| node_distributions
node_study_config -->|"builds distribution"| node_distributions
node_run_cli -->|"writes artifacts"| node_outputs
node_run_cli -->|"renders summaries"| node_terminal
node_study_cli -->|"runs simulation"| node_study_engine
node_study_cli -->|"renders study"| node_terminal
node_study_engine -->|"creates population"| node_users
node_study_engine -->|"samples scores"| node_distributions
node_study_engine -->|"advances scores"| node_processes
node_study_engine -->|"assigns systems and arms"| node_strategies
node_study_engine -->|"computes gains and bounds"| node_evaluation
node_study_engine -->|"returns round rows"| node_outputs
node_processes -->|"draws score values"| node_distributions
node_strategies -->|"hashes buckets"| node_hashing
node_study_cli -->|"writes study rows"| node_outputs

click node_run_config "https://github.com/eaminc/nips2027/blob/main/exp/spec.py"
click node_study_config "https://github.com/eaminc/nips2027/blob/main/exp/spec.py"
click node_run_cli "https://github.com/eaminc/nips2027/blob/main/exp/run.py"
click node_study_cli "https://github.com/eaminc/nips2027/blob/main/exp/study.py"
click node_users "https://github.com/eaminc/nips2027/blob/main/src/abhack/users/core.py"
click node_user_csv "https://github.com/eaminc/nips2027/blob/main/src/abhack/users/io.py"
click node_layer_csv "https://github.com/eaminc/nips2027/blob/main/src/abhack/layer/io.py"
click node_layer_logic "https://github.com/eaminc/nips2027/blob/main/src/abhack/layer/core.py"
click node_hashing "https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/hash.py"
click node_score_csv "https://github.com/eaminc/nips2027/blob/main/src/abhack/metric/io.py"
click node_score_logic "https://github.com/eaminc/nips2027/blob/main/src/abhack/metric/core.py"
click node_distributions "https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/distributions.py"
click node_processes "https://github.com/eaminc/nips2027/blob/main/src/abhack/process/core.py"
click node_strategies "https://github.com/eaminc/nips2027/blob/main/src/abhack/strategies/core.py"
click node_study_engine "https://github.com/eaminc/nips2027/blob/main/src/abhack/study/core.py"
click node_evaluation "https://github.com/eaminc/nips2027/blob/main/src/abhack/evaluate/core.py"
click node_terminal "https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/term.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_run_config,node_study_config,node_run_cli,node_study_cli toneBlue
class node_users,node_user_csv,node_layer_csv,node_layer_logic,node_hashing,node_score_csv,node_outputs toneAmber
class node_distributions,node_processes,node_strategies,node_study_engine toneMint
class node_score_logic,node_evaluation,node_terminal toneRose
class node_experimenter toneIndigo
```

## Components

### Configuration and runs

- [Run config](https://github.com/eaminc/nips2027/blob/main/exp/spec.py): `exp/spec.py`
- [Study config](https://github.com/eaminc/nips2027/blob/main/exp/spec.py): `exp/spec.py`
- [Run workflow](https://github.com/eaminc/nips2027/blob/main/exp/run.py): `exp/run.py`
- [Study workflow](https://github.com/eaminc/nips2027/blob/main/exp/study.py): `exp/study.py`

### Population and artifacts

- [User IDs](https://github.com/eaminc/nips2027/blob/main/src/abhack/users/core.py): `src/abhack/users/core.py`
- [User CSV I/O](https://github.com/eaminc/nips2027/blob/main/src/abhack/users/io.py): `src/abhack/users/io.py`
- [Bucket CSV I/O](https://github.com/eaminc/nips2027/blob/main/src/abhack/layer/io.py): `src/abhack/layer/io.py`
- [Bucket assignment](https://github.com/eaminc/nips2027/blob/main/src/abhack/layer/core.py): `src/abhack/layer/core.py`
- [Stable hashing](https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/hash.py): `src/abhack/utils/hash.py`
- [Score CSV I/O](https://github.com/eaminc/nips2027/blob/main/src/abhack/metric/io.py): `src/abhack/metric/io.py`
- **Experiment outputs**

### Experiment simulation

- [Score distributions](https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/distributions.py): `src/abhack/utils/distributions.py`
- [Score processes](https://github.com/eaminc/nips2027/blob/main/src/abhack/process/core.py): `src/abhack/process/core.py`
- [System and agents](https://github.com/eaminc/nips2027/blob/main/src/abhack/strategies/core.py): `src/abhack/strategies/core.py`
- [Study simulation](https://github.com/eaminc/nips2027/blob/main/src/abhack/study/core.py): `src/abhack/study/core.py`

### Metrics and reporting

- [Score checks](https://github.com/eaminc/nips2027/blob/main/src/abhack/metric/core.py): `src/abhack/metric/core.py`
- [Gain and bounds](https://github.com/eaminc/nips2027/blob/main/src/abhack/evaluate/core.py): `src/abhack/evaluate/core.py`
- [Terminal reports](https://github.com/eaminc/nips2027/blob/main/src/abhack/utils/term.py): `src/abhack/utils/term.py`

### Other components

- **Experimenter**

## Connections

- Experimenter → Run workflow: runs config (evidence: `README.md`)
- Experimenter → Study workflow: runs study (evidence: `README.md`)
- Run workflow → Run config: loads config (evidence: `exp/run.py`)
- Study workflow → Study config: loads config (evidence: `exp/study.py`)
- Run workflow → User CSV I/O: writes users (evidence: `exp/run.py`)
- User CSV I/O → User IDs: generates IDs (evidence: `src/abhack/users/io.py`)
- Run workflow → Bucket CSV I/O: writes and checks (evidence: `exp/run.py`)
- Bucket CSV I/O → User CSV I/O: reads IDs (evidence: `src/abhack/layer/io.py`)
- Bucket CSV I/O → Bucket assignment: assigns buckets (evidence: `src/abhack/layer/io.py`)
- Bucket assignment → Stable hashing: hashes IDs (evidence: `src/abhack/layer/core.py`)
- Run workflow → Score CSV I/O: writes and checks (evidence: `exp/run.py`)
- Score CSV I/O → User CSV I/O: reads IDs (evidence: `src/abhack/metric/io.py`)
- Score CSV I/O → Score distributions: draws scores (evidence: `src/abhack/metric/io.py`)
- Score CSV I/O → Score checks: checks scores (evidence: `src/abhack/metric/io.py`)
- Run config → Score distributions: builds distributions (evidence: `exp/spec.py`)
- Study config → Score distributions: builds distribution (evidence: `exp/spec.py`)
- Run workflow → Experiment outputs: writes artifacts (evidence: `exp/run.py`)
- Run workflow → Terminal reports: renders summaries (evidence: `exp/run.py`)
- Study workflow → Study simulation: runs simulation (evidence: `exp/study.py`)
- Study workflow → Terminal reports: renders study (evidence: `exp/study.py`)
- Study simulation → User IDs: creates population (evidence: `src/abhack/study/core.py`)
- Study simulation → Score distributions: samples scores (evidence: `src/abhack/study/core.py`)
- Study simulation → Score processes: advances scores (evidence: `src/abhack/study/core.py`)
- Study simulation → System and agents: assigns systems and arms (evidence: `src/abhack/study/core.py`)
- Study simulation → Gain and bounds: computes gains and bounds (evidence: `src/abhack/study/core.py`)
- Study simulation → Experiment outputs: returns round rows (evidence: `README.md`)
- Score processes → Score distributions: draws score values (evidence: `src/abhack/process/core.py`)
- System and agents → Stable hashing: hashes buckets (evidence: `src/abhack/strategies/core.py`)
- Study workflow → Experiment outputs: writes study rows (evidence: `README.md`)
