{"id":29829252,"url":"https://github.com/nitintonypaul/mop","last_synced_at":"2025-07-29T08:33:38.187Z","repository":{"id":305801614,"uuid":"1022745500","full_name":"nitintonypaul/MOP","owner":"nitintonypaul","description":"Multi-Objective Black-Litterman Portfolio Allocation Engine","archived":false,"fork":false,"pushed_at":"2025-07-22T03:12:17.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-22T05:24:03.326Z","etag":null,"topics":["black-litterman","portfolio-optimization","risk-management"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nitintonypaul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T18:24:39.000Z","updated_at":"2025-07-22T03:14:10.000Z","dependencies_parsed_at":"2025-07-22T05:24:38.286Z","dependency_job_id":"881a708b-3d9e-43c8-9bc0-71580cd5f35d","html_url":"https://github.com/nitintonypaul/MOP","commit_stats":null,"previous_names":["nitintonypaul/mop"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nitintonypaul/MOP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitintonypaul%2FMOP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitintonypaul%2FMOP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitintonypaul%2FMOP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitintonypaul%2FMOP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nitintonypaul","download_url":"https://codeload.github.com/nitintonypaul/MOP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitintonypaul%2FMOP/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267653390,"owners_count":24122195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["black-litterman","portfolio-optimization","risk-management"],"created_at":"2025-07-29T08:33:36.998Z","updated_at":"2025-07-29T08:33:38.174Z","avatar_url":"https://github.com/nitintonypaul.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-Objective Portfolio Allocation Engine\n\nA Python-based engine designed for advanced portfolio optimization\n\n---\n\n## Project Objective\n\nThis project aims to develop a **multi-objective portfolio allocation engine** in Python. It provides a versatile framework for exploring and applying various portfolio optimization techniques, including those for high-performance and computationally intensive financial analysis.\n\n---\n\n## Core Features\n\n* **Multiple Optimization Models:** Implements a suite of industry-standard optimization techniques:\n    * **Minimum Variance:** Aims to find the portfolio with the lowest possible risk.\n    * **Maximum Diversification (MDP):** Seeks to maximize the portfolio's diversification ratio.\n    * **Mean-Variance Optimization (MVO):** The classic Markowitz model to balance risk and return (Black Litterman).\n    * **Conditional Value at Risk (CVaR):** Focuses on minimizing losses in the worst-case scenarios (tail risk).\n    * **Mean-CVaR:** Maximizes return while minimizing worst-case (tail) losses.\n* **Black-Litterman Model Integration:** Fuses market-implied returns with an investor's custom views to produce more stable and intuitive allocations.\n* **Robust Risk Modeling:** Uses the Ledoit-Wolf shrinkage estimator to compute a well-conditioned and stable covariance matrix.\n* **Performance Backtesting:** Evaluates a \"buy-and-hold\" portfolio strategy against historical data, reporting key metrics like Sharpe Ratio, Sortino Ratio, and total returns.\n* **Portfolio Persistence:** Save your configured portfolios to disk and load them back in later sessions for continued analysis.\n\n---\n\n## Workflow\n\n```mermaid\n%% The User's Journey with the Portfolio Engine\ngraph TD\n    subgraph \"Step 1: Initialization\"\n        A[Start: Provide Tickers \u0026 Amount] --\u003e B(Create Portfolio Instance)\n        C[Start: Provide Filename] --\u003e D(Load Portfolio Instance)\n    end\n    \n    B --\u003e E{Portfolio Object Ready}\n    D --\u003e E\n\n    subgraph \"Step 2: Take Action\"\n        E -- \"Call .Optimize(method, ...)\" --\u003e F[Select \u0026 Run Optimizer]\n        F --\u003e G[Update Portfolio Weights]\n        G --\u003e E\n        \n        E -- \"Call .Stats() / .Performance()\" --\u003e H[Generate Reports]\n        \n        E -- \"Call .Save(filename)\" --\u003e I[Save Weights to File]\n    end\n\n    subgraph \"Step 3: Endpoints\"\n        H --\u003e J((View Output))\n        I --\u003e K((File Saved))\n    end\n    \n    style E fill:#000,stroke:#111,stroke-width:2px\n```\n\n---\n\n## Installation \u0026 Usage\n\nTo get started with the engine:\n\n1.  **Clone the repository (or download the ZIP file):**\n    ```bash\n    git clone https://github.com/nitintonypaul/MOP.git\n    ```\n    \n2.  **Navigate into the directory:**\n    ```bash\n    cd MOP\n    ```\n    \n3. **Create a virtual environment (recommended):**\n   - **Windows:**\n     ```bash\n     python -m venv venv\n     venv\\Scripts\\activate\n     ```\n   - **macOS/Linux:**\n     ```bash\n     python3 -m venv venv\n     source venv/bin/activate\n     ```  \n\n4. **Install required packages:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n   \n5.  **Run the demo:**\n    ```bash\n    python main.py\n    ```\n\nThe core optimization engine is located in the `mopEngine/` directory. You can integrate it into your own Python projects by copying the `mopEngine/` folder.\n\n---\n\n## Quickstart: A Tutorial\n\nThis guide will walk you through the entire process of creating, optimizing, analyzing, and saving a portfolio.\n\n### 1. Initializing a Portfolio\n\nFirst, import the `Portfolio` class and create an instance. You need to provide a list of stock tickers and the total initial investment amount.\n\nWhen you create a `Portfolio` object, it automatically:\n-   Fetches the last year of daily stock price data from Yahoo Finance.\n-   Calculates the asset covariance matrix using the Ledoit-Wolf method.\n-   Initializes the portfolio with equal weights for all assets.\n    \n    ```py\n    from mopEngine.portfolio import Portfolio\n    import logging\n\n    # Configure basic logging to see the engine's output\n    logging.basicConfig(level=logging.INFO, format='[%(asctime)s] %(message)s', datefmt='%H:%M:%S')\n\n    # Define your assets and total investment\n    tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN']\n    initial_amount = 100000\n\n    # Create a portfolio instance\n    p = Portfolio(tickers, initial_amount)\n    print(\"Portfolio created successfully!\")\n\n    ```\n\n### 2. Viewing Portfolio Statistics\n\nUse the `.Stats()` method to see the current allocation of assets in your portfolio, including their weights and monetary values.\n    \n```py\n    # Display the initial, equally-weighted portfolio\n    print(\"--- Initial Portfolio Allocation ---\")\n    print(p.Stats())\n```\n\n**Output:**\n\n    --- Initial Portfolio Allocation ---\n    STOCK      WEIGHT    AMOUNT\n    AAPL         0.25   25000.0\n    MSFT         0.25   25000.0\n    GOOGL        0.25   25000.0\n    AMZN         0.25   25000.0\n\n### 3. Optimizing the Portfolio\n\nThe core of the engine is the `.Optimize()` method. You can choose from several allocation strategies by specifying the `method` parameter.\n\n#### Example: Minimum Variance Optimization\n\nThis will calculate the asset weights that result in the lowest possible portfolio volatility.\n\n```py\n    print(\"\\nOptimizing for Minimum Variance...\")\n    p.Optimize(method=\"variance\")\n\n    # Display the new, optimized allocation\n    print(\"--- Optimized Portfolio Allocation (Min Variance) ---\")\n    print(p.Stats())\n```\n\n**Output (example values):**\n\n    Optimizing for Minimum Variance...\n    --- Optimized Portfolio Allocation (Min Variance) ---\n    STOCK      WEIGHT    AMOUNT\n    AAPL        0.358   35800.0\n    MSFT        0.112   11200.0\n    GOOGL       0.481   48100.0\n    AMZN        0.049    4900.0\n\n### 4. Analyzing Performance\n\nAfter optimizing, you can run a simple backtest with the `.Performance()` method. This evaluates how your new (static) weights would have performed over the past year.\n\nThe method returns a list of (metric, value) tuples, which can be easily printed or converted to a dictionary.\n```py\n    print(\"\\n--- Backtest Performance Results ---\")\n    performance_results = p.Performance()\n\n    # Use tabulate for a clean printout\n    from tabulate import tabulate\n    print(tabulate(list(performance_results), headers=[\"METRIC\", \"VALUE\"]))\n```\n\n**Output (example values):**\n\n    --- Backtest Performance Results ---\n    METRIC                      VALUE\n    ------------------------  ---------\n    Sharpe                      1.845\n    Sortino                     3.123\n    Volatility (Annual)         18.551%\n    Highest Return (Daily)      2.781%\n    Lowest Return (Daily)       -3.411%\n    Average Return (Daily)      0.142%\n    Total Return (Compounded)   41.876%\n    Win Ratio                   58.110%\n\n### 5. Saving and Loading a Portfolio\n\nYou can persist your portfolio's state (tickers, weights, and amount) to a file and load it back later. This is useful for saving the results of a time-consuming optimization.\n\n#### Saving the Portfolio\nThe `Portfolio.Save()` is a classmethod. You pass it the portfolio instance and a filename.\n\n```py\n    # Save our optimized portfolio to 'my_tech_portfolio.bin'\n    filename = \"my_tech_portfolio\"\n    Portfolio.Save(p, filename)\n    print(f\"\\nPortfolio saved to {filename}.bin\")\n```\n\n#### Loading the Portfolio\nThe `Portfolio.Load()` classmethod reconstructs a portfolio from a file. It will re-fetch fresh market data but will apply the saved weights.\n\n```py\n    # Imagine this is a new session. Let's load our saved portfolio.\n    print(\"\\nLoading portfolio from disk...\")\n    loaded_p = Portfolio.Load(filename)\n\n    # Verify that the loaded portfolio has the correct, optimized weights\n    print(\"--- Loaded Portfolio Allocation ---\")\n    print(loaded_p.Stats())\n```\n\nThis tutorial covers the complete workflow of the Multi-Objective Portfolio Allocation Engine. Feel free to experiment with different tickers, optimization methods, and parameters.\n\n---\n\n## Disclaimer\n\nThis software is provided for **educational and research purposes only**. It is not intended for live trading or investment decisions. The author is **not liable for any financial losses or damages** incurred from the use of this software. Users should exercise their own due diligence and consult with a financial professional.\n\n---\n## License\n\nThis project is open-sourced under the **Apache 2.0 License**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitintonypaul%2Fmop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitintonypaul%2Fmop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitintonypaul%2Fmop/lists"}