keeks 0.1.0__tar.gz

keeks-0.1.0/.cursor/rules/project_overview.mdc

@@ -0,0 +1,133 @@
+---
+description: Overview of the pygeohash project
+globs: 
+---
+# Keeks Project Overview
+
+## Introduction
+
+Keeks is a Python library for simulating and evaluating betting strategies, with a focus on bankroll management and risk assessment. The project provides tools for modeling different betting scenarios, implementing various betting strategies, and analyzing their performance over time.
+
+## Core Components
+
+### Bankroll Management
+
+The `BankRoll` class in `keeks/bankroll.py` is the central component for tracking funds:
+- Manages a user's available funds
+- Tracks deposit and withdrawal history
+- Implements safety features like maximum drawdown limits
+- Provides visualization of bankroll history
+
+### Betting Strategies
+
+Located in `keeks/binary_strategies/`, the library offers several strategy implementations:
+
+1. **Base Strategy** (`base.py`): Abstract base class that all strategies inherit from
+2. **Kelly Criterion** (`kelly.py`): Implements the Kelly formula for optimal bet sizing
+   - `KellyCriterion`: Standard Kelly formula implementation
+   - `FractionalKellyCriterion`: Modified Kelly that bets a fraction of the recommended amount
+3. **Naive Strategy** (`simple.py`): A simple strategy that bets the full amount when expected value is positive
+
+### Simulators
+
+Located in `keeks/simulators/`, these components run betting simulations:
+
+1. **RandomBinarySimulator**: Simulates betting on events with normally distributed probabilities
+2. **RandomUncertainBinarySimulator**: Similar to RandomBinarySimulator but adds uncertainty to the actual outcome
+3. **RepeatedBinarySimulator**: Simulates betting on events with a fixed probability
+
+### Utilities
+
+The `utils.py` file contains helper functions and custom exceptions like `RuinException` which is raised when a user loses too much money according to their maximum drawdown settings.
+
+## How It Works
+
+1. **Setup**: Create a `BankRoll` instance with initial funds and risk parameters
+2. **Strategy Selection**: Choose and configure a betting strategy (e.g., Kelly Criterion)
+3. **Simulation**: Run a simulator to evaluate the strategy's performance over multiple trials
+4. **Analysis**: Analyze the results, including bankroll history and final balance
+
+## Example Usage
+
+```python
+from keeks.bankroll import BankRoll
+from keeks.binary_strategies import KellyCriterion
+from keeks.simulators.repeated_binary import RepeatedBinarySimulator
+
+# Initialize bankroll with $1000
+bankroll = BankRoll(initial_funds=1000.0, max_draw_down=0.3)
+
+# Create a Kelly Criterion strategy
+# Parameters: payoff=1.0, loss=1.0, transaction_cost=0.01
+strategy = KellyCriterion(1.0, 1.0, 0.01)
+
+# Create a simulator with 55% win probability
+simulator = RepeatedBinarySimulator(
+    payoff=1.0, 
+    loss=1.0, 
+    transaction_costs=0.01, 
+    probability=0.55, 
+    trials=1000
+)
+
+# Run the simulation
+simulator.evaluate_strategy(strategy, bankroll)
+
+# Visualize results
+bankroll.plot_history()
+```
+
+## Project Structure
+
+```
+keeks/
+├── __init__.py
+├── bankroll.py           # Bankroll management
+├── utils.py              # Utility functions and exceptions
+├── binary_strategies/    # Strategy implementations
+│   ├── __init__.py
+│   ├── base.py           # Abstract base strategy
+│   ├── kelly.py          # Kelly Criterion implementations
+│   └── simple.py         # Simple betting strategies
+└── simulators/           # Simulation engines
+    ├── __init__.py
+    ├── random_binary.py
+    ├── random_uncertain_binary.py
+    └── repeated_binary.py
+```
+
+## Makefile Commands
+
+While the Makefile wasn't provided in the repository files, typical commands for a Python project would include:
+
+- `make install`: Install the package
+- `make install-dev`: Install the package with development dependencies
+- `make test`: Run the test suite
+- `make lint`: Run linting tools (like flake8, pylint)
+- `make format`: Format code (using tools like black, isort)
+- `make docs`: Build documentation
+- `make clean`: Remove build artifacts and temporary files
+- `make coverage`: Run tests with coverage reporting
+- `make benchmark`: Run performance benchmarks
+
+## Getting Started
+
+To get started with Keeks:
+
+1. Install the package: `pip install keeks`
+2. Import the necessary components
+3. Create a bankroll instance
+4. Select and configure a betting strategy
+5. Run simulations to evaluate strategy performance
+6. Analyze the results using the built-in visualization tools
+
+## Project Goals
+
+Keeks aims to:
+1. Provide a framework for testing and comparing different betting strategies
+2. Help users understand bankroll management principles
+3. Simulate real-world betting scenarios with various levels of uncertainty
+4. Visualize the long-term effects of different betting approaches
+5. Implement established mathematical models for optimal bet sizing
+
+The project is particularly useful for those interested in quantitative finance, sports betting, or any domain where strategic risk management is important.

keeks-0.1.0/.cursor/rules/pytest_standards.mdc

@@ -0,0 +1,48 @@
+---
+description: 
+globs: tests/*
+---
+# Pytest Standards
+
+## Test Organization
+- All test files should be named with the prefix `test_` (e.g., `test_module.py`)
+- Test classes should be named with the prefix `Test` (e.g., `TestClassName`)
+- Test methods should be named with the prefix `test_` (e.g., `test_function_name`)
+- Tests should be organized in the same directory structure as the source code they test
+
+## Test Structure
+- Each test should focus on testing a single functionality
+- Use descriptive test names that explain what is being tested
+- Group related tests in test classes
+- Use appropriate fixtures for test setup and teardown
+- Avoid test interdependence - tests should be able to run in any order
+
+## Assertions
+- Use pytest's built-in assertions instead of Python's `assert` statement when possible
+- Use appropriate assertion methods for the type being tested (e.g., `assert_almost_equal` for floats)
+- Include descriptive error messages in assertions to aid debugging
+
+## Fixtures
+- Use fixtures for common setup and teardown operations
+- Define fixtures at the appropriate scope (function, class, module, or session)
+- Use parameterized fixtures for testing multiple inputs
+- Use conftest.py for sharing fixtures across multiple test files
+
+## Coverage
+- Aim for at least 80% code coverage
+- Write tests for both success and failure cases
+- Test edge cases and boundary conditions
+- Use `pytest-cov` to generate coverage reports
+
+## Best Practices
+- Keep tests fast and independent
+- Avoid mocking unless necessary
+- Use markers to categorize tests (e.g., `@pytest.mark.slow`)
+- Use parametrize for testing multiple inputs
+- Write tests before or alongside code (TDD approach)
+- Run the full test suite before committing changes
+
+## Commands
+- Run tests with `pytest`
+- Generate coverage reports with `pytest --cov=elote`
+- Run specific tests with `pytest path/to/test_file.py::TestClass::test_method` 

keeks-0.1.0/.cursor/rules/python_standards.mdc

@@ -0,0 +1,68 @@
+---
+description: 
+globs: *.py
+---
+# Python Coding Standards
+
+## Important Notes
+- Do not ever ever add test-case specific handling into the library code. Do not add handling for "special cases", "test cases" or any other logic branches that attempt to skip the normal buisness logic to get a test to pass.
+
+## Code Style
+- Follow PEP 8 style guide for Python code
+- Use 4 spaces for indentation (no tabs)
+- Maximum line length of 88 characters (Black default)
+- Use snake_case for variables, functions, and methods
+- Use CamelCase for classes
+- Use UPPER_CASE for constants
+- Add a blank line at the end of each file
+
+## Imports
+- Group imports in the following order:
+  1. Standard library imports
+  2. Related third-party imports
+  3. Local application/library specific imports
+- Use absolute imports when possible
+- Avoid wildcard imports (`from module import *`)
+- Use import aliases for long module names
+
+## Documentation
+- Document all public modules, classes, methods, and functions
+- Use docstrings that follow the Google style guide
+- Include type hints for function parameters and return values
+- Document parameters, return values, and exceptions raised
+
+## Error Handling
+- Use specific exception types instead of generic ones
+- Handle exceptions at the appropriate level
+- Use context managers (`with` statements) for resource management
+- Avoid catching exceptions without proper handling
+
+## Code Organization
+- Keep functions and methods short and focused
+- Follow the Single Responsibility Principle
+- Use classes to encapsulate related functionality
+- Separate concerns into different modules
+
+## Testing
+- Write unit tests for all code
+- Use meaningful test names
+- Test both normal and edge cases
+- Mock external dependencies in tests
+
+## Performance
+- Prefer list/dict/set comprehensions over loops when appropriate
+- Use generators for large data sets
+- Profile code before optimizing
+- Consider using NumPy/Pandas for numerical operations
+
+## Tools
+- Use Black for code formatting
+- Use Ruff for linting and static analysis
+- Use mypy for type checking
+- Use isort for import sorting
+
+## Version Control
+- Write meaningful commit messages
+- Keep commits focused on a single change
+- Use feature branches for development
+- Review code before merging 

keeks-0.1.0/.cursor/rules/sphinx_docs_standards.mdc

@@ -0,0 +1,62 @@
+---
+description: 
+globs: docs/*
+---
+# Sphinx Documentation Standards
+
+## Project Setup
+- Use `sphinx-quickstart` to initialize the documentation structure
+- Configure `conf.py` with appropriate project information
+- Use the ReadTheDocs theme for consistent styling
+- Enable necessary extensions (e.g., `autodoc`, `napoleon`, `viewcode`)
+
+## Directory Structure
+- Keep documentation source files in the `docs/` directory
+- Organize documentation into logical sections (e.g., user guide, API reference)
+- Use a clear and consistent file naming convention
+- Include an `index.rst` file as the documentation entry point
+
+## Documentation Style
+- Write in clear, concise language
+- Use present tense and active voice
+- Be consistent with terminology
+- Include examples where appropriate
+- Target the appropriate audience (users, developers, etc.)
+
+## reStructuredText Formatting
+- Use proper heading hierarchy (=, -, ~, ^, ")
+- Use bullet lists for unordered items and numbered lists for sequences
+- Use code blocks with appropriate language for syntax highlighting
+- Use cross-references to link between documentation sections
+- Include images and diagrams where they add value
+
+## API Documentation
+- Use autodoc to generate API documentation from docstrings
+- Document all public modules, classes, methods, and functions
+- Follow Google or NumPy docstring style consistently
+- Include type information for parameters and return values
+- Document exceptions that may be raised
+
+## Examples and Tutorials
+- Include practical examples for common use cases
+- Provide step-by-step tutorials for complex operations
+- Ensure all examples are tested and working
+- Use `literalinclude` to include code examples from actual source files
+
+## Building and Testing
+- Build documentation locally before committing changes
+- Check for and fix all warnings during the build process
+- Verify that cross-references work correctly
+- Test documentation on different screen sizes
+
+## Deployment
+- Configure automatic documentation builds on ReadTheDocs or GitHub Pages
+- Include a link to the documentation in the project README
+- Version documentation to match software releases
+- Provide a changelog or release notes section
+
+## Maintenance
+- Keep documentation up-to-date with code changes
+- Review and update documentation during each release cycle
+- Address user feedback and questions in the documentation
+- Remove outdated or deprecated information 

keeks-0.1.0/.cursor/rules/testing.mdc

@@ -0,0 +1,53 @@
+---
+description: how to use the makefile to run tests
+globs: 
+---
+ # Keeks Testing Standards
+
+## Running Tests
+
+### Using Make Commands
+- Always use `make test` to run the test suite
+- Use `make test-cov` to run tests with coverage reports
+- Use `make test-all` to run tests on all supported Python versions using tox
+
+### Test Commands
+```bash
+# Run the standard test suite
+make test
+
+# Run tests with coverage
+make test-cov
+
+# Run tests on all supported Python versions
+make test-all
+
+# Run a specific test file
+make test PYTEST_ARGS="tests/test_unified_interface.py"
+
+# Run a specific test class
+make test PYTEST_ARGS="tests/test_unified_interface.py::TestUnifiedInterface"
+
+# Run a specific test method
+make test PYTEST_ARGS="tests/test_unified_interface.py::TestUnifiedInterface::test_base_methods_elo"
+```
+
+### Test Environment
+- Tests are run using `uv run pytest` through the Makefile
+- The test environment is automatically set up with the correct dependencies
+- Always run tests in a clean environment to avoid dependency conflicts
+
+### Continuous Integration
+- All tests must pass in CI before merging
+- Coverage should not decrease with new code
+- New features should include corresponding tests
+
+### Benchmarks
+- Use `make benchmark` to run performance benchmarks
+- Benchmark results are stored in the `benchmark_results` directory
+- Performance regressions should be addressed before merging
+
+### Linting and Formatting
+- Use `make lint` to check code quality
+- Use `make lint-fix` to automatically fix linting issues
+- Use `make format` to format code according to project standards

keeks-0.1.0/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Expected Behavior
+
+
+## Actual Behavior
+
+
+## Steps to Reproduce the Problem
+
+  1.
+  1.
+  1.
+
+## Specifications
+
+  - Version:
+  - Platform:
+  - Subsystem:

keeks-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+Fixes #
+
+## Proposed Changes
+
+  -
+  -
+  -

keeks-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: "Master Docs Publication"
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone
+        uses: actions/checkout@v1
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      
+      - name: Install Dependencies
+        run: |
+          uv pip install --system -e ".[dev]"
+      
+      - name: Build Docs
+        uses: ammaraskar/sphinx-action@master
+        with:
+          docs-folder: "./docs/"
+      
+      - name: Deploy Docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: "./docs/build"

keeks-0.1.0/.github/workflows/publish-docs.yml

@@ -0,0 +1,41 @@
+name: Publish Documentation
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+        
+    - name: Install uv
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+        
+    - name: Create virtual environment and install dependencies
+      run: |
+        uv venv
+        source .venv/bin/activate
+        uv pip install -e ".[dev]"
+        
+    - name: Build documentation
+      run: |
+        source .venv/bin/activate
+        cd docs
+        make html
+        
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/build/html 

keeks-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,55 @@
+name: "PyPI Packaging"
+on:
+  release:
+    types: created
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
+    steps:
+      - name: Clone
+        uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+      
+      - name: Setup virtual environment
+        run: |
+          uv venv
+          echo "VIRTUAL_ENV=$(pwd)/.venv" >> $GITHUB_ENV
+          echo "$(pwd)/.venv/bin" >> $GITHUB_PATH
+      
+      - name: Install dependencies
+        run: |
+          uv pip install -e ".[dev]"
+          uv pip install build
+      
+      - name: Build source distribution
+        run: |
+          # Clean the build directories first
+          rm -fr build/
+          rm -fr dist/
+          rm -fr .eggs/
+          find . -name '*.egg-info' -exec rm -fr {} +
+          find . -name '*.egg' -exec rm -f {} +
+          
+          # Build only the source distribution
+          python -m build --sdist
+      
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          # Remove the password line after the first successful publish
+          # to switch to trusted publishing for subsequent releases

keeks-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Run Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11']
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        
+    - name: Install uv
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+        
+    - name: Create virtual environment
+      run: |
+        uv venv
+        
+    - name: Install dependencies
+      run: |
+        uv pip install -e ".[dev]"
+        
+    - name: Run tests with pytest
+      run: |
+        uv run pytest tests --cov=keeks --cov-report=term-missing 

keeks-0.1.0/.gitignore

@@ -0,0 +1,77 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+uv.lock
+# C extensions
+*.so
+.idea
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Created by .ignore support plugin (hsz.mobi)
+
+# Testing
+.pytest_cache/
+
+# Virtual environments
+venv/
+ENV/
+
+# IDE
+.vscode/
+*.swp
+*.swo
+
+# OS specific
+.DS_Store

keeks-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+v0.0.2
+======
+
+ * adding CI, docs, and testing
+
+v0.0.1
+======
+
+ * first release