Welcome to the AI Football Analyst repository! This project serves as a comprehensive, AI-powered system designed to revolutionize how football teams prepare, execute, and review matches.

By combining Data Engineering, Statistical Analysis, and Generative AI, this backend engine processes complex football metrics to act as an automated tactical assistant for coaches and analysts.

The system is divided into operational phases that cover the entire lifecycle of a football match. It evaluates historical data, synthesizes player performance, and generates actionable tactical recommendations.

Everything a coach needs before the whistle blows.

• Opponent Intelligence: Performs deep historical analysis on the upcoming opponent to identify weaknesses, common formations, and scoring patterns.
• Tactical Strategy & Formation: AI-driven recommendations for the best tactical setup (e.g., 4-3-3, 3-5-2) specifically tailored to counter the opponent's style.
• Starting Lineup Optimization: Recommends the optimal Starting XI and bench players by evaluating recent player scores, fitness statistics, and real-position heatmaps.
• Positional & Heatmap Analysis: Understands micro-tactics by analyzing where players actually operate on the pitch, rather than just their nominal positions.
• Targeted Training Plan: Generates a customized, actionable training regimen focusing on specific drills needed to prepare for the next match.

A dedicated module (/apis/in_match/) currently in development to provide real-time advantage:

• Live tracking of tactical execution.
• On-the-fly suggestions for substitutions and formation changes based on live match flow and player fatigue.

Review and improve based on hard data.

• Automated Match Reports: Analyzes key match events (passes, shots, defensive actions) right after the game.
• Performance Scoring: Objectively evaluates team and individual player performances to see what went right and what needs improvement for the next game.

• Features powerful notebooks (web_scraping.ipynb) to fetch, parse, and aggregate real-world football data, ensuring the AI models are fed with high-quality, up-to-date metrics.

• Data Processing & Analytics: Pandas, NumPy, Statistics
• Generative AI Engine: Google GenAI (Gemini) used to synthesize raw analytical data into human-readable tactical plans and training regimes.
• Backend API: Flask acts as the central hub, unifying complex multi-match analysis pipelines into seamless RESTful APIs.
• External Integration: Requests library for fetching remote event and team data.
• Deployment-Ready: Fully configured with a unified app.py, requirements.txt, and a Dockerfile specifically optimized for Hugging Face Spaces.

├── apis/
│   ├── pre_match/          # Core engine for predictive and tactical planning
│   ├── post_match/         # Match review and performance analysis
│   └── in_match/           # Scalable architecture for future real-time tracking
├── notebooks/
│   ├── pre_match.ipynb     # Research & validation for pre-match analysis
│   ├── post_match.ipynb    # Research & validation for post-match analysis
│   └── web_scraping.ipynb  # Custom data extraction pipelines
├── app.py                  # Centralized Flask web server
├── Dockerfile              # Docker image configuration for HF Spaces
├── requirements.txt        # Production dependencies
└── .dockerignore           # Prevents uploading local caches

The unified Flask application exposes the following POST endpoints:

• /pre_match: Expects team_id, num_matches, and opponent_id. Returns Starting XI, strategy, and training plan.
• /post_match: Expects team_id and event_id. Returns match and fatigue analysis.

1. Clone the repository & install dependencies:

   git clone <repository_link>
   cd AI
   pip install -r requirements.txt

2. Run the API server:

   python app.py

This repository is 100% ready to be deployed for free on Hugging Face Spaces via Docker. Just create a new Blank Docker Space, and sync/upload this repository to it. The Dockerfile handles the configuration and runs the app on port 7860.