Skip to content

Twoeme/Football_gupa

BranchesTags

Repository files navigation

⚽ Football Gupa — AI-Powered World Cup 2026 Betting Assistant

An end-to-end application that analyzes football match data and delivers structured betting recommendations powered by a local AI model via Ollama. Built with FastAPI, Next.js 14, and SQLite for offline-first fixture data.

✨ Features

Feature Description
🧠 AI Recommendations Submits match context to a local Ollama model (kimi-k2.5:cloud) and returns a structured betting recommendation with confidence score and reasoning
📅 Match Schedule Viewer Displays the full 2026 World Cup fixture list (group stage → Final) with team logos and dates
💾 Offline-First Data Fixtures are stored in a local SQLite database — zero API calls needed after the first seed
🔄 Smart API Caching When the external football API is available, it updates the DB automatically; otherwise it falls back to the built-in static schedule
🎨 Clay-Inspired UI Clean white/blue design system with generous border radii, oat borders, and playful hover animations
🔒 CORS-Enabled FastAPI backend is pre-configured to accept requests from the Next.js frontend

🗂️ Project Structure

Football_gupa/
│
├── main.py                  # FastAPI app — routes & CORS setup
├── requirements.txt         # Python dependencies (pinned)
├── seed_db.py               # Seed DB from API-Sports (1 API call, then cached)
├── seed_static.py           # Seed DB from built-in schedule (zero API calls)
├── world_cup.db             # SQLite fixture database (auto-created)
├── DESIGN.md                # UI design system reference (Clay-inspired)
│
├── models/
│   └── schemas.py           # Pydantic models: MatchInput, BettingRecommendation, MatchOverview
│
├── services/
│   ├── ai_agent.py          # Calls local Ollama model, returns structured JSON
│   ├── football_api.py      # Fixture fetcher — DB → JSON cache → live API
│   └── database.py          # SQLite layer: init, upsert, query helpers
│
└── frontend/                # Next.js 14 application
    └── app/
        ├── page.tsx         # Main page — two-tab layout (Predictor / Matches)
        ├── globals.css      # Design tokens + all component styles
        ├── lib/
        │   └── api.ts       # Service layer — all fetch calls (never in components)
        └── components/
            ├── MatchForm.tsx    # Match input form with form picker + odds
            ├── ResultCard.tsx   # AI result display with animated confidence bar
            └── MatchesViewer.tsx # World Cup match cards grid

🚀 Getting Started

Prerequisites

Tool Version
Python 3.11+
Node.js 18+
Ollama Latest
API-Sports Account Optional (for live fixture data)

1. Clone the Repository

git clone https://github.com/twoeme/Football_gupa.git
cd Football_gupa/Football_gupa

2. Set Up the Python Backend

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# Install dependencies
pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the Football_gupa/ root:

# Required for AI recommendations
OLLAMA_URL=http://localhost:11434/api/generate
OLLAMA_MODEL=kimi-k2.5:cloud

# Optional — only needed if you want live fixture updates from API-Sports
API_SPORTS_KEY=your_api_sports_key_here

⚠️ Never commit your .env file. It is listed in .gitignore.

4. Seed the Match Database

Run the seeder once. It will try the live API first, and automatically fall back to the built-in 2026 World Cup schedule if the API is unavailable:

python seed_db.py

Or, to skip the API entirely and use the built-in static schedule (zero API cost):

python seed_static.py

You should see output like:

Static seed complete — 62 fixture(s) written. DB now holds 62 match(es).

5. Start the AI Model

Make sure Ollama is running and the model is available:

ollama run kimi-k2.5:cloud

6. Start the Backend

In the Football_gupa/ directory:

uvicorn main:app --reload

The API is now live at http://127.0.0.1:8000.
Interactive docs available at http://127.0.0.1:8000/docs.

7. Set Up and Start the Frontend

In a new terminal, navigate into the frontend folder:

cd frontend
npm install
npm run dev

Open http://localhost:3000 in your browser. 🎉

🔌 API Reference

GET /

Returns a welcome message and a link to the Swagger docs.

GET /matches

Returns all World Cup 2026 fixtures from the local SQLite database.

Response:

{
  "matches": [
    {
      "fixture_id": 900013,
      "date": "2026-06-13T01:00:00+00:00",
      "status": "NS",
      "home_team": "USA",
      "home_logo": "https://media.api-sports.io/football/teams/2.png",
      "away_team": "Panama",
      "away_logo": "https://media.api-sports.io/football/teams/70.png",
      "home_goals": null,
      "away_goals": null
    }
  ]
}

POST /analyze_match

Submits a match for AI analysis and returns a betting recommendation.

Request body:

{
  "team_a": "Argentina",
  "team_b": "France",
  "team_a_recent_form": "W W W W W",
  "team_b_recent_form": "W W W D W",
  "odds_team_a": 2.80,
  "odds_draw": 3.10,
  "odds_team_b": 2.75,
  "additional_context": "Mbappé is in top form. Messi recovering from minor fatigue."
}

Response:

{
  "recommended_bet": "Argentina to Win",
  "confidence_score": 72.5,
  "reasoning": "Argentina's perfect recent form combined with their slight odds advantage..."
}

🧩 How the Fixture Data Pipeline Works

python seed_db.py
  ├── API key present?
  │     ├── YES → Call API-Sports (1 request) → Write to world_cup.db
  │     │             └── API returns 0 results? → fallback ↓
  │     └── NO → fallback ↓
  └── seed_static.py → 62 announced WC2026 fixtures → world_cup.db

GET /matches (frontend request)
  ├── world_cup.db has rows? → Serve from SQLite (free, instant)
  ├── No DB rows but fresh JSON cache? → Load cache → seed DB → serve
  └── Nothing cached → call API live → seed DB → serve

After the first seed, every frontend request is served from the local SQLite file — no API quota consumed.

🛠️ Tech Stack

Backend

Library Version Purpose
FastAPI 0.115.4 REST API framework
Uvicorn 0.32.0 ASGI server
Pydantic 2.9.2 Request/response validation
Requests 2.32.3 HTTP client for Ollama + API-Sports
python-dotenv 1.0.1 Environment variable loading
SQLite3 stdlib Local fixture database

Frontend

Library Version Purpose
Next.js 14.2.3 React framework with App Router
React 18.3.1 UI library
TypeScript 5.4.5 Type safety
Lucide React 0.378.0 Icons

AI

Tool Purpose
Ollama Runs local LLMs without cloud API keys
kimi-k2.5:cloud Default model for match analysis

⚙️ Configuration Reference

Variable Default Description
OLLAMA_URL http://localhost:11434/api/generate Ollama API endpoint
OLLAMA_MODEL kimi-k2.5:cloud Model name to use for analysis
API_SPORTS_KEY — Your API-Sports key (optional)
NEXT_PUBLIC_API_URL http://localhost:8000 Backend URL for the Next.js app

📌 Notes & Limitations

  • Betting disclaimer: This tool is for educational and entertainment purposes only. It does not guarantee any betting outcome. Always gamble responsibly.
  • AI model: The quality of recommendations depends on the local Ollama model you have installed. Larger models will generally produce better reasoning.
  • API-Sports free tier: The free plan allows 100 requests per day. The SQLite caching system is designed to minimise this usage to as few as 1 request total.
  • Fixture data accuracy: The static schedule (seed_static.py) is based on officially announced 2026 World Cup groupings and dates. Knockout rounds use placeholder bracket notation until results are determined.

📄 License

This project is part of a Data Analytics portfolio. Feel free to fork and adapt for personal use.

Built with ⚽ FastAPI + Next.js + Ollama

About

An end-to-end application that analyzes football match data and delivers structured betting recommendations powered by a local AI model via Ollama.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages