quant-greeks-cli 0.1.0
A CLI tool for option pricing and Greeks calculation
Requires Python: >=3.7

# Quant Greeks CLI Tool

![CI](https://github.com/Patience-Fuglo/quant-greeks-cli/actions/workflows/ci.yml/badge.svg)

A lightweight command-line tool for calculating option prices and Greeks using Black-Scholes and Binomial models. Built for traders, quants, and finance students to analyze options risk and sensitivity directly from your terminal.

---

## Features

- **Comprehensive Greeks:** Delta, Gamma, Vega, Theta, Rho for Black-Scholes and Binomial (European/American)
- **Flexible Option Pricing:** Black-Scholes and Binomial models with American/European support
- **Implied Volatility Solver:** Calculate implied volatility given a market price
- **Dividend Yield Support:** Pass continuous dividend yield with `--q`
- **Batch/Portfolio Processing:** Process CSV/JSON and output table, CSV, or JSON
- **Parameter Sweep & Plotting:** Analyze/visualize how Greeks change with any parameter and save as tables, CSV, JSON, or PNG plot
- **Put-Call Parity Checker:** Verify arbitrage-free pricing with a simple CLI command
- **Robust CLI & Error Handling:** Helpful messages, input validation, and usage hints
- **100% Test Coverage:** Core logic thoroughly tested, including CLI behaviors
- **CI/CD:** GitHub Actions for continuous integration

---

## Installation

From PyPI:
```bash
pip install quant-greeks-cli
```
Or from source:
```bash
git clone https://github.com/Patience-Fuglo/quant-greeks-cli.git
cd quant-greeks-cli
pip install -r requirements.txt
pip install .
```

---

## Usage

Basic Greeks calculation:
```bash
quant-greeks --option_type call --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2
```
For help:
```bash
quant-greeks --help
```

### Option Argument Guide

- `--option_type`: `"call"` or `"put"`
- `--S`: Spot price
- `--K`: Strike price
- `--T`: Time to maturity (years)
- `--r`: Annual risk-free rate (decimal)
- `--sigma`: Volatility (decimal)
- `--q`: Continuous dividend yield (optional, default 0)

---

## Example Features

- **Implied Volatility Calculation:**
  ```bash
  python cli.py --implied_vol --option_type call --S 100 --K 100 --T 1 --r 0.05 --price 10
  ```
  Output:
  ```
  Implied volatility: 0.18797
  ```
- **Binomial Pricing (with American support):**
  ```bash
  python cli.py --model binomial --option_type put --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2 --steps 200 --american
  ```
- **Pretty table/CSV/JSON/plot outputs**
- **Parameter sweep:**
  ```bash
  python cli.py sweep --param S --start 80 --end 120 --steps 5 --option_type call --K 100 --T 1 --r 0.05 --sigma 0.2 --output plot --plot_metric delta
  ```
  - `--output plot`: Save a PNG file (`plot.png`) of the sweep result in your working directory.
  - `--plot_metric`: Metric to plot on the y-axis (price, delta, gamma, vega, theta, rho).

- **Portfolio/batch processing:**
  ```bash
  python cli.py batch --file my_options.csv --output table
  ```

**Supported models and parameters:**
- `--model`: Choose `binomial` (default: `black-scholes`)
- `--steps`: Number of steps for binomial (default: 100)
- `--american`: Enable American-style exercise for binomial pricing

---

## Put-Call Parity Checker

You can check put-call parity directly from the CLI:

```bash
python cli.py parity --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2 --q 0.03
```
**Sample Output**
```
Put-Call Parity holds: True
```

---

## Output Formats

Choose how results are displayed or saved:

- **plain** (default): One result per line
- **table**: Formatted terminal table
- **csv**: Save results for further analysis
- **json**: Machine-readable output
- **plot**: Save parameter sweep as PNG

### Examples

**Pretty table:**
```bash
python cli.py price --option_type call --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2 --output table
```

**CSV export:**
```bash
python cli.py price --option_type call --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2 --output csv --csvfile myresults.csv
```

**Classic (plain):**
```bash
python cli.py price --option_type call --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2
```

---

## Batch/Portfolio Processing

You can process multiple options at once from a CSV or JSON file using the `batch` subcommand.

### Usage

```bash
python cli.py batch --file my_options.csv --output table
python cli.py batch --file my_options.json --output csv
```

- Replace `my_options.csv` or `my_options.json` with your file path.
- Use `--output table`, `--output csv`, or `--output json` to choose the output format.
- Use `--csvfile <filename>` to specify the output CSV name (optional).

### Example CSV File

```csv
option_type,S,K,T,r,sigma,q,model,steps,american
call,100,100,1,0.05,0.2,0.0,black-scholes,100,False
put,50,45,0.5,0.03,0.25,0.01,black-scholes,100,False
call,120,110,2,0.04,0.22,0.01,binomial,200,True
put,80,85,0.8,0.02,0.18,0.0,binomial,150,False
```

### Example JSON File

```json
[
  {"option_type":"call","S":100,"K":100,"T":1,"r":0.05,"sigma":0.2,"q":0.0,"model":"black-scholes","steps":100,"american":false},
  {"option_type":"put","S":50,"K":45,"T":0.5,"r":0.03,"sigma":0.25,"q":0.01,"model":"black-scholes","steps":100,"american":false}
]
```

---

## Parameter Sweep & Plotting

You can analyze how Greeks and prices change as you vary a single parameter, and visualize the results.

### Usage

```bash
python cli.py sweep --param <PARAM> --start <START> --end <END> --steps <N> --option_type <call|put> --S <S> --K <K> --T <T> --r <r> --sigma <sigma> [--q <q>] --output plot --plot_metric price
```

- `--param`: S, K, T, r, sigma, or q
- `--plot_metric`: price, delta, gamma, vega, theta, or rho

### Output

- PNG plot saved to `plot.png`
- Table, CSV, or JSON output for further analysis

---
## Advanced Testing and Coverage

This project includes a robust suite of automated tests, reflecting best practices in quantitative finance software development:

- **Comprehensive Unit and Integration Testing:**  
  All core option pricing functions (binomial, Black-Scholes, Greeks) are covered with a range of tests, including edge cases such as zero volatility, American vs. European options, and invalid parameter handling.

- **CLI and Batch Testing:**  
  The command-line interface is tested end-to-end for batch processing, file I/O, and user error handling.

- **Substantial Code Coverage:**  
  Recent test runs demonstrate major improvements in coverage:
  - **binomial.py:** Coverage increased from 3% to 85%
  - **greeks.py:** Coverage increased from 22% to 69%
  - **All 14 tests pass**, and the coverage report is now a meaningful indicator of code reliability.

- **Continuous Improvement:**  
  Tests are designed to make it easy to add new models and features with confidence. Coverage reports guide further development and ensure that new code is tested.

- **Tools Used:**  
  - `pytest` for test execution
  - `pytest-cov` for coverage measurement

**Result:**  
This testing approach ensures that the codebase is reliable, maintainable, and ready for professional quantitative finance workflows. 

---

*See the `/tests` directory and the latest coverage report for details, or run `pytest --cov=.` to check coverage yourself.*
## Error Handling

Smart error messages for:
- Missing/invalid arguments or parameter combinations
- Incompatible option/model settings
- Required parameters for implied volatility or sweep
- File format validation for batch mode

**Examples:**
```bash
python cli.py price --option_type call --S -100 --K 100 --T 1 --r 0.05 --sigma 0.2
# Error(s): Stock price S must be positive.

python cli.py price --option_type call --S 100 --K 100 --T 1 --r 0.05 --sigma 0.2 --model black-scholes --american
# Error(s): Black-Scholes model does not support American options. Use binomial model with --american.
```

---

## Testing

Run all tests using:
```bash
pytest
```
Check coverage:
```bash
pytest --cov=.
```
Generate HTML report:
```bash
pytest --cov=. --cov-report=html
```
Open `htmlcov/index.html` for details.

### Test Coverage

- All core logic for pricing and Greeks is tested, including edge cases and American options.
- CLI behaviors (such as help and error messages) are included using subprocess.
- Example test files:
  - `tests/test_binomial.py` (European and American, edge/exception cases)
  - `tests/test_black_scholes.py` (normal and error branches)
  - `tests/test_greeks.py` (normal and error branches)
  - `tests/test_implied_vol.py` (normal and error branches)
  - `tests/test_cli.py` (CLI help and error response)
- CLI code itself is not directly unit tested, but its output and error handling are verified through CLI tests.

---


## Contributing

Pull requests are welcome! Please add tests for any new features and follow the standard fork/branch/PR workflow.

---

## License

MIT License

---

## Author

Patience Fuglo

```