Skip to main content

​
Quick Start Guide

This guide will help you set up OddsEngine and run your first probability calculation in just a few minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed
  • Python 3.10 or higher installed
  • Git for cloning the repository
  • At least 4GB of available RAM for Oracle Database
If you need detailed installation instructions for these prerequisites, see the Installation Guide.

​
Getting Started

1

Clone the Repository

Clone the OddsEngine repository to your local machine:
git clone https://github.com/puj-course/FIS_2610_3517_G2.git
cd FIS_2610_3517_G2
2

Configure Environment Variables

Create a .env file in the project root with your configuration:
# API Configuration
API_TENNIS_KEY=your_api_key_here
API_TENNIS_BASE_URL=https://api-tennis.com/v1

# Database Configuration
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE=XEPDB1
ORACLE_USER=oddsengine
ORACLE_PASSWORD=your_secure_password

# Application Configuration
LOG_LEVEL=INFO
Sign up for a free API key at api-tennis.com - you get 1,000 requests per month on the free tier.
3

Start Docker Services

Launch the Oracle Database and other required services using Docker Compose:
docker-compose up -d
Wait for the database to initialize (this may take 1-2 minutes on first run):
docker-compose logs -f db
Look for the message: DATABASE IS READY TO USE!
4

Install Python Dependencies

Create a virtual environment and install dependencies:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
5

Initialize the Database

Run the database migration scripts to set up the schema:
python scripts/setup.sh
This will create the necessary tables for players, matches, and probability calculations.
6

Launch the Application

Start the OddsEngine desktop application:
python src/main/python/app.py
The PyQt interface will open, showing the main dashboard.

​
Your First Probability Calculation

Now that OddsEngine is running, let’s calculate the probability of a simple bet:
1

Fetch Match Data

In the OddsEngine interface:
  1. Navigate to Data Sync → Fetch Matches
  2. Select a date range (e.g., upcoming week)
  3. Choose tournament filter (ATP/WTA or both)
  4. Click Sync Data
The system will fetch match data from API-Tennis and populate your local database.
2

View Available Matches

Go to the Matches tab to see the list of upcoming tennis matches with:
  • Player names and rankings
  • Tournament information
  • Surface type (clay, grass, hard court)
  • Historical head-to-head records
3

Calculate Single Match Probability

Select a match and click Analyze. OddsEngine will:
  1. Load player statistics (win rate, surface performance)
  2. Apply probabilistic models using Pandas
  3. Calculate the estimated probability for each outcome
  4. Display the results with confidence intervals
# Example output
Match: Djokovic vs. Alcaraz
Surface: Hard Court

Djokovic Win Probability: 58.3% (±4.2%)
Alcaraz Win Probability: 41.7% (±4.2%)

Model Confidence: High
Based on: 127 data points
4

Create a Combined Bet (Parlay)

To calculate combined probabilities:
  1. Navigate to Parlays → New Parlay
  2. Add 2-5 matches to your combination
  3. Select your predicted outcome for each match
  4. Click Calculate Combined Probability
OddsEngine will multiply the individual probabilities and show:
  • Overall parlay success probability
  • Expected value analysis
  • Risk assessment
Combined probabilities assume statistical independence between matches. The system will warn you if matches involve the same players or have other dependencies.

​
Understanding the Results

OddsEngine provides several metrics for each calculation:
  • Win Probability: Statistical likelihood of the outcome (0-100%)
  • Confidence Interval: Margin of error based on data quality
  • Model Confidence: High/Medium/Low based on available data points
  • Expected Value: Whether the bet offers positive expected value
OddsEngine provides analytical tools for educational and research purposes. Probabilities are estimates based on historical data and statistical models. Always bet responsibly.

​
Fallback Mode

If the API-Tennis service is unavailable or you’ve exceeded your rate limit, OddsEngine automatically switches to mock data mode: 
⚠️  API-Tennis unavailable - switching to mock data provider
✓  Mock data loaded: 50 matches from cache
This allows you to continue testing and development without interruption.

​
Next Steps

Explore Jupyter Notebooks

Check out jupyter/notebooks/ for data exploration and custom analysis

Customize Models

Modify probability models in src/main/python/models/ to fit your strategy

API Integration

Learn how to extend the API client for additional data sources

Read Full Documentation

Visit the Installation Guide for advanced configuration

​
Troubleshooting

Database connection fails?
  • Ensure Docker containers are running: docker-compose ps
  • Check logs: docker-compose logs db
  • Verify credentials in .env file
API rate limit exceeded?
  • OddsEngine automatically switches to mock data
  • Wait until next month for rate limit reset
  • Consider caching more data locally
PyQt interface doesn’t launch?
  • Verify Python version: python --version (must be 3.10+)
  • Check PyQt installation: pip list | grep PyQt
  • Review logs in temp/application.log
For more help, check the GitHub Issues or consult the full Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us