# lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent architecture

> Architecture diagram of the GitHub repository lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent
- Repository: https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent

## Overview

This is a Python status-investigation agent and teaching lab. The main workflow accepts a user question, runs an LLM/tool loop, queries GitHub or Cloudflare status data, and returns an answer with a trace. The CLI selects snapshot or live data and an LLM provider. A separate bonus toolset adds three providers and paginated incident details. Eval runs exercise the agent and use mechanical checks plus an LLM judge. Core runtime paths were sampled; the bonus and eval capabilities are also documented in the README. Not every unsampled connection is shown.

Main entry points: [`evals/run_evals.py`](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/run_evals.py) (Eval runner), [`agent.py`](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/agent.py) (Agent loop), [`bonus/tools.py`](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/bonus/tools.py) (Bonus status tools), [`run.py`](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/run.py) (CLI runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Agent interaction"]
  node_cli["CLI runner<br/>[run.py]"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_trace["Run trace<br/>[agent.py]"]
end

subgraph group_models["Model providers"]
  node_model_adapter["Provider adapter<br/>[providers.py]"]
  node_llm{{"LLM service"}}
end

subgraph group_status["Status investigation"]
  node_core_tools["Core status tools<br/>[status_tools.py]"]
  node_core_snapshots[("Core snapshots")]
  node_core_apis{{"GitHub and Cloudflare APIs"}}
  node_bonus_tools["Bonus status tools<br/>[tools.py]"]
  node_bonus_snapshots[("Bonus snapshots")]
  node_bonus_apis{{"Additional status APIs"}}
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Eval runner<br/>[run_evals.py]"]
  node_eval_cases["Eval cases<br/>[cases.json]"]
  node_scenario_tools["Fault scenarios<br/>[scenarios.py]"]
  node_grader["Eval grader<br/>[grading.py]"]
  node_bonus_cases["Bonus cases<br/>[cases.json]"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_cli
node_cli -->|"runs"| node_agent
node_cli -->|"configures"| node_model_adapter
node_cli -->|"selects"| node_core_tools
node_cli -->|"selects bonus"| node_bonus_tools
node_agent -->|"requests completion"| node_model_adapter
node_model_adapter -->|"sends requests"| node_llm
node_agent -->|"executes calls"| node_core_tools
node_agent -->|"executes calls"| node_bonus_tools
node_agent -->|"records results"| node_trace
node_core_tools -->|"reads snapshots"| node_core_snapshots
node_core_tools -->|"fetches status"| node_core_apis
node_bonus_tools -->|"reads core snapshots"| node_core_snapshots
node_bonus_tools -->|"reads snapshots"| node_bonus_snapshots
node_bonus_tools -->|"fetches status"| node_bonus_apis
node_user -->|"requests evaluation"| node_eval_runner
node_eval_runner -->|"loads cases"| node_eval_cases
node_eval_runner -->|"loads bonus cases"| node_bonus_cases
node_eval_runner -->|"runs cases"| node_agent
node_eval_runner -->|"creates providers"| node_model_adapter
node_eval_runner -->|"selects scenarios"| node_scenario_tools
node_eval_runner -->|"selects bonus tools"| node_bonus_tools
node_eval_runner -->|"grades results"| node_grader
node_grader -->|"requests judge"| node_model_adapter

click node_cli "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/run.py"
click node_agent "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/agent.py"
click node_trace "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/agent.py"
click node_model_adapter "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/providers.py"
click node_core_tools "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/status_tools.py"
click node_core_snapshots "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/tree/main/fixtures"
click node_bonus_tools "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/bonus/tools.py"
click node_bonus_snapshots "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/tree/main/bonus/fixtures"
click node_eval_runner "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/run_evals.py"
click node_eval_cases "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/cases.json"
click node_scenario_tools "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/scenarios.py"
click node_grader "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/grading.py"
click node_bonus_cases "https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/bonus/cases.json"

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_agent,node_trace toneBlue
class node_model_adapter,node_llm toneAmber
class node_core_tools,node_core_snapshots,node_core_apis,node_bonus_tools,node_bonus_snapshots,node_bonus_apis toneMint
class node_eval_runner,node_eval_cases,node_scenario_tools,node_grader,node_bonus_cases toneRose
class node_user toneIndigo
```

## Components

### Agent interaction

- [CLI runner](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/run.py): `run.py`
- [Agent loop](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/agent.py): `agent.py`
- [Run trace](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/agent.py): `agent.py`

### Model providers

- [Provider adapter](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/providers.py): `providers.py`
- **LLM service**

### Status investigation

- [Core status tools](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/status_tools.py): `status_tools.py`
- [Core snapshots](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/tree/main/fixtures): `fixtures`
- **GitHub and Cloudflare APIs**
- [Bonus status tools](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/bonus/tools.py): `bonus/tools.py`
- [Bonus snapshots](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/tree/main/bonus/fixtures): `bonus/fixtures`
- **Additional status APIs**

### Evaluation

- [Eval runner](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/run_evals.py): `evals/run_evals.py`
- [Eval cases](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/cases.json): `evals/cases.json`
- [Fault scenarios](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/scenarios.py): `evals/scenarios.py`
- [Eval grader](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/evals/grading.py): `evals/grading.py`
- [Bonus cases](https://github.com/lyslama/k5-l3a-day4-lythanhlam-2a202603475-reactloopagent/blob/main/bonus/cases.json): `bonus/cases.json`

### Other components

- **Questioner**

## Connections

- Questioner → CLI runner: asks (evidence: `README.md`)
- CLI runner → Agent loop: runs (evidence: `run.py`)
- CLI runner → Provider adapter: configures (evidence: `run.py`)
- CLI runner → Core status tools: selects (evidence: `run.py`)
- CLI runner → Bonus status tools: selects bonus (evidence: `run.py`)
- Agent loop → Provider adapter: requests completion (evidence: `agent.py`)
- Provider adapter → LLM service: sends requests (evidence: `providers.py`)
- Agent loop → Core status tools: executes calls (evidence: `agent.py`)
- Agent loop → Bonus status tools: executes calls (evidence: `agent.py`)
- Agent loop → Run trace: records results (evidence: `agent.py`)
- Core status tools → Core snapshots: reads snapshots (evidence: `status_tools.py`)
- Core status tools → GitHub and Cloudflare APIs: fetches status (evidence: `status_tools.py`)
- Bonus status tools → Core snapshots: reads core snapshots (evidence: `bonus/tools.py`)
- Bonus status tools → Bonus snapshots: reads snapshots (evidence: `bonus/tools.py`)
- Bonus status tools → Additional status APIs: fetches status (evidence: `bonus/tools.py`)
- Questioner → Eval runner: requests evaluation (evidence: `README.md`)
- Eval runner → Eval cases: loads cases (evidence: `evals/run_evals.py`)
- Eval runner → Bonus cases: loads bonus cases (evidence: `evals/run_evals.py`)
- Eval runner → Agent loop: runs cases (evidence: `evals/run_evals.py`)
- Eval runner → Provider adapter: creates providers (evidence: `evals/run_evals.py`)
- Eval runner → Fault scenarios: selects scenarios (evidence: `evals/run_evals.py`)
- Eval runner → Bonus status tools: selects bonus tools (evidence: `evals/run_evals.py`)
- Eval runner → Eval grader: grades results (evidence: `evals/run_evals.py`)
- Eval grader → Provider adapter: requests judge (evidence: `evals/grading.py`)