Deploy RunRate Lab cricket analytics coach

.dockerignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+.playwright-cli/
+.git/
+tests/__pycache__/

.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+.playwright-cli/
+.pytest_cache/
+.streamlit/secrets.toml
+.env
+.env.*
+!.env.example
+*.log
+output/
+dist/
+build/

.streamlit/config.toml

@@ -0,0 +1,12 @@
+[theme]
+primaryColor = "#22C55E"
+backgroundColor = "#F7FAF5"
+secondaryBackgroundColor = "#EAF5E5"
+textColor = "#0F2418"
+font = "sans serif"
+
+[server]
+maxUploadSize = 200
+
+[browser]
+gatherUsageStats = false

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --upgrade pip \
+    && pip install -r requirements.txt
+
+COPY . .
+
+EXPOSE 8501
+
+HEALTHCHECK CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8501/_stcore/health')"
+
+CMD ["streamlit", "run", "app.py", "--server.address=0.0.0.0", "--server.port=8501"]

Makefile

@@ -0,0 +1,16 @@
+.PHONY: install run test check
+
+install:
+	python3 -m venv .venv
+	.venv/bin/python -m pip install --upgrade pip
+	.venv/bin/python -m pip install -r requirements.txt
+
+run:
+	.venv/bin/streamlit run app.py
+
+test:
+	.venv/bin/python -m unittest discover -s tests
+
+check:
+	.venv/bin/python -m compileall app.py tests
+	.venv/bin/python -m unittest discover -s tests

README.md

@@ -1,10 +1,163 @@
 ---
-title: Runrate Lab
-emoji: 🏆
-colorFrom: red
-colorTo: red
+title: RunRate Lab
+emoji: 🏏
+colorFrom: green
+colorTo: yellow
 sdk: docker
+app_port: 8501
 pinned: false
+short_description: Learn cricket analytics through a T20 chase.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🏏 RunRate Lab
+
+**Play. Analyze. Improve.**
+
+RunRate Lab is an interactive cricket analytics learning game. You play a T20 chase in a 2.5D cricket arcade, choose shot intent and aim lane, swing at live deliveries, and learn how analytics explains every outcome through expected runs, wicket risk, variance, Monte Carlo simulation, and decision quality.
+
+## What You Learn
+
+- **Expected runs:** the long-run value of a shot before the random result appears.
+- **Wicket risk:** the chance that a shot leads to dismissal.
+- **Variance:** why a good decision can fail and a bad decision can succeed.
+- **Decision quality:** whether the shot created enough value for the risk accepted.
+- **Monte Carlo simulation:** repeated trials that estimate the probability of `0`, `1`, `2`, `3`, `4`, `6`, or `W`.
+- **Match pressure:** how required run rate changes which risks are rational.
+
+## How To Play
+
+1. Click **Start T20 Chase**.
+2. Choose **Defend**, **Drive**, **Cut / Pull**, or **Loft**.
+3. Choose **Leg Side**, **Straight**, or **Off Side**.
+4. Hold mouse, touch, or Space to start the delivery and charge your shot.
+5. Release near the green impact band.
+6. Read the **Analytics Coach** panel after every ball, then press **Next Ball**.
+7. Use the **Interactive Analytics Lab** to recreate a shot and change one input at a time.
+8. Complete the **Learning Path** missions to build analytics intuition.
+
+Keyboard controls:
+
+- `1`: Defend
+- `2`: Drive
+- `3`: Cut / Pull
+- `4`: Loft
+- `A` and `D`: change aim lane
+- `Space`: hold and release swing
+- `Enter`: next ball during review
+
+## Game Features
+
+- 2.5D batting-end view with pitch depth, field ring, crease, stumps, and ball scaling.
+- Keyframed batter rig with helmet, torso, pads, arms, gloves, and an attached bat.
+- Shot intent and aim lane choices before every delivery.
+- Required review pause after each ball so the coach panel remains readable.
+- Result toast, boundary flash, wicket shake, shot trails, and replay-style commentary.
+- Process streak and Process Score after every over showing average xRuns, actual runs, average wicket risk, best decision, and variance flag.
+- In-game settings for reduced flashing, color-safe feedback, and the first-ball hold-release prompt.
+
+## Learning Path
+
+RunRate Lab includes five guided modules:
+
+1. **Expected Runs:** compare two shot intents against the same delivery.
+2. **Wicket Risk:** complete an over using only shots under a target risk budget.
+3. **Variance And Luck:** identify lucky and unlucky outcomes.
+4. **Timing Sensitivity:** compare early, perfect, and late releases for the same setup.
+5. **Match Pressure:** compare Drive and Loft at different required run rates.
+
+## Project Structure
+
+- `app.py`: Streamlit app, browser game, analytics lab, learning path, and charts.
+- `requirements.txt`: minimal runtime dependencies.
+- `Dockerfile`: Hugging Face Docker Space deployment.
+- `.streamlit/config.toml`: app theme and Streamlit settings.
+- `tests/test_runrate_lab.py`: focused analytics tests.
+
+## Local Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -r requirements.txt
+```
+
+## Run Locally
+
+```bash
+.venv/bin/streamlit run app.py
+```
+
+Open:
+
+```text
+http://localhost:8501
+```
+
+## Test
+
+```bash
+make check
+```
+
+Or run only unit tests:
+
+```bash
+.venv/bin/python -m unittest discover -s tests
+```
+
+## Docker
+
+Build and run locally:
+
+```bash
+docker build -t runrate-lab .
+docker run --rm -p 8501:8501 runrate-lab
+```
+
+Open:
+
+```text
+http://localhost:8501
+```
+
+## Deploy To Hugging Face Spaces
+
+1. Create a new Hugging Face Space.
+2. Choose **Docker** as the SDK.
+3. Clone the Space repository.
+4. Copy these files into the Space repository:
+   - `app.py`
+   - `requirements.txt`
+   - `Dockerfile`
+   - `.streamlit/config.toml`
+   - `README.md`
+5. Commit:
+
+```bash
+git add .
+git commit -m "Build RunRate Lab cricket analytics coach"
+```
+
+6. Push:
+
+```bash
+git push
+```
+
+7. Wait for the Space build logs to finish.
+8. Open the Space URL and verify:
+   - the app loads
+   - the game starts
+   - shot intent and aim lane controls work
+   - hold-and-release swing works
+   - the bat remains attached to both glove anchors during the swing
+   - a delivery pauses on the review state until **Next Ball** is pressed
+   - the Analytics Coach updates after each ball
+   - Analytics Lab charts render
+   - no app console errors appear
+
+## Notes
+
+- No external APIs, model downloads, database, login, or webcam access are required.
+- The canvas game runs client-side for smooth animation.
+- The analytics lab uses deterministic simulation seeds so repeated slider setups are stable for learning.

requirements.txt

@@ -0,0 +1,4 @@
+streamlit
+pandas
+numpy
+plotly

tests/test_runrate_lab.py

@@ -0,0 +1,126 @@
+import unittest
+
+from streamlit.testing.v1 import AppTest
+
+import app
+
+
+class RunRateLabAnalyticsTests(unittest.TestCase):
+    def test_probabilities_sum_to_approximately_100(self):
+        probabilities, metrics = app.simulate_outcome_distribution(
+            "Length Ball",
+            timing_error_ms=0,
+            power=70,
+            required_rate=8.5,
+            samples=5000,
+        )
+        self.assertAlmostEqual(probabilities["Probability"].sum(), 100.0, places=6)
+        self.assertGreater(metrics["expected_runs"], 0)
+        self.assertEqual(metrics["shot_intent"], "Drive")
+        self.assertEqual(metrics["aim_lane"], "Straight")
+
+    def test_perfect_timing_beats_large_timing_error(self):
+        pitch = app.get_pitch("Length Ball")
+        perfect_contact = app.calculate_contact(0, 70, pitch)
+        late_contact = app.calculate_contact(180, 70, pitch)
+        self.assertGreater(perfect_contact, late_contact)
+
+    def test_required_rate_increases_wicket_risk(self):
+        pitch = app.get_pitch("Cutter")
+        contact = app.calculate_contact(20, 85, pitch)
+        normal_risk = app.calculate_wicket_risk(contact, 85, 20, 8.0, pitch)
+        pressure_risk = app.calculate_wicket_risk(contact, 85, 20, 12.0, pitch)
+        self.assertGreater(pressure_risk, normal_risk)
+
+    def test_overcharged_power_increases_wicket_risk(self):
+        pitch = app.get_pitch("Bouncer")
+        contact = app.calculate_contact(0, 95, pitch)
+        normal_risk = app.calculate_wicket_risk(contact, 80, 0, 8.0, pitch)
+        overhit_risk = app.calculate_wicket_risk(contact, 95, 0, 8.0, pitch)
+        self.assertGreater(overhit_risk, normal_risk)
+
+    def test_loft_has_higher_upside_and_risk_than_defend(self):
+        pitch = app.get_pitch("Half Volley")
+        defend_contact = app.calculate_contact(0, 88, pitch, "Defend", "Straight")
+        defend_risk = app.calculate_wicket_risk(defend_contact, 88, 0, 8.0, pitch, "Defend", "Straight")
+        defend_xruns = app.calculate_expected_runs(defend_contact, 88, defend_risk, "Defend", "Straight")
+
+        loft_contact = app.calculate_contact(0, 88, pitch, "Loft", "Straight")
+        loft_risk = app.calculate_wicket_risk(loft_contact, 88, 0, 8.0, pitch, "Loft", "Straight")
+        loft_xruns = app.calculate_expected_runs(loft_contact, 88, loft_risk, "Loft", "Straight")
+
+        self.assertGreater(loft_risk, defend_risk)
+        self.assertGreater(loft_xruns, defend_xruns)
+
+    def test_correct_shot_delivery_matchup_improves_contact(self):
+        pitch = app.get_pitch("Bouncer")
+        drive_contact = app.calculate_contact(0, 76, pitch, "Drive", "Straight")
+        pull_contact = app.calculate_contact(0, 76, pitch, "Cut / Pull", "Straight")
+        self.assertGreater(pull_contact, drive_contact)
+
+    def test_decision_quality_thresholds(self):
+        self.assertEqual(app.classify_decision_quality(4.5, 0.12), "Excellent Process")
+        self.assertEqual(app.classify_decision_quality(3.0, 0.20), "Good Process")
+        self.assertEqual(app.classify_decision_quality(4.0, 0.35), "Risky But Rational")
+        self.assertEqual(app.classify_decision_quality(1.2, 0.18), "Low-Value Shot")
+        self.assertEqual(app.classify_decision_quality(1.9, 0.35), "Poor Risk Tradeoff")
+
+    def test_luck_classification(self):
+        self.assertEqual(app.classify_luck(6, 2.0, False, 0.15), "Lucky Result")
+        self.assertEqual(app.classify_luck(0, 4.0, False, 0.12), "Unlucky Result")
+        self.assertEqual(app.classify_luck(0, 3.0, True, 0.10), "Unlucky Result")
+        self.assertEqual(app.classify_luck(2, 2.2, False, 0.15), "Expected Result")
+
+    def test_generated_game_model_uses_python_constants(self):
+        rendered = app.build_game_html(180)
+        self.assertNotIn("__DELIVERIES_JSON__", rendered)
+        self.assertNotIn("__SHOTS_JSON__", rendered)
+        self.assertNotIn("__AIMS_JSON__", rendered)
+        for delivery in app.PITCH_MODEL["Delivery"]:
+            self.assertIn(delivery, rendered)
+        for shot in app.SHOT_MODEL["Shot"]:
+            self.assertIn(shot, rendered)
+        for aim in app.AIM_MODEL["Aim"]:
+            self.assertIn(aim, rendered)
+
+    def test_sample_table_has_ten_trials(self):
+        table = app.simulate_sample_table("Yorker", 0, 70, 9.0, shot_intent="Defend", aim_lane="Straight")
+        self.assertEqual(len(table), 10)
+        self.assertIn("Shot", table.columns)
+        self.assertIn("Aim", table.columns)
+        self.assertIn("Decision", table.columns)
+
+    def test_learning_summary_handles_partial_logs(self):
+        summary = app.build_learning_summary([{"actual_runs": 4}, {"unexpected": 99}])
+        self.assertEqual(summary["balls"], 2.0)
+        self.assertEqual(summary["avg_xruns"], 0.0)
+        self.assertEqual(summary["avg_wicket_risk"], 0.0)
+        self.assertEqual(summary["avg_actual_runs"], 4.0)
+
+    def test_game_pauses_for_review_between_balls(self):
+        self.assertIn('id="nextBallBtn"', app.GAME_HTML)
+        self.assertIn('state.mode = "between"', app.GAME_HTML)
+        self.assertIn('state.mode === "between" ? "Review"', app.GAME_HTML)
+        self.assertIn("Shot Intent", app.GAME_HTML)
+        self.assertIn("Aim Lane", app.GAME_HTML)
+        self.assertIn("Process Score", app.GAME_HTML)
+        self.assertIn('id="processPill"', app.GAME_HTML)
+        self.assertIn('id="settingsModal"', app.GAME_HTML)
+        self.assertIn("Reduce Flashing", app.GAME_HTML)
+        self.assertIn("hidden-during-play", app.GAME_HTML)
+        self.assertIn("hidden-for-review", app.GAME_HTML)
+        self.assertIn("Coach ready. Press Next Ball when done.", app.GAME_HTML)
+        self.assertIn("Restart Match", app.GAME_HTML)
+
+
+class RunRateLabStreamlitTests(unittest.TestCase):
+    def test_streamlit_app_renders(self):
+        test_app = AppTest.from_file("app.py")
+        test_app.run(timeout=15)
+        self.assertFalse(test_app.exception)
+        self.assertTrue(any("RunRate Lab" in title.value for title in test_app.title))
+        self.assertGreaterEqual(len(test_app.metric), 4)
+
+
+if __name__ == "__main__":
+    unittest.main()