# vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent architecture

> Architecture diagram of the GitHub repository vox304/k5-l3a-day4-vocongminh-2a202603520-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/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent
- Repository: https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent

## Overview

This repository is a Python lab for building a status-investigation agent, not a finished agent product: `agent.py` currently raises `NotImplementedError`. The intended user workflow is to submit a question through the CLI, have an LLM request status tools, and receive tool results in the conversation before a final answer. The lab also supports snapshot/live status data, an optional multi-provider bonus toolset, and evaluation with an LLM judge. The agent-loop relationships are documented, but its runtime implementation is not present in the sampled source.

Main entry points: [`evals/run_evals.py`](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/run_evals.py) (Eval runner), [`providers.py`](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/providers.py) (LLM adapter), [`run.py`](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/run.py) (CLI runner), [`agent.py`](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/agent.py) (Agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_cli["CLI runner<br/>[run.py]"]
  node_loop["Agent loop<br/>[agent.py]"]
  node_provider["LLM adapter<br/>[providers.py]"]
end

subgraph group_status["Status investigation"]
  node_status_tools["Core status tools<br/>[status_tools.py]"]
  node_snapshots["Status snapshots"]
end

subgraph group_bonus["Bonus tools"]
  node_bonus_tools["Bonus status 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_cases["Eval cases<br/>[cases.json]"]
  node_grader["Case grader<br/>[grading.py]"]
end

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

node_user -->|"submits question"| node_cli
node_cli -->|"runs agent"| node_loop
node_cli -->|"configures provider"| node_provider
node_cli -->|"selects core tools"| node_status_tools
node_cli -->|"selects bonus tools"| node_bonus_tools
node_loop -.->|"requests completion"| node_provider
node_provider -->|"sends requests"| node_llm
node_llm -->|"returns response"| node_provider
node_loop -.->|"executes tool calls"| node_status_tools
node_loop -.->|"executes tool calls"| node_bonus_tools
node_status_tools -->|"reads snapshot"| node_snapshots
node_status_tools -->|"fetches live status"| node_status_api
node_bonus_tools -->|"reads snapshot"| node_bonus_snapshots
node_bonus_tools -->|"fetches live status"| node_status_api
node_eval_runner -->|"runs cases"| node_loop
node_eval_runner -->|"creates providers"| node_provider
node_eval_runner -->|"selects scenario tools"| node_scenarios
node_scenarios -->|"extends core tools"| node_status_tools
node_eval_runner -->|"runs bonus tools"| node_bonus_tools
node_eval_runner -->|"loads cases"| node_cases
node_eval_runner -->|"grades results"| node_grader
node_grader -->|"requests judge score"| node_provider

click node_cli "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/run.py"
click node_loop "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/agent.py"
click node_provider "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/providers.py"
click node_status_tools "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/status_tools.py"
click node_snapshots "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/tree/main/fixtures"
click node_bonus_tools "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/bonus/tools.py"
click node_bonus_snapshots "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/tree/main/bonus/fixtures"
click node_eval_runner "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/run_evals.py"
click node_scenarios "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/scenarios.py"
click node_cases "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/cases.json"
click node_grader "https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/grading.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_loop,node_provider,node_user toneBlue
class node_status_tools,node_snapshots toneAmber
class node_bonus_tools,node_bonus_snapshots,node_status_api toneMint
class node_eval_runner,node_scenarios,node_cases,node_grader toneRose
class node_llm toneIndigo
```

## Components

### Agent runtime

- [CLI runner](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/run.py): `run.py`
- [Agent loop](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/agent.py): `agent.py`
- [LLM adapter](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/providers.py): `providers.py`

### Status investigation

- [Core status tools](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/status_tools.py): `status_tools.py`
- [Status snapshots](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/tree/main/fixtures): `fixtures`

### Bonus tools

- [Bonus status tools](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/bonus/tools.py): `bonus/tools.py`
- [Bonus snapshots](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/tree/main/bonus/fixtures): `bonus/fixtures`

### Evaluation

- [Eval runner](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/run_evals.py): `evals/run_evals.py`
- [Eval scenarios](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/scenarios.py): `evals/scenarios.py`
- [Eval cases](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/cases.json): `evals/cases.json`
- [Case grader](https://github.com/vox304/k5-l3a-day4-vocongminh-2a202603520-reactloopagent/blob/main/evals/grading.py): `evals/grading.py`

### Other components

- **User**
- **LLM service**
- **Status APIs**

## Connections

- User → CLI runner: submits question (evidence: `README.md`)
- CLI runner → Agent loop: runs agent (evidence: `run.py`)
- CLI runner → LLM adapter: configures provider (evidence: `run.py`)
- CLI runner → Core status tools: selects core tools (evidence: `run.py`)
- CLI runner → Bonus status tools: selects bonus tools (evidence: `run.py`)
- Agent loop → LLM adapter: requests completion (evidence: `README.md`)
- LLM adapter → LLM service: sends requests (evidence: `providers.py`)
- LLM service → LLM adapter: returns response (evidence: `providers.py`)
- Agent loop → Core status tools: executes tool calls (evidence: `README.md`)
- Agent loop → Bonus status tools: executes tool calls (evidence: `README.md`)
- Core status tools → Status snapshots: reads snapshot (evidence: `status_tools.py`)
- Core status tools → Status APIs: fetches live status (evidence: `status_tools.py`)
- Bonus status tools → Bonus snapshots: reads snapshot (evidence: `bonus/tools.py`)
- Bonus status tools → Status APIs: fetches live status (evidence: `bonus/tools.py`)
- Eval runner → Agent loop: runs cases (evidence: `evals/run_evals.py`)
- Eval runner → LLM adapter: creates providers (evidence: `evals/run_evals.py`)
- Eval runner → Eval scenarios: selects scenario tools (evidence: `evals/run_evals.py`)
- Eval scenarios → Core status tools: extends core tools (evidence: `evals/scenarios.py`)
- Eval runner → Bonus status tools: runs bonus tools (evidence: `evals/run_evals.py`)
- Eval runner → Eval cases: loads cases (evidence: `evals/run_evals.py`)
- Eval runner → Case grader: grades results (evidence: `evals/run_evals.py`)
- Case grader → LLM adapter: requests judge score (evidence: `evals/grading.py`)