Skip to content
Back to search

premier-league-chatbot

Premier League 2026-27 chatbot: RAG + tool calling on Azure OpenAI, own MCP server, evals and AI Ops

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elidehaene01--premier-league-chatbot/badge.svg)](/listings/elidehaene01--premier-league-chatbot)

HTML

<a href="/listings/elidehaene01--premier-league-chatbot"><img src="/api/listings/elidehaene01--premier-league-chatbot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This guide assumes no programming experience. It is written for Windows. On a Mac or Linux the steps are the same, but type `python3` where it says `py`. Each step says what you should see, and the [troubleshooting](#when-something-goes-wrong) section covers the usual problems.

It takes about 30 minutes, most of it waiting for installs and the first data load.

What it costs

The data is free. The language model and the safety check run on Microsoft Azure, which you pay for: - One chat answer costs well under one cent. - Loading the news into the search index costs about one cent. - A full evaluation run costs about $0.90. You only run it when you choose to.

Step 1: Install four programs

Install each one with its default options:

| Program | Where to get it | Why | |---|---|---| | **Git** | https://git-scm.com/downloads | downloads the code | | **Python 3.12 or newer** | https://www.python.org/downloads/ (tick **"Add python.exe to PATH"** in the installer) | runs the chatbot | | **Node.js** (the "LTS" version) | https://nodejs.org/ | runs the web page | | **Docker Desktop** | https://www.docker.com/products/docker-desktop/ | runs the database |

After installing Docker Desktop, start it once and wait until it says **Engine running** at the bottom left. Restart your computer if the installer asks you to.

**Check:** open **PowerShell** (press the Windows key and type `PowerShell`) and type these one at a time:

git --version
py --version
node --version
docker --version

Each one should print a version number. If one says "not recognized", install that program again, then close and reopen PowerShell.

Step 2: Download the code

In PowerShell:

cd ~\Documents
git clone https://github.com/EliDehaene01/premier-league-chatbot.git
cd premier-league-chatbot

**You should see** "Cloning into 'premier-league-chatbot'..." and then a new prompt. From now on, run every command from this `premier-league-chatbot` folder. If you open a new PowerShell window, first type `cd ~\Documents\premier-league-chatbot`.

Step 3: Get the Azure keys

The chatbot needs two Azure services. If someone gave you the values below, skip this step.

1. **Azure OpenAI**, through [Microsoft Foundry](https://ai.azure.com/). Create a project, then deploy two models: - a chat model, for example `gpt-5.4-mini`; - the embedding model `text-embedding-3-small`.

Note the endpoint (it looks like `https://<name>.openai.azure.com/openai/v1`), the API key and the two deployment names. 2. **Azure AI Content Safety**. Create the resource in the [Azure portal](https://portal.azure.com/); the free tier (F0) is enough. Note its endpoint and key. It checks every news article for hidden instructions before the model reads it.

Step 4: Fill in your settings

copy .env.example .env
notepad .env

Notepad opens the file `.env`. Fill in: - `POSTGRES_PASSWORD`: make up any password. It only protects the database on your own computer. - `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_CHAT_DEPLOYMENT` and `AZURE_OPENAI_EMBEDDING_DEPLOYMENT`, from step 3. - `CONTENT_SAFETY_ENDPOINT` and `CONTENT_SAFETY_API_KEY`, from step 3.

Leave everything else as it is. Save and close Notepad.

`.env` holds your keys. It is never uploaded to GitHub (the repository ignores it), so don't put keys anywhere else.

Step 5: Start the database

docker compose up -d

**You should see** "Container premier-league-chatbot-postgres-1 Started". The first time it also downloads the database image, which takes a minute. The database then starts by itself whenever Docker Desktop runs.

Step 6: Install the chatbot

py -m pip install -e ".[dev]"

**You should see** a lot of "Collecting..." lines and finally "Successfully installed ...". This takes a few minutes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 280 lines
  1. # Premier League chatbot
  2. A chatbot about the current Premier League season (2026-27). Ask it about the table, results, fixtures, line-ups, players or the latest news. It answers from real data and shows where every fact came from.
  3. - **Stats** (scores, positions, points, goals) come from tool calls on a database that is filled from the Premier League's own data feeds. The model never states a number it did not get from a tool.
  4. - **News** comes from searching official premierleague.com articles (RAG). Every news answer cites the article's title, date and link.
  5. - **Weekly summaries** are written automatically: a matchweek recap on Tuesday morning and news highlights on Friday morning.
  6. - **Its tools are an MCP server**, so Claude Desktop, Claude Code and VS Code can use them too.
  7. The chat app runs on your own computer only. What is public is the **[project website](https://elidehaene01.github.io/premier-league-chatbot/)**:
  8. - the weekly summaries;
  9. - a [showcase](https://elidehaene01.github.io/premier-league-chatbot/showcase.html) with a demo recording, screenshots and recorded conversations;
  10. - the [AI Ops dashboard](https://elidehaene01.github.io/premier-league-chatbot/ops.html) with cost, speed, eval scores and data freshness.
  11. ![A full chat session with the local app (74 s demo recording)](docs/showcase/10-chat-demo.gif)
  12. | News with sources | Line-ups | "Why" questions |
  13. |---|---|---|
  14. | ![](docs/showcase/02-news-with-sources.png) | ![](docs/showcase/03-lineup.png) | ![](docs/showcase/05-why-question.png) |
  15. How it fits together: [ARCHITECTURE.md](ARCHITECTURE.md). Every decision and why: [ARCHITECTURE.md, Decisions](ARCHITECTURE.md#decisions) and [docs/adr/](docs/adr/).
  16. ---
  17. ## Getting started
  18. This guide assumes no programming experience. It is written for Windows. On a Mac or Linux the steps are the same, but type `python3` where it says `py`. Each step says what you should see, and the [troubleshooting](#when-something-goes-wrong) section covers the usual problems.
  19. It takes about 30 minutes, most of it waiting for installs and the first data load.
  20. ### What it costs
  21. The data is free. The language model and the safety check run on Microsoft Azure, which you pay for:
  22. - One chat answer costs well under one cent.
  23. - Loading the news into the search index costs about one cent.
  24. - A full evaluation run costs about $0.90. You only run it when you choose to.
  25. ### Step 1: Install four programs
  26. Install each one with its default options:
  27. | Program | Where to get it | Why |
  28. |---|---|---|
  29. | **Git** | https://git-scm.com/downloads | downloads the code |
  30. | **Python 3.12 or newer** | https://www.python.org/downloads/ (tick **"Add python.exe to PATH"** in the installer) | runs the chatbot |
  31. | **Node.js** (the "LTS" version) | https://nodejs.org/ | runs the web page |
  32. | **Docker Desktop** | https://www.docker.com/products/docker-desktop/ | runs the database |
  33. After installing Docker Desktop, start it once and wait until it says **Engine running** at the bottom left. Restart your computer if the installer asks you to.
  34. **Check:** open **PowerShell** (press the Windows key and type `PowerShell`) and type these one at a time:
  35. ```powershell
  36. git --version
  37. py --version
  38. node --version
  39. docker --version
  40. ```
  41. Each one should print a version number. If one says "not recognized", install that program again, then close and reopen PowerShell.
  42. ### Step 2: Download the code
  43. In PowerShell:
  44. ```powershell
  45. cd ~\Documents
  46. git clone https://github.com/EliDehaene01/premier-league-chatbot.git
  47. cd premier-league-chatbot
  48. ```
  49. **You should see** "Cloning into 'premier-league-chatbot'..." and then a new prompt. From now on, run every command from this `premier-league-chatbot` folder. If you open a new PowerShell window, first type `cd ~\Documents\premier-league-chatbot`.
  50. ### Step 3: Get the Azure keys
  51. The chatbot needs two Azure services. If someone gave you the values below, skip this step.
  52. 1. **Azure OpenAI**, through [Microsoft Foundry](https://ai.azure.com/). Create a project, then deploy two models:
  53. - a chat model, for example `gpt-5.4-mini`;
  54. - the embedding model `text-embedding-3-small`.
  55. Note the endpoint (it looks like `https://<name>.openai.azure.com/openai/v1`), the API key and the two deployment names.
  56. 2. **Azure AI Content Safety**. Create the resource in the [Azure portal](https://portal.azure.com/); the free tier (F0) is enough. Note its endpoint and key. It checks every news article for hidden instructions before the model reads it.
  57. ### Step 4: Fill in your settings
  58. ```powershell
  59. copy .env.example .env
  60. notepad .env
  61. ```
  62. Notepad opens the file `.env`. Fill in:
  63. - `POSTGRES_PASSWORD`: make up any password. It only protects the database on your own computer.
  64. - `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_CHAT_DEPLOYMENT` and `AZURE_OPENAI_EMBEDDING_DEPLOYMENT`, from step 3.
  65. - `CONTENT_SAFETY_ENDPOINT` and `CONTENT_SAFETY_API_KEY`, from step 3.
  66. Leave everything else as it is. Save and close Notepad.
  67. `.env` holds your keys. It is never uploaded to GitHub (the repository ignores it), so don't put keys anywhere else.
  68. ### Step 5: Start the database
  69. ```powershell
  70. docker compose up -d
  71. ```
  72. **You should see** "Container premier-league-chatbot-postgres-1 Started". The first time it also downloads the database image, which takes a minute. The database then starts by itself whenever Docker Desktop runs.
  73. ### Step 6: Install the chatbot
  74. ```powershell
  75. py -m pip install -e ".[dev]"
  76. ```
  77. **You should see** a lot of "Collecting..." lines and finally "Successfully installed ...". This takes a few minutes.
  78. **Check:** `py -m pytest -m "not live" -q` runs the tests. It should end with a line like "110 passed" and no failures.
  79. ### Step 7: Load the season
  80. ```powershell
  81. py -m ingestion backfill --season 2026
  82. ```
  83. This downloads all clubs, players, matches, the table and the news articles so far. It takes about 3 minutes. **You should see** a summary that ends with a `"quality"` block in which every check says `"ok"`.
  84. Then build the news search index (about one cent of Azure):
  85. ```powershell
  86. py -m backend.rag.build_index
  87. ```
  88. **You should see** something like `"articles_indexed": 797` and `"chunks_written": 1529`.
  89. **Quick test in the terminal:**
  90. ```powershell
  91. py -m backend.chat --ask "Who is top of the league?"
  92. ```
  93. It prints the tools it used, an answer with `[1]`-style sources, and the cost of the answer.
  94. ### Step 8: Start the app
  95. The app has two parts that each need their own PowerShell window.
  96. **Window 1, the backend:**
  97. ```powershell
  98. cd ~\Documents\premier-league-chatbot
  99. py -m uvicorn backend.api.main:create_app --factory --port 8000
  100. ```
  101. **You should see** "Uvicorn running on http://127.0.0.1:8000". Leave this window open.
  102. **Window 2, the web page:**
  103. ```powershell
  104. cd ~\Documents\premier-league-chatbot\frontend
  105. npm ci
  106. npm run dev
  107. ```
  108. `npm ci` takes a minute the first time. **You should see** "Local: http://localhost:5173/". Leave this window open too.
  109. ### Step 9: Chat
  110. Open **http://localhost:5173** in your browser.
  111. - Click a suggested question, or type your own.
  112. - The badge at the top shows whether the data is up to date.
  113. - The **This week** page shows the latest weekly summaries.
  114. To stop the app, press `Ctrl+C` in both windows. To start it again later, repeat step 8 only.
  115. ### Keeping the data up to date
  116. Run these once a week, or let Windows do it for you (below):
  117. ```powershell
  118. py -m ingestion matchweek # new results, table and articles, and adds them to the search index
  119. py -m ingestion news # new articles only
  120. ```
  121. To schedule them on Windows, run this once in PowerShell, with your `<python>` path (see [MCP](#use-the-tools-from-claude-or-vs-code-mcp) for how to find it):
  122. ```powershell
  123. powershell -ExecutionPolicy Bypass -File scripts\schedule_windows.ps1 -Python "<python>"
  124. ```
  125. It registers six tasks in Task Scheduler: the two data loads, the two weekly summaries (each one calls Azure and publishes the website) and two freshness checks. Docker Desktop must be running at those times.
  126. ### When something goes wrong
  127. | What you see | What to do |
  128. |---|---|
  129. | `py` or `python` is "not recognized", or typing `python` opens the Microsoft Store | Reinstall Python from python.org with "Add python.exe to PATH" ticked, and use `py`. The Store's `python` is only a shortcut that opens the Store. |
  130. | `docker compose up -d` says it cannot connect to the Docker daemon | Docker Desktop isn't running. Start it and wait for **Engine running**. |
  131. | "port is already allocated" for 5433 | Something else uses that port. Pick another, for example `POSTGRES_PORT=5434` in `.env`, and run `docker compose up -d` again. |
  132. | `password authentication failed` | You changed `POSTGRES_PASSWORD` after the database was first created. Put the old password back, or remove the database and start over with `docker compose down -v` and then `docker compose up -d`. This deletes the loaded data. |
  133. | Windows blocks Python inside a `.venv` folder ("Smart App Control") | Install without a virtual environment, as in step 6. |
  134. | The chat says news retrieval is unavailable | The Content Safety settings in `.env` are missing or wrong, or the free tier is briefly rate-limited. Check the two `CONTENT_SAFETY_*` values and try again a minute later. |
  135. | `401` or `404` errors from Azure | An endpoint, key or deployment name in `.env` is wrong. The endpoint must end in `/openai/v1`, and the deployment names must match what you created in Foundry. |
  136. | The web page loads but answers never come | Window 1 (the backend) isn't running, or it stopped with an error. Look there. |
  137. | `npm` is "not recognized" | Install Node.js, then close and reopen PowerShell. |
  138. ---
  139. ## Use the tools from Claude or VS Code (MCP)
  140. The chatbot's tools also run as an MCP server, so other AI apps can use the same data. [ARCHITECTURE.md, MCP](ARCHITECTURE.md#mcp-server) explains what MCP tools, resources and prompts are. You need steps 1 to 7 done first. Find the full path of your Python with `py -c "import sys; print(sys.executable)"`; the examples below call it `<python>`.
  141. - **Claude Desktop:** open Settings > Developer > **Edit config**. Inside `"mcpServers"`, add:
  142. ```json
  143. "premier-league": { "command": "<python>", "args": ["-m", "mcp_server"] }
  144. ```
  145. Write the path with double backslashes (`C:\\Users\\...`). Quit Claude Desktop from the tray and reopen it; "premier-league" should show as **Running**. Name it in your question ("Use the premier-league tools: who is top?"), or Claude may use its own web search instead.
  146. - **Claude Code:** `claude mcp add --scope local premier-league -- "<python>" -m mcp_server`. In PowerShell, type `claude.cmd` instead of `claude`.
  147. - **VS Code:** the repository's `.vscode/mcp.json` starts the server with `python`. On Windows, change `"command"` to your `<python>` path. Then start the server from the MCP view and ask in Copilot Chat (agent mode).
  148. Recorded demos of all three: [docs/showcase/](docs/showcase/).
  149. ---
  150. ## Command reference
  151. For developers. Every command runs from the repository folder; `py` on Windows, `python` elsewhere.
  152. ```bash
  153. # data
  154. python -m ingestion backfill --season 2026 # first load
  155. python -m ingestion matchweek # weekly: latest matchweek + new articles (+ index)
  156. python -m ingestion news # new articles (+ index)
  157. python -m ingestion rebuild # rebuild silver from bronze, no network
  158. python -m backend.rag.build_index # embed new or changed articles
  159. # chat
  160. python -m backend.chat # interactive terminal chat
  161. uvicorn backend.api.main:create_app --factory --port 8000
  162. cd frontend && npm ci && npm run dev # http://localhost:5173
  163. # weekly summaries and the website
  164. python -m digests recap | news # write a summary (one Azure call or a few)
  165. python -m digests publish --out preview # render the site into a folder
  166. python -m digests publish --push # publish to the gh-pages branch
  167. # MCP server
  168. python -m mcp_server # stdio, for Claude Desktop / VS Code
  169. python -m mcp_server --http # http://127.0.0.1:8765/mcp
  170. # quality
  171. ruff check . && pytest -m "not live" # lint + tests (no Azure)
  172. cd frontend && npm run lint && npm test
  173. python -m evals.retrieval_smoke # search quality, fractions of a cent
  174. python -m evals.run --dataset chat_v1 # full eval, 165 cases, about $0.90
  175. python -m evals.run --subset smoke # 25 cases, about $0.15
  176. python -m evals.digests # summary evals
  177. # AI Ops
  178. python scripts/langfuse_env.py # once: Langfuse secrets into .env
  179. docker compose -f docker-compose.langfuse.yml up -d # tracing UI on http://localhost:3000
  180. python -m backend.observability.freshness # is the data up to date?
  181. python -m evals.feedback review # thumbs-down answers to look at
  182. ```
  183. Evals need `pip install -e ".[eval]"` and exit non-zero below `evals/thresholds.yaml`. Latest full results: [docs/EVAL_RESULTS.md](docs/EVAL_RESULTS.md). The **Eval gate** workflow on GitHub runs the full set on every pull request that changes how the chatbot answers (about $0.90 a run). It skips draft pull requests, so work as a draft and mark it ready for review to run it once. It can also be started by hand (Actions > Eval gate > Run workflow).
  184. ## Project status
  185. | Phase | What | Status |
  186. |---|---|---|
  187. | 0 | Setup and data source spike | done |
  188. | 1 | Ingestion: bronze / silver / gold | done |
  189. | 2 | RAG + tools + chat loop | done |
  190. | 3 | Evals dataset | done |
  191. | 4 | API + React UI + structured citations | done |
  192. | 5 | Weekly summaries (GitHub Pages) + own MCP server | done |
  193. | 6 | AI Ops: tracing, eval gate, dashboard, feedback loop | done |
  194. | 7 | Clean-up and documentation | done |
  195. The data comes from the public JSON feeds that premierleague.com itself uses ([docs/data_sources.md](docs/data_sources.md)). This is a personal, non-commercial project, not affiliated with the Premier League. Code: [MIT license](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.