CFB Scout

AI-powered college football scouting intelligence agent.

Setup

1. Create virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"

2. Configure environment:

   cp .env.example .env
   # Edit .env with your credentials:
   # - DATABASE_URL: Supabase connection string
   # - ANTHROPIC_API_KEY: Claude API key
   # - REDDIT_* (optional): Reddit API credentials when approved

3. Deploy schema (first time only):

   psql "$DATABASE_URL" -f src/storage/schema.sql

   Or use the Supabase SQL Editor.

Usage

# Seed test data for development
python scripts/run_pipeline.py --seed

# Crawl 247Sports recruiting data
python scripts/run_pipeline.py --crawl-247 --teams texas ohio-state --years 2025

# Process reports through Claude summarization
python scripts/run_pipeline.py --process

# Link entities (connect reports to player profiles)
python scripts/run_pipeline.py --link

# Run full pipeline
python scripts/run_pipeline.py --all --teams texas --years 2025

# Run grading pipeline (update player grades)
python scripts/run_pipeline.py --grade

# Review pending player links (interactive)
python scripts/run_pipeline.py --review-links

API Server

# Start the API server (development)
python scripts/run_api.py --reload

# Start on specific host/port
python scripts/run_api.py --host 0.0.0.0 --port 8080

# API docs available at http://localhost:8000/docs

Testing

pytest tests/ -v

Project Structure

cfb-scout/
├── src/
│   ├── api/            # REST API
│   │   ├── main.py         # FastAPI application
│   │   └── models.py       # Pydantic response models
│   ├── crawlers/       # Data source crawlers
│   │   ├── base.py         # BaseCrawler, CrawlResult
│   │   └── recruiting/     # Recruiting site crawlers
│   │       └── two47.py    # 247Sports commits crawler
│   ├── processing/     # Processing pipeline
│   │   ├── summarizer.py       # Sentiment & summary extraction
│   │   ├── pipeline.py         # Batch processing orchestration
│   │   ├── entity_extraction.py # Player name extraction (regex + Claude)
│   │   ├── entity_linking.py   # Connect reports to player profiles
│   │   ├── player_matching.py  # 3-tier matching (deterministic/vector/fuzzy)
│   │   ├── aggregation.py      # Player profile aggregation
│   │   └── grading.py          # Grading pipeline
│   └── storage/        # Database operations
│       ├── db.py           # Connection & CRUD helpers
│       └── schema.sql      # Supabase schema
├── scripts/            # CLI tools
│   ├── run_pipeline.py     # Main pipeline entry point
│   └── run_api.py          # API server launcher
└── tests/              # Test suite

Database Schema

All tables live in the scouting schema:

• reports - Raw crawled content with summaries
• players - Player scouting profiles with grades/traits
• player_timeline - Longitudinal tracking snapshots
• team_rosters - Position group analysis
• crawl_jobs - Crawl job tracking

Phase 1 Status

• Schema deployed to Supabase
• Claude summarization working
• Processing pipeline functional
• Reddit crawler (awaiting API approval)
• End-to-end pipeline verified

Phase 2 Status

• 247Sports commits crawler
• Player entity extraction (regex + Claude)
• Fuzzy name matching against roster/recruits
• Scouting player profile creation
• Report-to-player linking

Phase 3 Status

• Player profile aggregation
• Composite grading system
• Timeline tracking snapshots
• FastAPI REST endpoints
• Player/team query API

Phase 4 Status

• PFF API integration
• Trend analysis (rising/falling stocks)
• Player comparison engine
• Watch lists
• Draft board with projections

Phase 5 Status

• Alert system (grade/status/report changes)
• Alert history and notifications
• Transfer portal tracking
• Destination predictions
• Team portal impact analysis

Phase 6A Status (Foundation)

• pgvector extension enabled
• player_embeddings table with HNSW index
• pending_links table for review queue
• Embedding generation module (OpenAI)
• Database functions for embeddings
• Backfill embeddings for current roster (in progress)

Phase 6B Status (Unified Player Mart)

• player_mart materialized view (30K players)
• Joins roster, recruiting, scouting, portal data
• Indexes for team/position/portal queries
• Refresh function (CONCURRENTLY)
• pg_cron nightly refresh (7:30 AM CT)

Phase 6C Status (Enhanced Matching)

• Tier 1: Deterministic matching (exact name+team+year, athlete_id)
• Tier 2: Vector similarity via pgvector (>= 0.92 threshold)
• Tier 3: Fuzzy fallback with rapidfuzz
• Pending links review queue for 0.80-0.92 confidence
• CLI command: --review-links

API Endpoints

Players

• GET /players - List players with filters
• GET /players/{id} - Player detail with timeline
• GET /players/{id}/trend - Player trend analysis
• GET /players/{id}/similar - Find similar players

Teams

• GET /teams - Team summaries
• GET /teams/{name}/players - Team roster

Trends

• GET /trends/rising - Players with rising grades
• GET /trends/falling - Players with falling grades

Comparisons

• GET /compare/{id1}/{id2} - Head-to-head comparison

Watch Lists

• GET /watchlists?user_id=X - User's watch lists
• POST /watchlists?user_id=X - Create watch list
• POST /watchlists/{id}/players/{player_id} - Add to list
• DELETE /watchlists/{id}/players/{player_id} - Remove from list
• DELETE /watchlists/{id} - Delete list

Draft Board

• GET /draft/board - Full draft rankings
• GET /draft/position/{pos} - Position rankings

Alerts

• GET /alerts?user_id=X - User's active alerts
• POST /alerts?user_id=X - Create alert rule
• DELETE /alerts/{id} - Delete alert
• POST /alerts/{id}/deactivate - Deactivate alert
• GET /alerts/history?user_id=X - Fired alerts
• POST /alerts/history/{id}/read - Mark as read

Transfer Portal

• GET /transfer-portal/active - Current portal players
• GET /transfer-portal/player/{id} - Player transfer history
• GET /transfer-portal/player/{id}/predict - Destination predictions
• GET /teams/{name}/transfers - Team transfer activity
• GET /teams/{name}/portal-impact - Portal impact analysis
• POST /transfer-portal/snapshot - Generate daily snapshot