{"id":28383546,"url":"https://github.com/thchilly/blackjack-card-counting","last_synced_at":"2025-10-10T03:17:13.504Z","repository":{"id":296133417,"uuid":"991257489","full_name":"thchilly/blackjack-card-counting","owner":"thchilly","description":"Optimal Black Jack policy that also attempts to use card counting to beat the dealer using Reinforcement Learning techniques","archived":false,"fork":false,"pushed_at":"2025-05-29T04:51:50.000Z","size":17408,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T13:48:05.115Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thchilly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-27T11:06:17.000Z","updated_at":"2025-05-29T04:51:53.000Z","dependencies_parsed_at":"2025-05-29T05:42:54.340Z","dependency_job_id":null,"html_url":"https://github.com/thchilly/blackjack-card-counting","commit_stats":null,"previous_names":["thchilly/blackjack-card-counting"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thchilly/blackjack-card-counting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thchilly%2Fblackjack-card-counting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thchilly%2Fblackjack-card-counting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thchilly%2Fblackjack-card-counting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thchilly%2Fblackjack-card-counting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thchilly","download_url":"https://codeload.github.com/thchilly/blackjack-card-counting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thchilly%2Fblackjack-card-counting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002554,"owners_count":26083418,"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-10T02:00:06.843Z","response_time":62,"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":[],"created_at":"2025-05-30T05:44:44.883Z","updated_at":"2025-10-10T03:17:13.499Z","avatar_url":"https://github.com/thchilly.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blackjack Card Counting - RL Project\n\nA comprehensive Python framework for Blackjack, combining environment simulation, model-based benchmarks, model-free learning, card-counting, and a user-friendly GUI:\n\n- **Custom Environment**  \n  A custom `BlackjackEnv` implementation: supports multiple decks, reshuffling, natural-pay rules (3:2), ace handling, and a running Hi–Lo count.\n\n- **Model-Based Ground Truth**  \n  Exact MDP solutions via Value Iteration and Policy Iteration under infinite-deck assumptions, yielding the canonical “basic strategy” hit/stand policy.\n\n- **Model-Free Baseline**  \n  Tabular Q-Learning recovers the optimal hit/stand policy from scratch, using linearly decaying learning and exploration rates.\n\n- **Card-Counting Extension**  \n  Augments the Q-Learning state with a simple Hi–Lo running count (Low/Neutral/High bins) to adapt play decisions based on shoe composition.\n\n- **Graphical Interface**  \n  A Tkinter-based GUI for human play: choose decks, view dealer upcard and remaining cards, track session stats, and play via Hit/Stay buttons.\n\n- **Experiments \u0026 Visualization**  \n  Jupyter notebook with training scripts, learning curves, win-rate comparisons, and policy heatmaps for both baseline and counting agents.\n\n- **Full Report (PDF)**  \n  Detailed write-up of methodology, experiments, and results in `report/Blackjack_Card_Counting_Phase1.pdf`.\n\n\n\n## Project Structure\n\n```text\nblackjack/\n├── agents/\n│   ├── q_learning_agent.py\n│   └── value_iteration.py\n├── envs/\n│   ├── blackjack_env.py\n│   └── blackjack_env1.py\n├── gui/\n│   └── simple_gui.py\n├── materials/\n│   └── playing-cards-master/\n├── notebooks/\n│   └── experiments.ipynb\n├── figures/\n├── test_env.py\n├── requirements.txt\n└── README.md\n```\n\n## Installation\n\n1. **Clone** this repo  \n   ```bash\n   git clone https://github.com/yourusername/blackjack.git\n   cd blackjack\n   ```\n\n2. **Create and Activate** a virtual-env (optional but recommended)\n     ```bash\n     python3 -m venv .venv\n     source .venv/bin/activate   # Mac/Linux\n     .venv\\Scripts\\activate      # Windows\n     ```\n\n4. **Install** dependencies\n      ```bash\n      pip install -r requirements.txt\n      ```\n      \n## Smoke Test\nRun a quick environment sanity check:\n    ```bash\n    python test_env.py\n    ```\n\n## Launch the GUI\n  ```bash\n  python -m gui.simple gui\n  ```\n\n* Enter number of decks (1–8).\n* Use the 👊 Hit, ✋ Stay, and 🔄 New Game buttons.\n* Watch session stats \u0026 remaining cards update in real time.\n\n## Jupyter Experiments and Analysis\nAll RL training \u0026 evaluation code is in:\n  ```bash\n  notebooks/experiments.ipynb\n  ```\n\nLaunch with:\n  ```bash\njupyter lab notebooks/experiments.ipynb\n  ```\n\n\n\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthchilly%2Fblackjack-card-counting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthchilly%2Fblackjack-card-counting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthchilly%2Fblackjack-card-counting/lists"}