# bunny-1432/openenv architecture

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

- Interactive diagram: https://gitdiagram.com/bunny-1432/openenv
- Repository: https://github.com/bunny-1432/openenv

## Overview

#### Purpose and Entry Points
This repository implements an OpenEnv-compatible email-triage environment for RL training and agent evaluation. Agents interact through typed MCP-style tools to inspect synthetic emails, classify/triage them, and submit replies; the environment returns observations, dense reward, and completion state.

Primary runtime entry point: `server/app.py` (served with Uvicorn). Python consumers use `client.py`; the reference model-driving loop is `inference.py`.

#### HTTP and OpenEnv Server Boundary
`server/app.py` constructs the FastAPI/OpenEnv application, exposing health, reset, and environment interaction endpoints (including the framework’s HTTP/WebSocket capabilities). It is the boundary between remote agents/clients and per-episode environment logic.

Deployment is container-oriented through `Dockerfile`; environment metadata/spec compliance is declared in `openenv.yaml`.

#### Episode Environment and Tool Dispatch
`server/email_environment.py` is the core `MCPEnvironment` implementation. It owns episode state—episode identifier, selected task, step count, active emails, submissions, accumulated scoring—and implements reset/step behavior.

Its action boundary is the six named tools: list/read email, classify, set priority/labels, submit reply, and inspect task status. Each call produces textual agent-facing feedback plus structured reward/done semantics, enforcing task step limits.

#### Tasks and Grading
`server/tasks.py` defines the three benchmark modes and deterministic grading policies:
- Single-email classification with exact/related-category credit.
- Batch inbox triage scored from ranking correlation and label accuracy.
- Reply drafting assessed through heuristic tone, coverage, length, and structure signals.

This module separates task objectives and reward evaluation from environment orchestration in `server/email_environment.py`, allowing a common tool lifecycle across difficulty levels.

#### Synthetic Data Layer
`server/email_data.py` supplies the fixed synthetic email corpus and task-relevant ground truth. Deterministic seeded content makes episode scoring reproducible and avoids external mailbox, identity, or email-provider dependencies.

The environment selects this data during reset, then exposes only tool-requested content to the agent, preserving the intended read-before-act workflow.

#### Contract Models and Client Integration
`models.py` contains Pydantic action/observation contracts used at the environment interface. `client.py` wraps the server for synchronous Python usage: reset an episode and invoke a tool with arguments.

Thus clients need not import server internals; the server remains the authoritative stateful executor and grader.

#### Baseline Inference and External Services
`inference.py` runs an autonomous baseline against the HTTP environment. It uses an OpenAI-compatible LLM API, typically the Hugging Face Router, configured by `HF_TOKEN`, `API_BASE_URL`, and `MODEL_NAME`; the environment URL is separately configurable.

Material runtime dependencies are Python, FastAPI/Uvicorn, OpenEnv Core, FastMCP, and Pydantic, with Docker providing the production launch envelope.

Main entry points: [`server/app.py`](https://github.com/bunny-1432/openenv/blob/main/server/app.py) (FastAPI/OpenEnv app), [`server/email_environment.py`](https://github.com/bunny-1432/openenv/blob/main/server/email_environment.py) (Email environment), [`server/tasks.py`](https://github.com/bunny-1432/openenv/blob/main/server/tasks.py) (Benchmark modes), [`inference.py`](https://github.com/bunny-1432/openenv/blob/main/inference.py) (Baseline inference loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Environment Server"]
  node_app["FastAPI/OpenEnv app<br/>HTTP/WebSocket server<br/>[app.py]"]
  node_environment["Email environment<br/>MCPEnvironment"]
  node_tools{{"Six triage tools<br/>MCP tool dispatch"}}
  node_models["Interface contracts<br/>Pydantic models<br/>[models.py]"]
end

subgraph group_tasks["Tasks and Data"]
  node_task_modes["Benchmark modes<br/>task definitions<br/>[tasks.py]"]
  node_grading{{"Deterministic grading<br/>reward policies<br/>[tasks.py]"}}
  node_email_data[("Synthetic email corpus<br/>seeded dataset<br/>[email_data.py]")]
end

subgraph group_consumers["Clients and Baseline"]
  node_client["Python client<br/>synchronous client<br/>[client.py]"]
  node_inference["Baseline inference loop<br/>autonomous agent<br/>[inference.py]"]
  node_llm_api(("OpenAI-compatible LLM API<br/>external service"))
end

node_docker{{"Docker launch<br/>container deployment"}}
node_spec["OpenEnv spec<br/>environment metadata<br/>[openenv.yaml]"]

node_docker -->|"launches"| node_app
node_spec -.->|"declares environment"| node_app
node_app -->|"routes reset and actions"| node_environment
node_models -->|"defines request/response contracts"| node_app
node_environment -->|"dispatches actions"| node_tools
node_tools -->|"reads requested content"| node_email_data
node_environment -->|"selects task on reset"| node_task_modes
node_environment -->|"evaluates submissions"| node_grading
node_task_modes -->|"defines scoring objectives"| node_grading
node_email_data -->|"provides ground truth"| node_task_modes
node_client -->|"HTTP reset and tool calls"| node_app
node_inference -->|"drives episode over HTTP"| node_app
node_inference -->|"model completions"| node_llm_api

click node_docker "https://github.com/bunny-1432/openenv/blob/main/Dockerfile"
click node_spec "https://github.com/bunny-1432/openenv/blob/main/openenv.yaml"
click node_app "https://github.com/bunny-1432/openenv/blob/main/server/app.py"
click node_environment "https://github.com/bunny-1432/openenv/blob/main/server/email_environment.py"
click node_tools "https://github.com/bunny-1432/openenv/blob/main/server/email_environment.py"
click node_models "https://github.com/bunny-1432/openenv/blob/main/models.py"
click node_task_modes "https://github.com/bunny-1432/openenv/blob/main/server/tasks.py"
click node_grading "https://github.com/bunny-1432/openenv/blob/main/server/tasks.py"
click node_email_data "https://github.com/bunny-1432/openenv/blob/main/server/email_data.py"
click node_client "https://github.com/bunny-1432/openenv/blob/main/client.py"
click node_inference "https://github.com/bunny-1432/openenv/blob/main/inference.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_app,node_environment,node_tools,node_models toneBlue
class node_task_modes,node_grading,node_email_data toneAmber
class node_client,node_inference,node_llm_api toneMint
class node_docker,node_spec toneNeutral
```

## Components

### Environment Server

Authoritative stateful OpenEnv runtime.

- [FastAPI/OpenEnv app](https://github.com/bunny-1432/openenv/blob/main/server/app.py): HTTP/WebSocket server · Exposes health, reset, and environment interaction endpoints. · `server/app.py`
- [Email environment](https://github.com/bunny-1432/openenv/blob/main/server/email_environment.py): MCPEnvironment · Owns per-episode state and reset/step lifecycle. · `server/email_environment.py`
- [Six triage tools](https://github.com/bunny-1432/openenv/blob/main/server/email_environment.py): MCP tool dispatch · List/read, classify, prioritize/label, reply, and status actions. · `server/email_environment.py`
- [Interface contracts](https://github.com/bunny-1432/openenv/blob/main/models.py): Pydantic models · Action and observation contracts at the environment interface. · `models.py`

### Tasks and Data

Deterministic benchmarks, grading, and synthetic inbox data.

- [Benchmark modes](https://github.com/bunny-1432/openenv/blob/main/server/tasks.py): task definitions · Classification, batch triage, and reply-drafting objectives. · `server/tasks.py`
- [Deterministic grading](https://github.com/bunny-1432/openenv/blob/main/server/tasks.py): reward policies · Computes task-specific dense reward and completion. · `server/tasks.py`
- [Synthetic email corpus](https://github.com/bunny-1432/openenv/blob/main/server/email_data.py): seeded dataset · Fixed emails and ground truth with no external mailbox dependency. · `server/email_data.py`

### Clients and Baseline

External consumers of the HTTP environment.

- [Python client](https://github.com/bunny-1432/openenv/blob/main/client.py): synchronous client · Resets episodes and invokes tools without importing server internals. · `client.py`
- [Baseline inference loop](https://github.com/bunny-1432/openenv/blob/main/inference.py): autonomous agent · Drives the HTTP environment with an LLM. · `inference.py`
- **OpenAI-compatible LLM API**: external service · Typically the Hugging Face Router.

### Other components

- [Docker launch](https://github.com/bunny-1432/openenv/blob/main/Dockerfile): container deployment · Production launch envelope. · `Dockerfile`
- [OpenEnv spec](https://github.com/bunny-1432/openenv/blob/main/openenv.yaml): environment metadata · Declares OpenEnv compliance metadata. · `openenv.yaml`

## Connections

- Docker launch → FastAPI/OpenEnv app: launches
- OpenEnv spec → FastAPI/OpenEnv app: declares environment
- FastAPI/OpenEnv app → Email environment: routes reset and actions
- Interface contracts → FastAPI/OpenEnv app: defines request/response contracts
- Email environment → Six triage tools: dispatches actions
- Six triage tools → Synthetic email corpus: reads requested content
- Email environment → Benchmark modes: selects task on reset
- Email environment → Deterministic grading: evaluates submissions
- Benchmark modes → Deterministic grading: defines scoring objectives
- Synthetic email corpus → Benchmark modes: provides ground truth
- Python client → FastAPI/OpenEnv app: HTTP reset and tool calls
- Baseline inference loop → FastAPI/OpenEnv app: drives episode over HTTP
- Baseline inference loop → OpenAI-compatible LLM API: model completions