YAML Metadata Warning:empty or missing yaml metadata in repo card
Check out the documentation for more information.
AI Football Journalist
An autonomous football journalist that turns real ESPN match data into professional match reports — then checks its own work before showing you the result.
Pick a competition, load a recent game, choose what kind of article you want, and the agent handles the rest: fetching the data, building context, writing the piece, and running a second-pass evaluation so you can see what it got right (or wrong).
Everything lives in AIFJ.ipynb. Open it, run the cells, and use the Gradio interface in your browser.
What it does
The agent pulls completed matches from ESPN and builds a structured picture of the game — scores, goals, cards, substitutions, and whatever competition context applies.
From there, a Groq LLM writes the article in a BBC Sport / ESPN style. A second Groq call acts as an editor: it compares the article against the source data and gives you pass/fail scores plus a written summary explaining the verdict.
You get two outputs in the UI:
- Generated Article — the full match report
- Evaluation Report — pass/fail per category, a summary paragraph, and any issues found
The evaluator is meant to catch real factual mistakes (wrong score, invented goal scorer, made-up stats), not punish good writing. A 1-1 draw where one team wins on penalties? Fine, as long as the article says both things correctly.
Competitions supported
Big 5 Leagues — Premier League, La Liga, Serie A, Bundesliga, Ligue 1
League table positions are pulled in so the article can mention where each team stands and what the result means.
European Tournaments — UEFA Champions League
Knockout ties get aggregate context where two legs exist. Finals and single-leg games are handled too — including penalty shootouts.
World Cup — FIFA World Cup Group Stage
Live group standings are fetched so the article can talk about points, goal difference, and what the result means for qualification. Group-stage stakes (top two advance, best third-placed teams, tiebreakers) are baked into the writing prompt.
Article focus options
You can steer what kind of piece gets written:
- Full Match Report
- Star Player Performance
- Key Match Moments
- Tactical Analysis
- Timeline Summary
- Short News Summary
How to run it
1. Install dependencies
pip install requests trafilatura beautifulsoup4 langchain langgraph groq gradio
2. Open AIFJ.ipynb and run all cells
You'll be prompted for a Groq API key the first time. Get one at console.groq.com.
3. Use the Gradio UI
- Choose a Competition Category (Big 5 Leagues, European Tournaments, or World Cup)
- Click Load Latest 4 Completed Matches
- Pick a match from the dropdown
- Select an Article Focus
- Click Generate Article
The article appears first. The evaluation report shows directly underneath — pass/fail lines, then a summary paragraph explaining why each check passed or failed.
How the pipeline works
Behind the scenes, data flows like this:
ESPN API → Match Context → Groq Article → LLM Evaluator → Gradio
LangGraph defines the full agent flow (league selection, match loading, context building, generation, evaluation). The Gradio UI runs the same logic when you click Generate.
Context building adapts to the competition:
- League games — table positions for both teams
- Champions League knockouts — aggregate scores and who advanced
- World Cup group stage — group standings and qualification implications
Standout players are detected from goal events and passed into the article prompt.
What the evaluator checks
| Check | What it's looking for |
|---|---|
| Factual correctness | Teams, result, and core facts match the source data |
| Hallucination check | No invented players, goals, or standings |
| Score consistency | Full-time score is right; penalties/aggregate treated separately |
| Event consistency | Goals and key moments broadly match the source |
| Focus compliance | Article matches the focus you selected |
| Writing quality | Rated poor / fair / good / excellent (doesn't affect pass/fail) |
When World Cup group stage matches are involved, it also checks that group-stage context is handled reasonably — not that every stat is quoted verbatim.
Every evaluation includes a summary paragraph walking through the verdict, even when everything passes.
Tech stack
Python, Gradio, Groq (llama-3.3-70b-versatile), LangGraph, LangChain, and the public ESPN soccer API.
Project structure
FDJA/
├── AIFJ.ipynb # Full application (data, agent, UI)
├── README.md # This file
└── Autonomous Football Journalist Agent.pdf # Original project proposal