# stonybrooknlp/appworld architecture

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

## Overview

AppWorld is a simulated multi-app environment and benchmark for agents that solve natural-language tasks through interactive code and API calls. The main workflow is task selection, agent interaction with a task world and its app APIs, then evaluation against task ground truth. The README also documents serving the environment through APIs or MCP, plus task generation and agent experiments. Those latter areas are represented at their documented directory or entry-point level; source excerpts were not provided for their internal wiring.

Main entry points: [`src/appworld/environment.py`](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/environment.py) (AppWorld), [`src/appworld/evaluator.py`](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/evaluator.py) (Evaluator), [`src/appworld/serve/environment.py`](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/environment.py) (Environment Server), [`src/appworld/apps/lib/apis`](https://github.com/stonybrooknlp/appworld/tree/main/src/appworld/apps/lib/apis) (App APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Task Runtime"]
  node_cli["CLI<br/>[cli.py]"]
  node_task["Task<br/>[task.py]"]
  node_environment["AppWorld<br/>[environment.py]"]
  node_evaluator["Evaluator<br/>[evaluator.py]"]
  node_ground_truth["Ground Truth<br/>[ground_truth.py]"]
end

subgraph group_world["Simulated Apps"]
  node_app_apis["App APIs"]
  node_api_auth["API Authentication<br/>[authentication.py]"]
  node_app_models["App Models"]
  node_app_db[("App Databases<br/>[db.py]")]
  node_api_collections["API Catalog<br/>[apis.py]"]
  node_api_docs["API Docs<br/>[api_docs.py]"]
end

subgraph group_interfaces["Serving Interfaces"]
  node_serve_api["API Server<br/>[apis.py]"]
  node_serve_environment["Environment Server<br/>[environment.py]"]
  node_serve_mcp["MCP Server<br/>[_mcp.py]"]
  node_serve_uis["UI Server<br/>[uis.py]"]
  node_requester["API Requester<br/>[requester.py]"]
end

subgraph group_research["Benchmark Research"]
  node_task_generation["Task Generation"]
  node_generation_validation["Task Validation"]
  node_experiments["Agent Experiments"]
  node_leaderboard["Leaderboard<br/>[leaderboard.py]"]
end

node_agent(("Agent"))

node_agent -->|"interacts with"| node_environment
node_environment -->|"loads task"| node_task
node_environment -->|"executes calls"| node_app_apis
node_app_apis -->|"checks identity"| node_api_auth
node_app_apis -->|"uses models"| node_app_models
node_app_models -->|"reads and writes"| node_app_db
node_environment -->|"evaluates run"| node_evaluator
node_evaluator -->|"checks against"| node_ground_truth
node_cli -->|"starts world"| node_environment
node_cli -->|"starts evaluation"| node_evaluator
node_serve_api -->|"serves world"| node_serve_environment
node_serve_environment -->|"exposes runtime"| node_environment
node_serve_mcp -->|"exposes tools"| node_serve_environment
node_serve_uis -->|"serves interface"| node_serve_environment
node_requester -->|"sends requests"| node_serve_api
node_api_collections -->|"documents APIs"| node_api_docs
node_task_generation -->|"validated by"| node_generation_validation
node_experiments -->|"runs experiments"| node_cli
node_evaluator -->|"reports results"| node_leaderboard

click node_cli "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/cli.py"
click node_task "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/task.py"
click node_environment "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/environment.py"
click node_evaluator "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/evaluator.py"
click node_ground_truth "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/ground_truth.py"
click node_app_apis "https://github.com/stonybrooknlp/appworld/tree/main/src/appworld/apps/lib/apis"
click node_api_auth "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/apps/lib/apis/authentication.py"
click node_app_models "https://github.com/stonybrooknlp/appworld/tree/main/src/appworld/apps/lib/models"
click node_app_db "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/apps/lib/models/db.py"
click node_api_collections "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/collections/apis.py"
click node_api_docs "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/collections/api_docs.py"
click node_serve_api "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/apis.py"
click node_serve_environment "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/environment.py"
click node_serve_mcp "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/_mcp.py"
click node_serve_uis "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/uis.py"
click node_task_generation "https://github.com/stonybrooknlp/appworld/tree/main/generate/tasks"
click node_generation_validation "https://github.com/stonybrooknlp/appworld/blob/main/generate/tasks/generate_and_validate_tasks.py"
click node_experiments "https://github.com/stonybrooknlp/appworld/tree/main/experiments/code"
click node_leaderboard "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/leaderboard.py"
click node_requester "https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/requester.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_task,node_environment,node_evaluator,node_ground_truth toneBlue
class node_app_apis,node_api_auth,node_app_models,node_app_db,node_api_collections,node_api_docs toneAmber
class node_serve_api,node_serve_environment,node_serve_mcp,node_serve_uis,node_requester toneMint
class node_task_generation,node_generation_validation,node_experiments,node_leaderboard toneRose
class node_agent toneIndigo
```

## Components

### Task Runtime

- [CLI](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/cli.py): `src/appworld/cli.py`
- [Task](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/task.py): `src/appworld/task.py`
- [AppWorld](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/environment.py): `src/appworld/environment.py`
- [Evaluator](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/evaluator.py): `src/appworld/evaluator.py`
- [Ground Truth](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/ground_truth.py): `src/appworld/ground_truth.py`

### Simulated Apps

- [App APIs](https://github.com/stonybrooknlp/appworld/tree/main/src/appworld/apps/lib/apis): `src/appworld/apps/lib/apis`
- [API Authentication](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/apps/lib/apis/authentication.py): `src/appworld/apps/lib/apis/authentication.py`
- [App Models](https://github.com/stonybrooknlp/appworld/tree/main/src/appworld/apps/lib/models): `src/appworld/apps/lib/models`
- [App Databases](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/apps/lib/models/db.py): `src/appworld/apps/lib/models/db.py`
- [API Catalog](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/collections/apis.py): `src/appworld/collections/apis.py`
- [API Docs](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/collections/api_docs.py): `src/appworld/collections/api_docs.py`

### Serving Interfaces

- [API Server](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/apis.py): `src/appworld/serve/apis.py`
- [Environment Server](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/environment.py): `src/appworld/serve/environment.py`
- [MCP Server](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/_mcp.py): `src/appworld/serve/_mcp.py`
- [UI Server](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/serve/uis.py): `src/appworld/serve/uis.py`
- [API Requester](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/requester.py): `src/appworld/requester.py`

### Benchmark Research

- [Task Generation](https://github.com/stonybrooknlp/appworld/tree/main/generate/tasks): `generate/tasks`
- [Task Validation](https://github.com/stonybrooknlp/appworld/blob/main/generate/tasks/generate_and_validate_tasks.py): `generate/tasks/generate_and_validate_tasks.py`
- [Agent Experiments](https://github.com/stonybrooknlp/appworld/tree/main/experiments/code): `experiments/code`
- [Leaderboard](https://github.com/stonybrooknlp/appworld/blob/main/src/appworld/leaderboard.py): `src/appworld/leaderboard.py`

### Other components

- **Agent**

## Connections

- Agent → AppWorld: interacts with
- AppWorld → Task: loads task
- AppWorld → App APIs: executes calls
- App APIs → API Authentication: checks identity
- App APIs → App Models: uses models
- App Models → App Databases: reads and writes
- AppWorld → Evaluator: evaluates run
- Evaluator → Ground Truth: checks against
- CLI → AppWorld: starts world
- CLI → Evaluator: starts evaluation
- API Server → Environment Server: serves world
- Environment Server → AppWorld: exposes runtime
- MCP Server → Environment Server: exposes tools
- UI Server → Environment Server: serves interface
- API Requester → API Server: sends requests
- API Catalog → API Docs: documents APIs
- Task Generation → Task Validation: validated by
- Agent Experiments → CLI: runs experiments
- Evaluator → Leaderboard: reports results