# sarvamai/llm_intent_entity architecture

> Architecture diagram of the GitHub repository sarvamai/llm_intent_entity, 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/sarvamai/llm_intent_entity
- Repository: https://github.com/sarvamai/llm_intent_entity

## Overview

This package evaluates ASR transcriptions for preservation of intent and entities, rather than textual similarity. The main workflow loads a dataset, normalizes reference and predicted text, submits evaluation prompts to an LLM, computes aggregate metrics, and saves results and logs; Google Sheets upload is an optional output. The README also documents language support, caching, and failed-request reporting. Source excerpts establish the main orchestration, API request handling, and Sheets upload; links not directly shown in the excerpts are omitted.

Main entry points: [`src/llm_intent_entity/main.py`](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/main.py) (Evaluation orchestration), [`src/llm_intent_entity/llm_api.py`](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/llm_api.py) (LLM request client), [`src/llm_intent_entity/utilities.py`](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.py) (Sheets upload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Evaluation workflow"]
  node_orchestrator["Evaluation orchestration<br/>[main.py]"]
end

subgraph group_language["Language processing"]
  node_normalization["Text normalization<br/>[utilities.py]"]
end

subgraph group_llm["LLM evaluation"]
  node_llm_client["LLM request client<br/>[llm_api.py]"]
end

subgraph group_results["Results and reporting"]
  node_metrics["Intent and entity metrics<br/>[utilities.py]"]
  node_result_files["CSV and evaluation logs<br/>[main.py]"]
  node_sheets_upload["Sheets upload<br/>[utilities.py]"]
end

node_dataset(("Dataset input"))
node_vertex["Vertex AI"]
node_google_sheets[("Google Sheets")]

node_dataset -->|"provides dataset"| node_orchestrator
node_orchestrator -->|"normalizes text"| node_normalization
node_orchestrator -->|"queues prompts"| node_llm_client
node_llm_client -.->|"requests evaluations"| node_vertex
node_orchestrator -->|"calculates scores"| node_metrics
node_orchestrator -->|"writes results"| node_result_files
node_orchestrator -->|"uploads results"| node_sheets_upload
node_sheets_upload -->|"writes worksheets"| node_google_sheets

click node_orchestrator "https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/main.py"
click node_normalization "https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.py"
click node_llm_client "https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/llm_api.py"
click node_metrics "https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.py"
click node_result_files "https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/main.py"
click node_sheets_upload "https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.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_orchestrator toneBlue
class node_normalization,node_google_sheets toneAmber
class node_llm_client toneMint
class node_metrics,node_result_files,node_sheets_upload toneRose
class node_dataset,node_vertex toneIndigo
```

## Components

### Evaluation workflow

- [Evaluation orchestration](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/main.py): `src/llm_intent_entity/main.py`

### Language processing

- [Text normalization](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.py): `src/llm_intent_entity/utilities.py`

### LLM evaluation

- [LLM request client](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/llm_api.py): `src/llm_intent_entity/llm_api.py`

### Results and reporting

- [Intent and entity metrics](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.py): `src/llm_intent_entity/utilities.py`
- [CSV and evaluation logs](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/main.py): `src/llm_intent_entity/main.py`
- [Sheets upload](https://github.com/sarvamai/llm_intent_entity/blob/main/src/llm_intent_entity/utilities.py): `src/llm_intent_entity/utilities.py`

### Other components

- **Dataset input**
- **Vertex AI**
- **Google Sheets**

## Connections

- Dataset input → Evaluation orchestration: provides dataset (evidence: `README.md`)
- Evaluation orchestration → Text normalization: normalizes text (evidence: `src/llm_intent_entity/main.py`)
- Evaluation orchestration → LLM request client: queues prompts (evidence: `src/llm_intent_entity/main.py`)
- LLM request client → Vertex AI: requests evaluations
- Evaluation orchestration → Intent and entity metrics: calculates scores (evidence: `src/llm_intent_entity/main.py`)
- Evaluation orchestration → CSV and evaluation logs: writes results (evidence: `src/llm_intent_entity/main.py`)
- Evaluation orchestration → Sheets upload: uploads results (evidence: `src/llm_intent_entity/main.py`)
- Sheets upload → Google Sheets: writes worksheets (evidence: `src/llm_intent_entity/utilities.py`)
