Metadata-Version: 2.4
Name: sports-skills
Version: 0.33.0
Summary: Lightweight Python SDK for sports data — football, F1, NFL, NBA, WNBA, NHL, MLB, tennis, CFB, CBB, golf, volleyball, prediction markets, betting analysis, and news
Project-URL: Reviewed source, https://github.com/machina-sports/sports-skills/tree/3b135bb324a39710df024a22e8d9fba434b8e6a2
Author-email: Machina Sports <hello@machina.gg>
License-Expression: MIT
License-File: LICENSE
Keywords: arbitrage,atp,betting,cbb,cfb,college-basketball,college-football,eredivisie,f1,football,golf,kalshi,lpga,mlb,nba,ncaa,nevobo,news,nfl,nhl,odds-comparison,pga,polymarket,prediction-markets,prophetx,sports,tennis,volleyball,wnba,wta
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9.10
Requires-Dist: feedparser>=6.0
Provides-Extra: all
Requires-Dist: fastf1>=3.0; extra == 'all'
Requires-Dist: nfl-data-py>=0.3; (python_version < '3.10') and extra == 'all'
Requires-Dist: nflreadpy>=0.1; (python_version >= '3.10') and extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: py-clob-client-v2>=1.0.1; extra == 'all'
Requires-Dist: pyarrow>=14; (python_version >= '3.10') and extra == 'all'
Provides-Extra: cbb
Provides-Extra: cfb
Provides-Extra: dev
Requires-Dist: fastf1>=3.0; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: f1
Requires-Dist: fastf1>=3.0; extra == 'f1'
Requires-Dist: pandas>=2.0; extra == 'f1'
Provides-Extra: golf
Provides-Extra: mlb
Provides-Extra: nba
Provides-Extra: nfl
Requires-Dist: nfl-data-py>=0.3; (python_version < '3.10') and extra == 'nfl'
Requires-Dist: nflreadpy>=0.1; (python_version >= '3.10') and extra == 'nfl'
Requires-Dist: pyarrow>=14; (python_version >= '3.10') and extra == 'nfl'
Provides-Extra: nhl
Provides-Extra: polymarket
Requires-Dist: py-clob-client-v2>=1.0.1; extra == 'polymarket'
Provides-Extra: site
Requires-Dist: jinja2>=3.1; extra == 'site'
Requires-Dist: pyyaml>=6.0; extra == 'site'
Provides-Extra: tennis
Provides-Extra: wnba
Description-Content-Type: text/markdown

# sports-skills

https://sports-skills.sh

A lightweight, zero-config Python SDK and CLI for live sports data and prediction markets. 

Built natively for AI agents, but works perfectly as a standalone Python library for developers. Wraps publicly available sports data sources and APIs into unified, deterministic commands.

**Zero API keys. Zero signup. Just works.**

---

## 📦 Installation

Install as a global CLI tool (recommended for agents):

```bash
uv tool install sports-skills
# or
pip install sports-skills
```

Base install includes all sports modules.

Install as a Python library:

```bash
uv add sports-skills
# or
pip install sports-skills
```

Optional extras:

```bash
pip install "sports-skills[all]"
pip install "sports-skills[dev]"
```

---

## ⚡ What's Included

- **Football (Soccer)**: ESPN, Understat, FPL, Transfermarkt, football-data.co.uk, ClubElo — 25 commands across 30 leagues
- **US Sports**: NFL, NBA, WNBA, NHL, MLB, College Football (CFB), College Basketball (CBB) — live scores, standings, depth charts, injuries, and leaders
- **Analytics backends** (same modules, second source): nflverse for NFL (EPA, weekly tables, 1999+), NBA Stats for NBA (shot charts, advanced ratings, 1946+), the official MLB Stats API (pitch-level velocity/spin/exit-velocity, 1901+), the official NHL API (coordinate play-by-play, 1917+), and the NCAA's own endpoints for college (FCS/D2/D3 scoreboards, March Madness bracket)
- **Tennis**: ATP and WTA tournament scores, rankings, calendars, and player profiles
- **Golf**: PGA, LPGA, and DP World tour scorecards and leaderboards
- **College XC/TF**: NCAA cross country and track & field — athlete profiles, personal records, meet results, and news via The Stride Report
- **Volleyball**: Nevobo — Dutch volleyball (Eredivisie, Topdivisie, Superdivisie) standings, schedules, results, clubs
- **Racing**: Formula 1 (via FastF1) — lap times, telemetry, and race results
- **Esports**: Dota 2 (OpenDota) and League of Legends esports (Leaguepedia) — pro matches, leagues, teams, and tournaments
- **Prediction Markets**: Polymarket & Kalshi live odds and order books, including esports implied-probability odds (CS2/LoL/Dota2)
- **News**: Multi-sport news aggregators

---

## 💻 CLI Usage

The package exposes a `sports-skills` binary. 

List all supported sports:
```bash
sports-skills --help
```

List commands for a specific sport:
```bash
sports-skills nfl
```

Execute a command:
```bash
sports-skills nfl get_scoreboard --date 2026-02-24
sports-skills football get_current_season --competition_id premier-league
sports-skills polymarket search_markets --query "super bowl"
sports-skills news fetch_items --query "Lando Norris" --limit 5
sports-skills xctf get_news --limit 5
sports-skills xctf search_athlete --name "Jane Hedengren" --school "UT_college_f_BYU"
```

All CLI output is printed as strict JSON, making it perfect for AI agents (Claude, GPT, Gemini) to parse and reason over.

---

## 🐍 Python SDK Usage

You can use the exact same commands directly in your Python code:

```python
from sports_skills import nfl, football, polymarket, xctf

# Get live NFL scores
scores = nfl.get_scoreboard(date="2026-02-24")
print(scores["data"]["events"])

# Get Premier League standings
table = football.get_season_standings(season_id="premier-league-2025")
print(table["data"]["standings"])

# Fetch live odds from Polymarket
markets = polymarket.search_markets(query="super bowl")
print(markets["data"]["markets"])

# Get latest NCAA XC/TF news from The Stride Report
news = xctf.get_news(limit=5)
print(news["data"]["articles"])

# Look up an athlete's PRs
profile = xctf.get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren")
print(profile["data"]["prs"])
```

## 🏗️ AI Agent Integration

`sports-skills` is built on the Anthropic Level-3 Agent capability spec. Every command is deterministic and automatically generates its own JSON Schema.

To extract the OpenAI/Anthropic compatible tool schema for any module:

```bash
sports-skills nfl schema
```

Prints `{sport, version, tools}` — `tools` is one Anthropic/OpenAI-shaped tool definition per command.

---

## Machina Sports Schema (canonical output)

Football event commands can emit the **Machina Sports Schema** envelope instead of the native payload: one provider's observation of one event, serialized as JSON-LD against the [IPTC Sport Schema](https://sportschema.org) 1.1 profile, with a provider-id crosswalk, a capability report, and a provenance block naming the pinned upstream commit.

```bash
# One event → one envelope, printed directly
sports-skills football get_event_summary --event_id=740000 \
  --format=machina-canonical --observed-at=2026-03-01T22:05:00+00:00

# A day's fixtures → {provider, format, events}, every event a full envelope
sports-skills football get_daily_schedule --date=2026-03-01 \
  --canonical --observed-at=2026-03-01T22:05:00+00:00
```

`--canonical` is an alias for `--format=machina-canonical`. It is supported on `football get_event_summary` and `football get_daily_schedule` (also reachable as `scores`); every other command refuses the flag by name rather than wrapping data the schema does not describe.

**`--observed-at` is required and must carry a UTC offset.** It is never read from the clock: it is the one input that makes the document reproducible, and the reference fixtures this output is tested byte-for-byte against depend on it being stated rather than guessed.

**Rights: prototype only.** Every envelope carries `rights: {"data_class": "open-public", "prototype_only": true, "commercial_use": false}`. Gate a consumer against them with `--consumer-tier`:

```bash
sports-skills football get_event_summary --event_id=740000 --canonical \
  --observed-at=2026-03-01T22:05:00+00:00 --consumer-tier=production
# → refused: rights-prototype-only, exit status 1
```

`prototype` (the default) is served. `production` refuses every envelope this package can produce, with one actionable finding and a nonzero exit status — including a query that returns nothing, which is refused before the provider is called, because the licence answer is the adapter's and not the result set's. For licensed data cleared for commercial use, see [machina.gg](https://machina.gg).

The default output of every command is unchanged: no module on the native path imports the canonical package, and the CLI reaches it only when you ask for it by name.

---

## License
MIT
