# will3watson3/pitch-intent-metric architecture

> Architecture diagram of the GitHub repository will3watson3/pitch-intent-metric, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/will3watson3/pitch-intent-metric
- Repository: https://github.com/will3watson3/pitch-intent-metric

## Overview

Pitch Intent Metric is a research estimator for plausible pitch finish locations from reviewed catcher-glove targets and earlier comparable pitches. The workflow validates and joins audit labels with pitch-level Statcast records, then estimates provisional finishes from historical target-to-finish offsets, abstaining when support is inadequate. The pilot runner also compares model variants and evaluates endpoint errors over held-out games. The README documents baselines and temporal evaluation; the sampled runner excerpt is partial, so only clearly supported connections are shown.

Main entry points: [`scripts/run_intent_pilot.py`](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py) (Pilot runner), [`scripts/build_webb_sweeper_intent_pilot.py`](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/build_webb_sweeper_intent_pilot.py) (Validate and join)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Data preparation"]
  node_build_join["Validate and join"]
  node_model_ready["Model-ready pitches"]
end

subgraph group_inference["Intent inference"]
  node_pilot_runner["Pilot runner"]
  node_comparable_inference["Comparable inference"]
  node_provisional_estimates["Provisional estimates"]
end

subgraph group_evaluation["Pilot evaluation"]
  node_variant_results["Variant predictions"]
  node_baselines["Baseline comparisons"]
  node_temporal_evaluation["Temporal evaluation"]
  node_pilot_reports["Pilot reports"]
end

node_researcher(("Researcher"))
node_reviewed_inputs["Reviewed labels"]
node_statcast_inputs["Statcast records"]
node_historical_data["Pitch history"]

node_researcher -->|"selects group"| node_build_join
node_reviewed_inputs -->|"reads labels"| node_build_join
node_statcast_inputs -->|"reads records"| node_build_join
node_build_join -->|"writes accepted pitches"| node_model_ready
node_researcher -->|"runs pilot"| node_pilot_runner
node_pilot_runner -->|"loads audited pitches"| node_model_ready
node_pilot_runner -->|"loads history"| node_historical_data
node_pilot_runner -->|"calls inference"| node_comparable_inference
node_comparable_inference -->|"estimates finishes"| node_provisional_estimates
node_pilot_runner -->|"writes predictions"| node_variant_results
node_pilot_runner -->|"compares methods"| node_baselines
node_pilot_runner -->|"evaluates held-out games"| node_temporal_evaluation
node_baselines -->|"reports metrics"| node_pilot_reports
node_temporal_evaluation -->|"reports results"| node_pilot_reports

click node_build_join "https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/build_webb_sweeper_intent_pilot.py"
click node_pilot_runner "https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py"
click node_comparable_inference "https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py"
click node_baselines "https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py"
click node_temporal_evaluation "https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.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_build_join,node_model_ready,node_reviewed_inputs toneBlue
class node_pilot_runner,node_comparable_inference,node_provisional_estimates toneAmber
class node_variant_results,node_baselines,node_temporal_evaluation,node_pilot_reports toneMint
class node_researcher,node_statcast_inputs,node_historical_data toneIndigo
```

## Components

### Data preparation

- [Validate and join](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/build_webb_sweeper_intent_pilot.py): `scripts/build_webb_sweeper_intent_pilot.py`
- **Model-ready pitches**

### Intent inference

- [Pilot runner](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py): `scripts/run_intent_pilot.py`
- [Comparable inference](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py): `scripts/run_intent_pilot.py`
- **Provisional estimates**

### Pilot evaluation

- **Variant predictions**
- [Baseline comparisons](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py): `scripts/run_intent_pilot.py`
- [Temporal evaluation](https://github.com/will3watson3/pitch-intent-metric/blob/main/scripts/run_intent_pilot.py): `scripts/run_intent_pilot.py`
- **Pilot reports**

### Other components

- **Researcher**
- **Reviewed labels**
- **Statcast records**
- **Pitch history**

## Connections

- Researcher → Validate and join: selects group
- Reviewed labels → Validate and join: reads labels
- Statcast records → Validate and join: reads records
- Validate and join → Model-ready pitches: writes accepted pitches
- Researcher → Pilot runner: runs pilot
- Pilot runner → Model-ready pitches: loads audited pitches
- Pilot runner → Pitch history: loads history
- Pilot runner → Comparable inference: calls inference
- Comparable inference → Provisional estimates: estimates finishes
- Pilot runner → Variant predictions: writes predictions
- Pilot runner → Baseline comparisons: compares methods
- Pilot runner → Temporal evaluation: evaluates held-out games
- Baseline comparisons → Pilot reports: reports metrics
- Temporal evaluation → Pilot reports: reports results