Skip to main content

🤖 Backend / AI Developer Quickstart

:::note Audit scope (2026-07-23) This guide targets the excluded GPU backend. It was inventoried but not reverified, so its last_verified date is intentionally unchanged. :::

You're improving the AI video analysis pipeline (RunPod GPU backend).

:::tip TL;DR

  • Repo: acesense-gpu-backend (Python 3.11 — strict)
  • Stack: YOLO v8 • TrackNet • MediaPipe • CatBoost • OpenCV • PyTorch
  • Runs on: RunPod RTX 4090 serverless (prod) • local CPU/MPS/CUDA (dev) :::

🚀 Get Running in 5 Minutes​

# 1. Clone
git clone git@github.com:Acesense/acesense-gpu-backend.git
cd acesense-gpu-backend

# 2. Create Python 3.11 venv (REQUIRED — not 3.12+)
python3.11 -m venv venv
source venv/bin/activate

# 3. Install deps
pip install -r requirements/requirements.txt

# 4. Run a local clip
python main.py --path_input_video input_videos/sample.mp4 --dev

:::warning Python 3.11.x only CatBoost + MediaPipe do not ship wheels for Python 3.12+. Using a newer version will silently fail or install broken builds. :::

🏎️ Dev Cache (96% Faster Iteration)​

The --dev flag caches intermediate ML inference so you can iterate on downstream logic without re-running expensive models:

# First run — ~90s for a 30s video (builds cache)
python main.py --path_input_video input_videos/sample.mp4 --dev

# Subsequent runs — ~3s (cached)
python main.py --path_input_video input_videos/sample.mp4 --dev

# Clear cache when models change
rm -rf .dev/cache/

Cache lives in .dev/cache/<video_hash>/ with one pickle per stage (ball tracking, court, players, bounces, shots).

📂 Pipeline Structure​

src/
├── core/           # GameProcessor — the orchestrator
├── tracking/       # Ball tracking (TrackNet)
├── surface/        # Court detection (CourtDetectorNet)
├── players/        # Player detection (FasterRCNN + MediaPipe)
├── events/         # Bounce detection (CatBoost)
├── classification/ # Shot classification
├── analysis/       # Game stats + recommendations
├── export/         # PDF/JSON/video reports
├── io/             # Video I/O, Firebase upload
├── render/         # Overlay visualization
└── utils/          # Dev cache, helpers

🧭 Common Workflows​

Run against Firebase (cloud mode)​

python main.py \
  --path_input_video video.mp4 \
  --cloud \
  --firebase_bucket acesense-prod.firebasestorage.app \
  --firebase_credentials firebasecred/firebase-admin.json

Test on a real RunPod-style invocation​

python runpod_handler.py  # simulates the serverless handler locally

Ship a new model version​

  1. Drop the new weights into games/tennis/models/
  2. Bump the version in Dockerfile
  3. Build + push: docker build -t akshaysarode/acesense:vNN . && docker push akshaysarode/acesense:vNN
  4. Update the RunPod endpoint image tag in the RunPod Console

See the Deployment Guide for the full flow.

🧪 Tests​

pytest tests/ -v

🎯 Next Steps​