Football Stat Analytics

Football Stat Analytics is a command-line application that analyzes football athlete performance with AI. It indexes scouting reports, answers questions grounded in those reports and offers an interactive chat with analyst personas. It is an academic project.

Language models readily produce statements that sound right but have no support: invented numbers, actions the data never mentioned and flattering adjectives. In sports analysis that is worse than no answer. The challenge was to keep every answer tied to the evidence the user supplies or to the reports that were indexed.

Answers pass through layers of checking. Deterministic rules enforce the output format and reject unsupported numbers and wording. A semantic verifier, a second model that must quote the evidence, judges each statement. A failed answer gets one automatic correction attempt, and answers based on reports end with a grounding report showing what could be traced back to the retrieved excerpts.

The application is written in TypeScript on Node.js, using native type stripping and the built-in SQLite module. Ingestion extracts text from PDF reports, translates it, splits it into chunks, generates embeddings with the OpenAI API and stores them in SQLite. Retrieval ranks chunks by a hybrid score that combines embedding similarity and keyword overlap, and sends the five best to the answer prompt. The chat keeps its session history in SQLite and summarizes older messages when the context grows. The code separates AI behavior (personas, policies, validation and verification) from storage and retrieval, and 109 automated tests cover it with stubbed model calls, so they run without an API key.

• Rules in code, not only in prompts.

  Prompt instructions alone cannot guarantee that the model follows a policy, so the most important rules are checked by code.

• A judge that is not trusted blindly.

  The verifier must quote the evidence, and a quote that is not in the evidence is rejected. If the verifier itself fails, the chat keeps working and shows a warning.

• Optional consensus, off by default.

  Answering with the median of three samples costs three times the generation and did not make the scores reliably stable, so it is available but disabled.

• Simple local storage.

  Conversation history and embeddings live in SQLite files, which keeps the project easy to run and inspect.

In development. The project describes itself as experimental: answers are not checked against official statistics, PDF ingestion does not run OCR, and the checks are safeguards that do not replace human review. A known limitation is retrieval: the index has no athlete metadata to filter on, so a question about one athlete can retrieve excerpts about others.

View on GitHub (opens in a new tab)