# hundredeuk2/trackmyllm architecture

> Architecture diagram of the GitHub repository hundredeuk2/trackmyllm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hundredeuk2/trackmyllm
- Repository: https://github.com/hundredeuk2/trackmyllm

## Overview

##### Project type and purpose
- This is a lightweight Python SDK / library (“TrackMyLLM(cost)”) that developers import into their code to automatically measure and accumulate the monetary cost of their OpenAI API calls.
- It offers both synchronous and asynchronous decorators to wrap OpenAI client calls, loads pricing data from a YAML file, computes per-call cost, and exposes cumulative costs.

##### File structure
- setup.py: packaging and installation entry point.
- tracker/
- cost_tracker.py – core decorator and cost‐accumulation logic
- pricing_loader.py – loads and parses pricing.yaml
- pricing.yaml – defines per‐model cost parameters
- __init__.py – exposes the package’s public API
- tutorial/openai.ipynb – example usage notebook.

##### README for additional insights
- Describes two usage patterns (class‐based wrapper and standalone function).
- Demonstrates how cost_tracker intercepts OpenAI client calls, records individual costs, and computes totals.
- Mentions dependencies: openai Python package and the pricing YAML file baked into the tracker module.

##### Main components
a. Client Application (user code)
b. TrackMyLLM(cost) Library
– cost_tracker decorator
– pricing_loader + pricing.yaml
c. OpenAI Python Client (sync and async interfaces)
d. External OpenAI API Service
e. Internal Data Store (in‐memory dict of costs)

##### Relationships and interactions
1. At import/initialization, pricing_loader reads pricing.yaml into memory.
2. User code marks functions or methods with @cost_tracker.track_cost().
3. When the decorated method executes, cost_tracker:
- Forwards the call to the OpenAI Python client.
- Waits for the API response.
- Extracts usage metrics (#tokens in/out).
- Computes cost (via the loaded pricing parameters).
- Appends cost entries into an in‐memory dict keyed by model_name.
- Returns the original API response to the caller.
4. User code can query cost_tracker.costs or call total_cost() to retrieve aggregates.

##### Architectural patterns and design principles
- Decorator pattern: cost_tracker wraps arbitrary methods/functions without modifying them.
- Single Responsibility: pricing_loader only loads pricing; cost_tracker only tracks cost.
- Inversion of Control: the decorator intercepts calls rather than the user having to call a special API.
- Configuration externalized: pricing.yaml separate from code so it can be updated independently.

##### Technologies and libraries
- Python standard library (functools, yaml parser if used).
- openai (sync and asyncio clients).
- PyPI packaging via setup.py.
- YAML for configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing code
    UC["User Code\n(tutorial/openai.ipynb)"]:::user

    %% Library package root and modules
    subgraph "TrackMyLLM(cost) Library"
        direction TB
        APIinit["__init__.py"]:::lib
        Loader["pricing_loader.py"]:::lib
        PricingYAML["pricing.yaml"]:::lib
        Tracker["cost_tracker.py"]:::lib
        Store["In-Memory Cost Store"]:::lib
    end

    %% Packaging entry
    Setup["setup.py"]:::lib

    %% External and client services
    OC["OpenAI Python Client"]:::lib
    EXT["OpenAI API Service"]:::ext

    %% Relationships
    Setup -.->|packages| APIinit
    UC -->|invoke decorated function| Tracker
    Tracker -->|load pricing| Loader
    Loader -->|reads config| PricingYAML
    Tracker -->|invoke chat.completions.create| OC
    OC -->|HTTPS request| EXT
    EXT -->|response| OC
    OC -->|returns response| Tracker
    Tracker -->|compute cost & store| Store
    Tracker -->|return API response| UC

    %% Click events
    click UC "https://github.com/hundredeuk2/trackmyllm/blob/main/tutorial/openai.ipynb"
    click Tracker "https://github.com/hundredeuk2/trackmyllm/blob/main/tracker/cost_tracker.py"
    click Loader "https://github.com/hundredeuk2/trackmyllm/blob/main/tracker/pricing_loader.py"
    click PricingYAML "https://github.com/hundredeuk2/trackmyllm/blob/main/tracker/pricing.yaml"
    click APIinit "https://github.com/hundredeuk2/trackmyllm/blob/main/tracker/__init__.py"
    click Setup "https://github.com/hundredeuk2/trackmyllm/blob/main/setup.py"

    %% Styles
    classDef user fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef lib fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ext fill:#ffe5b4,stroke:#333,stroke-width:1px
```
