Noir Blackjack

Browser-based blackjack with Hi-Lo card counting, basic strategy, and Monte Carlo EV analysis. Python FastAPI backend, vanilla JS frontend.

Features

• 1-8 deck shoe (configurable via dropdown)
• Hi-Lo card counting with running/true count display
• Basic strategy with Hi-Lo deviations (Illustrious 18)
• 1/4 Kelly betting for optimal bankroll management
• Monte Carlo simulation (5000 hands) for action recommendations
• Session analytics with true count correlation and shoe depth tracking
• Console simulators for batch testing and analysis

Quick Start

git clone https://github.com/your-username/noir-blackjack.git
cd noir-blackjack
pip install -r requirements.txt
python3 -m uvicorn backend.main:app --reload --port 8000

Open http://localhost:8000

Game Rules

Rule	Value
Decks	1-8 (selectable)
Dealer	Stands on soft 17
Blackjack	3:2 payout
Insurance	No
Surrender	No
DAS	No
Resplit	No
Cut card	75% penetration

Controls

Button	Action
Hit	Draw one card
Stand	Keep total, dealer plays
Double	Double bet, one card, turn ends
Split	Split pair into two hands (extra bet)
Counter	Toggle Hi-Lo counter panel
Algorithm	Toggle Monte Carlo recommendation panel
Continue	Next hand (same shoe/bankroll)
New Shoe	Reshuffle, reset count
Reset	New shoe + $1000 bankroll

Card Counter

Running count, true count, per-rank remaining cards with probability bars.

Algorithm Panel

Monte Carlo simulation shows:

• Recommended action
• Per-action EV with std deviation
• Dealer outcome distribution
• Edge/Kelly analysis
• Session stats

Console Simulator

Run batch simulations from the terminal:

# Algorithm (basic strategy + Hi-Lo + Kelly)
python3 -m console.algo_runner --hands 5000 --decks 6

# Flat-bet baseline (no counting)
python3 -m console.dumb_runner --hands 5000 --decks 6 --bet 5

# Interactive manual play
python3 -m console.manual_runner --hands 100 --decks 6

# Analyze all results
python3 -m console.analyzer

Results saved to console/results/ as JSON with per-hand data.

Algorithm Details

See ALGORITHM.md for complete technical documentation:

• Hi-Lo counting system
• Basic strategy tables
• Hi-Lo deviation indices
• 1/4 Kelly criterion betting
• Simulation results (47,974 hands analyzed)
• Known limitations

Results & Analytics

47,974 hands analyzed across all methods. Noir-themed visualizations generated with Matplotlib.

Summary

Method Comparison

True Count Analysis

Cumulative Profit

Bankroll Distribution

Deck Size Performance

Hand Results

Bet Distribution

Testing

python3 -m pytest tests/ -v

62 tests covering API, game logic, counting, strategy, and Monte Carlo.

Tech Stack

• Backend: Python 3, FastAPI, Pydantic, Uvicorn
• Frontend: Vanilla JS, CSS3
• Data: NumPy, Pandas, Matplotlib
• Testing: Pytest
• Card Assets: Kenney (CC0)

Project Structure

backend/
  main.py          # FastAPI server + game logic
  models.py        # Card, Shoe, Hand, CountState
  strategy.py      # Basic strategy + deviations
  counting.py      # Hi-Lo system + Kelly criterion
  monte_carlo.py   # MC simulation (5000 rounds)

console/
  algo_runner.py   # Algorithm sessions
  dumb_runner.py   # Flat-bet baseline
  manual_runner.py # Interactive play
  analyzer.py      # Statistics + graphs
  data_collector.py # JSON format

frontend/
  index.html       # Main UI
  style.css        # Noir theme
  app.js           # Game logic

cards/             # Card sprite assets
tests/             # 62 tests

License

Card assets by Kenney (CC0). Code: MIT.