Skip to content

README.md

Latest commit

 

History

History
199 lines (155 loc) · 4.94 KB

README.md

File metadata and controls

199 lines (155 loc) · 4.94 KB

TransformerPredictionModel

Project to predict sports player performance outcomes using complex ML modeling.

🚀 Quick Start

Prerequisites

  • Python 3.12+
  • uv (Python package manager)
  • just (command runner)
  • Rust/Cargo (for Rust components)
  • Git

Install prerequisites on macOS:

Option 1: Homebrew (recommended)

brew install uv just rust

Option 2: Official installers

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install just and rust via Homebrew
brew install just rust

Option 3: Using Rust/Cargo (alternative for just)

# Install uv via official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Rust toolchain (includes cargo)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install just via cargo
cargo install just

Installation

  1. Clone the repository

    git clone https://github.com/JonathanPLev/TransformerPredictionModel.git
cd TransformerPredictionModel

  2. Set up Python environment

    # Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --dev

  3. Verify installation

    # Check available commands
just --list

# Run linting and tests
just check-all

🛠️ Development

Available Commands

Use just <command> to run these tasks:

Python Development

  • just lint-python - Lint Python code with Ruff
  • just fix-python - Auto-fix Python issues
  • just format-python - Format Python code
  • just type-check - Run MyPy type checking

Testing

  • just test - Run pytest tests
  • just test-cov - Run tests with coverage
  • just coverage-report - Generate HTML coverage report

Other Languages

  • just lint-yaml - Lint YAML files
  • just lint-json - Lint JSON files
  • just lint-rust - Lint Rust code (if applicable)
  • just format-rust - Format Rust code

Convenience Commands

  • just lint-all - Run all linting tasks
  • just format-all - Run all formatting tasks
  • just check-all - Run all checks (lint + type check)
  • just test-all - Run tests + all checks
  • just clean - Clean Python cache files

Development Workflow

  1. Create a feature branch

    git checkout -b feat/your-feature-name

  2. Make your changes and test

    # Sync dependencies if you added any
uv sync --dev

# Run checks locally
just check-all
just test-cov

  3. Commit with conventional format

    git add .
git commit -m "feat: add new prediction model"

  4. Push and create PR

    git push origin feat/your-feature-name
# Create PR on GitHub

Commit Convention

This project follows Conventional Commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • style: - Code style changes
  • refactor: - Code refactoring
  • perf: - Performance improvements
  • test: - Test additions/modifications
  • chore: - Maintenance tasks

🏗️ Project Structure

TransformerPredictionModel/
├── .github/                 # GitHub workflows and templates
│   ├── workflows/          # CI/CD workflows
│   └── pull_request_template.md
├── src/                    # Source code (create as needed)
├── tests/                  # Test files (create as needed)
├── pyproject.toml         # Python project configuration
├── justfile               # Task runner commands
├── uv.lock               # Dependency lock file
└── README.md             # This file

🧪 Testing

Run tests with coverage:

just test-cov

Generate HTML coverage report:

just coverage-report
# Open htmlcov/index.html in your browser

📋 Contributing

  1. Fork the repository
  2. Create a feature branch following the naming convention: feat/description, fix/description, etc.
  3. Make your changes and ensure all checks pass locally
  4. Write tests for new functionality
  5. Submit a pull request with a clear description

PR Requirements

  • All CI checks must pass
  • Code owner approval required
  • Conventional commit format in PR title
  • Fill out the PR template completely

🔧 Configuration

Python Dependencies

  • Runtime: Defined in pyproject.toml under dependencies
  • Development: Defined in pyproject.toml under tool.uv.dev-dependencies

Code Quality Tools

  • Linting: Ruff
  • Type Checking: MyPy
  • Testing: Pytest with coverage
  • YAML Linting: yamllint

🤝 Support

For questions or issues, please:

  1. Check existing Issues
  2. Create a new issue with detailed information
  3. Follow the issue template guidelines