Step-by-step · From blank screen to live edges

How to use WinMatic in 10 minutes.

This page walks you through the full loop: training the model, exploring predictions, scanning for value bets and tracking how the engine performs over time.

Jump to Predictor Open API docs (/docs)

1. Before you start – make sure the engine is running

WinMatic is a FastAPI backend plus static pages. If the backend isn’t running, all buttons will show dashes (–) and empty cards.

Start the server:

Open a terminal and go to your project folder:
cd /Users/mutarosi/football-predictor
Run the API using your start script:
./start.sh
Make sure the env variable is set (you already did this):
export API_FOOTBALL_KEY="your_real_key"

Then check:
http://127.0.0.1:8001/health → should say {"status":"ok"}
http://127.0.0.1:8001/docs → Swagger with all endpoints

Tip: Leave this terminal window open while you use the app. You’ll see useful logs for training, API calls and any errors.

2. Train or refresh the model

The model uses historic fixtures + features (team strength, Elo, form, odds, etc.) and trains a RandomForest to predict home/away goals. From that we derive 1X2 probabilities and edge.

Step 2.1

Open the training endpoint

Go to /docs and find POST /train (or whatever your training endpoint shows as). Click it, then click Try it out → Execute.

Model training

Step 2.2

Wait for training to finish

In the terminal you’ll see it fetch seasons (2018–2025), build features, and train the RandomForest. When it’s done, you’ll typically see metrics like logloss, Brier, hit-rate vs market.

Artifacts saved

Step 2.3

Check metrics page

Open /static/metrics.html. You should now see calibration curves, hit-rates and team strength charts reflecting the latest model.

Sanity check

When to retrain? For a hobby setup, retraining once a week or once every few matchdays is usually enough.

3. Use the Predictor – explore matches and probabilities

The Predictor page is where you browse upcoming fixtures, view 1X2 probabilities, and get a detailed reasoning panel for each match.

Step 3.1

Open the page

Go to /static/predictor.html or click Predictions in the top menu. The app will call /predict/upcoming and load today’s and upcoming matches.

Step 3.2

Use date & filters

On the left controls, choose:

League (e.g. Premier League 39)
Date or number of days ahead
Minimum edge / confidence slider (if present)

Filters

Step 3.3

Expand a match card

Click any match card. It expands to show:

Model 1X2 probabilities
Suggested side (home/draw/away)
Possible scoreline range
Key reasoning: form, xG-style proxies, top scorers, etc.

Reasoning

Important: Treat these as model suggestions, not automatic bets. Always check odds, team news, injuries and your own judgement.

4. Value Scanner & Bet of the day

The Value Scanner combines model probabilities with live bookmaker odds (via API-Football) to find where the model thinks the price is off.

Step 4.1

Open Value Scanner

Go to /static/value.html or click Value Scanner in the menu. This calls /value-bets?league=39&days_ahead=… on the backend.

Step 4.2

Understand the edge

For each candidate bet, you’ll see:

Model probability vs implied odds probability
Edge (difference) – e.g. +8% or +12%
Which side the model likes (Home / Draw / Away)

Edge

Step 4.3

Bet of the day

The Bet of the day is simply the strongest edge for your chosen league & day range. You can treat it as “top pick”, but only if it also makes sense to you.

Top pick

Quota safety: Avoid spam-clicking Value Scanner. Each refresh uses several odds calls. Your backend already has protections, but it’s still good API hygiene.

5. Track results & improve over time

WinMatic logs predictions into artifacts/history.db. The Metrics / Results pages help you see how the model behaves in the wild.

Step 5.1

Open Metrics / Results page

Go to /static/metrics.html or click Results or Metrics in the top menu. You’ll see hit-rates, calibration plots and team strength visuals.

Step 5.2

Update actual outcomes

When real matches finish, you can extend the backend to fill in actual_result for each fixture in predictions_history. Then, metrics will reflect true performance.

Optional dev

Step 5.3

Iterate the model

Over time you can:

Tweak features (form windows, xG proxies, etc.)
Adjust RandomForest hyper-parameters
Experiment with other models (XGBoost, neural nets)

Retrain, compare metrics, and keep what actually improves out-of-sample results.

Model evolution

Mindset: Think of WinMatic as your lab. You’re not trying to be perfect on day one – you’re building a system you can improve and trust over months.