optPricing 2.3.1__tar.gz → 2.3.2__tar.gz

optpricing-2.3.2/.coveragerc

@@ -0,0 +1,4 @@
+[run]
+source = src/optpricing
+omit =
+    src/optpricing/dashboard/pages/*

{optpricing-2.3.1 → optpricing-2.3.2}/.gitignore

@@ -25,6 +25,7 @@ htmlcov/
 site/
 
 # Ignore my local notes file
-todo.txt
 todo/
 notes/
+text_drafts/
+todo.txt

optpricing-2.3.2/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: optpricing
+Version: 2.3.2
+Summary: A financial options pricing and analysis library.
+Author-email: Diljit Singh <first_last22@google.com>
+License: # MIT LICENSE
+        
+        Copyright 2025 Diljit Singh
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://diljit22.github.io/quantfin/
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy~=2.2.5
+Requires-Dist: scipy~=1.15.2
+Requires-Dist: pandas~=2.2.3
+Requires-Dist: numba~=0.61.2
+Requires-Dist: pyyaml~=6.0.2
+Requires-Dist: click~=8.1
+Requires-Dist: typer~=0.15.2
+Requires-Dist: streamlit~=1.45.1
+Requires-Dist: matplotlib~=3.10.1
+Requires-Dist: plotly~=6.1.2
+Requires-Dist: yfinance~=0.2.63
+Requires-Dist: tabulate~=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff==0.11.6; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocstrings[python]; extra == "dev"
+Requires-Dist: mkdocs-section-index; extra == "dev"
+Requires-Dist: line_profiler; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: codecov; extra == "dev"
+Dynamic: license-file
+
+# OptPricing: A Quantitative Finance Library for Derivative Pricing and Analysis
+
+[![Tests](https://img.shields.io/github/actions/workflow/status/diljit22/quantfin/ci.yml?branch=main&label=tests)](https://github.com/diljit22/quantfin/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/diljit22/quantfin/branch/main/graph/badge.svg)](https://codecov.io/gh/diljit22/quantfin)
+[![Ruff](https://img.shields.io/github/actions/workflow/status/diljit22/quantfin/ci.yml?branch=main&label=ruff)](https://github.com/diljit22/quantfin/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/github/actions/workflow/status/diljit22/quantfin/ci.yml?branch=main&label=docs)](https://github.com/diljit22/quantfin/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/optpricing.svg)](https://pypi.org/project/optpricing/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`optpricing` is a Python library for pricing, calibrating, and analyzing financial derivatives. It is built with a focus on architectural clarity, model breadth, and practical usability through a robust API, command-line interface, and an interactive dashboard.
+
+Diljit Singh
+linkedin.com/in/singhdiljit/
+
+---
+
+## Core Features
+
+* **Model Library**: Implements a comprehensive set of models, including:
+  * **Stochastic Volatility**: Heston, SABR
+  * **Jump-Diffusion**: Merton, Bates, Kou, SABR with Jumps
+  * **Pure Levy Processes**: Variance Gamma (VG), Normal Inverse Gaussian (NIG), CGMY, Hyperbolic
+  * **Interest Rate Models**: Vasicek, Cox-Ingersoll-Ross (CIR), Put-Call Parity Implied Rate
+  * **Local Volatility**: Dupire's Equation
+
+* **Pricing Engines**: Provides a suite of numerical methods, allowing for technique comparison and validation:
+  * Analytic closed-form solutions
+  * Numerical integration and FFT-based pricing via characteristic functions
+  * Finite difference (PDE) solver using a Crank-Nicolson scheme
+  * Binomial and trinomial tree methods (CRR, TOPM, Leisen-Reimer) for European and American options
+  * High-performance Monte Carlo engine for European and American options, accelerated with `numba`, featuring variance reduction techniques (e.g., antithetic variates, control variates, importance sampling)
+
+* **Interfaces**:
+  * **Programmatic API**: Use the package as a Python library to build custom financial models in your scripts. Define options, stocks, rates, and models programmatically to compute prices and other metrics.
+  * **Command-Line Interface (CLI)**: A robust CLI for live pricing, data management, model calibration, and historical backtesting.
+  * **Interactive Dashboard (UI)**: A Streamlit application for visual analysis of option chains, implied volatility surfaces, and model calibrations.
+
+* **Workflow Automation**: High-level classes that orchestrate complex tasks like daily calibration runs and out-of-sample performance evaluation.
+
+---
+
+## Quick Start
+
+`optpricing` is designed for a straightforward installation using `pip` and is compatible with Python 3.10 and higher.
+
+### 1. Install the Library
+
+```bash
+pip install optpricing
+```
+
+### 2. Download Historical Data
+
+Some models require historical data (e.g., for calibration). Download data for a ticker like SPY:
+
+```bash
+optpricing data download --ticker SPY
+```
+
+For more details, see the [Getting Started Guide](https://diljit22.github.io/quantFin/guide/getting_started/).
+
+### 3. Use the CLI
+
+Price an option directly from the terminal. The command below fetches the live option chain for AAPL, retrieves the current dividend rate, calculates the implied risk-free rate from at-the-money contracts, and prices the contract with Heston’s model using its default pricing technique (FFT):
+
+```bash
+optpricing price --ticker AAPL --strike 630 --maturity 2025-12-19 --model Heston --param "rho=-0.7" --param "vol_of_vol=0.5"
+```
+
+To price the same contract as an American Option use:
+
+```bash
+optpricing price -t AAPL -k 210 -T 2025-12-19 --style american --model Heston --param "rho=-0.7" --param "vol_of_vol=0.5"
+```
+
+For more details, see the [CLI Guide](https://diljit22.github.io/quantFin/guide/CLI/).
+
+### 4. Launch the Dashboard
+
+Visualize option chains and model outputs, interact with a pricing calculator featuring 15 models and 10 techniques.
+
+```bash
+optpricing dashboard
+```
+
+For more details, see the [Dashboard Guide](https://diljit22.github.io/quantFin/guide/dashboard/).
+
+### 5. Use the Programmatic API
+
+The most powerful way to use the package is via the API, which provides customization of nearly every aspect of pricing:
+
+```python
+from optpricing import Option, OptionType, Rate, Stock, ZeroCouponBond
+from optpricing.models import BSMModel, CIRModel, VasicekModel
+from optpricing.techniques import ClosedFormTechnique
+
+# Define an option, underlying and rate
+option = Option(strike=105, maturity=1.0, option_type=OptionType.CALL)
+stock = Stock(spot=100, dividend=0.01)
+rate = Rate(rate=0.05)
+
+# Choose a model and technique
+bsm_model = BSMModel(params={"sigma": 0.20})
+cf_technique = ClosedFormTechnique()
+
+result = cf_technique.price(option, stock, bsm_model, rate)
+print(f"The option price is: {result.price:.4f}")
+
+
+delta = cf_technique.delta(option, stock, bsm_model, rate)
+gamma = cf_technique.gamma(option, stock, bsm_model, rate)
+vega = cf_technique.vega(option, stock, bsm_model, rate)
+
+print(f"Delta: {delta:.4f}")
+print(f"Gamma: {gamma:.4f}")
+print(f"Vega:  {vega:.4f}")
+
+target_price = 7.50
+iv = cf_technique.implied_volatility(
+    option, stock, bsm_model, rate, target_price=target_price
+)
+print(f"Implied volatility for price ${target_price:.2f}: {iv:.4%}")
+
+
+# Zero Coupon Bond
+bond = ZeroCouponBond(maturity=1.0)
+r0_stock = Stock(spot=0.05)  # initial short rate
+dummy_rate = Rate(rate=0.0)  # ignored by rate models
+
+vasicek = VasicekModel(params={"kappa": 0.86, "theta": 0.09, "sigma": 0.02})
+cir = CIRModel(params={"kappa": 0.86, "theta": 0.09, "sigma": 0.02})
+
+p_vasi = cf_technique.price(bond, r0_stock, vasicek, dummy_rate).price
+p_cir = cf_technique.price(bond, r0_stock, cir, dummy_rate).price
+
+print(f"Vasicek ZCB Price: {p_vasi:.4f}")
+print(f"CIR ZCB Price:     {p_cir:.4f}")
+```
+
+For more details, see the [API Guide](https://diljit22.github.io/quantFin/guide/API/).
+
+---
+
+## Documentation
+
+The full documentation includes installation instructions, user guides, examples, and a complete API reference.
+
+* **[View the Official Documentation](https://diljit22.github.io/quantFin/)**
+
+### Guides
+
+* [Introduction](https://diljit22.github.io/quantFin/guide/introduction/)
+* [Installation](https://diljit22.github.io/quantFin/guide/installation/)
+* [Getting Started](https://diljit22.github.io/quantFin/guide/getting_started/)
+* [CLI](https://diljit22.github.io/quantFin/guide/CLI/)
+* [Dashboard](https://diljit22.github.io/quantFin/guide/dashboard/)
+* [API](https://diljit22.github.io/quantFin/guide/API/)
+* [Examples](https://diljit22.github.io/quantFin/guide/examples/)
+* [API Reference](https://diljit22.github.io/quantFin/reference/)
+
+## Contributing
+
+Contributions are welcome; see [CONTRIBUTING](/CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

optpricing-2.3.2/README.md

@@ -0,0 +1,168 @@
+# OptPricing: A Quantitative Finance Library for Derivative Pricing and Analysis
+
+[![Tests](https://img.shields.io/github/actions/workflow/status/diljit22/quantfin/ci.yml?branch=main&label=tests)](https://github.com/diljit22/quantfin/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/diljit22/quantfin/branch/main/graph/badge.svg)](https://codecov.io/gh/diljit22/quantfin)
+[![Ruff](https://img.shields.io/github/actions/workflow/status/diljit22/quantfin/ci.yml?branch=main&label=ruff)](https://github.com/diljit22/quantfin/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/github/actions/workflow/status/diljit22/quantfin/ci.yml?branch=main&label=docs)](https://github.com/diljit22/quantfin/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/optpricing.svg)](https://pypi.org/project/optpricing/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`optpricing` is a Python library for pricing, calibrating, and analyzing financial derivatives. It is built with a focus on architectural clarity, model breadth, and practical usability through a robust API, command-line interface, and an interactive dashboard.
+
+Diljit Singh
+linkedin.com/in/singhdiljit/
+
+---
+
+## Core Features
+
+* **Model Library**: Implements a comprehensive set of models, including:
+  * **Stochastic Volatility**: Heston, SABR
+  * **Jump-Diffusion**: Merton, Bates, Kou, SABR with Jumps
+  * **Pure Levy Processes**: Variance Gamma (VG), Normal Inverse Gaussian (NIG), CGMY, Hyperbolic
+  * **Interest Rate Models**: Vasicek, Cox-Ingersoll-Ross (CIR), Put-Call Parity Implied Rate
+  * **Local Volatility**: Dupire's Equation
+
+* **Pricing Engines**: Provides a suite of numerical methods, allowing for technique comparison and validation:
+  * Analytic closed-form solutions
+  * Numerical integration and FFT-based pricing via characteristic functions
+  * Finite difference (PDE) solver using a Crank-Nicolson scheme
+  * Binomial and trinomial tree methods (CRR, TOPM, Leisen-Reimer) for European and American options
+  * High-performance Monte Carlo engine for European and American options, accelerated with `numba`, featuring variance reduction techniques (e.g., antithetic variates, control variates, importance sampling)
+
+* **Interfaces**:
+  * **Programmatic API**: Use the package as a Python library to build custom financial models in your scripts. Define options, stocks, rates, and models programmatically to compute prices and other metrics.
+  * **Command-Line Interface (CLI)**: A robust CLI for live pricing, data management, model calibration, and historical backtesting.
+  * **Interactive Dashboard (UI)**: A Streamlit application for visual analysis of option chains, implied volatility surfaces, and model calibrations.
+
+* **Workflow Automation**: High-level classes that orchestrate complex tasks like daily calibration runs and out-of-sample performance evaluation.
+
+---
+
+## Quick Start
+
+`optpricing` is designed for a straightforward installation using `pip` and is compatible with Python 3.10 and higher.
+
+### 1. Install the Library
+
+```bash
+pip install optpricing
+```
+
+### 2. Download Historical Data
+
+Some models require historical data (e.g., for calibration). Download data for a ticker like SPY:
+
+```bash
+optpricing data download --ticker SPY
+```
+
+For more details, see the [Getting Started Guide](https://diljit22.github.io/quantFin/guide/getting_started/).
+
+### 3. Use the CLI
+
+Price an option directly from the terminal. The command below fetches the live option chain for AAPL, retrieves the current dividend rate, calculates the implied risk-free rate from at-the-money contracts, and prices the contract with Heston’s model using its default pricing technique (FFT):
+
+```bash
+optpricing price --ticker AAPL --strike 630 --maturity 2025-12-19 --model Heston --param "rho=-0.7" --param "vol_of_vol=0.5"
+```
+
+To price the same contract as an American Option use:
+
+```bash
+optpricing price -t AAPL -k 210 -T 2025-12-19 --style american --model Heston --param "rho=-0.7" --param "vol_of_vol=0.5"
+```
+
+For more details, see the [CLI Guide](https://diljit22.github.io/quantFin/guide/CLI/).
+
+### 4. Launch the Dashboard
+
+Visualize option chains and model outputs, interact with a pricing calculator featuring 15 models and 10 techniques.
+
+```bash
+optpricing dashboard
+```
+
+For more details, see the [Dashboard Guide](https://diljit22.github.io/quantFin/guide/dashboard/).
+
+### 5. Use the Programmatic API
+
+The most powerful way to use the package is via the API, which provides customization of nearly every aspect of pricing:
+
+```python
+from optpricing import Option, OptionType, Rate, Stock, ZeroCouponBond
+from optpricing.models import BSMModel, CIRModel, VasicekModel
+from optpricing.techniques import ClosedFormTechnique
+
+# Define an option, underlying and rate
+option = Option(strike=105, maturity=1.0, option_type=OptionType.CALL)
+stock = Stock(spot=100, dividend=0.01)
+rate = Rate(rate=0.05)
+
+# Choose a model and technique
+bsm_model = BSMModel(params={"sigma": 0.20})
+cf_technique = ClosedFormTechnique()
+
+result = cf_technique.price(option, stock, bsm_model, rate)
+print(f"The option price is: {result.price:.4f}")
+
+
+delta = cf_technique.delta(option, stock, bsm_model, rate)
+gamma = cf_technique.gamma(option, stock, bsm_model, rate)
+vega = cf_technique.vega(option, stock, bsm_model, rate)
+
+print(f"Delta: {delta:.4f}")
+print(f"Gamma: {gamma:.4f}")
+print(f"Vega:  {vega:.4f}")
+
+target_price = 7.50
+iv = cf_technique.implied_volatility(
+    option, stock, bsm_model, rate, target_price=target_price
+)
+print(f"Implied volatility for price ${target_price:.2f}: {iv:.4%}")
+
+
+# Zero Coupon Bond
+bond = ZeroCouponBond(maturity=1.0)
+r0_stock = Stock(spot=0.05)  # initial short rate
+dummy_rate = Rate(rate=0.0)  # ignored by rate models
+
+vasicek = VasicekModel(params={"kappa": 0.86, "theta": 0.09, "sigma": 0.02})
+cir = CIRModel(params={"kappa": 0.86, "theta": 0.09, "sigma": 0.02})
+
+p_vasi = cf_technique.price(bond, r0_stock, vasicek, dummy_rate).price
+p_cir = cf_technique.price(bond, r0_stock, cir, dummy_rate).price
+
+print(f"Vasicek ZCB Price: {p_vasi:.4f}")
+print(f"CIR ZCB Price:     {p_cir:.4f}")
+```
+
+For more details, see the [API Guide](https://diljit22.github.io/quantFin/guide/API/).
+
+---
+
+## Documentation
+
+The full documentation includes installation instructions, user guides, examples, and a complete API reference.
+
+* **[View the Official Documentation](https://diljit22.github.io/quantFin/)**
+
+### Guides
+
+* [Introduction](https://diljit22.github.io/quantFin/guide/introduction/)
+* [Installation](https://diljit22.github.io/quantFin/guide/installation/)
+* [Getting Started](https://diljit22.github.io/quantFin/guide/getting_started/)
+* [CLI](https://diljit22.github.io/quantFin/guide/CLI/)
+* [Dashboard](https://diljit22.github.io/quantFin/guide/dashboard/)
+* [API](https://diljit22.github.io/quantFin/guide/API/)
+* [Examples](https://diljit22.github.io/quantFin/guide/examples/)
+* [API Reference](https://diljit22.github.io/quantFin/reference/)
+
+## Contributing
+
+Contributions are welcome; see [CONTRIBUTING](/CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

{optpricing-2.3.1 → optpricing-2.3.2}/codecov.yml

@@ -3,3 +3,5 @@ coverage:
   status:
     project:
       enabled: false
+ignore:
+  - "src/optpricing/dashboard/pages/*"

optpricing-2.3.2/docs/guide/API.md

@@ -0,0 +1,127 @@
+# Guide: Programmatic API
+
+The `optpricing` Python API provides a powerful, object-oriented framework for building custom financial analysis scripts and workflows. Its modular design allows you to mix and match models, techniques, and data to suit your specific research needs.
+
+This guide covers the fundamental components and provides examples for common use cases.
+
+---
+
+## Core Concepts: Atoms, Models, and Techniques
+
+All programmatic workflows are built on three core components:
+
+1. **Atoms**: Immutable data classes like `Option`, `Stock`, and `Rate` that represent the basic inputs.
+2. **Models**: Classes representing financial theories, such as `BSMModel` or `HestonModel` (and many others).
+3. **Techniques**: Classes representing numerical algorithms, such as `ClosedFormTechnique` or `MonteCarloTechnique` (and many others).
+
+You instantiate these components and pass them to a technique's `price` method to get a result.
+
+## Example 1: Pricing a Standard European Option
+
+This example demonstrates the most common use case: pricing a European call option using the Black-Scholes-Merton model's analytic formula.
+
+```python
+from optpricing import Option, OptionType, Rate, Stock
+from optpricing.models import BSMModel
+from optpricing.techniques import ClosedFormTechnique
+
+# 1. Define the core Atoms
+option = Option(strike=105, maturity=1.0, option_type=OptionType.CALL)
+stock = Stock(spot=100.0, dividend=0.01)
+rate = Rate(rate=0.05)
+
+# 2. Instantiate the Model and Technique
+bsm_model = BSMModel(params={"sigma": 0.20})
+cf_technique = ClosedFormTechnique()
+
+# 3. Calculate the price and Greeks
+result = cf_technique.price(option, stock, bsm_model, rate)
+delta = cf_technique.delta(option, stock, bsm_model, rate)
+gamma = cf_technique.gamma(option, stock, bsm_model, rate)
+
+print(f"The option price is: {result.price:.4f}")
+print(f"Delta: {delta:.4f}")
+print(f"Gamma: {gamma:.4f}")
+```
+
+## Example 2: Pricing an American Option with Monte Carlo
+
+The API's flexibility allows you to easily switch to more complex scenarios. Here, we price an American option using the Heston model with the Longstaff-Schwartz Monte Carlo method.
+
+```python
+from optpricing.models import HestonModel
+from optpricing.techniques import AmericanMonteCarloTechnique
+
+# 1. Define an American option Atom
+american_option = Option(strike=105, maturity=1.0, option_type=OptionType.PUT)
+
+# 2. Instantiate a more complex model and the appropriate technique
+heston_model = HestonModel(params={
+    "v0": 0.04,
+    "kappa": 2.0,
+    "theta": 0.05,
+    "rho": -0.7,
+    "vol_of_vol": 0.5
+})
+lsmc_technique = AmericanMonteCarloTechnique(n_paths=20000, n_steps=100)
+
+# 3. Calculate the price
+# Note: The 'v0' parameter is passed as a keyword argument for the simulation
+result = lsmc_technique.price(
+    american_option,
+    stock,
+    heston_model,
+    rate,
+    v0=heston_model.params['v0']
+)
+print(f"The American option price is: {result.price:.4f}")
+```
+
+## Example 3: Calculating Implied Volatility
+
+The library includes mixins for common tasks like calculating implied volatility. This functionality is available on most technique objects.
+
+```python
+# Using the components from Example 1
+target_price = 7.50
+
+iv = cf_technique.implied_volatility(
+    option,
+    stock,
+    bsm_model,
+    rate,
+    target_price=target_price
+)
+
+print(f"Implied volatility for a target price of ${target_price:.2f}: {iv:.4%}")
+```
+
+## Example 4: Pricing an Interest Rate Product
+
+The framework is not limited to equity options. It can be used to price other derivatives, such as Zero-Coupon Bonds using short-rate models.
+
+```python
+from optpricing.atoms import ZeroCouponBond
+from optpricing.models import VasicekModel
+
+# 1. Define a ZeroCouponBond Atom
+bond = ZeroCouponBond(maturity=5.0, face_value=1000.0)
+
+# 2. For rate models, the 'stock.spot' is re-interpreted as the initial short rate r0
+r0_stock = Stock(spot=0.03)
+# The 'rate' atom is ignored by rate models but required by the technique signature
+dummy_rate = Rate(rate=0.0)
+
+# 3. Instantiate the Vasicek model
+vasicek_model = VasicekModel(params={"kappa": 0.86, "theta": 0.05, "sigma": 0.02})
+
+# 4. Price using the ClosedFormTechnique
+price_result = cf_technique.price(bond, r0_stock, vasicek_model, dummy_rate)
+print(f"Price of 5-Year ZCB under Vasicek model: ${price_result.price:.2f}")
+```
+
+## Advanced Usage: Extending the Library
+
+The library's true power lies in its extensibility. By inheriting from `BaseModel` and `BaseTechnique`, you can easily add your own custom models and pricing algorithms, which will automatically integrate with the existing framework.
+
+For a complete and detailed list of all available classes, methods, and functions, please consult the full **[API Reference](../reference/index.md)**.

optpricing-2.3.2/docs/guide/CLI.md

@@ -0,0 +1,150 @@
+# Guide: Command-Line Interface (CLI)
+
+The `optpricing` CLI is a powerful tool for performing complex financial analysis directly from your terminal. It provides access to pricing, data management, calibration, and backtesting workflows without requiring any Python scripting.
+
+## Main Commands
+
+These are the top-level commands available directly after `optpricing`.
+
+### `price`
+
+Prices a single option using live market data. This command automatically fetches the underlying spot price, estimates the dividend yield, and calculates an implied risk-free rate from the live option chain before pricing the specified contract.
+
+**Usage:**
+`optpricing price [OPTIONS]`
+
+**Key Options:**
+
+- `--ticker, -t TEXT`: Stock ticker (e.g., 'AAPL'). **[required]**
+- `--strike, -k FLOAT`: Strike price. **[required]**
+- `--maturity, -T TEXT`: Maturity date in YYYY-MM-DD format. **[required]**
+- `--type TEXT`: 'call' or 'put'. [default: call]
+- `--style TEXT`: 'european' or 'american'. [default: european]
+- `--model, -m TEXT`: Model to use (e.g., 'BSM', 'Heston'). [default: BSM]
+- `--param TEXT`: Set a model parameter (e.g., `sigma=0.2`). Can be used multiple times.
+
+**Example:**
+
+```bash
+# Price an American put on TSLA using the Heston model
+optpricing price -t TSLA -k 290 -T 2026-01-16 --style american --model Heston
+```
+
+### `calibrate`
+
+Calibrates model parameters to saved market data. This workflow loads a market snapshot, filters for liquid options, and uses an optimization routine to find the model parameters that best fit the observed market prices.
+
+**Usage:**
+`optpricing calibrate [OPTIONS]`
+
+**Key Options:**
+
+- `--ticker, -t TEXT`: Ticker for the snapshot to use. **[required]**
+- `--model, -m TEXT`: Model to calibrate ('BSM' or 'Merton'). Can be used multiple times. **[required]**
+- `--date, -d TEXT`: Snapshot date (YYYY-MM-DD). Defaults to the latest available.
+
+**Example:**
+
+```bash
+# Calibrate the BSM and Merton models to a specific historical snapshot
+optpricing calibrate -t SPY -m BSM -m Merton --date 2025-07-08
+```
+
+### `backtest`
+
+Runs a historical out-of-sample backtest for a model. The workflow iterates through all available historical data, calibrates the model on day `D`, and evaluates its pricing accuracy on the unseen data from day `D+1`.
+
+**Usage:**
+`optpricing backtest [OPTIONS]`
+
+**Key Options:**
+
+- `--ticker, -t TEXT`: Ticker to backtest. **[required]**
+- `--model, -m TEXT`: Model to backtest. **[required]**
+- `--verbose, -v`: Enable detailed logging output.
+
+**Example:**
+
+```bash
+optpricing backtest -t SPY -m BSM -v
+```
+
+### `dashboard`
+
+Launches the interactive Streamlit dashboard.
+
+**Usage:**
+`optpricing dashboard`
+
+---
+
+## Sub-Command Groups
+
+### `data`
+
+Tools for downloading and managing market data.
+
+**Usage:**
+`optpricing data [COMMAND]`
+
+**Commands:**
+
+- `download`: Downloads and saves historical log returns for one or more tickers.
+
+  ```bash
+  optpricing data download --ticker AAPL --period 5y
+  ```
+
+- `snapshot`: Fetches and saves a live market data snapshot of the full option chain.
+
+  ```bash
+  optpricing data snapshot --ticker TSLA
+  ```
+
+- `dividends`: Fetches and displays live forward dividend yields.
+
+  ```bash
+  optpricing data dividends --ticker JPM
+  ```
+
+### `demo`
+
+Runs benchmark scripts from the `examples/` directory (requires a local clone of the repository).
+
+**Usage:**
+`optpricing demo [COMMAND]`
+
+**Commands:**
+
+- `european`: Runs the European options benchmark across all models.
+
+  ```bash
+  optpricing demo european --model Heston
+  ```
+
+- `american`: Runs the American options benchmark.
+
+  ```bash
+  optpricing demo american
+  ```
+
+- `rates`: Runs the interest rate models benchmark.
+
+  ```bash
+  optpricing demo rates
+  ```
+
+### `tools`
+
+Miscellaneous financial utility tools.
+
+**Usage:**
+`optpricing tools [COMMAND]`
+
+**Commands:**
+
+- `implied-rate`: Calculates the implied risk-free rate from a live call-put pair using put-call parity.
+
+  ```bash
+  optpricing tools implied-rate --ticker SPY --strike 630 --maturity 2025-12-19
+  ```