# redbarron23/obs-agent architecture

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

- Interactive diagram: https://gitdiagram.com/redbarron23/obs-agent
- Repository: https://github.com/redbarron23/obs-agent

## Overview

obs-agent answers natural-language Azure and GCP logging-cost questions using an LLM tool-use loop over deterministic synthetic data. Users enter through the CLI/REPL or Streamlit chat; the agent calls cost-analysis tools, receives formatted results, and returns a concise answer, with streaming and conversation history supported. The graph also preserves provider integration and the documented evaluation harness. Source excerpts show the main calls; provider API behavior and some agent-loop details are documented in the README.

Main entry points: [`tools.py`](https://github.com/redbarron23/obs-agent/blob/main/tools.py) (Tool dispatch), [`agent.py`](https://github.com/redbarron23/obs-agent/blob/main/agent.py) (Agent loop), [`data.py`](https://github.com/redbarron23/obs-agent/blob/main/data.py) (Billing DataFrames), [`evals.py`](https://github.com/redbarron23/obs-agent/blob/main/evals.py) (Ground-truth evals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI / REPL<br/>[agent.py]"]
  node_web["Streamlit chat<br/>[app.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_loop["Agent loop<br/>[agent.py]"]
  node_providers{{"LLM providers<br/>[agent.py]"}}
end

subgraph group_analysis["Cost analysis"]
  node_dispatch["Tool dispatch<br/>[tools.py]"]
  node_azure["Azure overages<br/>[tools.py]"]
  node_gcp["GCP rankings<br/>[tools.py]"]
  node_trend["Daily trends<br/>[tools.py]"]
  node_spikes["Spike detection<br/>[tools.py]"]
  node_crosscloud["Cross-cloud comparison<br/>[tools.py]"]
end

subgraph group_data["Synthetic billing data"]
  node_datasets[("Billing DataFrames<br/>[data.py]")]
end

subgraph group_quality["Evaluation"]
  node_evals["Ground-truth evals<br/>[evals.py]"]
end

node_user(("Cost analyst"))

node_user -->|"asks"| node_cli
node_user -->|"asks"| node_web
node_cli -->|"runs"| node_loop
node_web -->|"calls"| node_loop
node_loop -->|"requests"| node_providers
node_providers -->|"returns response"| node_loop
node_loop -->|"dispatches tools"| node_dispatch
node_dispatch -->|"invokes"| node_azure
node_dispatch -->|"invokes"| node_gcp
node_dispatch -->|"invokes"| node_trend
node_dispatch -->|"invokes"| node_spikes
node_dispatch -->|"invokes"| node_crosscloud
node_azure -->|"reads"| node_datasets
node_gcp -->|"reads"| node_datasets
node_trend -->|"reads"| node_datasets
node_spikes -->|"reads"| node_datasets
node_crosscloud -->|"reads"| node_datasets
node_evals -->|"dry-run checks"| node_dispatch
node_evals -->|"live checks"| node_loop

click node_cli "https://github.com/redbarron23/obs-agent/blob/main/agent.py"
click node_web "https://github.com/redbarron23/obs-agent/blob/main/app.py"
click node_loop "https://github.com/redbarron23/obs-agent/blob/main/agent.py"
click node_providers "https://github.com/redbarron23/obs-agent/blob/main/agent.py"
click node_dispatch "https://github.com/redbarron23/obs-agent/blob/main/tools.py"
click node_azure "https://github.com/redbarron23/obs-agent/blob/main/tools.py"
click node_gcp "https://github.com/redbarron23/obs-agent/blob/main/tools.py"
click node_trend "https://github.com/redbarron23/obs-agent/blob/main/tools.py"
click node_spikes "https://github.com/redbarron23/obs-agent/blob/main/tools.py"
click node_crosscloud "https://github.com/redbarron23/obs-agent/blob/main/tools.py"
click node_datasets "https://github.com/redbarron23/obs-agent/blob/main/data.py"
click node_evals "https://github.com/redbarron23/obs-agent/blob/main/evals.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_web toneBlue
class node_loop,node_providers toneAmber
class node_dispatch,node_azure,node_gcp,node_trend,node_spikes,node_crosscloud toneMint
class node_datasets toneRose
class node_evals,node_user toneIndigo
```

## Components

### User interfaces

- [CLI / REPL](https://github.com/redbarron23/obs-agent/blob/main/agent.py): `agent.py`
- [Streamlit chat](https://github.com/redbarron23/obs-agent/blob/main/app.py): `app.py`

### Agent runtime

- [Agent loop](https://github.com/redbarron23/obs-agent/blob/main/agent.py): `agent.py`
- [LLM providers](https://github.com/redbarron23/obs-agent/blob/main/agent.py): `agent.py`

### Cost analysis

- [Tool dispatch](https://github.com/redbarron23/obs-agent/blob/main/tools.py): `tools.py`
- [Azure overages](https://github.com/redbarron23/obs-agent/blob/main/tools.py): `tools.py`
- [GCP rankings](https://github.com/redbarron23/obs-agent/blob/main/tools.py): `tools.py`
- [Daily trends](https://github.com/redbarron23/obs-agent/blob/main/tools.py): `tools.py`
- [Spike detection](https://github.com/redbarron23/obs-agent/blob/main/tools.py): `tools.py`
- [Cross-cloud comparison](https://github.com/redbarron23/obs-agent/blob/main/tools.py): `tools.py`

### Synthetic billing data

- [Billing DataFrames](https://github.com/redbarron23/obs-agent/blob/main/data.py): `data.py`

### Evaluation

- [Ground-truth evals](https://github.com/redbarron23/obs-agent/blob/main/evals.py): `evals.py`

### Other components

- **Cost analyst**

## Connections

- Cost analyst → CLI / REPL: asks (evidence: `README.md`)
- Cost analyst → Streamlit chat: asks (evidence: `README.md`)
- CLI / REPL → Agent loop: runs (evidence: `README.md`)
- Streamlit chat → Agent loop: calls (evidence: `app.py`)
- Agent loop → LLM providers: requests (evidence: `README.md`)
- LLM providers → Agent loop: returns response (evidence: `README.md`)
- Agent loop → Tool dispatch: dispatches tools (evidence: `README.md`)
- Tool dispatch → Azure overages: invokes (evidence: `tools.py`)
- Tool dispatch → GCP rankings: invokes (evidence: `tools.py`)
- Tool dispatch → Daily trends: invokes (evidence: `tools.py`)
- Tool dispatch → Spike detection: invokes (evidence: `tools.py`)
- Tool dispatch → Cross-cloud comparison: invokes (evidence: `tools.py`)
- Azure overages → Billing DataFrames: reads (evidence: `tools.py`)
- GCP rankings → Billing DataFrames: reads (evidence: `tools.py`)
- Daily trends → Billing DataFrames: reads (evidence: `tools.py`)
- Spike detection → Billing DataFrames: reads (evidence: `tools.py`)
- Cross-cloud comparison → Billing DataFrames: reads (evidence: `tools.py`)
- Ground-truth evals → Tool dispatch: dry-run checks (evidence: `evals.py`)
- Ground-truth evals → Agent loop: live checks (evidence: `evals.py`)
