⚡ ScoutLab — AI-assisted player scouting app

Find the right player for your project — not just a good player.

ScoutLab is a scouting application that combines classic attribute-based search with an AI recommendation engine: describe your team's identity (playing style, tactical trends, squad statistics) and get players ranked by fit with your technical project, not just by raw quality.

Portfolio project — Hamza Skali (Polytech Paris-Saclay). Companion to the football-xg-model repo: the xG project proves the modelling rigour; ScoutLab turns analytics into a product.

---

Product vision

Scouting tools answer "who is good?". Clubs actually ask "who fits us?" — a pressing team doesn't need the best striker, it needs the best striker who presses. ScoutLab is built around that difference:

1. Search (v1): explore the player database through the filters scouts actually use — position, market value, strengths, and detailed technical / physical / mental-tactical attributes.
2. Fit engine (v2): describe your team once (style of play, tactical tendencies, squad stats), and ScoutLab recommends players ranked by adequacy with your project, with a natural-language justification for every recommendation.

Features

🔍 Menu 1 — Player search (this release)

• Position picker on a pitch-logic grid (GK / DF / MF / FW families, precise roles)
• Market value range filter
• Strengths multi-select (e.g. finishing, long passing, aerial duels, pace...)
• Attribute filters with live search, grouped the way scouts think:
  • Technical: finishing, first touch, dribbling, crossing, long shots, passing, tackling...
  • Physical: pace, acceleration, stamina, strength, jumping, agility...
  • Mental & tactical: vision, composure, positioning, work rate, pressing intensity, decisions, leadership...
• Results as player cards: photo placeholder, role, club, age, market value, top strengths, attribute ratings at a glance
• Sort by relevance, value, age, or overall rating

🧭 Menu 2 — My team & AI recommendations (next release)

• Team profile: formation, possession/pressing/transition tendencies, squad statistics, key players, style descriptors
• LangChain-powered fit engine: the team profile + candidate pool are fed to an LLM chain that scores adequacy and explains each recommendation ("fits your high line: elite recovery pace, aggressive positioning")
• Shortlists: save, compare, export

Architecture

APP SCOUT/
├── frontend/            React (Vite) — this release ships the main menu
│   └── src/
│       ├── components/  SearchFilters, PlayerCard, TopBar, ...
│       ├── data/        mock player dataset (v1) → API client (v2)
│       └── styles/      dark theme, neon-green design tokens
├── backend/             (v2) Python FastAPI
│   ├── api/             REST endpoints: /players, /search, /recommend
│   ├── services/        data providers (FBref/Transfermarkt via soccerdata)
│   └── fit_engine/      LangChain chain: team profile → ranked recommendations
└── README.md

Why this stack

• React + Vite frontend: fast dev loop, component model fits a filter-heavy UI.
• Python FastAPI backend: direct access to the football-data ecosystem (soccerdata/FBref scraping, pandas pipelines) and to the ML stack already built in the xG project; automatic OpenAPI docs.
• LangChain for the fit engine: orchestrates the LLM calls (team-profile summarisation → candidate scoring → justification generation) with structured outputs, so recommendations stay parseable and testable.

v2 data flow (fit engine)

Team profile (form) ──┐
                      ├─► FastAPI /recommend ─► LangChain chain:
Candidate pool     ───┘        1. profile → search constraints (structured output)
(filtered players)             2. hard filter (position, budget) in pandas
                               3. LLM scores fit per candidate (batch, JSON output)
                               4. ranked list + one-line justification each

Design system

Dark, focused, "war-room" aesthetic:

Token	Value	Use
--bg	#0B0D0C	app background
--surface	#141715	cards, panels
--surface-2	#1C201D	inputs, hover
--border	#2A2F2B	hairlines
--text	#E8ECE9	primary text
--text-dim	#9AA39C	secondary text
--accent	#3DFF6E	neon green — actions, highlights, focus
--accent-dim	#1F7A3D	accent borders, tags

Rules: neon green is scarce (CTAs, active states, key numbers — never body text); generous spacing; ratings colour-scaled (red → yellow → neon green).

Getting started

cd frontend
npm install
npm run dev        # http://localhost:5173

Backend (v2): cd backend && pip install -r requirements.txt && uvicorn api.main:app.

Roadmap

• README & product definition
• v1.0 — main menu: player search UI with full filtering (mock dataset)
• v1.1: player detail view (radar chart, percentiles vs position)
• v1.2: FastAPI backend serving real data (soccerdata/FBref), replace mocks
• v2.0: team profile menu + LangChain fit engine
• v2.1: shortlists, comparison view, export

Data & licences (v2 note)

Real player data will come from public sources (FBref via soccerdata, market values from public datasets) for non-commercial portfolio use, with attribution. The v1 mock dataset is entirely fictional.