Predict soccer match outcomes from two team names using an AI model, backed by historical match data.

Input: home team + away team
Output: home win %, draw %, away win %, confidence, and AI reasoning

npm install
cp .env.example .env

Add your OpenAI key to .env:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

# Defaults: remote England Premier League 2020 data + AI model
npm run toolbox -- predict --home Arsenal --away Chelsea

# Shorthand
npm run toolbox -- predict Arsenal Chelsea

# Other league/year
npm run toolbox -- predict Barcelona "Real Madrid" --source remote --league Spain --division 1 --year 2020

Example output:

{
  "match": "Arsenal vs Chelsea",
  "homeWin": "41.2%",
  "draw": "27.5%",
  "awayWin": "31.3%",
  "confidence": "68.0%",
  "model": "ai",
  "aiModel": "gpt-4o-mini",
  "reasoning": "Arsenal's home form and recent head-to-head edge Chelsea slightly..."
}

npm run toolbox -- predict Arsenal Chelsea --no-ai --source dummy

1. Loads historical data (remote by default for predict)
2. Builds context — team form, head-to-head, league draw rate
3. Calls the AI model via Vercel AI SDK with structured output
4. Blends dataset signals with the model's football knowledge (especially when data is sparse)

The AI step is required by default. Without OPENAI_API_KEY, the CLI prints setup instructions. Use --no-ai only if you want the local statistical model.

import { predictMatch } from "./src/index.js";

const result = await predictMatch("Arsenal", "Chelsea", {
  source: "remote",
  params: { league: "England", division: 1, year: 2020 },
});
// result.model === "ai", result.reasoning, result.homeWin, ...

npm run toolbox -- data load
npm run toolbox -- strategy backtest
npm run toolbox -- strategy picks