# ahmaddaghlas55/air_hokey_ml_testing- architecture

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

## Overview

Autonomous Air Hockey runs a human-versus-robot match in a simulated table: the game loop reads table state, asks the robot strategy for a target, and advances the backend. The robot combines rule-based attack/defense with optional Q-table corrections and difficulty parameters. Logged player hits feed a player model and scripted training opponent; training produces a Q-table used at runtime and evaluated in headless matches. The README describes swapping in a hardware backend, but no hardware implementation is present. Some subsystem links are based on README documentation or the SOURCE INDEX rather than fully shown source.

Main entry points: [`sim_backend.py`](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/sim_backend.py) (Simulation backend), [`strategy.py`](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/strategy.py) (Robot strategy), [`evaluate.py`](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/evaluate.py) (Headless evaluator), [`train.py`](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/train.py) (Residual RL trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Match runtime"]
  node_main["Game loop<br/>[main.py]"]
  node_backend["Simulation backend<br/>[sim_backend.py]"]
  node_interface["Backend interface<br/>[interface.py]"]
  node_world["Physics world<br/>[physics_env.py]"]
end

subgraph group_policy["Robot policy"]
  node_strategy["Robot strategy<br/>[strategy.py]"]
  node_predictor["Trajectory predictor<br/>[predictor.py]"]
  node_qpolicy["Runtime Q policy<br/>[qpolicy.py]"]
  node_difficulty["Difficulty parameters<br/>[difficulty.py]"]
end

subgraph group_adapt["Player adaptation"]
  node_hits["Player hit log"]
  node_player_model["Player model builder<br/>[player_model.py]"]
  node_model["Player fingerprint<br/>[player_model.json]"]
  node_opponent["Scripted opponent<br/>[sim_opponent.py]"]
end

subgraph group_learn["Training and evaluation"]
  node_qtable[("Residual Q-table<br/>[qtable.npy]")]
  node_trainer["Residual RL trainer<br/>[train.py]"]
  node_evaluator["Headless evaluator<br/>[evaluate.py]"]
  node_results["Evaluation records<br/>[eval_results.jsonl]"]
end

node_human(("Human player"))

node_human -->|"controls paddle"| node_backend
node_main -->|"reads state; sets target"| node_backend
node_main -->|"requests target"| node_strategy
node_backend -->|"implements"| node_interface
node_backend -->|"steps; reads state"| node_world
node_backend -->|"appends hit records"| node_hits
node_backend -->|"previews trajectory"| node_predictor
node_strategy -->|"returns target"| node_backend
node_strategy -->|"predicts intercept"| node_predictor
node_strategy -->|"requests correction"| node_qpolicy
node_qpolicy -->|"loads and queries"| node_qtable
node_strategy -->|"uses presets"| node_difficulty
node_hits -->|"provides hit history"| node_player_model
node_player_model -->|"writes fingerprint"| node_model
node_model -->|"informs difficulty"| node_difficulty
node_model -->|"configures behavior"| node_opponent
node_opponent -->|"provides simulated play"| node_trainer
node_trainer -->|"runs episodes"| node_world
node_trainer -->|"uses classical plan"| node_strategy
node_trainer -->|"warm-starts; saves"| node_qtable
node_evaluator -->|"runs matches"| node_world
node_evaluator -->|"evaluates against"| node_opponent
node_evaluator -->|"uses classical plan"| node_strategy
node_evaluator -->|"reads table"| node_qtable
node_evaluator -->|"appends records"| node_results

click node_main "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/main.py"
click node_backend "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/sim_backend.py"
click node_interface "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/interface.py"
click node_world "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/physics_env.py"
click node_hits "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/opponent_hits.jsonl"
click node_strategy "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/strategy.py"
click node_predictor "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/predictor.py"
click node_qpolicy "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/qpolicy.py"
click node_qtable "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/qtable.npy"
click node_difficulty "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/difficulty.py"
click node_player_model "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/player_model.py"
click node_model "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/player_model.json"
click node_opponent "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/sim_opponent.py"
click node_trainer "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/train.py"
click node_evaluator "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/evaluate.py"
click node_results "https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/eval_results.jsonl"

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_main,node_backend,node_interface,node_world toneBlue
class node_strategy,node_predictor,node_qpolicy,node_difficulty toneAmber
class node_hits,node_player_model,node_model,node_opponent toneMint
class node_qtable,node_trainer,node_evaluator,node_results toneRose
class node_human toneIndigo
```

## Components

### Match runtime

- [Game loop](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/main.py): `main.py`
- [Simulation backend](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/sim_backend.py): `sim_backend.py`
- [Backend interface](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/interface.py): `interface.py`
- [Physics world](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/physics_env.py): `physics_env.py`

### Robot policy

- [Robot strategy](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/strategy.py): `strategy.py`
- [Trajectory predictor](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/predictor.py): `predictor.py`
- [Runtime Q policy](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/qpolicy.py): `qpolicy.py`
- [Difficulty parameters](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/difficulty.py): `difficulty.py`

### Player adaptation

- [Player hit log](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/opponent_hits.jsonl): `opponent_hits.jsonl`
- [Player model builder](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/player_model.py): `player_model.py`
- [Player fingerprint](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/player_model.json): `player_model.json`
- [Scripted opponent](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/sim_opponent.py): `sim_opponent.py`

### Training and evaluation

- [Residual Q-table](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/qtable.npy): `qtable.npy`
- [Residual RL trainer](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/train.py): `train.py`
- [Headless evaluator](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/evaluate.py): `evaluate.py`
- [Evaluation records](https://github.com/ahmaddaghlas55/air_hokey_ml_testing-/blob/main/eval_results.jsonl): `eval_results.jsonl`

### Other components

- **Human player**

## Connections

- Human player → Simulation backend: controls paddle (evidence: `README.md`)
- Game loop → Simulation backend: reads state; sets target (evidence: `main.py`)
- Game loop → Robot strategy: requests target (evidence: `main.py`)
- Simulation backend → Backend interface: implements (evidence: `sim_backend.py`)
- Simulation backend → Physics world: steps; reads state (evidence: `sim_backend.py`)
- Simulation backend → Player hit log: appends hit records (evidence: `sim_backend.py`)
- Simulation backend → Trajectory predictor: previews trajectory (evidence: `sim_backend.py`)
- Robot strategy → Simulation backend: returns target (evidence: `main.py`)
- Robot strategy → Trajectory predictor: predicts intercept (evidence: `strategy.py`)
- Robot strategy → Runtime Q policy: requests correction (evidence: `strategy.py`)
- Runtime Q policy → Residual Q-table: loads and queries (evidence: `qpolicy.py`)
- Robot strategy → Difficulty parameters: uses presets (evidence: `strategy.py`)
- Player hit log → Player model builder: provides hit history (evidence: `player_model.py`)
- Player model builder → Player fingerprint: writes fingerprint (evidence: `player_model.py`)
- Player fingerprint → Difficulty parameters: informs difficulty (evidence: `README.md`)
- Player fingerprint → Scripted opponent: configures behavior (evidence: `sim_opponent.py`)
- Scripted opponent → Residual RL trainer: provides simulated play (evidence: `train.py`)
- Residual RL trainer → Physics world: runs episodes (evidence: `train.py`)
- Residual RL trainer → Robot strategy: uses classical plan (evidence: `train.py`)
- Residual RL trainer → Residual Q-table: warm-starts; saves (evidence: `train.py`)
- Headless evaluator → Physics world: runs matches (evidence: `evaluate.py`)
- Headless evaluator → Scripted opponent: evaluates against (evidence: `evaluate.py`)
- Headless evaluator → Robot strategy: uses classical plan (evidence: `evaluate.py`)
- Headless evaluator → Residual Q-table: reads table (evidence: `evaluate.py`)
- Headless evaluator → Evaluation records: appends records (evidence: `README.md`)
