Stage-based TypeScript pipeline for soccer betting research — ingest historical data, run walk-forward backtests, and surface value-bet recommendations. Uses adapter/stage vocabulary instead of traditional dataloader/bettor naming.

• Ingest stage — extract training matrices and upcoming fixtures from mock or live soccer CSV adapters
• Evaluate stage — odds-comparison value detection with chronological walk-forward backtests
• Adapter layer — Redis-backed cache with automatic in-memory fallback
• Classifier stage — optional ML-based betting stage (ClassifierStage)
• CLI flow runner — ingest / evaluate / adapter command groups

Requirements: Node.js 20+, OPENAI_API_KEY in .env

npm install
cp .env.example .env   # add OPENAI_API_KEY
npm run flow -- evaluate matchup --home Arsenal --away Chelsea

Pipeline stages: team intel → baseline → LLM outcome (use --no-ai for baseline only).

betting-insight-pipeline/
├── cmd/flow.ts                 CLI orchestrator (ingest → evaluate → adapter)
├── contracts/tables.ts         Table, TrainData, ParamGrid type contracts
├── shared/                     Frame utils, validators, edge math, ChronoSplit
├── adapters/
│   ├── data/                   BaseDataAdapter, MockSoccerAdapter, LiveSoccerAdapter
│   └── cache/                  Redis adapter, memory store, cache key builder
├── stages/betting/             BaseBettingStage, OddsCompareStage, runBacktestStage
├── pipeline/index.ts           Public library exports
└── test/suite/                 Vitest unit tests

flowchart LR
  A[ingest batch] --> B[MockSoccerAdapter]
  B --> C[Training X / Y / O tables]
  C --> D[evaluate walkforward]
  D --> E[OddsCompareStage + ChronoSplit]
  E --> F[Backtest metrics]
  C --> G[evaluate recommend]
  G --> H[Fixture value bets]
  I[adapter ping] --> J[Redis or memory cache]

# List training parameter combinations
npm run flow -- ingest manifest

# Export training CSVs
npm run flow -- ingest batch --out ./exports

# Run backtest and save results
npm run flow -- evaluate walkforward --out ./results

# Find value bets on fixtures (skip cache)
npm run flow -- evaluate recommend --no-cache

# Verify Redis
npm run flow -- adapter ping

import {
  MockSoccerAdapter,
  OddsCompareStage,
  runBacktestStage,
  ChronoSplit,
  isValueBet,
  impliedProbability,
} from "./pipeline/index.js";

const adapter = new MockSoccerAdapter();
const [X, Y, O] = adapter.extractTrainData(0, "williamhill");

const stage = new OddsCompareStage(["williamhill"], 0.03);
stage.fit(X, Y);

if (O) {
  const results = runBacktestStage(stage, X, Y, O, new ChronoSplit(2));
  console.log(results);
}

Copy .env.example to .env:

• runbooks/ingest-evaluate.md — ingest → evaluate workflow
• CONTRIBUTING.md — development guidelines

Telegram: https://t.me/snipmaxi