# utsavhirani/email-action-extractor architecture

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

- Interactive diagram: https://gitdiagram.com/utsavhirani/email-action-extractor
- Repository: https://github.com/utsavhirani/email-action-extractor

## Overview

This project extracts business actions from an Email and, chiefly, evaluates extractor output against hand-labelled cases. The extraction workflow routes through a single entry point to either an offline keyword baseline or an optional OpenRouter LLM, returning validated actions. Separately, the evaluator loads golden cases, matches predicted actions, grades them, and builds a report; it accepts an extractor function rather than importing the extractor. Edges reflect documented or excerpted calls; no direct connection from the sample runner to evaluation is shown.

Main entry points: [`core/models.py`](https://github.com/utsavhirani/email-action-extractor/blob/main/core/models.py) (Email and Actions), [`core/extractor.py`](https://github.com/utsavhirani/email-action-extractor/blob/main/core/extractor.py) (Extraction Entry), [`core/llm_extractor.py`](https://github.com/utsavhirani/email-action-extractor/blob/main/core/llm_extractor.py) (LLM Extractor), [`evaluator/runner.py`](https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/runner.py) (Evaluation Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Models"]
  node_sample["Sample Runner<br/>[main.py]"]
  node_api["Extraction Entry<br/>[extractor.py]"]
  node_models["Email and Actions<br/>[models.py]"]
end

subgraph group_extract["Action Extraction"]
  node_config["Runtime Settings<br/>[config.py]"]
  node_stub["Keyword Baseline<br/>[stub_extractor.py]"]
  node_llm["LLM Extractor<br/>[llm_extractor.py]"]
  node_prompts["Prompt Builder<br/>[prompts.py]"]
end

subgraph group_eval["Evaluation"]
  node_golden["Golden Cases<br/>[golden.json]"]
  node_dataset["Dataset Loader<br/>[dataset.py]"]
  node_runner["Evaluation Runner<br/>[runner.py]"]
  node_matching["Action Matching<br/>[matching.py]"]
  node_metrics["Scoring Metrics<br/>[metrics.py]"]
end

subgraph group_integrations["External Integration"]
  node_openrouter["OpenRouter"]
end

node_caller(("Caller"))

node_caller -->|"calls"| node_api
node_sample -->|"calls"| node_api
node_sample -->|"builds email"| node_models
node_api -->|"checks mode"| node_config
node_api -->|"dispatches to"| node_stub
node_api -->|"dispatches to"| node_llm
node_api -->|"uses types"| node_models
node_stub -->|"builds actions"| node_models
node_llm -->|"reads settings"| node_config
node_llm -->|"builds prompts"| node_prompts
node_llm -->|"validates output"| node_models
node_llm -->|"sends request"| node_openrouter
node_prompts -->|"formats email"| node_models
node_golden -->|"loaded by"| node_dataset
node_dataset -->|"validates cases"| node_models
node_runner -->|"matches actions"| node_matching
node_runner -->|"grades and aggregates"| node_metrics
node_runner -->|"uses types"| node_models
node_metrics -->|"scores matches"| node_matching
node_metrics -->|"grades fields"| node_models

click node_sample "https://github.com/utsavhirani/email-action-extractor/blob/main/main.py"
click node_api "https://github.com/utsavhirani/email-action-extractor/blob/main/core/extractor.py"
click node_models "https://github.com/utsavhirani/email-action-extractor/blob/main/core/models.py"
click node_config "https://github.com/utsavhirani/email-action-extractor/blob/main/core/config.py"
click node_stub "https://github.com/utsavhirani/email-action-extractor/blob/main/core/stub_extractor.py"
click node_llm "https://github.com/utsavhirani/email-action-extractor/blob/main/core/llm_extractor.py"
click node_prompts "https://github.com/utsavhirani/email-action-extractor/blob/main/core/prompts.py"
click node_golden "https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/data/golden.json"
click node_dataset "https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/dataset.py"
click node_runner "https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/runner.py"
click node_matching "https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/matching.py"
click node_metrics "https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/metrics.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_sample,node_api,node_models toneBlue
class node_config,node_stub,node_llm,node_prompts toneAmber
class node_golden,node_dataset,node_runner,node_matching,node_metrics toneMint
class node_openrouter toneRose
class node_caller toneIndigo
```

## Components

### Entry and Models

- [Sample Runner](https://github.com/utsavhirani/email-action-extractor/blob/main/main.py): `main.py`
- [Extraction Entry](https://github.com/utsavhirani/email-action-extractor/blob/main/core/extractor.py): `core/extractor.py`
- [Email and Actions](https://github.com/utsavhirani/email-action-extractor/blob/main/core/models.py): `core/models.py`

### Action Extraction

- [Runtime Settings](https://github.com/utsavhirani/email-action-extractor/blob/main/core/config.py): `core/config.py`
- [Keyword Baseline](https://github.com/utsavhirani/email-action-extractor/blob/main/core/stub_extractor.py): `core/stub_extractor.py`
- [LLM Extractor](https://github.com/utsavhirani/email-action-extractor/blob/main/core/llm_extractor.py): `core/llm_extractor.py`
- [Prompt Builder](https://github.com/utsavhirani/email-action-extractor/blob/main/core/prompts.py): `core/prompts.py`

### Evaluation

- [Golden Cases](https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/data/golden.json): `evaluator/data/golden.json`
- [Dataset Loader](https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/dataset.py): `evaluator/dataset.py`
- [Evaluation Runner](https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/runner.py): `evaluator/runner.py`
- [Action Matching](https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/matching.py): `evaluator/matching.py`
- [Scoring Metrics](https://github.com/utsavhirani/email-action-extractor/blob/main/evaluator/metrics.py): `evaluator/metrics.py`

### External Integration

- **OpenRouter**

### Other components

- **Caller**

## Connections

- Caller → Extraction Entry: calls (evidence: `README.md`)
- Sample Runner → Extraction Entry: calls (evidence: `main.py`)
- Sample Runner → Email and Actions: builds email (evidence: `main.py`)
- Extraction Entry → Runtime Settings: checks mode (evidence: `core/extractor.py`)
- Extraction Entry → Keyword Baseline: dispatches to (evidence: `core/extractor.py`)
- Extraction Entry → LLM Extractor: dispatches to (evidence: `core/extractor.py`)
- Extraction Entry → Email and Actions: uses types (evidence: `core/extractor.py`)
- Keyword Baseline → Email and Actions: builds actions (evidence: `core/stub_extractor.py`)
- LLM Extractor → Runtime Settings: reads settings (evidence: `core/llm_extractor.py`)
- LLM Extractor → Prompt Builder: builds prompts (evidence: `core/llm_extractor.py`)
- LLM Extractor → Email and Actions: validates output (evidence: `core/llm_extractor.py`)
- LLM Extractor → OpenRouter: sends request (evidence: `core/llm_extractor.py`)
- Prompt Builder → Email and Actions: formats email (evidence: `core/prompts.py`)
- Golden Cases → Dataset Loader: loaded by (evidence: `evaluator/dataset.py`)
- Dataset Loader → Email and Actions: validates cases (evidence: `evaluator/dataset.py`)
- Evaluation Runner → Action Matching: matches actions (evidence: `evaluator/runner.py`)
- Evaluation Runner → Scoring Metrics: grades and aggregates (evidence: `evaluator/runner.py`)
- Evaluation Runner → Email and Actions: uses types (evidence: `evaluator/runner.py`)
- Scoring Metrics → Action Matching: scores matches (evidence: `evaluator/metrics.py`)
- Scoring Metrics → Email and Actions: grades fields (evidence: `evaluator/metrics.py`)
