System Requirements Document (SRD)

1. Introduction

This document outlines the requirements for developing a horse race prediction system. The system will leverage automated data scraping, custom machine learning models, and a web portal to predict outcomes of horse races. It will also include functionality to compare predictions with actual race results for performance evaluation. The system will incorporate all relevant features such as horse performance, track conditions, jockey stats, and related factors to maximize prediction accuracy. Additionally, it will implement two predictive modeling approaches: independent horse-based prediction and race-level competitive inference. The system will address challenges such as class imbalance and edge cases in the data, and utilize cross-validation for robust model evaluation. Automated data scraping will be implemented to gather training data, prediction data, and race results for continuous model improvement and evaluation. The scraping system will include retries, alerts, validation mechanisms, and error logging to ensure reliability and accuracy. Error details will be logged in a file stored on S3, following best practices for service usage. Simulations of retries and alert triggers will be conducted during testing to ensure robustness.

2. System Overview

The horse race prediction system aims to provide accurate predictions for upcoming horse races using historical race data and relevant features. The system will scrape data from Racing Australia to gather training data, prediction data, and race results. It will train custom predictive models using two distinct approaches and display results through an intuitive web portal. The portal will allow users to view predictions, compare them with actual results, and analyze model performance over time. The system will also provide insights into the factors influencing predictions, enabling users to understand the model's decision-making process. The system will incorporate best practices for handling class imbalance and edge cases in the data, ensuring reliable predictions. Cross-validation will be used to evaluate model performance, and the system will continuously update its training data and predictions through automated scraping. The scraping system will include retries, alerts, validation mechanisms, and error logging to handle potential failures and ensure data integrity. Simulations of retries and alert triggers will be conducted during testing to ensure the system is robust and reliable. Error logs will be stored in a file on S3 for easier debugging and troubleshooting.

3. Functional Requirements as Story Points

• As a User, I should be able to scrape horse race data from Racing Australia for training the predictive model.
• As a User, I should be able to scrape race results after each race to compare them with model predictions and evaluate model performance.
• As a User, I should be able to scrape prediction data for upcoming races to perform inferencing before the races occur.
• As a User, I should be able to include relevant features such as horse performance, track conditions, jockey stats, and other related factors in the predictive model.
• As a User, I should be able to train two predictive models:
  • One that predicts outcomes based on each horse and its related features independently.
  • Another that predicts outcomes by considering all horses in a race collectively to understand competitiveness and infer results.
• As a User, I should be able to predict outcomes for upcoming horse races using both models.
• As a User, I should be able to view predictions and comparison results through an intuitive web portal.
• As a User, I should be able to analyze model performance over time using visualizations and metrics.
• As a User, I should be able to view insights into the factors influencing predictions for better understanding and transparency.
• As a User, I should be able to evaluate the predictive models using cross-validation to ensure reliability.
• As a User, I should be able to address class imbalance and edge cases in the data during model training and evaluation.
• As a User, I should be able to rely on retries, alerts, and validation mechanisms in the automated scraping system to ensure data integrity and handle failures.

• As a User, I should be able to log error details in a file stored on S3 for easier debugging and troubleshooting.
• As a User, I should be able to simulate retries and alert triggers during testing to ensure the system is robust and reliable.

4. User Personas

1. Race Analyst

• Interested in analyzing horse race predictions and comparing them with actual results.
• Requires detailed insights into model performance, accuracy, and influencing factors.

2. Data Scientist

• Focused on improving the predictive models using historical data, performance metrics, and feature importance analysis.
• Requires access to raw data, model training logs, evaluation metrics, and insights into feature contributions.
• Needs tools to handle class imbalance and edge cases in the data effectively.

3. General User

• Interested in viewing predictions for upcoming races and understanding the influencing factors.
• Requires a simple and intuitive interface to access predictions, results, and insights.

4. System Administrator

• Responsible for maintaining the system, ensuring data scraping processes are running smoothly, and monitoring system performance.
• Requires tools to manage scraping schedules, monitor data pipelines, troubleshoot issues, and handle retries or alerts in case of scraping failures.
• Needs access to error logs stored on S3 for debugging and troubleshooting.
• Requires simulations of retries and alert triggers during testing to ensure system reliability.

5. Visuals Colors and Theme

The web portal will adopt a professional and intuitive design with the following color scheme:

• Primary Color: Royal Blue (#4169E1) - Represents trust and reliability.
• Secondary Color: Gold (#FFD700) - Symbolizes success and achievement.
• Background Color: White (#FFFFFF) - Ensures clarity and readability.
• Accent Color: Dark Green (#006400) - Represents growth and performance.

The theme will focus on simplicity and ease of use, with clean layouts and interactive visualizations. Graphs and charts will use contrasting colors for better readability, and the portal will feature a modern design with responsive elements. The interface will include clear navigation menus, interactive dashboards, and intuitive controls for accessing predictions, results, and insights.

6. Non-Functional Requirements

• The system should be able to handle large volumes of historical race data efficiently.
• The web portal should be responsive and accessible across devices (desktop, tablet, mobile).
• The predictive models should provide results within a reasonable timeframe (less than 5 seconds per prediction).
• The system should ensure data security and comply with relevant data privacy regulations.
• The portal should support concurrent users without performance degradation.
• The system should provide clear and interpretable insights into the factors influencing predictions.
• The system should allow users to switch between the two predictive models seamlessly.
• The system should implement cross-validation for robust model evaluation.
• The system should address class imbalance and edge cases in the data to ensure reliable predictions.
• The system should automate data scraping for training data, prediction data, and race results to ensure continuous updates.
• The automated scraping system should include retries, alerts, and validation mechanisms to handle failures and ensure data integrity.
• The system should log error details in a file stored on S3 for debugging and troubleshooting, following best practices for service usage.
• The system should simulate retries and alert triggers during testing to ensure robustness.

7. Tech Stack

Frontend

• React for web portal development.

Backend

• Python for data processing and model training.
• FastAPI for building APIs to serve predictions, results, and insights.

Database

• MySQL or MariaDB for storing historical race data, results, and model performance metrics.
• MongoDB for storing unstructured data, such as scraped raw data.

AI Tools

• Langchain for connecting and managing workflows.
• Litellm for routing tasks efficiently.

Local Orchestration

• Docker and docker-compose for containerization.

Server-Side Orchestration

• Kubernetes for managing server-side deployments.

Cloud Storage

• Amazon S3 for storing error logs and other relevant files.

8. Assumptions and Constraints

Assumptions

• Historical race data is available and accessible from Racing Australia.
• The system will primarily target horse races in Australia.
• Users will have internet access to use the web portal.
• Relevant features such as horse performance, track conditions, jockey stats, and other factors can be extracted and processed effectively.
• Cross-validation will provide reliable evaluation of model performance.
• Automated scraping processes will reliably gather training data, prediction data, and race results.
• The scraping system will include retries, alerts, validation mechanisms, and error logging to ensure reliability.
• Simulations of retries and alert triggers will ensure the system is robust during testing.

Constraints

• Scraping data from external websites must comply with their terms of service.
• The predictive models' accuracy depends on the quality and quantity of historical data and feature engineering.
• The system must operate within the limits of available computational resources.
• The system must ensure compliance with data privacy regulations when handling user data.
• Addressing class imbalance and edge cases may require additional computational resources and time.
• Automated scraping processes must be robust and handle potential changes in website structure.
• The scraping system must handle failures gracefully and provide alerts for troubleshooting.
• Error logs must be stored securely on S3 and follow best practices for service usage.

9. Glossary

• Data Scraping: The process of extracting data from websites.
• Predictive Model: A machine learning model used to predict outcomes based on input data.
• Race Results: The actual outcomes of horse races.
• Web Portal: An online platform for users to interact with the system.