JetQiao/football-prediction-skill

Intelligent Football (Soccer) Betting Prediction

Use deterministic scripts to perform data normalization, probability modeling, value calculation, backtesting, and HTML rendering; only use the AI agent to process unstructured intelligence with sources. Always produce a self-contained HTML, do not paste the full match schedule table in replies.

Choose a Workflow

• User wants to analyze all Chinese Football Lottery matches on a given day: run the "Full Daily Flow".
• User only needs a quick baseline or has no internet search capability: directly run daily, explicitly note market / intelligence degradation.
• User provides a historical CSV: run backtest.
• User asks about group standings or knockout rounds: read Tournament Simulation then run tournament.
• User provides only one match that is not in the Chinese Football Lottery schedule: construct an input JSON that conforms to Data Contracts, then run daily --input.

Command Entry Point

Prefer using the installed command:

football-predict doctor

If the command does not exist, use the open-source repository entry:

npx -y github:JetQiao/football-prediction-skill doctor

Hereinafter, football-predict denotes the available entry point; keep using the same entry point for the entire session.

Full Daily Flow

1. Determine the Chinese Football Lottery sales date; if not specified, use the user's local today. Do not confuse the match calendar day with the sales day.
2. Create a temporary working directory and pull the match schedule:

football-predict prepare --date YYYY-MM-DD --out /tmp/football-predict-YYYY-MM-DD

3. Read matches_*.json and intel_queue_*.json. Keep the model baseline for all B-level matches; only perform deep web retrieval for A-level matches in the queue.
4. Search and write intel.json according to the Intelligence Flow. Prohibited: articles written after kickoff, match results, or data visible only after market close.
5. Validate the intelligence:

football-predict validate-intel /tmp/football-predict-YYYY-MM-DD/intel.json

6. Generate the final artifact:

football-predict daily \
  --date YYYY-MM-DD \
  --input /tmp/football-predict-YYYY-MM-DD/matches_YYYY-MM-DD.json \
  --intel /tmp/football-predict-YYYY-MM-DD/intel.json

7. In the reply, only provide: the absolute HTML path, number of matches, number of high-confidence predictions, number of value signals, and key degradation warnings. Remind that probabilities are not guarantees, and avoid phrases like "sure win".

Market & Feature Enhancement

Use --features features.json to inject pre-match Elo/xG data, and --market market.json to inject sharp / market odds from the same prediction time point. Read Data Sources & Degradation to confirm source priority.

Never inject historical closing odds into predictions for an earlier time point. Degradation is allowed when real-time markets are unavailable, but report warnings must be preserved.

Backtesting

Obtain a league CSV (to which the user has rights) from football-data.co.uk and run locally:

football-predict backtest history.csv --min-train 120 --window 600

Compare Brier score, log-loss, and the Chinese Football Lottery SP baseline; also report sample size, ROI, and maximum drawdown. Do not cherry-pick only well-performing leagues or time periods.

Output Rules

• Retain prediction_*.json, report_*.html, and manifest_*.json.
• Deliver the HTML as the primary artifact; it must open offline and make no network requests.
• Preserve sources, generation time, run ID, missing information, and degradation reasons.
• Do not place bets, do not manage money on behalf of users, do not promise profits. Clearly remind users to bet responsibly and that minors are prohibited from betting.