# symmetry7/llm-cost-optimization architecture

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

- Interactive diagram: https://gitdiagram.com/symmetry7/llm-cost-optimization
- Repository: https://github.com/symmetry7/llm-cost-optimization

## Overview

ShopAssist resolves e-commerce support tickets into an action, a cited policy article, and (for the copilot path) a customer reply. Its two product workflows share ticket/order loading and a simulated LLM: Q1 builds one compact prompt and validates the response; Q2 triages deterministically, retrieves articles with BM25, composes once, then audits the draft. The README also documents the five policy cases and cost accounting. Edges reflect excerpts or README statements; the data directories are represented at their exact tree paths.

Main entry points: [`question2/agent.py`](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py) (SupportPipeline), [`question1/agent.py`](https://github.com/symmetry7/llm-cost-optimization/blob/main/question1/agent.py) (SupportCopilot), [`shared/llm.py`](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/llm.py) (LLM simulator client), [`shared/tools.py`](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/tools.py) (Ticket and order loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_q1["Q1 Copilot"]
  node_q1entry["Q1 CLI<br/>[run.py]"]
  node_copilot["SupportCopilot<br/>[agent.py]"]
end

subgraph group_q2["Q2 Pipeline"]
  node_q2entry["Q2 CLI<br/>[run.py]"]
  node_pipeline["SupportPipeline<br/>[agent.py]"]
  node_triage["Intent triage<br/>[agent.py]"]
  node_retrieval["BM25 retrieval<br/>[agent.py]"]
  node_compose["Draft composition<br/>[agent.py]"]
  node_audit["Draft audit<br/>[agent.py]"]
end

subgraph group_shared["Shared Runtime"]
  node_tools["Ticket and order loader<br/>[tools.py]"]
  node_kb["Article loader<br/>[kb.py]"]
  node_llm["LLM simulator client<br/>[llm.py]"]
  node_billing["Cost sessions<br/>[billing.py]"]
  node_tokens["Token counter<br/>[tokens.py]"]
end

subgraph group_policy["Policy Data"]
  node_tickets[("Ticket records")]
  node_orders[("Order records")]
  node_articles["Policy articles"]
end

subgraph group_harness["Simulator Harness"]
  node_reference["Decision simulator<br/>[reference.py]"]
end

node_operator(("Support operator"))

node_operator -->|"runs Q1"| node_q1entry
node_operator -->|"runs Q2"| node_q2entry
node_q1entry -->|"resolves tickets"| node_copilot
node_q2entry -->|"resolves tickets"| node_pipeline
node_copilot -->|"loads ticket data"| node_tools
node_tools -->|"reads tickets"| node_tickets
node_tools -->|"reads orders"| node_orders
node_copilot -->|"loads articles"| node_kb
node_kb -->|"reads articles"| node_articles
node_copilot -->|"sends prompt"| node_llm
node_copilot -->|"creates session"| node_billing
node_pipeline -->|"loads ticket data"| node_tools
node_pipeline -->|"dispatches triage"| node_triage
node_pipeline -->|"dispatches retrieval"| node_retrieval
node_pipeline -->|"dispatches compose"| node_compose
node_pipeline -->|"dispatches audit"| node_audit
node_triage -->|"supplies query terms"| node_retrieval
node_retrieval -->|"loads indexed articles"| node_kb
node_retrieval -->|"supplies top articles"| node_compose
node_compose -->|"sends draft prompt"| node_llm
node_compose -->|"uses compact helpers"| node_copilot
node_compose -->|"passes draft"| node_audit
node_audit -->|"parses and validates"| node_copilot
node_pipeline -->|"creates session"| node_billing
node_llm -->|"gets expected outcome"| node_reference
node_llm -->|"records call cost"| node_billing
node_billing -->|"counts prompt tokens"| node_tokens
node_llm -->|"counts cache prefix"| node_tokens

click node_q1entry "https://github.com/symmetry7/llm-cost-optimization/blob/main/question1/run.py"
click node_copilot "https://github.com/symmetry7/llm-cost-optimization/blob/main/question1/agent.py"
click node_q2entry "https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/run.py"
click node_pipeline "https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py"
click node_triage "https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py"
click node_retrieval "https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py"
click node_compose "https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py"
click node_audit "https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py"
click node_tools "https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/tools.py"
click node_tickets "https://github.com/symmetry7/llm-cost-optimization/tree/main/data/tickets"
click node_orders "https://github.com/symmetry7/llm-cost-optimization/tree/main/data/orders"
click node_kb "https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/kb.py"
click node_articles "https://github.com/symmetry7/llm-cost-optimization/tree/main/data/kb"
click node_llm "https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/llm.py"
click node_billing "https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/billing.py"
click node_tokens "https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/tokens.py"
click node_reference "https://github.com/symmetry7/llm-cost-optimization/blob/main/eval/reference.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_q1entry,node_copilot toneBlue
class node_q2entry,node_pipeline,node_triage,node_retrieval,node_compose,node_audit toneAmber
class node_tools,node_kb,node_llm,node_billing,node_tokens toneMint
class node_tickets,node_orders,node_articles toneRose
class node_reference,node_operator toneIndigo
```

## Components

### Q1 Copilot

- [Q1 CLI](https://github.com/symmetry7/llm-cost-optimization/blob/main/question1/run.py): `question1/run.py`
- [SupportCopilot](https://github.com/symmetry7/llm-cost-optimization/blob/main/question1/agent.py): `question1/agent.py`

### Q2 Pipeline

- [Q2 CLI](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/run.py): `question2/run.py`
- [SupportPipeline](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py): `question2/agent.py`
- [Intent triage](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py): `question2/agent.py`
- [BM25 retrieval](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py): `question2/agent.py`
- [Draft composition](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py): `question2/agent.py`
- [Draft audit](https://github.com/symmetry7/llm-cost-optimization/blob/main/question2/agent.py): `question2/agent.py`

### Shared Runtime

- [Ticket and order loader](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/tools.py): `shared/tools.py`
- [Article loader](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/kb.py): `shared/kb.py`
- [LLM simulator client](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/llm.py): `shared/llm.py`
- [Cost sessions](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/billing.py): `shared/billing.py`
- [Token counter](https://github.com/symmetry7/llm-cost-optimization/blob/main/shared/tokens.py): `shared/tokens.py`

### Policy Data

- [Ticket records](https://github.com/symmetry7/llm-cost-optimization/tree/main/data/tickets): `data/tickets`
- [Order records](https://github.com/symmetry7/llm-cost-optimization/tree/main/data/orders): `data/orders`
- [Policy articles](https://github.com/symmetry7/llm-cost-optimization/tree/main/data/kb): `data/kb`

### Simulator Harness

- [Decision simulator](https://github.com/symmetry7/llm-cost-optimization/blob/main/eval/reference.py): `eval/reference.py`

### Other components

- **Support operator**

## Connections

- Support operator → Q1 CLI: runs Q1 (evidence: `README.md`)
- Support operator → Q2 CLI: runs Q2 (evidence: `README.md`)
- Q1 CLI → SupportCopilot: resolves tickets (evidence: `question1/run.py`)
- Q2 CLI → SupportPipeline: resolves tickets (evidence: `question2/run.py`)
- SupportCopilot → Ticket and order loader: loads ticket data (evidence: `question1/agent.py`)
- Ticket and order loader → Ticket records: reads tickets (evidence: `shared/tools.py`)
- Ticket and order loader → Order records: reads orders (evidence: `shared/tools.py`)
- SupportCopilot → Article loader: loads articles (evidence: `question1/agent.py`)
- Article loader → Policy articles: reads articles (evidence: `shared/kb.py`)
- SupportCopilot → LLM simulator client: sends prompt (evidence: `question1/agent.py`)
- SupportCopilot → Cost sessions: creates session (evidence: `question1/agent.py`)
- SupportPipeline → Ticket and order loader: loads ticket data (evidence: `question2/agent.py`)
- SupportPipeline → Intent triage: dispatches triage (evidence: `question2/agent.py`)
- SupportPipeline → BM25 retrieval: dispatches retrieval (evidence: `question2/agent.py`)
- SupportPipeline → Draft composition: dispatches compose (evidence: `question2/agent.py`)
- SupportPipeline → Draft audit: dispatches audit (evidence: `question2/agent.py`)
- Intent triage → BM25 retrieval: supplies query terms (evidence: `question2/agent.py`)
- BM25 retrieval → Article loader: loads indexed articles (evidence: `question2/agent.py`)
- BM25 retrieval → Draft composition: supplies top articles (evidence: `question2/agent.py`)
- Draft composition → LLM simulator client: sends draft prompt (evidence: `question2/agent.py`)
- Draft composition → SupportCopilot: uses compact helpers (evidence: `question2/agent.py`)
- Draft composition → Draft audit: passes draft (evidence: `question2/agent.py`)
- Draft audit → SupportCopilot: parses and validates (evidence: `question2/agent.py`)
- SupportPipeline → Cost sessions: creates session (evidence: `question2/agent.py`)
- LLM simulator client → Decision simulator: gets expected outcome (evidence: `shared/llm.py`)
- LLM simulator client → Cost sessions: records call cost (evidence: `shared/llm.py`)
- Cost sessions → Token counter: counts prompt tokens (evidence: `shared/billing.py`)
- LLM simulator client → Token counter: counts cache prefix (evidence: `shared/llm.py`)