markowizard 0.1.0__tar.gz

markowizard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Gustavo Furtado
+
+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.

markowizard-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: markowizard
+Version: 0.1.0
+Summary: Markowitz portfolio optimization and analysis library
+Author-email: GusFurtado <gustavofurtado2@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/OutliersAnalytics/MarkoWizard
+Project-URL: Repository, https://github.com/OutliersAnalytics/MarkoWizard
+Project-URL: Documentation, https://github.com/OutliersAnalytics/MarkoWizard#readme
+Project-URL: Issues, https://github.com/OutliersAnalytics/MarkoWizard/issues
+Keywords: portfolio,finance,optimization,markowitz,efficient-frontier
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Requires-Dist: scipy>=1.8
+Requires-Dist: yfinance>=0.1.63
+Requires-Dist: plotly>=5.10
+Dynamic: license-file
+
+# MarkoWizard
+
+A modern Python library for Markowitz portfolio optimization and analysis.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+> **Previously known as _Diversificador_.** The original portfolio-analysis web app
+> built with [Dash](https://dash.plotly.com/) is no longer maintained, but it is
+> preserved on the [`dash-deprecated`](../../tree/dash-deprecated) branch for reference.
+
+## Features
+
+- **Markowitz Mean-Variance Optimization** — Compute the efficient frontier using `scipy.optimize`
+- **Capital Allocation Line** — Mix risky portfolios with risk-free assets
+- **Visualization** — Plotly-based charts for efficient frontier, allocation pie, CAL, correlation heatmaps, and price timelines
+- **Data Fetching** — Optional convenience functions for downloading market data via yfinance
+- **Web Application** — FastAPI backend with a dark-themed interactive frontend
+
+## Installation
+
+```bash
+pip install markowizard
+```
+
+That's everything the library needs: optimization (`scipy`), market-data
+fetching (`yfinance`), and visualization (`plotly`). No optional extras.
+
+## Quick Start (Library)
+
+```python
+from markowizard import MarkowitzOptimizer, CapitalAllocator
+from markowizard.data import fetch_prices, compute_monthly_returns
+from markowizard.visualization import efficiency_frontier_plot
+
+# Fetch prices and compute monthly returns (decimal form, e.g. 0.01 = 1%)...
+prices = fetch_prices(["AAPL", "MSFT", "GOOGL", "SPY"], period="5y")
+returns = compute_monthly_returns(prices)
+# ...or bring your own returns DataFrame (assets as columns).
+
+# Optimize
+optimizer = MarkowitzOptimizer(returns)
+portfolios = optimizer.optimize()
+
+# Compute Sharpe ratios (provide monthly risk-free rate)
+risk_free_rate = 0.005  # 0.5% per month
+portfolios = optimizer.compute_sharpe(risk_free_rate)
+
+# Plot the efficient frontier
+fig = efficiency_frontier_plot(portfolios, highlight_portfolio=50)
+fig.show()
+
+# Best portfolio (maximum Sharpe ratio)
+best = optimizer.max_sharpe_portfolio()
+print(best)
+
+# Capital allocation line
+allocator = CapitalAllocator(best, risk_free_rate)
+cal_points = allocator.capital_allocation_line(steps=21)
+```
+
+## Web Application
+
+An interactive web UI (FastAPI + a dark-themed frontend) lives in `backend/` and
+`frontend/`. It is **not part of the PyPI package** — run it from the container
+image or a clone.
+
+### Using Docker
+
+```bash
+docker run -p 8000:8000 ghcr.io/outliersanalytics/markowizard:latest
+```
+
+### From a clone
+
+```bash
+git clone https://github.com/OutliersAnalytics/MarkoWizard
+cd MarkoWizard
+uv run --with-requirements backend/requirements.txt uvicorn backend.main:app --port 8000
+```
+
+Open [http://localhost:8000](http://localhost:8000) — the app auto-submits with
+default tickers on load.
+
+It exposes a single endpoint, `POST /api/analyze`:
+
+```json
+{
+  "tickers": ["AAPL", "MSFT", "GOOGL", "SPY"],
+  "period": "5y",
+  "risk_free_rate": 0.005
+}
+```
+
+which returns the efficient frontier, max-Sharpe portfolio, capital-allocation-line
+points, and correlation matrix as JSON. The frontend renders the charts.
+
+## API Reference
+
+### `markowizard` (top-level)
+
+| Export | Description |
+|---|---|
+| `MarkowitzOptimizer` | Efficient frontier optimization (from `core`) |
+| `CapitalAllocator` | Risk-free asset allocation (from `allocation`) |
+| `__version__` | Package version string |
+
+### `markowizard.core`
+
+#### `MarkowitzOptimizer`
+
+```python
+class MarkowitzOptimizer:
+    def __init__(self, returns: pd.DataFrame) -> None
+    def optimize(self) -> pd.DataFrame
+    def compute_sharpe(self, risk_free_rate: float) -> pd.DataFrame
+    def max_sharpe_portfolio(self) -> pd.Series
+```
+
+**Constants**: `COL_RETURN = "Expected Return"`, `COL_RISK = "Risk"`, `COL_SHARPE = "Sharpe"`, `COL_RISK_FREE = "Risk-Free"`
+
+**Parameters**:
+- `returns`: DataFrame where each column is an asset and each row is a time period. Values must be in decimal form (e.g., 0.01 = 1%).
+
+**`optimize()`** computes the efficient frontier by solving 100 quadratic programming problems with varying risk-aversion parameters. Uses warm-starting: each iteration's solution seeds the next.
+
+**`compute_sharpe(risk_free_rate)`** adds a `Sharpe` column. `risk_free_rate` must match the period of `returns` (e.g., monthly).
+
+**`max_sharpe_portfolio()`** returns the tangency portfolio row.
+
+#### `MarkowitzOptimizer.portfolios` DataFrame columns
+
+| Column | Description |
+|---|---|
+| (ticker columns) | Asset weights (sum to 1, all >= 0) |
+| `Expected Return` | Expected portfolio return |
+| `Risk` | Portfolio standard deviation (risk) |
+| `Sharpe` | Sharpe ratio (after `compute_sharpe()`) |
+
+### `markowizard.allocation`
+
+#### `CapitalAllocator`
+
+```python
+class CapitalAllocator:
+    def __init__(self, portfolio: pd.Series | Mapping, risk_free_rate: float) -> None
+    @staticmethod
+    def weigh_risk_free(value: float, risk_free_value: float, p: float) -> float
+    def capital_allocation_line(self, steps: int = 21) -> list[dict]
+    def final_allocation(self, p: float) -> dict[str, float]
+    def expected_returns(self, p: float) -> tuple[float, float]
+```
+
+**`capital_allocation_line()`** returns points along the CAL, each with keys `p`, `expected_return`, `risk`, and `label`.
+
+**`final_allocation(p)`** returns asset weights including `Risk-Free` (risk-free portion).
+
+### `markowizard.visualization`
+
+| Function | Returns | Description |
+|---|---|---|
+| `efficiency_frontier_plot(portfolios, highlight_portfolio=0)` | `Figure` | Scatter plot of expected return vs risk |
+| `allocation_pie(portfolio)` | `Figure` | Pie chart of asset weights |
+| `capital_allocation_line_plot(cal_points, highlight_point=0)` | `Figure` | CAL risk-return trade-off |
+| `correlation_timeline(prices, ticker_a, ticker_b=None)` | `Figure` | Price history (single or normalized dual) |
+| `correlation_heatmap(corr_matrix)` | `Figure` | Correlation matrix heatmap |
+
+All visualization functions return Plotly `Figure` objects — call `.show()` to display.
+
+### `markowizard.data`
+
+| Function | Returns | Description |
+|---|---|---|
+| `fetch_prices(tickers, period="5y", auto_adjust=True)` | `pd.DataFrame` | Historical close prices from Yahoo Finance |
+| `compute_monthly_returns(prices)` | `pd.DataFrame` | Monthly returns from daily close prices |
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `core` | `MarkowitzOptimizer` — efficient frontier optimization |
+| `allocation` | `CapitalAllocator` — risk-free asset allocation |
+| `visualization` | Plotly chart functions (efficient frontier, pie, CAL, correlation) |
+| `data` | Market-data fetching and monthly-return helpers (yfinance) |
+
+The web application (`backend/`, `frontend/`) is kept in the repo but is not
+part of the installable package — see [Web Application](#web-application).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and contribution guidelines.
+
+## License
+
+MIT

markowizard-0.1.0/README.md

@@ -0,0 +1,195 @@
+# MarkoWizard
+
+A modern Python library for Markowitz portfolio optimization and analysis.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+> **Previously known as _Diversificador_.** The original portfolio-analysis web app
+> built with [Dash](https://dash.plotly.com/) is no longer maintained, but it is
+> preserved on the [`dash-deprecated`](../../tree/dash-deprecated) branch for reference.
+
+## Features
+
+- **Markowitz Mean-Variance Optimization** — Compute the efficient frontier using `scipy.optimize`
+- **Capital Allocation Line** — Mix risky portfolios with risk-free assets
+- **Visualization** — Plotly-based charts for efficient frontier, allocation pie, CAL, correlation heatmaps, and price timelines
+- **Data Fetching** — Optional convenience functions for downloading market data via yfinance
+- **Web Application** — FastAPI backend with a dark-themed interactive frontend
+
+## Installation
+
+```bash
+pip install markowizard
+```
+
+That's everything the library needs: optimization (`scipy`), market-data
+fetching (`yfinance`), and visualization (`plotly`). No optional extras.
+
+## Quick Start (Library)
+
+```python
+from markowizard import MarkowitzOptimizer, CapitalAllocator
+from markowizard.data import fetch_prices, compute_monthly_returns
+from markowizard.visualization import efficiency_frontier_plot
+
+# Fetch prices and compute monthly returns (decimal form, e.g. 0.01 = 1%)...
+prices = fetch_prices(["AAPL", "MSFT", "GOOGL", "SPY"], period="5y")
+returns = compute_monthly_returns(prices)
+# ...or bring your own returns DataFrame (assets as columns).
+
+# Optimize
+optimizer = MarkowitzOptimizer(returns)
+portfolios = optimizer.optimize()
+
+# Compute Sharpe ratios (provide monthly risk-free rate)
+risk_free_rate = 0.005  # 0.5% per month
+portfolios = optimizer.compute_sharpe(risk_free_rate)
+
+# Plot the efficient frontier
+fig = efficiency_frontier_plot(portfolios, highlight_portfolio=50)
+fig.show()
+
+# Best portfolio (maximum Sharpe ratio)
+best = optimizer.max_sharpe_portfolio()
+print(best)
+
+# Capital allocation line
+allocator = CapitalAllocator(best, risk_free_rate)
+cal_points = allocator.capital_allocation_line(steps=21)
+```
+
+## Web Application
+
+An interactive web UI (FastAPI + a dark-themed frontend) lives in `backend/` and
+`frontend/`. It is **not part of the PyPI package** — run it from the container
+image or a clone.
+
+### Using Docker
+
+```bash
+docker run -p 8000:8000 ghcr.io/outliersanalytics/markowizard:latest
+```
+
+### From a clone
+
+```bash
+git clone https://github.com/OutliersAnalytics/MarkoWizard
+cd MarkoWizard
+uv run --with-requirements backend/requirements.txt uvicorn backend.main:app --port 8000
+```
+
+Open [http://localhost:8000](http://localhost:8000) — the app auto-submits with
+default tickers on load.
+
+It exposes a single endpoint, `POST /api/analyze`:
+
+```json
+{
+  "tickers": ["AAPL", "MSFT", "GOOGL", "SPY"],
+  "period": "5y",
+  "risk_free_rate": 0.005
+}
+```
+
+which returns the efficient frontier, max-Sharpe portfolio, capital-allocation-line
+points, and correlation matrix as JSON. The frontend renders the charts.
+
+## API Reference
+
+### `markowizard` (top-level)
+
+| Export | Description |
+|---|---|
+| `MarkowitzOptimizer` | Efficient frontier optimization (from `core`) |
+| `CapitalAllocator` | Risk-free asset allocation (from `allocation`) |
+| `__version__` | Package version string |
+
+### `markowizard.core`
+
+#### `MarkowitzOptimizer`
+
+```python
+class MarkowitzOptimizer:
+    def __init__(self, returns: pd.DataFrame) -> None
+    def optimize(self) -> pd.DataFrame
+    def compute_sharpe(self, risk_free_rate: float) -> pd.DataFrame
+    def max_sharpe_portfolio(self) -> pd.Series
+```
+
+**Constants**: `COL_RETURN = "Expected Return"`, `COL_RISK = "Risk"`, `COL_SHARPE = "Sharpe"`, `COL_RISK_FREE = "Risk-Free"`
+
+**Parameters**:
+- `returns`: DataFrame where each column is an asset and each row is a time period. Values must be in decimal form (e.g., 0.01 = 1%).
+
+**`optimize()`** computes the efficient frontier by solving 100 quadratic programming problems with varying risk-aversion parameters. Uses warm-starting: each iteration's solution seeds the next.
+
+**`compute_sharpe(risk_free_rate)`** adds a `Sharpe` column. `risk_free_rate` must match the period of `returns` (e.g., monthly).
+
+**`max_sharpe_portfolio()`** returns the tangency portfolio row.
+
+#### `MarkowitzOptimizer.portfolios` DataFrame columns
+
+| Column | Description |
+|---|---|
+| (ticker columns) | Asset weights (sum to 1, all >= 0) |
+| `Expected Return` | Expected portfolio return |
+| `Risk` | Portfolio standard deviation (risk) |
+| `Sharpe` | Sharpe ratio (after `compute_sharpe()`) |
+
+### `markowizard.allocation`
+
+#### `CapitalAllocator`
+
+```python
+class CapitalAllocator:
+    def __init__(self, portfolio: pd.Series | Mapping, risk_free_rate: float) -> None
+    @staticmethod
+    def weigh_risk_free(value: float, risk_free_value: float, p: float) -> float
+    def capital_allocation_line(self, steps: int = 21) -> list[dict]
+    def final_allocation(self, p: float) -> dict[str, float]
+    def expected_returns(self, p: float) -> tuple[float, float]
+```
+
+**`capital_allocation_line()`** returns points along the CAL, each with keys `p`, `expected_return`, `risk`, and `label`.
+
+**`final_allocation(p)`** returns asset weights including `Risk-Free` (risk-free portion).
+
+### `markowizard.visualization`
+
+| Function | Returns | Description |
+|---|---|---|
+| `efficiency_frontier_plot(portfolios, highlight_portfolio=0)` | `Figure` | Scatter plot of expected return vs risk |
+| `allocation_pie(portfolio)` | `Figure` | Pie chart of asset weights |
+| `capital_allocation_line_plot(cal_points, highlight_point=0)` | `Figure` | CAL risk-return trade-off |
+| `correlation_timeline(prices, ticker_a, ticker_b=None)` | `Figure` | Price history (single or normalized dual) |
+| `correlation_heatmap(corr_matrix)` | `Figure` | Correlation matrix heatmap |
+
+All visualization functions return Plotly `Figure` objects — call `.show()` to display.
+
+### `markowizard.data`
+
+| Function | Returns | Description |
+|---|---|---|
+| `fetch_prices(tickers, period="5y", auto_adjust=True)` | `pd.DataFrame` | Historical close prices from Yahoo Finance |
+| `compute_monthly_returns(prices)` | `pd.DataFrame` | Monthly returns from daily close prices |
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `core` | `MarkowitzOptimizer` — efficient frontier optimization |
+| `allocation` | `CapitalAllocator` — risk-free asset allocation |
+| `visualization` | Plotly chart functions (efficient frontier, pie, CAL, correlation) |
+| `data` | Market-data fetching and monthly-return helpers (yfinance) |
+
+The web application (`backend/`, `frontend/`) is kept in the repo but is not
+part of the installable package — see [Web Application](#web-application).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and contribution guidelines.
+
+## License
+
+MIT

markowizard-0.1.0/markowizard/__init__.py

@@ -0,0 +1,21 @@
+"""
+markowizard: Markowitz portfolio optimization and analysis library.
+
+Provides tools for mean-variance optimization, capital allocation,
+visualization, and optional market data fetching.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from markowizard.allocation import CapitalAllocator
+from markowizard.core import MarkowitzOptimizer
+
+try:
+    __version__ = version("markowizard")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "CapitalAllocator",
+    "MarkowitzOptimizer",
+]

markowizard-0.1.0/markowizard/allocation.py

@@ -0,0 +1,138 @@
+"""
+Capital allocation line (CAL) analysis: mixing a risky portfolio with a
+risk-free asset.
+"""
+
+from collections.abc import Mapping
+
+import pandas as pd
+
+from markowizard.core import COL_RETURN, COL_RISK, COL_RISK_FREE, COL_SHARPE
+
+# Keys expected in the portfolio dict/series
+_PORTFOLIO_KEYS = {COL_RETURN, COL_RISK, COL_SHARPE}
+
+
+class CapitalAllocator:
+    """
+    Combines a risky portfolio with a risk-free asset to explore how
+    different allocations affect overall expected return and risk.
+
+    Parameters
+    ----------
+    portfolio : pandas.Series or dict-like
+        A dictionary or Series representing a single portfolio, containing
+        at least 'Expected Return' (expected return) and 'Risk' (risk/std).
+    risk_free_rate : float
+        Risk-free rate (e.g., monthly rate).
+
+    Attributes
+    ----------
+    portfolio : dict
+        The risky portfolio data.
+    rf : float
+        Risk-free rate.
+    """
+
+    def __init__(
+        self,
+        portfolio: pd.Series | Mapping[str, float],
+        risk_free_rate: float,
+    ) -> None:
+        self.portfolio = dict(portfolio)
+        self.rf = risk_free_rate
+
+    @staticmethod
+    def weigh_risk_free(value: float, risk_free_value: float, p: float) -> float:
+        """
+        Combine a risky value with a risk-free value given proportion ``p``
+        allocated to the risk-free asset.
+
+        Parameters
+        ----------
+        value : float
+            Value from the risky portfolio (e.g., expected return or risk).
+        risk_free_value : float
+            Corresponding value for the risk-free asset (0 for risk, rf for
+            return).
+        p : float
+            Proportion allocated to the risk-free asset (0 to 1).
+
+        Returns
+        -------
+        float
+            Weighted value.
+        """
+        return p * risk_free_value + (1 - p) * value
+
+    def capital_allocation_line(self, steps: int = 21) -> list[dict]:
+        """
+        Generate points along the Capital Allocation Line.
+
+        Parameters
+        ----------
+        steps : int, optional
+            Number of allocation points (default 21, i.e., 0% to 100% in 5%
+            increments).
+
+        Returns
+        -------
+        list of dict
+            Each dict has keys 'p' (risk-free proportion), 'expected_return',
+            'risk', and 'label'.
+        """
+        proportions = [i / (steps - 1) for i in range(steps)]
+        points: list[dict] = []
+
+        for p in proportions:
+            expected_return = self.weigh_risk_free(self.portfolio[COL_RETURN], self.rf, p)
+            risk = self.weigh_risk_free(self.portfolio[COL_RISK], 0.0, p)
+            points.append(
+                {
+                    "p": p,
+                    "expected_return": expected_return,
+                    "risk": risk,
+                    "label": f"{p:.0%} risk-free",
+                }
+            )
+
+        return points
+
+    def final_allocation(self, p: float) -> dict[str, float]:
+        """
+        Compute the final allocation weights given proportion ``p`` in the
+        risk-free asset.
+
+        Parameters
+        ----------
+        p : float
+            Proportion allocated to the risk-free asset (0 to 1).
+
+        Returns
+        -------
+        dict[str, float]
+        Mapping of asset names (including 'Risk-Free' for risk-free) to
+            their allocation percentages.
+        """
+        allocation: dict[str, float] = {COL_RISK_FREE: p}
+        for key, value in self.portfolio.items():
+            if key not in _PORTFOLIO_KEYS:
+                allocation[key] = (1 - p) * value
+        return allocation
+
+    def expected_returns(self, p: float) -> tuple[float, float]:
+        """
+        Expected return and risk for a given allocation to the risk-free asset.
+
+        Parameters
+        ----------
+        p : float
+            Proportion allocated to risk-free (0 to 1).
+
+        Returns
+        -------
+        tuple of (expected_return, risk)
+        """
+        ret = self.weigh_risk_free(self.portfolio[COL_RETURN], self.rf, p)
+        ris = self.weigh_risk_free(self.portfolio[COL_RISK], 0.0, p)
+        return ret, ris