AIFJ

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:

1. Generated Article — the full match report
2. 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

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