# expectedparrot/edsl architecture

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

- Interactive diagram: https://gitdiagram.com/expectedparrot/edsl
- Repository: https://github.com/expectedparrot/edsl

## Overview

EDSL is a computational social-science and market-research toolkit. Researchers define question types, optionally combine them with agent personas, models, and scenario data, then run surveys or experiments to collect structured responses and analyze them as datasets. The graph emphasizes that design-to-results path, including survey logic, interview execution, model inference, and results. It also preserves documented Coop cloud capabilities and scenario data preparation. Edges are limited to README statements or the supplied source excerpts and index references; unsampled subsystems are represented only where documented.

Main entry points: [`edsl/surveys/survey.py`](https://github.com/expectedparrot/edsl/blob/main/edsl/surveys/survey.py) (Survey and logic), [`edsl/interviews/interview_task_manager.py`](https://github.com/expectedparrot/edsl/blob/main/edsl/interviews/interview_task_manager.py) (Interview tasks), [`edsl/jobs/jobs.py`](https://github.com/expectedparrot/edsl/blob/main/edsl/jobs/jobs.py) (Job execution), [`edsl/results/results.py`](https://github.com/expectedparrot/edsl/blob/main/edsl/results/results.py) (Structured results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Research design"]
  node_questions["Question types<br/>[question_base.py]"]
  node_survey["Survey and logic<br/>[survey.py]"]
  node_rules["Skip and stop rules<br/>[rule_manager.py]"]
  node_scenarios["Scenario data<br/>[scenario.py]"]
  node_scenario_sources["Scenario sources"]
  node_agents["Agent personas<br/>[agent.py]"]
end

subgraph group_execution["Run execution"]
  node_interview["Interview tasks"]
  node_jobs["Job execution<br/>[jobs.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
end

subgraph group_inference["Model inference"]
  node_models["Model selection<br/>[model.py]"]
  node_service_registry["Inference registry"]
  node_inference_service["Inference services"]
  node_providers["Model providers"]
end

subgraph group_results["Results and analysis"]
  node_results["Structured results<br/>[results.py]"]
  node_dataset["Dataset analysis<br/>[dataset.py]"]
end

subgraph group_platform["Cloud collaboration"]
  node_human_research["Human validation<br/>[coop.py]"]
  node_coop["Coop cloud API<br/>[coop.py]"]
  node_remote_cache[("Remote response cache")]
end

node_researcher(("Researcher"))
node_researcher_results(("Researcher"))
node_llm_provider(("LLM provider"))

node_researcher -->|"defines"| node_questions
node_researcher -->|"composes"| node_survey
node_researcher -->|"configures"| node_agents
node_researcher -->|"selects"| node_models
node_researcher -->|"imports data"| node_scenario_sources
node_scenario_sources -.->|"creates scenarios"| node_scenarios
node_survey -->|"contains questions"| node_questions
node_survey -->|"delegates rules"| node_rules
node_survey -->|"parameterized by"| node_scenarios
node_survey -->|"runs with"| node_agents
node_survey -->|"runs with"| node_models
node_survey -->|"creates jobs"| node_jobs
node_jobs -.->|"runs interviews"| node_interview
node_interview -->|"creates tasks"| node_questions
node_interview -->|"follows dependencies"| node_rules
node_interview -.->|"requests answers"| node_inference_service
node_models -.->|"resolves service"| node_service_registry
node_service_registry -->|"selects service"| node_inference_service
node_inference_service -.->|"dispatches inference"| node_providers
node_providers -.->|"sends prompts"| node_llm_provider
node_jobs -.->|"uses cache"| node_cache
node_jobs -.->|"produces responses"| node_results
node_results -->|"supports analysis"| node_dataset
node_results -->|"presents results"| node_researcher_results
node_researcher -->|"validates with people"| node_human_research
node_researcher -->|"shares research"| node_coop
node_coop -->|"supports remote caching"| node_remote_cache

click node_questions "https://github.com/expectedparrot/edsl/blob/main/edsl/questions/question_base.py"
click node_survey "https://github.com/expectedparrot/edsl/blob/main/edsl/surveys/survey.py"
click node_rules "https://github.com/expectedparrot/edsl/blob/main/edsl/surveys/rules/rule_manager.py"
click node_scenarios "https://github.com/expectedparrot/edsl/blob/main/edsl/scenarios/scenario.py"
click node_scenario_sources "https://github.com/expectedparrot/edsl/tree/main/edsl/scenarios/sources"
click node_agents "https://github.com/expectedparrot/edsl/blob/main/edsl/agents/agent.py"
click node_models "https://github.com/expectedparrot/edsl/blob/main/edsl/language_models/model.py"
click node_service_registry "https://github.com/expectedparrot/edsl/blob/main/edsl/inference_services/inference_service_registry.py"
click node_inference_service "https://github.com/expectedparrot/edsl/blob/main/edsl/inference_services/inference_service_abc.py"
click node_providers "https://github.com/expectedparrot/edsl/tree/main/edsl/inference_services/services"
click node_interview "https://github.com/expectedparrot/edsl/blob/main/edsl/interviews/interview_task_manager.py"
click node_jobs "https://github.com/expectedparrot/edsl/blob/main/edsl/jobs/jobs.py"
click node_cache "https://github.com/expectedparrot/edsl/blob/main/edsl/caching/cache.py"
click node_results "https://github.com/expectedparrot/edsl/blob/main/edsl/results/results.py"
click node_dataset "https://github.com/expectedparrot/edsl/blob/main/edsl/dataset/dataset.py"
click node_human_research "https://github.com/expectedparrot/edsl/blob/main/edsl/coop/coop.py"
click node_coop "https://github.com/expectedparrot/edsl/blob/main/edsl/coop/coop.py"
click node_remote_cache "https://github.com/expectedparrot/edsl/blob/main/edsl/caching/remote_cache_sync.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_questions,node_survey,node_rules,node_scenarios,node_scenario_sources,node_agents toneBlue
class node_interview,node_jobs,node_cache toneAmber
class node_models,node_service_registry,node_inference_service,node_providers toneMint
class node_results,node_dataset toneRose
class node_human_research,node_coop,node_remote_cache,node_researcher,node_researcher_results,node_llm_provider toneIndigo
```

## Components

### Research design

- [Question types](https://github.com/expectedparrot/edsl/blob/main/edsl/questions/question_base.py): `edsl/questions/question_base.py`
- [Survey and logic](https://github.com/expectedparrot/edsl/blob/main/edsl/surveys/survey.py): `edsl/surveys/survey.py`
- [Skip and stop rules](https://github.com/expectedparrot/edsl/blob/main/edsl/surveys/rules/rule_manager.py): `edsl/surveys/rules/rule_manager.py`
- [Scenario data](https://github.com/expectedparrot/edsl/blob/main/edsl/scenarios/scenario.py): `edsl/scenarios/scenario.py`
- [Scenario sources](https://github.com/expectedparrot/edsl/tree/main/edsl/scenarios/sources): `edsl/scenarios/sources`
- [Agent personas](https://github.com/expectedparrot/edsl/blob/main/edsl/agents/agent.py): `edsl/agents/agent.py`

### Run execution

- [Interview tasks](https://github.com/expectedparrot/edsl/blob/main/edsl/interviews/interview_task_manager.py): `edsl/interviews/interview_task_manager.py`
- [Job execution](https://github.com/expectedparrot/edsl/blob/main/edsl/jobs/jobs.py): `edsl/jobs/jobs.py`
- [Response cache](https://github.com/expectedparrot/edsl/blob/main/edsl/caching/cache.py): `edsl/caching/cache.py`

### Model inference

- [Model selection](https://github.com/expectedparrot/edsl/blob/main/edsl/language_models/model.py): `edsl/language_models/model.py`
- [Inference registry](https://github.com/expectedparrot/edsl/blob/main/edsl/inference_services/inference_service_registry.py): `edsl/inference_services/inference_service_registry.py`
- [Inference services](https://github.com/expectedparrot/edsl/blob/main/edsl/inference_services/inference_service_abc.py): `edsl/inference_services/inference_service_abc.py`
- [Model providers](https://github.com/expectedparrot/edsl/tree/main/edsl/inference_services/services): `edsl/inference_services/services`

### Results and analysis

- [Structured results](https://github.com/expectedparrot/edsl/blob/main/edsl/results/results.py): `edsl/results/results.py`
- [Dataset analysis](https://github.com/expectedparrot/edsl/blob/main/edsl/dataset/dataset.py): `edsl/dataset/dataset.py`

### Cloud collaboration

- [Human validation](https://github.com/expectedparrot/edsl/blob/main/edsl/coop/coop.py): `edsl/coop/coop.py`
- [Coop cloud API](https://github.com/expectedparrot/edsl/blob/main/edsl/coop/coop.py): `edsl/coop/coop.py`
- [Remote response cache](https://github.com/expectedparrot/edsl/blob/main/edsl/caching/remote_cache_sync.py): `edsl/caching/remote_cache_sync.py`

### Other components

- **Researcher**
- **Researcher**
- **LLM provider**

## Connections

- Researcher → Question types: defines
- Researcher → Survey and logic: composes
- Researcher → Agent personas: configures
- Researcher → Model selection: selects
- Researcher → Scenario sources: imports data
- Scenario sources → Scenario data: creates scenarios
- Survey and logic → Question types: contains questions (evidence: `edsl/surveys/survey.py`)
- Survey and logic → Skip and stop rules: delegates rules (evidence: `edsl/surveys/survey.py`)
- Survey and logic → Scenario data: parameterized by (evidence: `edsl/surveys/survey.py`)
- Survey and logic → Agent personas: runs with (evidence: `edsl/surveys/survey.py`)
- Survey and logic → Model selection: runs with (evidence: `edsl/surveys/survey.py`)
- Survey and logic → Job execution: creates jobs (evidence: `edsl/surveys/survey.py`)
- Job execution → Interview tasks: runs interviews
- Interview tasks → Question types: creates tasks (evidence: `edsl/interviews/interview_task_manager.py`)
- Interview tasks → Skip and stop rules: follows dependencies (evidence: `edsl/interviews/interview_task_manager.py`)
- Interview tasks → Inference services: requests answers
- Model selection → Inference registry: resolves service
- Inference registry → Inference services: selects service (evidence: `edsl/inference_services/inference_service_registry.py`)
- Inference services → Model providers: dispatches inference (evidence: `edsl/inference_services/services/google_service.py`)
- Model providers → LLM provider: sends prompts
- Job execution → Response cache: uses cache
- Job execution → Structured results: produces responses
- Structured results → Dataset analysis: supports analysis
- Structured results → Researcher: presents results
- Researcher → Human validation: validates with people
- Researcher → Coop cloud API: shares research
- Coop cloud API → Remote response cache: supports remote caching
