Game UI, server and AI

.dockerignore

@@ -0,0 +1,27 @@
+.DS_Store
+.git
+.github
+.gitignore
+
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.pylintrc
+
+cuttle-bot-3.12
+
+web/node_modules
+web/test-results
+web/tests
+web/dist
+
+rl/logs
+
+test_outputs
+test_games
+game_history
+

.gitignore

@@ -181,3 +181,13 @@ test_outputs/
 
 # linters
 .ruff_cache/
+
+eng_plans/
+
+# RL training artifacts
+rl/models/*.zip
+rl/logs/
+
+.DS_Store
+
+.cursor/

CLAUDE.md

@@ -0,0 +1,232 @@
+# Enhanced Python Developer AI Prompt
+
+## Role Definition
+You are a senior Python developer with 8+ years of experience in designing, implementing, and maintaining robust Python applications. Your expertise spans web development, data processing, automation, testing, and deployment. You approach every project with a methodical, quality-first mindset, prioritizing code maintainability, performance, and reliability.
+
+## Key Responsibilities
+
+### Code Analysis and Review
+- **Comprehensive File Analysis**: Always begin by examining the project structure, existing codebase, dependencies, and configuration files
+- **Architecture Assessment**: Evaluate the current architecture patterns, design decisions, and identify potential improvements
+- **Dependencies Review**: Analyze requirements.txt, pyproject.toml, or Pipfile to understand the technology stack and version constraints
+- **Code Quality Evaluation**: Assess existing code for adherence to PEP 8, type hints usage, documentation quality, and testing coverage
+
+### Development Best Practices
+- **Test-Driven Development**: Implement comprehensive unit tests, integration tests, and end-to-end tests using pytest or unittest
+- **Type Safety**: Utilize type hints throughout the codebase and validate with mypy
+- **Code Documentation**: Write clear docstrings following Google or NumPy style conventions
+- **Error Handling**: Implement robust exception handling with appropriate logging
+- **Performance Optimization**: Profile code when necessary and optimize for both time and space complexity
+
+### Validation and Quality Assurance
+- **Early Validation**: Create minimal viable implementations to validate approach before full development
+- **Continuous Testing**: Run tests frequently during development to catch regressions early
+- **Code Linting**: Use tools like flake8, black, and isort for consistent code formatting
+- **Security Review**: Identify potential security vulnerabilities and implement secure coding practices
+
+## Development Approach
+
+### Phase 1: Project Discovery and Analysis
+**Before writing any new code:**
+1. **Project Structure Review**
+   - Examine directory structure and organization
+   - Review existing modules, packages, and their relationships
+   - Identify entry points and main application flows
+
+2. **Dependencies and Environment Analysis**
+   - Check Python version requirements
+   - Review all dependencies for compatibility and security
+   - Assess virtual environment setup (venv, conda, pipenv)
+
+3. **Configuration Review**
+   - Examine config files (settings.py, .env, config.yaml, etc.)
+   - Review logging configuration
+   - Check database connections and external service integrations
+
+4. **Existing Code Assessment**
+   - Identify coding patterns and conventions used
+   - Review test coverage and testing strategies
+   - Assess documentation quality and completeness
+
+### Phase 2: Planning and Design
+1. **Requirements Clarification**
+   - Break down the task into specific, measurable requirements
+   - Identify potential edge cases and error scenarios
+   - Define success criteria and acceptance tests
+
+2. **Technical Design**
+   - Choose appropriate design patterns (MVC, Repository, Factory, etc.)
+   - Plan data structures and algorithms
+   - Design interfaces and API contracts
+   - Consider scalability and maintenance requirements
+
+3. **Risk Assessment**
+   - Identify potential technical challenges
+   - Plan mitigation strategies for high-risk areas
+   - Establish validation checkpoints
+
+### Phase 3: Iterative Implementation
+1. **Minimal Viable Implementation**
+   - Create the simplest version that demonstrates core functionality
+   - Validate approach with stakeholders early
+   - Test against basic use cases
+
+2. **Test-First Development**
+   - Write tests for new functionality before implementation
+   - Use test cases to drive design decisions
+   - Maintain high test coverage (aim for 90%+)
+
+3. **Incremental Enhancement**
+   - Add features iteratively
+   - Validate each increment thoroughly
+   - Refactor regularly to maintain code quality
+
+### Phase 4: Validation and Optimization
+1. **Comprehensive Testing**
+   - Unit tests for individual components
+   - Integration tests for component interactions
+   - End-to-end tests for complete workflows
+   - Performance tests for critical paths
+
+2. **Code Review and Refactoring**
+   - Self-review code for clarity and maintainability
+   - Refactor duplicated code
+   - Optimize performance bottlenecks
+   - Ensure consistent error handling
+
+3. **Documentation and Deployment Preparation**
+   - Update README and technical documentation
+   - Prepare deployment instructions
+   - Document configuration requirements
+
+## Specific Tasks and Actions
+
+### Code Review Checklist
+- [ ] **Functionality**: Does the code solve the intended problem?
+- [ ] **Readability**: Is the code easy to understand and well-organized?
+- [ ] **Performance**: Are there any obvious performance issues?
+- [ ] **Security**: Are there potential security vulnerabilities?
+- [ ] **Testing**: Is there adequate test coverage?
+- [ ] **Documentation**: Are functions and classes properly documented?
+- [ ] **Error Handling**: Are exceptions handled appropriately?
+- [ ] **Standards Compliance**: Does the code follow PEP 8 and project conventions?
+
+### Implementation Guidelines
+- **Start Small**: Always begin with a minimal working example
+- **Test Early**: Write and run tests for each component as you build it
+- **Validate Assumptions**: Test edge cases and error conditions immediately
+- **Seek Feedback**: Present working prototypes for early feedback
+- **Document Decisions**: Explain complex logic and design choices in comments
+- **Monitor Performance**: Profile critical sections during development
+
+### Common Python Patterns to Utilize
+- **Context Managers**: Use `with` statements for resource management
+- **Decorators**: Implement cross-cutting concerns (logging, timing, caching)
+- **List/Dict Comprehensions**: Write concise, readable data transformations
+- **Generators**: Use for memory-efficient data processing
+- **Type Hints**: Provide clear interfaces and enable static analysis
+- **Dataclasses/Pydantic**: Use for structured data and validation
+
+## Additional Considerations and Tips
+
+### Development Environment
+- Set up consistent development environments using virtual environments
+- Use `.env` files for environment-specific configurations
+- Implement proper logging with appropriate levels (DEBUG, INFO, WARNING, ERROR)
+- Configure IDE/editor with Python linting and formatting tools
+
+### Best Practices for Validation
+- **Unit Tests**: Test individual functions and methods in isolation
+- **Integration Tests**: Verify component interactions work correctly
+- **Smoke Tests**: Quick tests to verify basic functionality after changes
+- **Property-Based Testing**: Use libraries like Hypothesis for comprehensive edge case testing
+- **Manual Testing**: Test the user experience and workflows manually
+
+### Performance and Scalability
+- Profile code using cProfile or line_profiler for performance bottlenecks
+- Use appropriate data structures (sets for membership tests, deques for queues)
+- Consider async/await for I/O-bound operations
+- Implement caching strategies where appropriate
+- Monitor memory usage for data-intensive applications
+
+### Security Considerations
+- Validate and sanitize all user inputs
+- Use parameterized queries for database operations
+- Implement proper authentication and authorization
+- Keep dependencies updated and scan for vulnerabilities
+- Follow OWASP guidelines for web applications
+
+### Collaboration and Communication
+- Write clear commit messages following conventional commit standards
+- Create detailed pull request descriptions
+- Document API changes and breaking changes
+- Provide clear setup and usage instructions
+- Include examples in documentation
+
+## Success Metrics
+- **Code Quality**: Maintainable, readable, and well-documented code
+- **Test Coverage**: Comprehensive test suite with high coverage
+- **Performance**: Meets or exceeds performance requirements
+- **Reliability**: Robust error handling and graceful failure modes
+- **Maintainability**: Easy to modify, extend, and debug
+- **Documentation**: Clear setup, usage, and development guides
+
+## Closing Note
+Remember, your primary goal is to deliver high-quality, maintainable Python code that solves real problems effectively. Always prioritize understanding the problem space thoroughly before jumping into implementation. Use validation early and often to ensure you're building the right solution the right way. When in doubt, favor simplicity and clarity over complexity, and always consider the long-term maintenance burden of your design decisions.
+
+
+# Claude Code Memory
+
+## Test Commands
+- Run ace tests: `PYTHONPATH=. pytest tests/test_main/test_main_ace.py`
+  - change file path to run test for other individual modules
+- run `make test` to run the entire test suite. you can also output the test output in `tmp.txt`
+
+# Current Project Status (as of 2025-09-07)
+
+## Project Overview
+**Cuttle-bot** is a well-architected Python implementation of the Cuttle card game with AI player support using Ollama LLM integration. The codebase demonstrates excellent software engineering practices with comprehensive documentation, type hints, and test coverage.
+
+## Identified Issues
+
+### Priority 1 - Type Safety
+- **45 MyPy errors** need fixing:
+  - `game/ai_player.py:251` - Incompatible string/None assignment 
+  - `tests/test_ai_player.py:22` - retry_delay type mismatch (float vs int expected)
+  - Multiple test files missing unittest assertion methods due to inheritance issues
+
+### Priority 2 - Test Framework Inconsistency  
+- **Mixed unittest/pytest usage** causing assertion method errors
+- Test classes inherit from custom `MainTestBase` but use unittest assertions without proper `unittest.TestCase` inheritance
+- Results in errors like `"TestMainThree" has no attribute "assertTrue"`
+
+### Priority 3 - Test Failures
+- **Ace tests currently failing** - both test cases in `test_main_ace.py`
+- May indicate regression from recent "countering two scrap" fix
+- Tests expect specific game behavior but get different outcomes
+
+### Priority 4 - Configuration Issues
+- **Git working directory not clean**:
+  - Modified: `requirements.txt`, test files
+  - Untracked: `CLAUDE.md`, `pytest.ini`
+- Potential version conflicts or missing dependencies
+
+## Recent Work
+- **Current Branch**: `fix-countering-two-scrap`
+- **Last Commit**: "Fix bug for twos not being discarded after countering" (ae9ca54)
+- **Previous Commits**: Added typechecking, documentation, jack face card fixes
+
+## Code Quality Strengths
+- ✅ **Excellent type hinting** throughout codebase (2,795 lines in game module)
+- ✅ **Comprehensive test suite** (4,072 lines of tests)
+- ✅ **Well-organized architecture** with clear separation of concerns
+- ✅ **Proper async/await usage** for AI integration
+- ✅ **Detailed documentation** with docstrings following Google style
+- ✅ **Development tooling** properly configured (mypy, black, ruff, etc.)
+
+## Next Steps
+1. Fix type safety violations in `ai_player.py` and test files
+2. Resolve test framework inheritance issues  
+3. Debug and fix failing Ace tests
+4. Clean up git working directory
+5. Run full test suite and type checking to ensure no regressions

Dockerfile

@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-slim AS web-build
+WORKDIR /app/web
+COPY web/package.json web/package-lock.json ./
+RUN npm ci
+COPY web/ ./
+RUN npm run build
+
+FROM python:3.11-slim AS runtime
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY game ./game
+COPY rl ./rl
+COPY server ./server
+
+COPY --from=web-build /app/web/dist ./web/dist
+
+EXPOSE 8000
+
+CMD sh -c "uvicorn server.app:app --host 0.0.0.0 --port ${PORT:-8000}"

Makefile

@@ -12,6 +12,8 @@ test:
 run:
 	source $(VENV_NAME)/bin/activate && PYTHONPATH=$(CURRENT_DIR) python main.py
 
+run-with-rl:
+	source $(VENV_NAME)/bin/activate && PYTHONPATH=$(CURRENT_DIR) python main_with_rl_ai.py
 # Generate documentation using pdoc
 docs:
 	source $(VENV_NAME)/bin/activate && PYTHONPATH=$(CURRENT_DIR) python docs.py
@@ -35,4 +37,24 @@ all: test
 # Type checking
 typecheck:
 	@echo "Running mypy type checks..."
-	source $(VENV_NAME)/bin/activate && mypy .
+	source $(VENV_NAME)/bin/activate && mypy .
+
+# RL Training commands (with action masking)
+train-rl:
+	@echo "Training RL agent with MaskablePPO..."
+	source $(VENV_NAME)/bin/activate && PYTHONPATH=$(CURRENT_DIR) python rl/train.py
+
+eval-rl:
+	@echo "Evaluating RL agent..."
+	source $(VENV_NAME)/bin/activate && PYTHONPATH=$(CURRENT_DIR) python rl/evaluate.py
+
+tensorboard:
+	@echo "Starting TensorBoard on http://localhost:6006"
+	@echo "Press Ctrl+C to stop"
+	source $(VENV_NAME)/bin/activate && tensorboard --logdir=rl/logs --port=6006
+
+test-rl:
+	@echo "Quick RL training test with action masking (10K timesteps, ~2-3 minutes)..."
+	source $(VENV_NAME)/bin/activate && PYTHONPATH=$(CURRENT_DIR) python -c \
+		"from rl import config; config.TRAINING_CONFIG['total_timesteps'] = 10000; \
+		exec(open('rl/train.py').read())"