# robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent architecture

> Architecture diagram of the GitHub repository robyvn/k5-l3-day4-nguyenngochieu-2a202603502-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/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent
- Repository: https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent

## Overview

This repository is a Python learning lab for building a status-investigation agent. Its intended user workflow is to submit a question through the CLI, let an LLM request status tools, and return a sourced answer; the agent loop is currently an unimplemented exercise. Users can also run evaluation cases that grade answers and traces, and optionally investigate five providers with paginated incident details. The graph reflects documented and excerpted relationships; the main loop’s runtime calls are described in the README but not implemented in the sampled agent source.

Main entry points: [`evals/run_evals.py`](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/run_evals.py) (Eval Runner), [`bonus/tools.py`](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/bonus/tools.py) (Bonus Tools), [`status_tools.py`](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/status_tools.py) (Status Tools), [`run.py`](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/run.py) (Run CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_cli["Run CLI<br/>[run.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_loop["Agent Loop<br/>[agent.py]"]
  node_provider["LLM Adapter<br/>[providers.py]"]
end

subgraph group_status["Status Investigation"]
  node_status_tools["Status Tools<br/>[status_tools.py]"]
  node_snapshots[("Core Snapshots")]
  node_bonus_tools["Bonus Tools<br/>[tools.py]"]
  node_bonus_snapshots[("Bonus Snapshots")]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Eval Runner<br/>[run_evals.py]"]
  node_scenarios["Eval Scenarios<br/>[scenarios.py]"]
  node_grader["LLM Grader<br/>[grading.py]"]
  node_eval_cases["Eval Cases<br/>[cases.json]"]
  node_bonus_cases["Bonus Cases<br/>[cases.json]"]
end

node_user(("User"))
node_llm{{"LLM API"}}
node_status_api{{"Status APIs"}}

node_user -->|"asks"| node_cli
node_cli -->|"runs"| node_loop
node_cli -->|"configures"| node_provider
node_cli -->|"selects"| node_status_tools
node_cli -->|"optionally selects"| node_bonus_tools
node_loop -.->|"requests completion"| node_provider
node_loop -.->|"executes tools"| node_status_tools
node_loop -.->|"optionally executes"| node_bonus_tools
node_provider -->|"sends requests"| node_llm
node_status_tools -->|"reads snapshots"| node_snapshots
node_status_tools -->|"fetches live data"| node_status_api
node_bonus_tools -->|"reads core snapshots"| node_snapshots
node_bonus_tools -->|"reads bonus snapshots"| node_bonus_snapshots
node_bonus_tools -->|"fetches live data"| node_status_api
node_bonus_tools -->|"uses schema"| node_status_tools
node_user -->|"runs evals"| node_eval_runner
node_eval_runner -->|"loads cases"| node_eval_cases
node_eval_runner -->|"optionally loads"| node_bonus_cases
node_eval_runner -->|"runs cases"| node_loop
node_eval_runner -->|"configures models"| node_provider
node_eval_runner -->|"selects tools"| node_scenarios
node_scenarios -->|"delegates"| node_status_tools
node_eval_runner -->|"grades results"| node_grader
node_grader -->|"requests judge completion"| node_provider

click node_cli "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/run.py"
click node_loop "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/agent.py"
click node_provider "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/providers.py"
click node_status_tools "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/status_tools.py"
click node_snapshots "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/tree/main/fixtures"
click node_bonus_tools "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/bonus/tools.py"
click node_bonus_snapshots "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/tree/main/bonus/fixtures"
click node_eval_runner "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/run_evals.py"
click node_scenarios "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/scenarios.py"
click node_grader "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/grading.py"
click node_eval_cases "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/cases.json"
click node_bonus_cases "https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-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_user toneBlue
class node_loop,node_provider toneAmber
class node_status_tools,node_snapshots,node_bonus_tools,node_bonus_snapshots,node_llm,node_status_api toneMint
class node_eval_runner,node_scenarios,node_grader,node_eval_cases,node_bonus_cases toneRose
```

## Components

### User Interface

- [Run CLI](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/run.py): `run.py`

### Agent Runtime

- [Agent Loop](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/agent.py): `agent.py`
- [LLM Adapter](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/providers.py): `providers.py`

### Status Investigation

- [Status Tools](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/status_tools.py): `status_tools.py`
- [Core Snapshots](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/tree/main/fixtures): `fixtures`
- [Bonus Tools](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/bonus/tools.py): `bonus/tools.py`
- [Bonus Snapshots](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/tree/main/bonus/fixtures): `bonus/fixtures`

### Evaluation

- [Eval Runner](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/run_evals.py): `evals/run_evals.py`
- [Eval Scenarios](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/scenarios.py): `evals/scenarios.py`
- [LLM Grader](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/grading.py): `evals/grading.py`
- [Eval Cases](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/evals/cases.json): `evals/cases.json`
- [Bonus Cases](https://github.com/robyvn/k5-l3-day4-nguyenngochieu-2a202603502-reactloopagent/blob/main/bonus/cases.json): `bonus/cases.json`

### Other components

- **User**
- **LLM API**
- **Status APIs**

## Connections

- User → Run CLI: asks (evidence: `README.md`)
- Run CLI → Agent Loop: runs (evidence: `run.py`)
- Run CLI → LLM Adapter: configures (evidence: `run.py`)
- Run CLI → Status Tools: selects (evidence: `run.py`)
- Run CLI → Bonus Tools: optionally selects (evidence: `run.py`)
- Agent Loop → LLM Adapter: requests completion (evidence: `README.md`)
- Agent Loop → Status Tools: executes tools (evidence: `README.md`)
- Agent Loop → Bonus Tools: optionally executes (evidence: `README.md`)
- LLM Adapter → LLM API: sends requests (evidence: `providers.py`)
- Status Tools → Core Snapshots: reads snapshots (evidence: `status_tools.py`)
- Status Tools → Status APIs: fetches live data (evidence: `status_tools.py`)
- Bonus Tools → Core Snapshots: reads core snapshots (evidence: `bonus/tools.py`)
- Bonus Tools → Bonus Snapshots: reads bonus snapshots (evidence: `bonus/tools.py`)
- Bonus Tools → Status APIs: fetches live data (evidence: `bonus/tools.py`)
- Bonus Tools → Status Tools: uses schema (evidence: `bonus/tools.py`)
- User → Eval Runner: runs evals (evidence: `README.md`)
- Eval Runner → Eval Cases: loads cases (evidence: `evals/run_evals.py`)
- Eval Runner → Bonus Cases: optionally loads (evidence: `evals/run_evals.py`)
- Eval Runner → Agent Loop: runs cases (evidence: `evals/run_evals.py`)
- Eval Runner → LLM Adapter: configures models (evidence: `evals/run_evals.py`)
- Eval Runner → Eval Scenarios: selects tools (evidence: `evals/run_evals.py`)
- Eval Scenarios → Status Tools: delegates (evidence: `evals/scenarios.py`)
- Eval Runner → LLM Grader: grades results (evidence: `evals/run_evals.py`)
- LLM Grader → LLM Adapter: requests judge completion (evidence: `evals/grading.py`)