# malyadritalentz/sre-incident-env architecture

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

- Interactive diagram: https://gitdiagram.com/malyadritalentz/sre-incident-env
- Repository: https://github.com/malyadritalentz/sre-incident-env

## Overview

1. **Repository purpose**
   - This repo implements a **reinforcement-learning / agent-evaluation environment** for SRE incident response.
   - The core product is an **interactive incident simulator** with three tasks of increasing difficulty: alert triage, cascading failure diagnosis, and post-mortem writing.

2. **Core architecture split**
   - The code is organized around three boundaries:
     - **Environment core**: episode state, step logic, rewards, and grading.
     - **Task definitions**: scenario content and deterministic scoring rules.
     - **API/runtime layer**: HTTP/WebSocket server plus client/inference entrypoints.
   - This separation lets the same environment run locally, in Docker, or as a hosted OpenEnv/HF Space service.

3. **Environment state and action model**
   - `models.py` defines the typed contract for the simulator: `Observation`, `Action`, `StepResult`, and likely state/session objects.
   - Observations expose only what the agent is allowed to know at each step: alerts, logs, metrics, team messages, timeline, feedback, and completion status.
   - Actions are task-agnostic at the protocol level (`classify`, `investigate`, `hypothesize`, `mitigate`, `escalate`, `resolve`, `write_postmortem`) and carry task-specific payloads.

4. **Simulation engine**
   - `environment.py` is the main runtime for **reset/step/state/grade** behavior.
   - It appears to enforce episode limits, track investigations, reveal hidden information, emit shaped rewards, and determine termination.
   - This is the boundary where the agent’s action history is transformed into the next observation and reward signal.

5. **Task and grader subsystem**
   - `tasks/scenarios.py` contains the scenario-specific content for the three incident types.
   - It also holds the **deterministic graders** that score episode output against ground truth.
   - The graders are programmatic, not model-based, which makes evaluation reproducible and suitable for benchmark-style comparison.

6. **Information flow by task**
   - **Task 1** exposes all alerts up front and mostly scores classification quality.
   - **Task 2** uses partial observability: alerts are visible initially, and `investigate` actions progressively reveal logs and evidence from specific services.
   - **Task 3** exposes everything at the start and evaluates long-form structured synthesis via a post-mortem artifact.

7. **Server/API layer**
   - `app.py` and `server/app.py` provide the runtime interface for agents and humans.
   - The README indicates endpoints for `/reset`, `/step`, `/state`, `/tasks`, `/grader`, and `/baseline`, plus a WebSocket channel.
   - This layer is a thin transport boundary over the environment core, translating HTTP/WebSocket requests into environment calls and returning serialized observations/results.

8. **Client and evaluation entrypoints**
   - `client.py` likely contains helper code for interacting with the server programmatically.
   - `inference.py` is the official submission/evaluation runner: it drives the environment, calls an external model endpoint, logs structured step events, and aggregates scores across tasks.
   - `baseline.py` provides a deterministic heuristic policy for local comparison without an LLM.

9. **External model dependency**
   - The inference pipeline can call an **OpenAI-compatible / Hugging Face router API** via environment variables like `HF_TOKEN`, `API_BASE_URL`, and `MODEL_NAME`.
   - That dependency is outside the simulator itself; the repo treats the model as an external decision-maker consuming observations and emitting actions.

10. **Deployment/runtime**
   - `Dockerfile`, `openenv.yaml`, and `requirements.txt`/`pyproject.toml` define packaging for **HF Spaces / Docker SDK** deployment and local execution.
   - The repo is designed to run as a service on port 7860, with FastAPI/Uvicorn-style startup in local dev.
   - `uv.lock` suggests a reproducible Python dependency lockfile.

11. **Validation**
   - `test_env.py` contains unit tests for the environment behavior and likely the grading/step transitions.
   - This is important architecturally because the environment is deterministic and benchmark-oriented; tests protect the contract between task definitions, state transitions, and scoring.

12. **How to diagram it**
   - Draw the system as: **Agent/LLM or baseline policy → API/server layer → environment engine → task/scenario + grader data**.
   - Show the environment producing **observations and rewards** back to the agent, with task scenarios controlling what is revealed and how success is scored.
   - Keep the model endpoint external, and treat the server as a stateless transport over a per-session environment state.

Main entry points: [`environment.py`](https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py) (Environment), [`server/app.py`](https://github.com/malyadritalentz/sre-incident-env/blob/main/server/app.py) (Server App), [`tasks/scenarios.py`](https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py) (Scenarios), [`inference.py`](https://github.com/malyadritalentz/sre-incident-env/blob/main/inference.py) (Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["API / Runtime"]
  node_app_entry["App Entry<br/>runtime entrypoint<br/>[app.py]"]
  node_server_app["Server App<br/>HTTP/WebSocket server<br/>[app.py]"]
  node_client_helper["Client<br/>[client.py]"]
  node_inference_runner["Inference<br/>evaluation runner<br/>[inference.py]"]
  node_baseline_policy["Baseline<br/>heuristic policy<br/>[baseline.py]"]
end

subgraph group_group_simulation["Simulation Core"]
  node_models_contract["Models<br/>protocol schema<br/>[models.py]"]
  node_environment_core["Environment<br/>episode engine<br/>[environment.py]"]
  node_episode_state[("Episode State<br/>stateful runtime<br/>[environment.py]")]
  node_action_logic{{"Action Flow<br/>action handler<br/>[environment.py]"}}
  node_reward_grading{{"Reward / Grade<br/>scoring boundary<br/>[environment.py]"}}
end

subgraph group_group_tasks["Tasks / Scenarios"]
  node_scenarios["Scenarios<br/>task content<br/>[scenarios.py]"]
  node_task1["Alert Triage<br/>task<br/>[scenarios.py]"]
  node_task2["Cascading Diagnosis<br/>task<br/>[scenarios.py]"]
  node_task3["Postmortem Writing<br/>task<br/>[scenarios.py]"]
  node_grader_rules{{"Graders<br/>deterministic scoring<br/>[scenarios.py]"}}
end

subgraph group_group_external["External Agent"]
  node_external_agent(("LLM / Policy<br/>agent"))
end

node_external_agent -->|"reset/step"| node_server_app
node_baseline_policy -->|"policy calls"| node_server_app
node_inference_runner -.->|"model query"| node_external_agent
node_client_helper -->|"api calls"| node_server_app
node_app_entry -->|"launches"| node_server_app
node_server_app -->|"session ops"| node_environment_core
node_environment_core -->|"uses contract"| node_models_contract
node_environment_core -->|"stores"| node_episode_state
node_environment_core -->|"applies"| node_action_logic
node_environment_core -->|"scores"| node_reward_grading
node_action_logic -->|"reveals facts"| node_scenarios
node_reward_grading -->|"evaluates"| node_grader_rules
node_scenarios -->|"defines"| node_task1
node_scenarios -->|"defines"| node_task2
node_scenarios -->|"defines"| node_task3
node_task1 -->|"classifies"| node_grader_rules
node_task2 -->|"evidence score"| node_grader_rules
node_task3 -->|"artifact score"| node_grader_rules
node_inference_runner -->|"episodes"| node_server_app
node_environment_core -->|"observations / rewards"| node_inference_runner

click node_app_entry "https://github.com/malyadritalentz/sre-incident-env/blob/main/app.py"
click node_server_app "https://github.com/malyadritalentz/sre-incident-env/blob/main/server/app.py"
click node_client_helper "https://github.com/malyadritalentz/sre-incident-env/blob/main/client.py"
click node_inference_runner "https://github.com/malyadritalentz/sre-incident-env/blob/main/inference.py"
click node_baseline_policy "https://github.com/malyadritalentz/sre-incident-env/blob/main/baseline.py"
click node_models_contract "https://github.com/malyadritalentz/sre-incident-env/blob/main/models.py"
click node_environment_core "https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py"
click node_episode_state "https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py"
click node_action_logic "https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py"
click node_reward_grading "https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py"
click node_scenarios "https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py"
click node_task1 "https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py"
click node_task2 "https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py"
click node_task3 "https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py"
click node_grader_rules "https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.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_entry,node_server_app,node_client_helper,node_inference_runner,node_baseline_policy toneBlue
class node_models_contract,node_environment_core,node_episode_state,node_action_logic,node_reward_grading toneAmber
class node_scenarios,node_task1,node_task2,node_task3,node_grader_rules toneMint
class node_external_agent toneRose
```

## Components

### API / Runtime

Transport and entrypoints that expose the simulator to agents and deployments.

- [App Entry](https://github.com/malyadritalentz/sre-incident-env/blob/main/app.py): runtime entrypoint · Top-level application entrypoint for serving or local runtime. · `app.py`
- [Server App](https://github.com/malyadritalentz/sre-incident-env/blob/main/server/app.py): HTTP/WebSocket server · FastAPI-style server exposing the simulator over HTTP and WebSocket. · `server/app.py`
- [Client](https://github.com/malyadritalentz/sre-incident-env/blob/main/client.py): api client · Programmatic client helpers for interacting with the server. · `client.py`
- [Inference](https://github.com/malyadritalentz/sre-incident-env/blob/main/inference.py): evaluation runner · Drives episodes against a model endpoint and aggregates scores. · `inference.py`
- [Baseline](https://github.com/malyadritalentz/sre-incident-env/blob/main/baseline.py): heuristic policy · Deterministic reference policy for local comparison. · `baseline.py`

### Simulation Core

Episode state, action handling, rewards, and grading logic.

- [Models](https://github.com/malyadritalentz/sre-incident-env/blob/main/models.py): protocol schema · Typed simulator contract for observations, actions, step results, and session state. · `models.py`
- [Environment](https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py): episode engine · Reset/step loop, reward shaping, termination, and state transitions. · `environment.py`
- [Episode State](https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py): stateful runtime · Per-session hidden and visible state tracked across steps. · `environment.py`
- [Action Flow](https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py): action handler · Transforms agent actions into investigations, mitigations, and episode progress. · `environment.py`
- [Reward / Grade](https://github.com/malyadritalentz/sre-incident-env/blob/main/environment.py): scoring boundary · Computes shaped rewards and final grading signals from task outcomes. · `environment.py`

### Tasks / Scenarios

Scenario content and deterministic scoring for the incident tasks.

- [Scenarios](https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py): task content · Incident definitions, hidden facts, and task-specific reveal structure. · `tasks/scenarios.py`
- [Alert Triage](https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py): task · All alerts are visible up front; scores classification quality. · `tasks/scenarios.py`
- [Cascading Diagnosis](https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py): task · Partial observability with investigations that reveal service evidence. · `tasks/scenarios.py`
- [Postmortem Writing](https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py): task · Full observability with structured long-form incident analysis. · `tasks/scenarios.py`
- [Graders](https://github.com/malyadritalentz/sre-incident-env/blob/main/tasks/scenarios.py): deterministic scoring · Programmatic scoring rules that compare outputs against ground truth. · `tasks/scenarios.py`

### External Agent

Model or policy outside the simulator that chooses actions from observations.

- **LLM / Policy**: agent · External decision-maker that consumes observations and emits actions.

## Connections

- LLM / Policy → Server App: reset/step · Agent drives the simulator through the server API.
- Baseline → Server App: policy calls · Baseline uses the same runtime boundary for local episodes.
- Inference → LLM / Policy: model query · Inference runner calls an external model endpoint to choose actions.
- Client → Server App: api calls · Client interacts with the simulator over HTTP/WebSocket.
- App Entry → Server App: launches · Application entrypoint starts the server runtime.
- Server App → Environment: session ops · Server forwards reset, step, state, and task requests to the environment.
- Environment → Models: uses contract · Environment is implemented against the typed observation/action protocol.
- Environment → Episode State: stores · Environment maintains per-episode hidden and visible state.
- Environment → Action Flow: applies · Environment applies actions to advance the simulation.
- Environment → Reward / Grade: scores · Environment emits rewards and terminal grading outputs.
- Action Flow → Scenarios: reveals facts · Task content controls what evidence can be uncovered by actions.
- Reward / Grade → Graders: evaluates · Final scoring is driven by deterministic grader logic.
- Scenarios → Alert Triage: defines · Scenario set includes the alert triage task.
- Scenarios → Cascading Diagnosis: defines · Scenario set includes the cascading diagnosis task.
- Scenarios → Postmortem Writing: defines · Scenario set includes the postmortem writing task.
- Alert Triage → Graders: classifies · Task 1 is primarily scored by alert classification quality.
- Cascading Diagnosis → Graders: evidence score · Task 2 is scored by investigation quality and diagnosis.
- Postmortem Writing → Graders: artifact score · Task 3 is scored by postmortem structure and content.
- Inference → Server App: episodes · Runner executes the environment through the service layer.
- Environment → Inference: observations / rewards · Step results flow back to the runner for decision and logging.
