pfisca 0.1.0
A comprehensive financial planning tool
License: MIT
Requires Python: >=3.11

# Prism

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A Python-based financial planning library for projecting net worth over time using Monte Carlo simulation. This tool helps individuals and families model their financial future by simulating various income, expense, investment, and tax scenarios across multiple years, with a focus on FIRE (Financial Independence, Retire Early) planning.

## Table of Contents

- [Prism](#prism)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Quick Start](#quick-start)
    - [Installation](#installation)
      - [From Source](#from-source)
      - [Using pip (when published)](#using-pip-when-published)
    - [Basic Usage](#basic-usage)
    - [Using as a Python Library](#using-as-a-python-library)
      - [Example: Calculate Stock Metrics](#example-calculate-stock-metrics)
      - [Example: Risk Calculations](#example-risk-calculations)
  - [Documentation](#documentation)
    - [Quick Links](#quick-links)
    - [Documentation Sections](#documentation-sections)
  - [Examples](#examples)
  - [Contributing](#contributing)
    - [Development Setup](#development-setup)
    - [Code Style](#code-style)
  - [Requirements](#requirements)
  - [License](#license)
  - [Future Enhancements](#future-enhancements)
  - [Acknowledgments](#acknowledgments)

## Features

- 💰 **Income Modeling**: Multiple sources (salaries, bonuses, RSUs) with growth and variability
- 📊 **Tax Calculations**: Federal, state, and payroll taxes with proper filing status
- 💸 **Expense Tracking**: Fixed, inflation-adjusted, or percentage-based expenses
- 📈 **Investment Simulation**: Monte Carlo simulation with correlated returns
- 🏦 **Portfolio Management**: Real market data integration for individual stocks
- 📉 **Stock Analysis**: Comprehensive metrics (alpha, beta, Sharpe, VaR, drawdown, etc.)
- 🔄 **Trading**: High-performance backtesting framework for trading strategies
- 🔥 **FIRE Planning**: Calculate timelines for Coast, Lean, Chubby, and Fat FIRE
- 💵 **Paycheck Calculations**: Detailed per-paycheck breakdowns with taxes and deductions

## Quick Start

### Installation

#### From Source

```bash
# Clone the repository
git clone https://github.com/adityahemanth/prism.git
cd prism

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

#### Using pip (when published)

```bash
pip install prism
```

### Basic Usage

Create a simple config file:

```yaml
# my_config.yaml
persons:
  - name: "Person 1"
    income_sources:
      - type: "base_salary"
        base_amount: 200000.0
```

Run the simulation:

```bash
python src/main.py my_config.yaml
```

This uses smart defaults for taxes, retirement, expenses, and investments. See [Getting Started Guide](docs/getting-started.md) for details.

### Using as a Python Library

```python
from prism import FinanceProjection

# Load configuration and run simulation
projection = FinanceProjection.from_config("config.yaml")
results = projection.run_simulation()
median_net_worth = results['net_worth_percentiles'][50]
print(f"Median net worth: ${median_net_worth:,.2f}")
```

#### Example: Calculate Stock Metrics

```python
from prism import calculate_stock_metrics, format_stock_metrics

# Calculate comprehensive metrics for a stock
metrics = calculate_stock_metrics("AAPL", years=5, benchmark_ticker="SPY")

# Print formatted output
print(format_stock_metrics(metrics))

# Access individual metrics
print(f"Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"Beta: {metrics.beta:.2f}")
print(f"Max Drawdown: {metrics.max_drawdown:.2%}")
```

#### Example: Risk Calculations

```python
import pandas as pd
from prism import (
    calculate_volatility,
    calculate_max_drawdown,
    calculate_sharpe_ratio
)

# Daily returns
returns = pd.Series([0.01, -0.02, 0.03, -0.01, 0.02] * 50)

# Calculate risk metrics
volatility = calculate_volatility(returns, annualized=True, periods_per_year=252)
max_dd = calculate_max_drawdown(returns)
sharpe = calculate_sharpe_ratio(returns, risk_free_rate=0.02, periods_per_year=252)

print(f"Volatility: {volatility:.2%}")
print(f"Max Drawdown: {max_dd:.2%}")
print(f"Sharpe Ratio: {sharpe:.2f}")
```

## Documentation

📚 **[Full Documentation](docs/README.md)** - Complete documentation index

### Quick Links

- **[Getting Started](docs/getting-started.md)** - Installation and basic usage
- **[Configuration Guide](docs/guides/configuration.md)** - Creating and customizing config files
- **[Financial Metrics Guide](docs/guides/financial-metrics.md)** - Comprehensive guide to metrics (Sharpe, Beta, VaR, etc.)
- **[Risk Calculations Guide](docs/guides/risk-calculations.md)** - Step-by-step risk analysis
- **[API Reference](docs/api/index.md)** - Complete API documentation
- **[Examples](examples/)** - Code examples

### Documentation Sections

- **[Guides](docs/guides/)** - Step-by-step guides for common tasks
  - [Configuration](docs/guides/configuration.md)
  - [Projections](docs/guides/projections.md)
  - [FIRE Planning](docs/guides/fire-planning.md)
  - [Financial Metrics](docs/guides/financial-metrics.md)
  - [Risk Calculations](docs/guides/risk-calculations.md)
- **[Topics](docs/topics/)** - Deep dives into specific features
  - [Trading](docs/topics/trading.md)
  - [Portfolio Management](docs/topics/portfolio-management.md)
  - [Stock Metrics](docs/topics/stock-metrics.md)
  - [Tax Calculations](docs/topics/tax-calculations.md)
- **[API Reference](docs/api/)** - Complete API documentation
- **[Reference](docs/reference/)** - Methodology and configuration reference

## Examples

Check out the [examples](examples/) directory for complete working examples:

- `library_usage.py` - Basic library usage
- `trading_example.py` - Simple backtesting example
- `advanced_trading_example.py` - Advanced backtesting strategies
- `portfolio_holdings_example.py` - Portfolio analysis
- `stock_metrics_example.py` - Stock metrics calculation

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Development Setup

```bash
# Clone and setup
git clone https://github.com/adityahemanth/prism.git
cd prism
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=html
```

### Code Style

- Follow PEP 8 style guidelines
- Use type hints where appropriate
- Write tests for new features
- Update documentation for API changes

## Requirements

- Python 3.9+
- NumPy >= 2.0.0
- pandas >= 2.0.0
- PyYAML >= 6.0.0
- yfinance >= 0.2.0
- scipy >= 1.10.0
- vectorbt >= 0.25.0 (for trading/backtesting)

See [requirements.txt](requirements.txt) for the complete list.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details (if available).

## Future Enhancements

For a comprehensive list of planned features, see [TODO.md](TODO.md).

## Acknowledgments

- Built with [NumPy](https://numpy.org/) and [pandas](https://pandas.pydata.org/) for numerical computing
- Market data provided by [yfinance](https://github.com/ranaroussi/yfinance)
- Backtesting powered by [vectorbt](https://github.com/polakowo/vectorbt)

---

**Note**: This library is for educational and personal financial planning purposes. Always consult with a qualified financial advisor for professional financial advice.