# mjyanna/promptagent architecture

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

- Interactive diagram: https://gitdiagram.com/mjyanna/promptagent
- Repository: https://github.com/mjyanna/promptagent

## Overview

PromptAgent searches for high-performing task prompts: the configured entry point builds a task, base and optimization models, a world model, and a search algorithm; search expands prompts using sampled task examples and retains candidates by evaluation reward. The README also documents standalone prompt testing and multiple task/model families. Source excerpts confirm MCTS and beam-search interaction with the world model, plus gradient-descent feedback; wiring for unsampled task and model implementations is represented only at the documented subsystem level.

Main entry points: [`src/prompt_optim_agent/language_model`](https://github.com/mjyanna/promptagent/tree/main/src/prompt_optim_agent/language_model) (Model adapters), [`src/prompt_optim_agent/agent.py`](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/agent.py) (Prompt agent), [`src/prompt_optim_agent/world_model/gradient_descent.py`](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/gradient_descent.py) (Prompt feedback), [`src/prompt_optim_agent/world_model/world_model.py`](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/world_model.py) (World model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_main["CLI entry<br/>[main.py]"]
  node_agent["Prompt agent<br/>[agent.py]"]
  node_test_cli["Prompt testing<br/>[test.py]"]
  node_result["Optimized prompts<br/>[mcts.py]"]
end

subgraph group_task_eval["Tasks and evaluation"]
  node_task_factory["Task registry<br/>[__init__.py]"]
  node_task_impl["Task implementations"]
  node_task_base["Task interface<br/>[base_task.py]"]
  node_datasets[("Task datasets")]
end

subgraph group_optimization["Prompt optimization"]
  node_world_model["World model<br/>[world_model.py]"]
  node_gradient["Prompt feedback"]
  node_prompt_templates["Optimization templates"]
  node_search_factory["Search registry<br/>[__init__.py]"]
  node_mcts["MCTS search<br/>[mcts.py]"]
  node_beam["Beam search<br/>[beam_search.py]"]
end

subgraph group_models["Model backends"]
  node_model_factory["Model registry<br/>[__init__.py]"]
  node_model_adapters["Model adapters"]
end

node_user(("User"))
node_openai{{"OpenAI API"}}
node_palm{{"PaLM API"}}
node_hf{{"Hugging Face"}}
node_ct{{"CTranslate2"}}

node_user -->|"configures run"| node_main
node_main -->|"starts agent"| node_agent
node_user -->|"supplies prompt"| node_test_cli
node_test_cli -->|"selects task"| node_task_factory
node_test_cli -->|"selects model"| node_model_factory
node_agent -->|"creates task"| node_task_factory
node_task_factory -->|"dispatches task"| node_task_impl
node_task_impl -->|"uses interface"| node_task_base
node_task_impl -->|"loads examples"| node_datasets
node_agent -->|"creates models"| node_model_factory
node_model_factory -->|"dispatches backend"| node_model_adapters
node_agent -->|"creates world model"| node_world_model
node_agent -->|"creates search"| node_search_factory
node_search_factory -->|"dispatches algorithm"| node_mcts
node_search_factory -->|"dispatches algorithm"| node_beam
node_mcts -->|"expands and evaluates"| node_world_model
node_beam -->|"expands and evaluates"| node_world_model
node_world_model -->|"generates candidates"| node_gradient
node_gradient -->|"formats and scores"| node_task_base
node_gradient -->|"runs base model"| node_model_adapters
node_gradient -->|"requests revisions"| node_model_adapters
node_gradient -->|"uses templates"| node_prompt_templates
node_mcts -->|"records search output"| node_result
node_model_adapters -.->|"calls API"| node_openai
node_model_adapters -.->|"calls API"| node_palm
node_model_adapters -.->|"loads or runs model"| node_hf
node_model_adapters -.->|"runs model"| node_ct

click node_main "https://github.com/mjyanna/promptagent/blob/main/src/main.py"
click node_agent "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/agent.py"
click node_test_cli "https://github.com/mjyanna/promptagent/blob/main/src/test.py"
click node_task_factory "https://github.com/mjyanna/promptagent/blob/main/src/tasks/__init__.py"
click node_task_impl "https://github.com/mjyanna/promptagent/tree/main/src/tasks"
click node_task_base "https://github.com/mjyanna/promptagent/blob/main/src/tasks/base_task.py"
click node_datasets "https://github.com/mjyanna/promptagent/tree/main/datasets"
click node_world_model "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/world_model.py"
click node_gradient "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/gradient_descent.py"
click node_prompt_templates "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/prompts/gradient_descent_prompts.py"
click node_search_factory "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/__init__.py"
click node_mcts "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/mcts.py"
click node_beam "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/beam_search.py"
click node_model_factory "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/language_model/__init__.py"
click node_model_adapters "https://github.com/mjyanna/promptagent/tree/main/src/prompt_optim_agent/language_model"
click node_result "https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/mcts.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_main,node_agent,node_test_cli,node_result,node_user toneBlue
class node_task_factory,node_task_impl,node_task_base,node_datasets toneAmber
class node_world_model,node_gradient,node_prompt_templates,node_search_factory,node_mcts,node_beam,node_openai,node_palm toneMint
class node_model_factory,node_model_adapters toneRose
class node_hf,node_ct toneIndigo
```

## Components

### Run orchestration

- [CLI entry](https://github.com/mjyanna/promptagent/blob/main/src/main.py): `src/main.py`
- [Prompt agent](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/agent.py): `src/prompt_optim_agent/agent.py`
- [Prompt testing](https://github.com/mjyanna/promptagent/blob/main/src/test.py): `src/test.py`
- [Optimized prompts](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/mcts.py): `src/prompt_optim_agent/search_algo/mcts.py`

### Tasks and evaluation

- [Task registry](https://github.com/mjyanna/promptagent/blob/main/src/tasks/__init__.py): `src/tasks/__init__.py`
- [Task implementations](https://github.com/mjyanna/promptagent/tree/main/src/tasks): `src/tasks`
- [Task interface](https://github.com/mjyanna/promptagent/blob/main/src/tasks/base_task.py): `src/tasks/base_task.py`
- [Task datasets](https://github.com/mjyanna/promptagent/tree/main/datasets): `datasets`

### Prompt optimization

- [World model](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/world_model.py): `src/prompt_optim_agent/world_model/world_model.py`
- [Prompt feedback](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/gradient_descent.py): `src/prompt_optim_agent/world_model/gradient_descent.py`
- [Optimization templates](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/world_model/prompts/gradient_descent_prompts.py): `src/prompt_optim_agent/world_model/prompts/gradient_descent_prompts.py`
- [Search registry](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/__init__.py): `src/prompt_optim_agent/search_algo/__init__.py`
- [MCTS search](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/mcts.py): `src/prompt_optim_agent/search_algo/mcts.py`
- [Beam search](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/search_algo/beam_search.py): `src/prompt_optim_agent/search_algo/beam_search.py`

### Model backends

- [Model registry](https://github.com/mjyanna/promptagent/blob/main/src/prompt_optim_agent/language_model/__init__.py): `src/prompt_optim_agent/language_model/__init__.py`
- [Model adapters](https://github.com/mjyanna/promptagent/tree/main/src/prompt_optim_agent/language_model): `src/prompt_optim_agent/language_model`

### Other components

- **User**
- **OpenAI API**
- **PaLM API**
- **Hugging Face**
- **CTranslate2**

## Connections

- User → CLI entry: configures run
- CLI entry → Prompt agent: starts agent
- User → Prompt testing: supplies prompt
- Prompt testing → Task registry: selects task
- Prompt testing → Model registry: selects model
- Prompt agent → Task registry: creates task
- Task registry → Task implementations: dispatches task
- Task implementations → Task interface: uses interface
- Task implementations → Task datasets: loads examples
- Prompt agent → Model registry: creates models
- Model registry → Model adapters: dispatches backend
- Prompt agent → World model: creates world model
- Prompt agent → Search registry: creates search
- Search registry → MCTS search: dispatches algorithm
- Search registry → Beam search: dispatches algorithm
- MCTS search → World model: expands and evaluates
- Beam search → World model: expands and evaluates
- World model → Prompt feedback: generates candidates
- Prompt feedback → Task interface: formats and scores
- Prompt feedback → Model adapters: runs base model
- Prompt feedback → Model adapters: requests revisions
- Prompt feedback → Optimization templates: uses templates
- MCTS search → Optimized prompts: records search output
- Model adapters → OpenAI API: calls API
- Model adapters → PaLM API: calls API
- Model adapters → Hugging Face: loads or runs model
- Model adapters → CTranslate2: runs model