markowizard 0.1.0__py3-none-any.whl

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/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

markowizard/core.py

@@ -0,0 +1,188 @@
+"""
+Core portfolio optimization using Markowitz Modern Portfolio Theory.
+
+Uses scipy.optimize to compute the efficient frontier.
+"""
+
+import logging
+from collections.abc import Callable
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import minimize
+
+logger = logging.getLogger(__name__)
+
+# English column names for display (region-agnostic)
+COL_RETURN = "Expected Return"
+COL_RISK = "Risk"
+COL_SHARPE = "Sharpe"
+COL_RISK_FREE = "Risk-Free"
+
+
+def _make_objective(
+    mu: float,
+    cov_matrix: np.ndarray,
+    mean_returns: np.ndarray,
+) -> Callable[[np.ndarray], float]:
+    """Build the quadratic objective function for a given risk-aversion parameter."""
+
+    def objective(w: np.ndarray) -> float:
+        return float(0.5 * mu * w @ cov_matrix @ w - mean_returns @ w)
+
+    return objective
+
+
+class MarkowitzOptimizer:
+    """
+    Performs Markowitz mean-variance optimization to find the efficient frontier.
+
+    Parameters
+    ----------
+    returns : pandas.DataFrame
+        DataFrame of historical asset returns, where each column is an asset
+        and each row is a time period (e.g., monthly returns). Returns should
+        be in decimal form (e.g., 0.01 = 1%), not percentage form.
+
+    Attributes
+    ----------
+    tickers : pandas.Index
+        Asset tickers/column names.
+    returns : pandas.DataFrame
+        The input returns data.
+    portfolios : pandas.DataFrame | None
+        DataFrame of optimized portfolios along the efficient frontier,
+        containing weights for each asset plus 'Expected Return',
+        'Risk' (std), and 'Sharpe' (Sharpe ratio).
+    n_assets : int
+        Number of assets in the portfolio.
+    """
+
+    def __init__(self, returns: pd.DataFrame) -> None:
+        if returns.empty:
+            raise ValueError("returns DataFrame must not be empty.")
+        if returns.shape[1] < 1:
+            raise ValueError("returns DataFrame must have at least one asset column.")
+
+        self.returns = returns
+        self.tickers = returns.columns
+        self.portfolios: pd.DataFrame | None = None
+        self.n_assets = returns.shape[1]
+
+    def optimize(self) -> pd.DataFrame:
+        """
+        Compute the efficient frontier by solving quadratic programming
+        problems for a range of risk-aversion parameters (mu).
+
+        Uses warm-starting: the optimal weights from one mu value serve as
+        the initial guess for the next, reducing total iterations.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Efficient frontier portfolios with columns for each asset weight,
+            'Expected Return', 'Risk', and 'Sharpe'.
+        """
+        returns_array = self.returns.values.T  # shape: (n_assets, n_periods)
+        n = self.n_assets
+
+        # Mean returns vector and covariance matrix
+        mean_returns = np.mean(returns_array, axis=1)
+        cov_matrix = np.cov(returns_array)
+
+        # Constraints: sum(weights) = 1
+        constraints: dict = {"type": "eq", "fun": lambda w: np.sum(w) - 1.0}
+
+        # Bounds: no short selling (weights >= 0)
+        bounds: list[tuple[float, float | None]] = [(0.0, None) for _ in range(n)]
+
+        # Generate a range of risk-aversion parameters (mu)
+        # Higher mu = more risk-averse -> lower risk portfolios
+        mus = [10 ** (t / 20 - 1) for t in range(100)]
+
+        portfolios_list: list[np.ndarray] = []
+        n_failed = 0
+
+        # Warm-start: start with equal weights, then use previous solution
+        w0 = np.ones(n) / n
+
+        for mu in mus:
+            objective = _make_objective(mu, cov_matrix, mean_returns)
+
+            result = minimize(
+                objective,
+                w0,
+                method="SLSQP",
+                bounds=bounds,
+                constraints=constraints,
+            )
+
+            if result.success:
+                portfolios_list.append(result.x)
+                w0 = result.x  # warm-start next iteration
+            else:
+                n_failed += 1
+                # Fall back to equal weights as a last resort
+                w_fallback = w0.copy()
+                portfolios_list.append(w_fallback)
+                logger.warning(
+                    "Optimization failed for mu=%f (iteration %d). "
+                    "Using previous weights as fallback.",
+                    mu,
+                    len(portfolios_list) - 1,
+                )
+
+        if n_failed > 0:
+            logger.warning("%d out of %d optimizations failed.", n_failed, len(mus))
+
+        # Build DataFrame
+        concat = np.array(portfolios_list)
+        df = pd.DataFrame(concat, columns=self.tickers)
+
+        # Compute expected return and risk for each portfolio
+        df[COL_RETURN] = concat @ mean_returns
+        df[COL_RISK] = np.sqrt(np.diag(concat @ cov_matrix @ concat.T))
+
+        # Sort by risk (ascending) so the frontier is ordered
+        df = df.sort_values(COL_RISK).reset_index(drop=True)
+
+        self.portfolios = df
+        return self.portfolios
+
+    def compute_sharpe(self, risk_free_rate: float) -> pd.DataFrame:
+        """
+        Compute the Sharpe ratio for each portfolio on the efficient frontier.
+
+        Parameters
+        ----------
+        risk_free_rate : float
+        Risk-free rate (e.g., monthly rate). Should be in decimal
+            form (e.g., 0.005 for 0.5% a.m.).
+
+        Returns
+        -------
+        pandas.DataFrame
+            The portfolios DataFrame with an added 'Sharpe' column.
+        """
+        if self.portfolios is None:
+            raise ValueError("Call optimize() before computing Sharpe ratios.")
+
+        self.portfolios[COL_SHARPE] = (
+            self.portfolios[COL_RETURN] - risk_free_rate
+        ) / self.portfolios[COL_RISK]
+        return self.portfolios
+
+    def max_sharpe_portfolio(self) -> pd.Series:
+        """
+        Return the portfolio with the highest Sharpe ratio.
+
+        Returns
+        -------
+        pandas.Series
+            The tangency (maximum Sharpe) portfolio.
+        """
+        if self.portfolios is None or COL_SHARPE not in self.portfolios.columns:
+            raise ValueError("Call optimize() and compute_sharpe() first.")
+
+        idx = self.portfolios[COL_SHARPE].idxmax()
+        return self.portfolios.loc[idx]

markowizard/data.py

@@ -0,0 +1,91 @@
+"""
+Convenience functions for fetching market data and computing returns.
+
+Use these to quickly download prices from Yahoo Finance. The core
+analytical modules also accept a pre-computed returns DataFrame directly,
+so these helpers are optional in practice.
+"""
+
+import re
+from typing import Any
+
+import pandas as pd
+import yfinance as yf
+
+# Pattern for validating Yahoo Finance ticker symbols
+_TICKER_PATTERN = re.compile(r"^[A-Z0-9.-]+$", re.IGNORECASE)
+
+
+def _validate_tickers(tickers: list[str]) -> None:
+    """Validate a list of ticker symbols against a safe pattern.
+
+    Parameters
+    ----------
+    tickers : list of str
+        Ticker symbols to validate.
+
+    Raises
+    ------
+    ValueError
+        If any ticker contains characters other than letters, digits,
+        dots, hyphens, or is empty.
+    """
+    for t in tickers:
+        if not t or not isinstance(t, str):
+            raise ValueError(f"Invalid ticker: {t!r}. Tickers must be non-empty strings.")
+        if not _TICKER_PATTERN.match(t):
+            raise ValueError(
+                f"Invalid ticker: {t!r}. Tickers may only contain letters, "
+                f"digits, dots, and hyphens."
+            )
+
+
+def fetch_prices(
+    tickers: list[str],
+    period: str = "5y",
+    auto_adjust: bool = True,
+) -> pd.DataFrame:
+    """
+    Download historical adjusted close prices for a list of tickers.
+
+    Parameters
+    ----------
+    tickers : list of str
+        Yahoo Finance ticker symbols (e.g., ['AAPL', 'MSFT', 'SPY']).
+        Each ticker must match ``^[A-Z0-9.-]+$``.
+    period : str, optional
+        Data period (default '5y'). See yfinance for valid periods.
+    auto_adjust : bool, optional
+        Whether to use auto-adjusted close prices (default True).
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame of closing prices with DatetimeIndex and tickers as columns.
+    """
+    _validate_tickers(tickers)
+    t = yf.Tickers(" ".join(tickers))
+    df: Any = t.history(period=period, auto_adjust=auto_adjust, progress=False)
+    return df["Close"]
+
+
+def compute_monthly_returns(prices: pd.DataFrame) -> pd.DataFrame:
+    """
+    Convert daily close prices to monthly percentage returns.
+
+    Parameters
+    ----------
+    prices : pd.DataFrame
+        Daily closing prices with DatetimeIndex and tickers as columns.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame of monthly percentage returns.
+    """
+    # Resample prices to end-of-month
+    monthly_prices = prices.resample("ME").last()
+
+    # Compute percentage change and drop NaN
+    returns: pd.DataFrame = monthly_prices.pct_change().dropna()
+    return returns

markowizard/visualization.py

@@ -0,0 +1,322 @@
+"""
+Plotly-based visualization functions for portfolio analysis.
+
+Returns standalone Plotly ``Figure`` objects (not tied to Dash).
+"""
+
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.graph_objects import Figure
+
+from markowizard.core import COL_RETURN, COL_RISK, COL_SHARPE
+
+# Shared default layout margin
+_DEFAULT_MARGIN = {"b": 10, "t": 10}
+
+
+def _build_hover_text(
+    risk: pd.Series,
+    expected_return: pd.Series,
+    sharpe: pd.Series | None = None,
+) -> list[str]:
+    """Build hover text from risk, return, and optional Sharpe columns."""
+    if sharpe is None:
+        sharpe = pd.Series([0.0] * len(risk), index=risk.index)
+    return [
+        f"<b>Expected Return:</b> {y:.1%}<br><b>Risk:</b> ±{x:.1%}<br><b>Sharpe Ratio:</b> {z:.2f}"
+        for x, y, z in zip(risk, expected_return, sharpe, strict=True)
+    ]
+
+
+def _marker_styles(
+    n: int,
+    highlight_idx: int,
+    base_color: str = "cyan",
+    highlight_color: str = "yellow",
+) -> tuple[list[str], list[int]]:
+    """Build marker color and size lists, highlighting one index."""
+    colors = [base_color if i != highlight_idx else highlight_color for i in range(n)]
+    sizes = [8 if i != highlight_idx else 12 for i in range(n)]
+    return colors, sizes
+
+
+def efficiency_frontier_plot(
+    portfolios: pd.DataFrame,
+    highlight_portfolio: int = 0,
+) -> Figure:
+    """
+    Plot the efficient frontier as a scatter plot of expected return vs risk.
+
+    Parameters
+    ----------
+    portfolios : pd.DataFrame
+        DataFrame with 'Expected Return', 'Risk', and 'Sharpe' columns
+        (as produced by MarkowitzOptimizer).
+    highlight_portfolio : int, optional
+        Index of the portfolio to highlight (default 0).
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    df = portfolios
+
+    sharpe_col = df.get(COL_SHARPE) if COL_SHARPE in df.columns else None
+    text = _build_hover_text(df[COL_RISK], df[COL_RETURN], sharpe_col)
+
+    marker_color, marker_size = _marker_styles(len(df), highlight_portfolio)
+
+    fig = go.Figure(
+        data=go.Scatter(
+            x=df[COL_RISK],
+            y=df[COL_RETURN],
+            name="Efficient Frontier",
+            mode="markers",
+            marker={
+                "size": marker_size,
+                "color": marker_color,
+                "opacity": 1,
+                "line": {"color": "blue", "width": 2},
+            },
+            hovertext=text,
+            hoverinfo="text",
+        ),
+        layout={
+            "margin": _DEFAULT_MARGIN,
+            "xaxis": {
+                "tickformat": ",.1%",
+                "title": {"text": "Risk (Standard Deviation)"},
+            },
+            "yaxis": {
+                "tickformat": ",.1%",
+                "title": {"text": "Expected Return (% p.m.)"},
+            },
+        },
+    )
+
+    # Annotate max Sharpe portfolio
+    if COL_SHARPE in df.columns:
+        max_sharpe = df[COL_SHARPE].idxmax()
+        fig.add_annotation(
+            x=df.loc[max_sharpe, COL_RISK],
+            y=df.loc[max_sharpe, COL_RETURN],
+            text="Max Sharpe Ratio",
+            showarrow=True,
+            arrowhead=1,
+            arrowwidth=2,
+            axref="pixel",
+            ax=100,
+            ayref="pixel",
+            ay=20,
+        )
+
+    return fig
+
+
+def allocation_pie(portfolio: pd.Series) -> Figure:
+    """
+    Pie chart showing asset allocation for a single portfolio.
+
+    Parameters
+    ----------
+    portfolio : pd.Series
+        A single portfolio row from the efficient frontier DataFrame.
+        Non-zero asset weights are displayed; meta columns like
+        'Expected Return', 'Risk', 'Sharpe' are excluded.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    # Filter out metadata columns and near-zero weights
+    keys_to_exclude = {COL_RETURN, COL_RISK, COL_SHARPE}
+    ds = portfolio[~portfolio.index.isin(keys_to_exclude)]
+    ds = ds[ds > 0.0001]
+
+    if ds.empty:
+        ds = pd.Series({"(no allocation)": 1.0})
+
+    fig = go.Figure(
+        data=go.Pie(
+            labels=ds.index.tolist(),
+            values=ds.values,
+            hole=0.4,
+            textinfo="label+percent",
+            hoverinfo="skip",
+        ),
+        layout=go.Layout(margin={"b": 0, "t": 0}),
+    )
+    return fig
+
+
+def capital_allocation_line_plot(
+    cal_points: list[dict],
+    highlight_point: int = 0,
+) -> Figure:
+    """
+    Plot the Capital Allocation Line (CAL) showing risk-return trade-offs
+    for different mixes of risky portfolio and risk-free asset.
+
+    Parameters
+    ----------
+    cal_points : list of dict
+        Output from CapitalAllocator.capital_allocation_line().
+    highlight_point : int, optional
+        Index of the point to highlight (default 0).
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    proportions = [p["p"] for p in cal_points]
+    retornos = [p["expected_return"] for p in cal_points]
+
+    text = [
+        f"<b>Risk-Free Proportion:</b> {p['p']:.0%}<br>"
+        f"<b>Expected Return:</b> {p['expected_return']:.1%} ± {p['risk']:.1%} p.m."
+        for p in cal_points
+    ]
+
+    marker_color, marker_size = _marker_styles(len(cal_points), highlight_point)
+
+    fig = go.Figure(
+        data=go.Scatter(
+            x=proportions,
+            y=retornos,
+            mode="lines+markers",
+            hovertext=text,
+            hoverinfo="text",
+            marker={
+                "size": marker_size,
+                "color": marker_color,
+                "opacity": 1,
+                "line": {"color": "blue", "width": 2},
+            },
+            line={"color": "blue", "width": 3},
+        ),
+        layout={
+            "margin": _DEFAULT_MARGIN,
+            "xaxis": {
+                "tickformat": ",.0%",
+                "autorange": "reversed",
+                "title": {"text": "Risk-Free Proportion"},
+            },
+            "yaxis": {
+                "tickformat": ",.1%",
+                "title": {"text": "Expected Return (% p.m.)"},
+            },
+        },
+    )
+
+    return fig
+
+
+def correlation_timeline(
+    prices: pd.DataFrame,
+    ticker_a: str,
+    ticker_b: str | None = None,
+) -> Figure:
+    """
+    Plot the price history of one or two assets, normalizing when comparing
+    two different assets.
+
+    Parameters
+    ----------
+    prices : pd.DataFrame
+        DataFrame of historical prices with DatetimeIndex and tickers as columns.
+    ticker_a : str
+        Primary ticker.
+    ticker_b : str or None, optional
+        Secondary ticker. If None or equal to ticker_a, plots a single line.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    if ticker_b is None or ticker_a == ticker_b:
+        return _plot_single(prices, ticker_a)
+
+    return _plot_multi(prices, ticker_a, ticker_b)
+
+
+def _plot_single(prices: pd.DataFrame, ticker: str) -> Figure:
+    """Plot a single ticker's price history."""
+    ds = prices[ticker].dropna()
+
+    fig = go.Figure(
+        data=go.Scatter(
+            x=ds.index,
+            y=ds,
+            name=ticker,
+            hoverinfo="skip",
+        ),
+        layout={
+            "margin": _DEFAULT_MARGIN,
+            "showlegend": False,
+        },
+    )
+    return fig
+
+
+def _plot_multi(prices: pd.DataFrame, ticker_a: str, ticker_b: str) -> Figure:
+    """Plot two tickers' price histories, normalized to [0, 1]."""
+    df = prices[[ticker_a, ticker_b]].dropna()
+
+    fig = go.Figure(
+        layout={
+            "yaxis": {"visible": False},
+            "margin": _DEFAULT_MARGIN,
+            "showlegend": False,
+        }
+    )
+
+    for ticker in [ticker_a, ticker_b]:
+        series = df[ticker]
+        min_val, max_val = series.min(), series.max()
+        normalized = (series - min_val) / (max_val - min_val) if max_val > min_val else series * 0
+
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=normalized,
+                name=ticker,
+                hoverinfo="skip",
+            )
+        )
+
+    return fig
+
+
+def correlation_heatmap(corr_matrix: pd.DataFrame) -> Figure:
+    """
+    Plot a correlation matrix heatmap.
+
+    Parameters
+    ----------
+    corr_matrix : pd.DataFrame
+        Square correlation matrix with ticker names as index and columns.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    fig = go.Figure(
+        data=go.Heatmap(
+            z=corr_matrix.values,
+            x=corr_matrix.columns.tolist(),
+            y=corr_matrix.index.tolist(),
+            text=corr_matrix.values.round(2),
+            texttemplate="%{text}",
+            colorscale="RdBu",
+            zmid=0,
+            zmin=-1,
+            zmax=1,
+            hovertemplate="%{x} vs %{y}: %{z:.2f}<extra></extra>",
+        ),
+        layout={
+            "margin": {"b": 80, "t": 30, "l": 80, "r": 20},
+            "xaxis": {"side": "bottom"},
+            "yaxis": {"autorange": "reversed"},
+        },
+    )
+    return fig

markowizard-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+markowizard/__init__.py,sha256=RkdrrVq_FtvFlzEDZ2wJE6nvuBS3QQjGmrCmPL_xF5I,524
+markowizard/allocation.py,sha256=FNgmvAEo_ILaQtOIJaxSvLgqNWSNc64GFlLIrxEceng,4140
+markowizard/core.py,sha256=YAjAHopZl_ZkKUxIkV-noyvGmQZWJh8wa3WA4JKt9vE,6231
+markowizard/data.py,sha256=vWibjfd4MZmDawdNK01xHuvqLAg8mjHu-J-UfF-ClY0,2635
+markowizard/visualization.py,sha256=GYo8jbjNQrFJdahlM2wZC0M1KhbQQhag9WC3yY7h_zE,8914
+markowizard-0.1.0.dist-info/licenses/LICENSE,sha256=ciVK0IDK6_Waky-Px_PPTIaurSZryh1qd40Uz8Z8c08,1072
+markowizard-0.1.0.dist-info/METADATA,sha256=Mjy5bghlDPmcTgi6acrkli1eCE9Vo7q55X_4BDWBUkk,8354
+markowizard-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+markowizard-0.1.0.dist-info/top_level.txt,sha256=RoPJgri1ExsDK7MJ_HVigphIwlMMc71zTPXrJdFZ54k,12
+markowizard-0.1.0.dist-info/RECORD,,

markowizard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

markowizard-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+markowizard