chore: Add tests, linting, CI workflow, and improved docs

chrisduvillard · claude · chrisduvillard · commit c505f3e60475 · 2026-02-19T11:04:24.000+01:00
- Add 19 pytest tests for TradingSimulator, simulate_drawdown, metric_box
- Configure ruff (pyproject.toml) with import sorting and style checks
- Add GitHub Actions CI workflow (Python 3.10 + 3.12, ruff + pytest)
- Rewrite README with setup, run, test, lint instructions and methodology
- Add CHANGELOG.md with full change summary and verification commands
- Fix import ordering across all files (ruff I001)
- Fix trailing whitespace in Welcome.py (ruff W291)
- Use flexible version ranges in requirements.txt for Python 3.10-3.13

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff pytest
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest -v
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,52 @@
+# Changelog
+
+## [1.1.0] - 2026-02-19
+
+### Audit & Documentation
+- Added `docs/audit_report.md` with full codebase audit (blockers, majors, minors)
+- Added `CHANGELOG.md`
+- Improved `README.md` with setup, run, test, and lint instructions
+
+### Bug Fixes (Blockers)
+- **Removed duplicate `st.set_page_config`** from Asset Correlation page — previously crashed on navigation
+- **Fixed JavaScript syntax error** in `utils/style.py` footer (trailing `.` replaced with `;`)
+
+### Bug Fixes (Majors)
+- **Removed duplicated `SLIDER_CONFIGS`** from page 1; now imports from `config.slider_configs`
+- **Removed unnecessary `sys.path.append` hack** from page 1
+- **Fixed malformed HTML comment** (unclosed `<!---`) in page 1
+- **Added missing `utils/__init__.py`** for reliable imports
+- **Cached `simulate_drawdown`** so it doesn't rerun 10,000 simulations on every slider change
+- **Restructured Asset Correlation page** — wrapped all logic in functions, added "Run Simulation" button to avoid recomputing on every widget interaction
+- **Removed unused functions** (`average_trade_progression`, `simulate_portfolio_risk`) from `risk_simulation.py`
+- **Added footer to page 2** for consistency with page 1
+- **Updated pandas** from 1.5.3 to 2.x (compatible with modern numpy/Python)
+
+### Bug Fixes (Minors)
+- **Fixed win-rate chart annotation** x-value mismatch (was `f"{value}"`, now `f"{value}%"` to match bar labels)
+
+### Refactoring
+- Extracted `_viridis_colors` and `_add_expected_return_annotation` shared helpers in page 1
+- Extracted `simulate_portfolio`, `calculate_metrics`, `style_metrics_table` in page 2
+- Moved drawdown simulation to `utils/risk_simulation.py` as `simulate_drawdown`
+- Added type hints throughout `risk_simulation.py`
+- Reduced metric display duplication with loop pattern
+
+### Tooling & CI
+- Added `pyproject.toml` with ruff and pytest configuration
+- Added `tests/` with 19 tests covering `TradingSimulator`, `simulate_drawdown`, and `metric_box`
+- Added `.github/workflows/ci.yml` running ruff + pytest on Python 3.10 and 3.12
+- Updated `requirements.txt` to use flexible version ranges for Python 3.10-3.13 compatibility
+
+### Verification Notes
+
+```bash
+# Run the app
+streamlit run Welcome.py
+
+# Run tests
+pytest -v
+
+# Run linter
+ruff check .
+```
diff --git a/README.md b/README.md
@@ -9,8 +9,8 @@
 
 ## Features
 
-- **Risk-Return Analysis**: Simulate various risk-return scenarios using adjustable parameters like win rate, trades per year, risk per trade, and return per unit of risk (RPUR).
-- **Asset Correlation Simulator**: Generate and visualize portfolio performance based on customizable asset correlation matrices, with options for single or random correlation ranges.
+- **Risk-Return Analysis**: Simulate various risk-return scenarios using adjustable parameters like win rate, trades per year, risk per trade, and return per unit of risk (RPUR). Uses Monte Carlo simulation to estimate expected returns and drawdowns.
+- **Asset Correlation Simulator**: Generate and visualize portfolio performance based on customizable asset correlation matrices, with options for single or random correlation ranges. Computes Sharpe, Sortino, Calmar ratios, max drawdown, and more.
 
 ## Screenshots
 
@@ -28,105 +28,104 @@
 
 ## Project Structure
 
-```bash
+```
 RiskSim/
-│
+├── Welcome.py                         # Streamlit entrypoint (landing page)
 ├── pages/
-│   ├── 1_🎯_risk_return_analysis.py   # Main page for risk-return simulations
-│   └── 2_📈_asset_correlation.py     # Main page for asset correlation simulations
-│
+│   ├── 1_🎯_risk_return_analysis.py   # Risk-return Monte Carlo simulation
+│   └── 2_📈_asset_correlation.py      # Asset correlation portfolio simulator
 ├── config/
-│   ├── slider_configs.py              # Configuration for slider inputs in the Streamlit UI
-│   └── __init__.py                    # Init file for config
-│
+│   └── slider_configs.py              # Centralized slider defaults and bounds
 ├── utils/
-│   ├── risk_simulation.py             # Core simulation logic for risk management and portfolio performance
-│   └── style.py                       # Styling and layout helpers for Streamlit app
-│
-├── docs/images/                       # Image assets for documentation and app UI
-│   ├── header_image.jpg
-│   ├── image.png
-│   ├── image_1.png
-│   ├── image_2.png
-│   ├── image_3.png
-│   └── image_4.png
-│
-├── venv/                              # Python virtual environment (optional)
-├── Welcome.py                         # Main entry point for the app
-├── README.md                          # This file
-├── LICENSE.txt                        # License information
-├── .gitignore                         # Files and directories to be ignored by git
-└── requirements.txt                   # Python dependencies
+│   ├── risk_simulation.py             # TradingSimulator class + drawdown simulation
+│   └── style.py                       # Footer and metric box HTML helpers
+├── tests/
+│   ├── test_risk_simulation.py        # Tests for simulation logic
+│   └── test_style.py                  # Tests for style helpers
+├── docs/
+│   ├── audit_report.md                # Codebase audit report
+│   └── images/                        # Screenshots and header image
+├── .github/workflows/ci.yml           # GitHub Actions CI (ruff + pytest)
+├── pyproject.toml                     # Ruff and pytest configuration
+├── requirements.txt                   # Python dependencies
+├── CHANGELOG.md                       # Change log
+├── LICENSE.txt                        # MIT License
+└── README.md
 ```
 
-## Installation
-
-To get started with **RiskSim**, follow these steps:
+## Setup
 
 ### Prerequisites
 
-Ensure you have Python 3.8+ installed. You'll also need `pip` to install the required dependencies.
+- Python 3.10 or higher
+- pip
 
-### Clone the Repository
+### Installation
 
 ```bash
-git clone https://github.com/your-username/RiskSim.git
+# Clone the repository
+git clone https://github.com/chrisduvillard/RiskSim.git
 cd RiskSim
+
+# Create and activate a virtual environment
+python -m venv .venv
+# On Windows:
+.venv\Scripts\activate
+# On macOS/Linux:
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
 ```
 
-### Create a Virtual Environment (Optional but Recommended)
+### Run the App
 
 ```bash
-python -m venv venv
-source venv/bin/activate  # On Windows use `venv\Scriptsctivate`
+streamlit run Welcome.py
 ```
 
-### Install Dependencies
+This launches the app in your browser. Use the sidebar to navigate between pages.
 
-Install the required Python packages by running:
+### Run Tests
 
 ```bash
-pip install -r requirements.txt
+pip install pytest
+pytest -v
 ```
 
-### Run the Application
-
-Start the application using Streamlit:
+### Run Linter
 
 ```bash
-streamlit run Welcome.py
+pip install ruff
+ruff check .
 ```
 
-This will launch the **RiskSim** app in your browser.
-
-## Usage
+## Methodology
 
 ### Risk-Return Analysis
 
-- Navigate to the **Risk-Return Analysis** section to simulate various risk-return scenarios.
-- You can adjust the number of trades per year, win rate, risk per trade, and RPUR.
-- View detailed metrics such as expected drawdown, Sharpe ratio, and more.
-  
+The Risk-Return Analysis page uses **Monte Carlo simulation** to model trading outcomes. Given a set of parameters (number of trades per year, win rate, risk per trade, and return per unit of risk), the simulator:
+
+1. Generates random trade sequences where each trade is a win or loss based on the specified win rate
+2. Applies compounding: each trade's P&L is a percentage of the *current* AUM (not the initial capital)
+3. Repeats this process thousands of times to build a distribution of outcomes
+4. Reports average returns across different RPUR levels and win rates
+5. Estimates the expected maximum consecutive-loss drawdown
+
 ### Asset Correlation Simulation
 
-- Use the **Asset Correlation** page to simulate portfolios with different asset correlations.
-- Choose between fixed or random correlation settings.
-- Visualize performance and compute portfolio metrics under various correlation regimes.
+The Asset Correlation page generates synthetic multi-asset portfolios using **correlated geometric Brownian motion**:
 
+1. Builds a correlation matrix (uniform or random within a range), ensuring positive definiteness
+2. Constructs a covariance matrix from per-asset volatilities and the correlation matrix
+3. Samples multivariate normal log-returns and converts to price paths
+4. Computes per-asset and portfolio performance metrics (Sharpe, Sortino, Calmar, max drawdown)
+5. Sweeps across correlation levels to show how diversification affects portfolio risk
 
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE.txt](LICENSE.txt) file for details.
 
 ## Author
 
-Made with ❤️ by [Chris](https://www.linkedin.com/in/christopheduvillard/)
-
-## Acknowledgments
-
-- Streamlit
-- Plotly
-
-## Contributing
-
-Contributions are welcome! Feel free to fork the repository, make improvements, and submit a pull request.
+Made by [Christophe Duvillard](https://www.linkedin.com/in/christopheduvillard/)
diff --git a/Welcome.py b/Welcome.py
@@ -44,7 +44,7 @@
 #### 🔍 Explore the Features of RiskSim:
 **Navigate Through the App Using the Sidebar:**
 
-- **📊 Risk-Return Analysis**: 
+- **📊 Risk-Return Analysis**:
     - Simulate how various trading parameters, such as win rate, number of trades, and risk per trade, affect your overall performance.
     - Use Monte Carlo simulations to explore potential outcomes based on your trading strategy.
     - Visualize the trade-off between risk and return to optimize your approach.
diff --git a/pages/1_🎯_risk_return_analysis.py b/pages/1_🎯_risk_return_analysis.py
@@ -1,10 +1,11 @@
-from utils.style import footer, metric_box
-from utils.risk_simulation import TradingSimulator, simulate_drawdown
-from config.slider_configs import SLIDER_CONFIGS
-import streamlit as st
+import numpy as np
 import plotly.express as plotly_express
 import plotly.graph_objects as go
-import numpy as np
+import streamlit as st
+
+from config.slider_configs import SLIDER_CONFIGS
+from utils.risk_simulation import TradingSimulator, simulate_drawdown
+from utils.style import footer, metric_box
 
 
 def _viridis_colors(values: list[float]) -> list[str]:
diff --git a/pages/2_📈_asset_correlation.py b/pages/2_📈_asset_correlation.py
@@ -1,8 +1,9 @@
-import streamlit as st
 import numpy as np
 import pandas as pd
-import plotly.graph_objs as go
 import plotly.express as px
+import plotly.graph_objs as go
+import streamlit as st
+
 from utils.style import footer
 
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,21 @@
+[project]
+name = "risksim"
+version = "1.0.0"
+description = "Risk-Return and Asset Correlation Simulator"
+requires-python = ">=3.10"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = [
+    "E501",  # line too long — handled by formatter where practical
+]
+
+[tool.ruff.lint.per-file-ignores]
+"pages/*.py" = ["E402"]  # module-level imports not at top (Streamlit pages)
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
diff --git a/requirements.txt b/requirements.txt
@@ -1,5 +1,5 @@
-numpy==1.26.4
-plotly==5.22.0
-streamlit==1.35.0
-htbuilder==0.6.2
-pandas==2.2.3
+numpy>=1.26.4,<3
+plotly>=5.22.0,<6
+streamlit>=1.35.0,<2
+htbuilder>=0.6.2,<1
+pandas>=2.0,<3
diff --git a/tests/__init__.py b/tests/__init__.py
diff --git a/tests/test_risk_simulation.py b/tests/test_risk_simulation.py
diff --git a/tests/test_style.py b/tests/test_style.py
diff --git a/utils/style.py b/utils/style.py
