Metadata-Version: 2.4
Name: sports-skills
Version: 0.16.4
Summary: Lightweight Python SDK for sports data — football, F1, NFL, NBA, WNBA, NHL, MLB, tennis, CFB, CBB, golf, prediction markets, betting analysis, and news
Author-email: Machina Sports <hello@machina.gg>
License-Expression: MIT
License-File: LICENSE
Keywords: arbitrage,atp,betting,cbb,cfb,college-basketball,college-football,f1,football,golf,kalshi,lpga,mlb,nba,ncaa,news,nfl,nhl,odds-comparison,pga,polymarket,prediction-markets,sports,tennis,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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: feedparser>=6.0
Provides-Extra: all
Requires-Dist: fastf1>=3.0; extra == 'all'
Requires-Dist: nfl-data-py>=0.3; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: py-clob-client>=0.1.8; 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; extra == 'nfl'
Provides-Extra: nhl
Provides-Extra: polymarket
Requires-Dist: py-clob-client>=0.1.8; extra == 'polymarket'
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 — 21 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
- **Tennis**: ATP and WTA tournament scores, rankings, calendars, and player profiles
- **Golf**: PGA, LPGA, and DP World tour scorecards and leaderboards
- **Racing**: Formula 1 (via FastF1) — lap times, telemetry, and race results
- **Prediction Markets**: Polymarket & Kalshi live odds and order books
- **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 --help
```

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 get_markets --query "super bowl"
sports-skills news fetch_items --query "Lando Norris" --limit 5
```

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

# 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.get_markets(query="bitcoin")
print(markets["data"]["markets"])
```

## 🏗️ 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:

```python
from sports_skills import nfl
import json

# Returns a list of dicts formatted exactly like Anthropic/OpenAI tools
schema = nfl.generate_schema()
print(json.dumps(schema, indent=2))
```

## License
MIT
