Metadata-Version: 2.4
Name: trademan
Version: 0.1.0
Summary: Trade and analyze stocks with portfolio optimization
Author-email: Kevin Russell <kevin@ottermatics.com>
License: MIT
Project-URL: Homepage, https://github.com/ottermatics/trademan
Project-URL: Repository, https://github.com/ottermatics/trademan
Project-URL: Issues, https://github.com/ottermatics/trademan/issues
Keywords: trading,portfolio,optimization,stocks,finance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: PyPortfolioOpt
Requires-Dist: randomname
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: cvxpy
Requires-Dist: yfinance
Requires-Dist: matplotlib
Requires-Dist: diskcache
Requires-Dist: scikit-learn
Requires-Dist: pandas
Requires-Dist: pytz
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black>=21.7b0; extra == "dev"
Requires-Dist: flake8>=3.7.8; extra == "dev"
Requires-Dist: bump2version>=1.0.1; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: sphinx>=4.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: coverage>=4.5.4; extra == "dev"
Requires-Dist: tox>=3.14.0; extra == "dev"
Requires-Dist: watchdog>=0.9.0; extra == "dev"
Requires-Dist: tomli>=1.2.0; python_version < "3.11" and extra == "dev"
Dynamic: license-file

# Trademan

[![PyPI version](https://badge.fury.io/py/trademan.svg)](https://badge.fury.io/py/trademan)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://ottermatics.github.io/trademan/)

A Python library and CLI tool for gathering market data and generating optimal portfolios using modern portfolio theory.

## Features

- 📊 **Market Data Collection**: Automated downloading and caching of S&P 500 and ETF data via yfinance
- 🎯 **Portfolio Optimization**: Multiple optimization strategies (Sharpe ratio, minimum volatility, etc.)
- 📈 **Visualization**: Generate beautiful portfolio allocation charts
- 🚀 **CLI Interface**: Easy-to-use command-line tools for quick analysis
- 🐍 **Python API**: Full programmatic access for custom workflows
- 💾 **Smart Caching**: Intelligent data caching to minimize API calls

## Installation

Install from PyPI:
```bash
pip install trademan
```

Install from source:
```bash
pip install git+https://github.com/ottermatics/trademan.git
```

## Quick Start

### CLI Usage

1. **Download Market Data**:
```bash
market_dl  # Downloads S&P 500 and ETF data
```

2. **Generate a Portfolio**:
```bash
# Create a Sharpe-optimized portfolio with $10,000 allocation
trademan -cls stocks -alloc 10000 -opt sharpe

# Minimum volatility ETF portfolio  
trademan -cls etfs -opt min_volatility -alloc 100000 -in QQQ,SPY,VTI
```

### Python API

```python
import trademan

# Get stock data for specific tickers
data = trademan.get_tickers(['AAPL', 'MSFT', 'GOOGL'])

# Create optimized portfolio
weights = trademan.make_portfolio(
    data, 
    opt='sharpe',           # Optimization method
    risk='ledoit_wolf',     # Risk model  
    allocate_amount=10000   # Dollar amount
)

# Visualize the portfolio
fig, ax = trademan.plot_portfolio(weights)
```

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `-cls` | Asset class: `etfs`, `stocks`, `all` | `all` |
| `-opt` | Optimization: `sharpe`, `min_volatility`, `eff_return`, `eff_risk` | `sharpe` |
| `-risk` | Risk model: `covariance`, `ledoit_wolf` | `ledoit_wolf` |
| `-alloc` | Amount to allocate (shows share counts) | None |
| `-gamma` | Weight regularization (higher = more diversified) | 2 |
| `-in` | Include specific tickers (comma-separated) | None |
| `-ex` | Exclude specific tickers (comma-separated) | None |
| `-min-wght` | Minimum weight threshold for assets | 0.01 |
| `-max-wght` | Maximum weight limit per asset | None |

## Configuration

Set environment variables to customize data storage:

```bash
export TRADEMAN_DATA_DIR="/path/to/data"      # Market data cache
export TRADEMAN_MEDIA_DIR="/path/to/charts"   # Generated charts
```

## Examples

### 1. Best Performing S&P 500 Stocks
Create a portfolio favoring established companies with cycle penalties:

```bash
trademan -cls stocks -gamma 1 -alloc 10000 -cycl-err 10 -max-wght 0.2
```

![Stocks Portfolio](./media/Stocks.png)

### 2. Low Volatility ETF Portfolio
Generate a conservative ETF allocation:

```bash
trademan -cls etfs -gamma 0.1 -alloc 100000 \
  -in QQQ,SCHG,VGT,SLV,VIG,SPY,VOO,VUG,IAU,PAVE \
  -opt min_volatility
```

![ETF Portfolio](./media/ETFS_Min_Volatility.png)

## How It Works

1. **Data Collection**: Downloads historical price data using yfinance
2. **Risk Modeling**: Calculates covariance matrices with Ledoit-Wolf shrinkage
3. **Return Estimation**: Uses mean historical returns with optional adjustments
4. **Optimization**: Applies modern portfolio theory via PyPortfolioOpt
5. **Allocation**: Converts weights to discrete share quantities
6. **Visualization**: Creates publication-ready portfolio charts

## Dependencies

- **PyPortfolioOpt**: Portfolio optimization algorithms
- **yfinance**: Market data source
- **pandas/numpy**: Data manipulation
- **matplotlib**: Visualization
- **diskcache**: Data caching
- **scikit-learn**: Additional analytics

## Development

Install development dependencies:
```bash
pip install -e .[dev]
```

Run tests:
```bash
pytest
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please read [CONTRIBUTING.rst](CONTRIBUTING.rst) for guidelines.
