#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
MARKOWITZ.SYSTEMS — 5-Minute Campus Quant & AI Seminar Lab Kit
University Edition: 香港科技大學 (The Hong Kong University of Science and Technology) | Country: Hong Kong
Department / Track: BSc in Data Science and Technology (DSCT) & MSc in Big Data Technology
Recommended Part-Time R&D Pod: POD-02 ($20-$45/hr USD, 10-25 hrs/wk, 0 hrs Exam-Safe Pause)
Apply & Preprints: https://markowitz.systems/uni/hk-the-hong-kong-university-of-science-and-technology | https://markowitz.systems/preprints
"""
import numpy as np

def effective_independent_agents(n_agents: int, avg_corr: float) -> float:
    """Theorem 2: N_eff = N / (1 + (N - 1) * rho_bar)"""
    return n_agents / (1.0 + (n_agents - 1.0) * avg_corr)

def ledoit_wolf_linear_shrinkage(returns_t_by_n: np.ndarray) -> tuple[np.ndarray, float]:
    """Theorem 3: Ledoit-Wolf shrinkage S_LW = (1 - delta*) S + delta* F when N > T or T is small."""
    t_obs, n_dim = returns_t_by_n.shape
    x = returns_t_by_n - returns_t_by_n.mean(axis=0, keepdims=True)
    sample_cov = (x.T @ x) / max(t_obs - 1, 1)
    mu_trace = np.trace(sample_cov) / n_dim
    target_f = mu_trace * np.eye(n_dim)
    delta_num = np.sum((x ** 2).T @ (x ** 2)) / (t_obs ** 2) - np.sum(sample_cov ** 2) / t_obs
    delta_den = np.sum((sample_cov - target_f) ** 2)
    delta_star = float(np.clip(delta_num / max(delta_den, 1e-12), 0.0, 1.0))
    return (1.0 - delta_star) * sample_cov + delta_star * target_f, delta_star

def downside_semivariance(returns_t_by_n: np.ndarray, tau: float = 0.85) -> np.ndarray:
    """Theorem 4: Markowitz (1959) Downside Semivariance Sigma^- below quality threshold tau."""
    shortfall = np.minimum(returns_t_by_n - tau, 0.0)
    return (shortfall.T @ shortfall) / max(returns_t_by_n.shape[0], 1)

def tobin_tangency_weights(mu: np.ndarray, cost: np.ndarray, cov: np.ndarray) -> tuple[np.ndarray, float]:
    """Theorem 5: Long-only projected tangency portfolio maximizing Agent Sharpe Ratio."""
    excess = mu - cost
    raw = np.linalg.solve(cov + 1e-6 * np.eye(len(mu)), excess)
    clipped = np.maximum(raw, 0.0)
    w = clipped / max(clipped.sum(), 1e-12)
    port_sr = float((w @ excess) / np.sqrt(max(w @ cov @ w, 1e-12)))
    return w, port_sr

if __name__ == "__main__":
    rng = np.random.default_rng(2082)
    N, T = 12, 8  # High-dimensional regime N > T on a 12-agent ensemble
    common_mode = rng.normal(0.0, 0.08, size=(T, 1))
    idiosyncratic = rng.normal(0.88, 0.05, size=(T, N))
    eval_matrix = np.clip(idiosyncratic + np.hstack([common_mode] * 6 + [-0.3 * common_mode] * 6), 0.0, 1.0)
    sigma_lw, delta = ledoit_wolf_linear_shrinkage(eval_matrix)
    sigma_semi = downside_semivariance(eval_matrix, tau=0.85)
    mu_hat = eval_matrix.mean(axis=0)
    token_cost = np.linspace(0.02, 0.09, N)
    w_opt, sr = tobin_tangency_weights(mu_hat, token_cost, sigma_lw + 0.5 * sigma_semi)
    print(f"[The Hong Kong University of Science and Technology] N_eff(50 homogeneous @ rho=0.70) = {effective_independent_agents(50, 0.70):.2f}")
    print(f"[The Hong Kong University of Science and Technology] N_eff(12 orthogonal @ illustrative rho=0.06) = {effective_independent_agents(12, 0.06):.2f}")
    print(f"Ledoit-Wolf optimal shrinkage intensity delta* = {delta:.3f} (N={N} > T={T})")
    print(f"Optimal Agent Portfolio Sharpe Ratio = {sr:.3f} | Top-3 weights = {np.round(w_opt[:3], 3)}")
