# venkatanaren/expense_ai_agent architecture

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

- Interactive diagram: https://gitdiagram.com/venkatanaren/expense_ai_agent
- Repository: https://github.com/venkatanaren/expense_ai_agent

## Overview

Expense Helper is a single-agent expense and KiwiSaver tracker. Users chat through the CLI or optional Streamlit UI; the agent sends tool-enabled requests to an NVIDIA-hosted model, dispatches requested operations, and persists records in SQLite. KiwiSaver also has CSV import and unit-price backfill paths, while usage reporting and benchmark scripts inspect agent telemetry. The main agent excerpt is partial, so internal tool dispatch and database ownership are represented at the agent boundary rather than split into unsupported subcomponents.

Main entry points: [`expense_agent.py`](https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py) (Agent loop and tools), [`app.py`](https://github.com/venkatanaren/expense_ai_agent/blob/main/app.py) (Streamlit UI), [`benchmark_agent.py`](https://github.com/venkatanaren/expense_ai_agent/blob/main/benchmark_agent.py) (Agent benchmark), [`import_kiwisaver.py`](https://github.com/venkatanaren/expense_ai_agent/blob/main/import_kiwisaver.py) (KiwiSaver CSV import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["CLI chat<br/>[expense_agent.py]"]
  node_web["Streamlit UI<br/>[app.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent["Agent loop and tools<br/>[expense_agent.py]"]
end

subgraph group_records["Expense and KiwiSaver records"]
  node_expense_ops["Expense operations<br/>[expense_agent.py]"]
  node_kiwi_ops["KiwiSaver operations<br/>[expense_agent.py]"]
  node_database[("SQLite records and telemetry<br/>[expense_agent.py]")]
end

subgraph group_operations["Data and telemetry utilities"]
  node_csv_import["KiwiSaver CSV import"]
  node_price_backfill["Implied price backfill"]
  node_usage_report["Usage report<br/>[usage_report.py]"]
  node_benchmark["Agent benchmark<br/>[benchmark_agent.py]"]
  node_comparison["Model comparison"]
end

node_user(("User"))
node_model{{"NVIDIA model API"}}

node_user -->|"enters chat"| node_cli
node_user -->|"uses tabs"| node_web
node_cli -->|"submits message"| node_agent
node_web -->|"calls run_agent"| node_agent
node_agent -->|"requests completion"| node_model
node_agent -->|"dispatches tools"| node_expense_ops
node_agent -->|"dispatches tools"| node_kiwi_ops
node_expense_ops -->|"reads and writes"| node_database
node_kiwi_ops -->|"reads and writes"| node_database
node_web -->|"queries records"| node_database
node_web -->|"gets summary"| node_kiwi_ops
node_csv_import -->|"inserts balances"| node_database
node_price_backfill -->|"updates prices"| node_database
node_usage_report -->|"reads call telemetry"| node_database
node_benchmark -->|"runs prompts"| node_agent
node_benchmark -->|"reads telemetry"| node_database
node_comparison -->|"runs prompts"| node_agent

click node_cli "https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py"
click node_web "https://github.com/venkatanaren/expense_ai_agent/blob/main/app.py"
click node_agent "https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py"
click node_expense_ops "https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py"
click node_kiwi_ops "https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py"
click node_database "https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py"
click node_csv_import "https://github.com/venkatanaren/expense_ai_agent/blob/main/import_kiwisaver.py"
click node_price_backfill "https://github.com/venkatanaren/expense_ai_agent/blob/main/backfill_implied_unit_price.py"
click node_usage_report "https://github.com/venkatanaren/expense_ai_agent/blob/main/usage_report.py"
click node_benchmark "https://github.com/venkatanaren/expense_ai_agent/blob/main/benchmark_agent.py"
click node_comparison "https://github.com/venkatanaren/expense_ai_agent/blob/main/benchmark_compare.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,node_user toneBlue
class node_agent toneAmber
class node_expense_ops,node_kiwi_ops,node_database,node_model toneMint
class node_csv_import,node_price_backfill,node_usage_report,node_benchmark,node_comparison toneRose
```

## Components

### User interaction

- [CLI chat](https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py): `expense_agent.py`
- [Streamlit UI](https://github.com/venkatanaren/expense_ai_agent/blob/main/app.py): `app.py`

### Agent runtime

- [Agent loop and tools](https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py): `expense_agent.py`

### Expense and KiwiSaver records

- [Expense operations](https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py): `expense_agent.py`
- [KiwiSaver operations](https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py): `expense_agent.py`
- [SQLite records and telemetry](https://github.com/venkatanaren/expense_ai_agent/blob/main/expense_agent.py): `expense_agent.py`

### Data and telemetry utilities

- [KiwiSaver CSV import](https://github.com/venkatanaren/expense_ai_agent/blob/main/import_kiwisaver.py): `import_kiwisaver.py`
- [Implied price backfill](https://github.com/venkatanaren/expense_ai_agent/blob/main/backfill_implied_unit_price.py): `backfill_implied_unit_price.py`
- [Usage report](https://github.com/venkatanaren/expense_ai_agent/blob/main/usage_report.py): `usage_report.py`
- [Agent benchmark](https://github.com/venkatanaren/expense_ai_agent/blob/main/benchmark_agent.py): `benchmark_agent.py`
- [Model comparison](https://github.com/venkatanaren/expense_ai_agent/blob/main/benchmark_compare.py): `benchmark_compare.py`

### Other components

- **User**
- **NVIDIA model API**

## Connections

- User → CLI chat: enters chat (evidence: `README.md`)
- User → Streamlit UI: uses tabs (evidence: `README.md`)
- CLI chat → Agent loop and tools: submits message (evidence: `README.md`)
- Streamlit UI → Agent loop and tools: calls run_agent (evidence: `app.py`)
- Agent loop and tools → NVIDIA model API: requests completion (evidence: `README.md`)
- Agent loop and tools → Expense operations: dispatches tools (evidence: `README.md`)
- Agent loop and tools → KiwiSaver operations: dispatches tools (evidence: `README.md`)
- Expense operations → SQLite records and telemetry: reads and writes (evidence: `expense_agent.py`)
- KiwiSaver operations → SQLite records and telemetry: reads and writes (evidence: `expense_agent.py`)
- Streamlit UI → SQLite records and telemetry: queries records (evidence: `app.py`)
- Streamlit UI → KiwiSaver operations: gets summary (evidence: `app.py`)
- KiwiSaver CSV import → SQLite records and telemetry: inserts balances (evidence: `import_kiwisaver.py`)
- Implied price backfill → SQLite records and telemetry: updates prices (evidence: `backfill_implied_unit_price.py`)
- Usage report → SQLite records and telemetry: reads call telemetry (evidence: `usage_report.py`)
- Agent benchmark → Agent loop and tools: runs prompts (evidence: `benchmark_agent.py`)
- Agent benchmark → SQLite records and telemetry: reads telemetry (evidence: `benchmark_agent.py`)
- Model comparison → Agent loop and tools: runs prompts (evidence: `benchmark_compare.py`)
