{"id":18223925,"url":"https://github.com/thg-muc/tip-genius","last_synced_at":"2025-10-29T04:30:25.838Z","repository":{"id":260966123,"uuid":"882841371","full_name":"thg-muc/tip-genius","owner":"thg-muc","description":"AI-powered soccer match prediction tool that leverages LLMs and odds data to generate informed predictions with a clean, modern web interface.","archived":false,"fork":false,"pushed_at":"2025-10-26T09:29:13.000Z","size":19996,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-26T11:26:25.827Z","etag":null,"topics":["ai","html","javascript","llm","predictions","python","soccer","vercel"],"latest_commit_sha":null,"homepage":"https://tip-genius.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thg-muc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-03T22:18:38.000Z","updated_at":"2025-10-26T09:28:58.000Z","dependencies_parsed_at":"2024-12-29T11:24:13.138Z","dependency_job_id":"5c69c82e-fe1f-4b2b-91f8-b8cbc6c923a9","html_url":"https://github.com/thg-muc/tip-genius","commit_stats":null,"previous_names":["thg-muc/tip-genius"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thg-muc/tip-genius","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thg-muc%2Ftip-genius","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thg-muc%2Ftip-genius/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thg-muc%2Ftip-genius/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thg-muc%2Ftip-genius/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thg-muc","download_url":"https://codeload.github.com/thg-muc/tip-genius/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thg-muc%2Ftip-genius/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281562510,"owners_count":26522685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","html","javascript","llm","predictions","python","soccer","vercel"],"created_at":"2024-11-04T01:05:28.514Z","updated_at":"2025-10-29T04:30:25.820Z","avatar_url":"https://github.com/thg-muc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚽️ Tip Genius V3.0.0\n\nAI-powered soccer match predictions with a modern, responsive web interface.\n\n## Overview\n\nTip Genius combines the power of Large Language Models (LLMs) with real-world odds data to generate informed soccer match predictions. The project features a clean, responsive web interface that displays predictions for various soccer leagues including the Premier League, Bundesliga, La Liga and UEFA Champions League.\n\n![Tip Genius iOS PWA](/.github/assets/screenshot_ios_pwa.png)\n\n`Mobile Progressive Web App running on iOS (showing dark mode / predictions / LLM picker)`\n\n## LLM Integration\n\nTip Genius leverages LLMs to generate match predictions by analyzing odds data and applying domain knowledge. The project uses a lightweight approach with direct API calls instead of individual LLM libraries, minimizing dependencies while maintaining robust performance. This approach ensures sustainable operation while delivering quality predictions.\n\nSo far, the following LLM models have been successfully tested with Tip Genius:\n\n- **Mistral Medium 3** (Free API available)\n- **Google Gemini 2.5 Flash** (Free API available)\n- **DeepSeek Chat**\n- **OpenAI GPT-5 Mini**\n- **Meta Llama 4 Maverick** (via DeepInfra)\n- **Microsoft Phi-4** (via DeepInfra)\n- **xAI Grok 3 Mini** (via OpenRouter)\n\nIssues with some LLMs:\n\n- Anthropic Claude (does not have a native JSON mode yet, sometimes struggles to generate valid prediction output)\n\n## Features\n\n- 🎯 Match predictions using advanced LLMs\n- 🌐 Clean, responsive web interface with dark mode support\n- 📊 Real-time odds data integration\n- 🎮 Team logo integration with fuzzy name matching\n- ⚡️ Fast, serverless architecture using Vercel\n- 📱 Mobile-friendly design with PWA support\n- 🎨 Modern UI with Tailwind CSS\n- 🔄 Automated prediction updates via GitHub Actions\n- 💾 Efficient data storage using Vercel KV (Redis)\n- 🔢 Build-time version generation for deployment tracking\n\n## Tech Stack\n\n### Frontend\n\n- HTML5 with semantic markup\n- Vanilla JavaScript\n- Tailwind CSS for styling\n- Service Workers for Progressive Web App (PWA) functionality\n- Smart image caching and preloading system\n\n### Backend\n\n- Python 3.12+ for prediction generation\n- Lightweight LLM integration via direct API calls (no heavy LLM libraries required)\n- Fuzzy team name matching for logo association\n- GitHub Actions for automation\n\n### Infrastructure\n\n- Vercel for hosting and serverless functions\n- Vercel KV Store for data persistence\n- GitHub for version control and CI/CD\n\n### Dependencies\n\nThe project intentionally maintains minimal dependencies:\n\n- `polars`: Fast, parallel data processing\n- `PyYAML`: Configuration management\n- `requests`: HTTP client for API calls (instead of heavier LLM libraries)\n- `python-slugify`: Consistent string normalization\n\nThis lightweight approach ensures:\n\n- Easier updates and maintenance\n- Faster deployment\n- Better performance\n\n## Development Tools\n\nThe project uses modern Python and frontend development tools for code quality and consistency:\n\n### Python Development\n\n- **uv**: Ultra-fast Python package manager replacing pip/conda\n- **ruff**: Fast Python linter and formatter (replaces black, isort, pylint)\n- **pyright**: Static type checker with standard strictness mode\n- **pre-commit**: Git hooks for automated quality checks\n\n### Frontend Development\n\n- **prettier**: Code formatter for JavaScript, CSS, JSON, and YAML files\n- **Tailwind CSS**: Utility-first CSS framework for styling\n\n### Quality Assurance\n\n- **Pre-commit hooks**: Automated checks for:\n  - Python linting and formatting (ruff)\n  - Type checking (pyright)\n  - Frontend formatting (prettier)\n  - Conventional commit message validation\n  - File quality checks (trailing whitespace, YAML syntax)\n\n### Development Commands\n\n```bash\n# Install dependencies\nuv sync\n\n# Install development dependencies\nuv sync --group dev\n\n# Run Python linting and formatting\nuv run ruff check --fix src/\nuv run ruff format src/\n\n# Run type checking\nuv run pyright src/\n\n# Format frontend files\nnpx prettier --write \"public/**/*.{js,css,json}\"\n\n# Install pre-commit hooks\nuv run pre-commit install\nuv run pre-commit install --hook-type commit-msg\n```\n\n## Vercel Setup\n\nTip Genius is designed to run completely on Vercel's free tier:\n\n1. **Project Configuration**:\n   - Create a new project in Vercel and link to your GitHub repository\n   - Set up a Vercel KV store (Redis) for data persistence\n   - Configure all environment variables in project settings\n\n2. **CI/CD Pipeline**:\n   - Automatic deployments triggered by GitHub push events\n   - Preview deployments for pull requests\n   - GitHub Actions handle prediction generation while Vercel manages deployment\n\n3. **Monitoring**:\n   - Access request logs and performance metrics in Vercel dashboard\n   - Web Analytics available in free tier\n\n## Local Development\n\n### Prerequisites\n\n- Python 3.12 or higher\n- Vercel CLI\n- Node.js and npm (latest LTS version)\n- Vercel account and KV store setup\n\n### Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/thg-muc/tip-genius.git\n   cd tip-genius\n   ```\n\n2. Set up Python environment using uv:\n\n   ```bash\n   # Install uv (fast Python package manager)\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # Install project dependencies\n   uv sync\n   ```\n\n3. Install Vercel CLI and login:\n\n   ```bash\n   npm i -g vercel\n   vercel login\n   ```\n\n4. Configure environment variables:\n\n   Create a `.env.local` file in the project root with the following variables:\n\n   ```bash\n   # API Keys for Odds Data\n   ODDS_API_KEY=your_odds_api_key\n\n   # API Keys for LLM Providers\n   ANTHROPIC_API_KEY=your_anthropic_api_key\n   DEEPINFRA_API_KEY=your_deepinfra_api_key\n   DEEPSEEK_API_KEY=your_deepseek_api_key\n   GOOGLE_API_KEY=your_google_api_key\n   MISTRAL_API_KEY=your_mistral_api_key\n   OPENAI_API_KEY=your_openai_api_key\n   OPENROUTER_API_KEY=your_openrouter_api_key\n\n   # Vercel KV (Redis) Configuration\n   KV_REST_API_TOKEN=your_vercel_kv_token\n   KV_REST_API_URL=your_vercel_kv_url\n   KV_REST_API_READ_ONLY_TOKEN=your_vercel_kv_readonly_token\n   KV_DEFAULT_KEY=Match_Predictions_Mistral-Medium_FourPointsScoring_named_with-info\n\n   # Debug Options (Optional)\n   DEBUG_MODE=TRUE\n   DEBUG_LOG_FILE=TRUE\n   DEBUG_LOG_DIR=logs\n   ```\n\n   For deployment, these variables should be added to Github Secrets and Vercel Environment Variables.\n\n### Running Locally\n\n1. Start the development server:\n\n   ```bash\n   vercel dev\n   ```\n\n2. Open \u003chttp://localhost:3000\u003e in your browser\n\n## Credits\n\n- Team logos originally sourced from [football-logos](https://github.com/luukhopman/football-logos) (thanks for your great work 👍🏻)\n- The `utils/process_team_logos.py` script can be used to automatically download and standardize all team logos from the repository\n\n## License\n\nThis project is licensed under the **MIT License with Commons Clause**. Free for personal, educational, and research use. Commercial use requires permission.\n\nSee the [LICENSE](LICENSE) file for complete terms.\n\n## Links\n\n- [Live Website](https://tip-genius.vercel.app)\n- [GitHub Repository](https://github.com/thg-muc/tip-genius)\n- [Author's LinkedIn](http://linkedin.com/in/thomas-glanzer)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthg-muc%2Ftip-genius","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthg-muc%2Ftip-genius","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthg-muc%2Ftip-genius/lists"}