# cmu-agents/assignment-1 architecture

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

- Interactive diagram: https://gitdiagram.com/cmu-agents/assignment-1
- Repository: https://github.com/cmu-agents/assignment-1

## Overview

This is a course assignment agent harness, not a standalone chess product: users run a code-fixing agent on a task, which works in a sandbox and produces a patch; the evaluation harness applies and grades that patch. A separate chess-playing agent uses a served chess game, and the repository also supports SWE-bench instances. The sampled sources show the sandbox, agent base, chess API client, and evaluation pieces; unsampled modules are represented only where the tree or documented interfaces support them.

Main entry points: [`src/assignment/cli.py`](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/cli.py) (CLI runners), [`src/assignment/env.py`](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/env.py) (Environment adapter), [`src/assignment/agent/base.py`](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/base.py) (ReAct loop), [`src/assignment/eval/harness.py`](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/eval/harness.py) (Patch evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run entrypoints"]
  node_cli["CLI runners<br/>[cli.py]"]
end

subgraph group_agents["Agent runtime"]
  node_code_agent["Code agent<br/>[code_agent.py]"]
  node_chess_agent["Chess agent<br/>[chess_agent.py]"]
  node_agent_base["ReAct loop<br/>[base.py]"]
  node_tool_schemas["Tool schemas<br/>[tools.py]"]
  node_chess_tools["Chess tools<br/>[chess_tools.py]"]
end

subgraph group_sandbox["Sandbox execution"]
  node_environment["Environment adapter<br/>[env.py]"]
  node_chess_sandbox["Chess server sandbox<br/>[chess_sandbox.py]"]
  node_image_builder["Testbed image builder<br/>[image.py]"]
end

subgraph group_tasks_eval["Tasks and evaluation"]
  node_task_model["Task definition<br/>[task.py]"]
  node_task_data["Chess task files"]
  node_instance_registry["SWE-bench instances<br/>[instances.py]"]
  node_instance_data["Vendored instances"]
  node_eval_harness["Patch evaluator<br/>[harness.py]"]
end

node_user(("Assignment user"))
node_model_service{{"OpenAI-compatible model"}}
node_modal{{"Modal sandbox"}}
node_chess_app["Chess application"]
node_patch["Agent patch"]
node_testbed["Task testbed"]

node_user -->|"starts run"| node_cli
node_cli -->|"launches"| node_code_agent
node_cli -->|"launches"| node_chess_agent
node_cli -->|"creates"| node_environment
node_code_agent -->|"uses loop"| node_agent_base
node_chess_agent -->|"uses loop"| node_agent_base
node_agent_base -->|"requests completion"| node_model_service
node_agent_base -->|"exposes tools"| node_tool_schemas
node_agent_base -->|"runs commands"| node_environment
node_chess_agent -->|"uses tools"| node_chess_tools
node_chess_agent -->|"requests game state"| node_chess_sandbox
node_chess_sandbox -->|"builds image"| node_image_builder
node_chess_sandbox -->|"inherits runtime"| node_environment
node_chess_sandbox -->|"serves application"| node_chess_app
node_environment -->|"creates sandbox"| node_modal
node_environment -->|"executes commands"| node_modal
node_cli -->|"loads task"| node_task_model
node_task_model -->|"reads task files"| node_task_data
node_cli -->|"selects instance"| node_instance_registry
node_instance_registry -->|"loads instance files"| node_instance_data
node_cli -->|"writes submission"| node_patch
node_eval_harness -->|"resolves image"| node_image_builder
node_eval_harness -->|"runs grading commands"| node_environment
node_eval_harness -->|"applies patch"| node_patch
node_eval_harness -->|"runs tests"| node_testbed
node_image_builder -->|"reads task source"| node_task_model

click node_cli "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/cli.py"
click node_code_agent "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/code_agent.py"
click node_chess_agent "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/chess_agent.py"
click node_agent_base "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/base.py"
click node_tool_schemas "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/tools.py"
click node_chess_tools "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/chess_tools.py"
click node_environment "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/env.py"
click node_chess_sandbox "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/chess_sandbox.py"
click node_chess_app "https://github.com/cmu-agents/assignment-1/tree/main/chess_app"
click node_task_model "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/task.py"
click node_task_data "https://github.com/cmu-agents/assignment-1/tree/main/tasks/chess-terminal-move"
click node_instance_registry "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/eval/instances.py"
click node_instance_data "https://github.com/cmu-agents/assignment-1/tree/main/tasks/swebench"
click node_image_builder "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/utils/image.py"
click node_eval_harness "https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/eval/harness.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_user toneBlue
class node_code_agent,node_chess_agent,node_agent_base,node_tool_schemas,node_chess_tools toneAmber
class node_environment,node_chess_sandbox,node_image_builder toneMint
class node_task_model,node_task_data,node_instance_registry,node_instance_data,node_eval_harness,node_testbed toneRose
class node_model_service,node_modal,node_patch toneIndigo
class node_chess_app toneTeal
```

## Components

### Run entrypoints

- [CLI runners](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/cli.py): `src/assignment/cli.py`

### Agent runtime

- [Code agent](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/code_agent.py): `src/assignment/agent/code_agent.py`
- [Chess agent](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/chess_agent.py): `src/assignment/agent/chess_agent.py`
- [ReAct loop](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/base.py): `src/assignment/agent/base.py`
- [Tool schemas](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/tools.py): `src/assignment/agent/tools.py`
- [Chess tools](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/agent/chess_tools.py): `src/assignment/agent/chess_tools.py`

### Sandbox execution

- [Environment adapter](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/env.py): `src/assignment/env.py`
- [Chess server sandbox](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/chess_sandbox.py): `src/assignment/chess_sandbox.py`
- [Testbed image builder](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/utils/image.py): `src/assignment/utils/image.py`

### Tasks and evaluation

- [Task definition](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/task.py): `src/assignment/task.py`
- [Chess task files](https://github.com/cmu-agents/assignment-1/tree/main/tasks/chess-terminal-move): `tasks/chess-terminal-move`
- [SWE-bench instances](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/eval/instances.py): `src/assignment/eval/instances.py`
- [Vendored instances](https://github.com/cmu-agents/assignment-1/tree/main/tasks/swebench): `tasks/swebench`
- [Patch evaluator](https://github.com/cmu-agents/assignment-1/blob/main/src/assignment/eval/harness.py): `src/assignment/eval/harness.py`

### Other components

- **Assignment user**
- **OpenAI-compatible model**
- **Modal sandbox**
- [Chess application](https://github.com/cmu-agents/assignment-1/tree/main/chess_app): `chess_app`
- **Agent patch**
- **Task testbed**

## Connections

- Assignment user → CLI runners: starts run
- CLI runners → Code agent: launches
- CLI runners → Chess agent: launches
- CLI runners → Environment adapter: creates
- Code agent → ReAct loop: uses loop
- Chess agent → ReAct loop: uses loop
- ReAct loop → OpenAI-compatible model: requests completion
- ReAct loop → Tool schemas: exposes tools
- ReAct loop → Environment adapter: runs commands
- Chess agent → Chess tools: uses tools
- Chess agent → Chess server sandbox: requests game state
- Chess server sandbox → Testbed image builder: builds image
- Chess server sandbox → Environment adapter: inherits runtime
- Chess server sandbox → Chess application: serves application
- Environment adapter → Modal sandbox: creates sandbox
- Environment adapter → Modal sandbox: executes commands
- CLI runners → Task definition: loads task
- Task definition → Chess task files: reads task files
- CLI runners → SWE-bench instances: selects instance
- SWE-bench instances → Vendored instances: loads instance files
- CLI runners → Agent patch: writes submission
- Patch evaluator → Testbed image builder: resolves image
- Patch evaluator → Environment adapter: runs grading commands
- Patch evaluator → Agent patch: applies patch
- Patch evaluator → Task testbed: runs tests
- Testbed image builder → Task definition: reads task source