Metadata-Version: 2.5
Name: langchain-footballcharts
Version: 0.1.0
Summary: LangChain tools for football-charts.com: tables, results, fixtures, model probabilities and Monte Carlo projections for 93 football leagues.
Project-URL: Homepage, https://www.football-charts.com/developers
Project-URL: Repository, https://github.com/ddevetak/langchain-footballcharts
Project-URL: Documentation, https://www.football-charts.com/developers
Author: Damir Devetak
License: MIT
License-File: LICENSE
Keywords: agent,football,langchain,predictions,soccer,statistics,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-core<2.0,>=0.3
Requires-Dist: pydantic>=2
Provides-Extra: test
Requires-Dist: langchain-tests>=0.3; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# langchain-footballcharts

LangChain tools for [football-charts.com](https://www.football-charts.com) — football
statistics and model probabilities for **93 leagues** (top flights, lower divisions
and women's leagues on five continents), exposed as ten read-only agent tools.

```bash
pip install langchain-footballcharts
```

```python
from langchain_footballcharts import FootballChartsToolkit

toolkit = FootballChartsToolkit(api_key="fc_...")   # or set FC_API_KEY
tools = toolkit.get_tools()
```

Get a free key in seconds at **[football-charts.com/developers](https://www.football-charts.com/developers)** —
no card. The free tier covers all 93 leagues for the current and previous season.

## What the tools return

| Tool | Data |
|---|---|
| `list_leagues` | every league, its key, and the seasons your key can read |
| `get_league_table` | standings: points, W/D/L, goals, last-5 form |
| `get_rankings` | the table re-ranked by luck-adjusted or goals views, with expected points |
| `get_results` | finished matches with FT/HT scores and **first-goal minute** |
| `get_fixtures` | upcoming matches with model probabilities (HT over 1.5, FT over 2.5) |
| `get_match` | one match: full probability block across markets, ratings, first-goal histograms |
| `get_season_projection` | 10,000-run Monte Carlo: title / top-4 / relegation probability per team |
| `get_team` | one team: table row, match log, goal-timing bins, per-team stats |
| `get_goal_timing` | goals per 15-minute bin per team, league-level timing stats |
| `get_track_record` | the public, settled prediction ledger — hit rates and P/L, losses included |

Probabilities, not tips. Every model signal Football Charts publishes is logged before
kickoff and settled in public; `get_track_record` returns that ledger unedited.

## Example: an agent

```python
from langchain.agents import create_agent
from langchain_anthropic import ChatAnthropic
from langchain_footballcharts import FootballChartsToolkit

agent = create_agent(
    ChatAnthropic(model="claude-sonnet-4-5"),
    tools=FootballChartsToolkit().get_tools(),
)
agent.invoke({"messages": [("user", "Which team in the Allsvenskan scores latest in matches?")]})
```

## Notes

- Every tool has a sync `_run` and async `_arun`; results are JSON strings so the full
  payload reaches the model.
- The API key is bound per tool instance, never read from a module-level global.
- Goalless matches come back as `first_goal_time: null, goalless: true`.
- Same ten tools, same names, as the [Football Charts MCP server](https://github.com/ddevetak/footballcharts-mcp).

## Development

```bash
pip install -e ".[test]"
pytest tests/unit_tests                 # offline, mocked API
FC_API_KEY=fc_... pytest tests/integration_tests   # against production
```

MIT.
