portfolio-rebalancer-cli 0.1.0__tar.gz

portfolio_rebalancer_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Cruz
+
+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.

portfolio_rebalancer_cli-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: portfolio-rebalancer-cli
+Version: 0.1.0
+Summary: A CLI tool for contribution-only portfolio rebalancing.
+Author-email: Aaron Cruz <aaron.m.cruz@rutgers.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aaronCruise/Portfolio-Rebalancer
+Project-URL: Bug Tracker, https://github.com/aaronCruise/Portfolio-Rebalancer/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest>=8.0.0
+Dynamic: license-file
+
+# Portfolio Rebalancer
+
+A CLI tool designed to help investors maintain their target asset allocation through contribution-only rebalancing.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aaronCruise/Portfolio-Rebalancer/main/images/output_example.png" alt="output_example"/>
+</p>
+
+This project was built using **Gemini CLI** to explore AI-driven development for architectural designs, scaffolding, and code generation.
+
+## Motivation
+I originally managed my investments and rebalancing through a spreadsheet. I ported the logic to a CLI tool to achieve:
+- Workflow efficiency. Faster execution and a foundation for future automation.
+- Version control. My investment strategy and portfolio can now be tracked with Git.
+- Reliability. All logic lies within modules that are invisible to the user. No more accidental formula breaks!
+
+## Features
+- **Tax-Efficient Logic:** Prioritizes buying underweight assets, never selling.
+- **JSON Portfolios:** Load your custom portfolio from a simple `json` file.
+- **Proportional Scaling:** Handles contributions that are too small to fill all gaps perfectly.
+- **Modern Python:** Built with type hints, dataclasses, and a modular package structure.
+
+## Installation
+
+Install the tool directly from PyPI:
+
+```bash
+pip install portfolio-rebalancer-cli
+```
+
+## Usage 
+
+1. **Configure your portfolio:**
+   Create a `portfolio.json` file in your current directory using the following format, adding asset classes and adjusting according to your portfolio:
+
+    ```json
+    {
+      "assets": [
+        {
+          "name": "US Total Stock",
+          "target_allocation": 0.60,
+          "current_balance": 6000.00
+        },
+        {
+          "name": "International Stock",
+          "target_allocation": 0.30,
+          "current_balance": 2000.00
+        },
+        {
+          "name": "Bond Market",
+          "target_allocation": 0.10,
+          "current_balance": 2000.00
+        }
+      ]
+    }
+    ```
+
+2. **Run the rebalancer:**
+
+    * **Default Mode** (looks for `portfolio.json` in current folder):
+      ```bash
+      rebalance --contribution 1000
+      ```
+
+    * **Custom File Mode**:
+      ```bash
+      rebalance --contribution 1000 --file my_custom_portfolio.json
+      ```
+
+## Development & Testing
+
+If you want to contribute or run the tests:
+
+```bash
+git clone https://github.com/aaronCruise/Portfolio-Rebalancer.git
+cd Portfolio-Rebalancer
+pip install -e .
+pytest
+```

portfolio_rebalancer_cli-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Portfolio Rebalancer
+
+A CLI tool designed to help investors maintain their target asset allocation through contribution-only rebalancing.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aaronCruise/Portfolio-Rebalancer/main/images/output_example.png" alt="output_example"/>
+</p>
+
+This project was built using **Gemini CLI** to explore AI-driven development for architectural designs, scaffolding, and code generation.
+
+## Motivation
+I originally managed my investments and rebalancing through a spreadsheet. I ported the logic to a CLI tool to achieve:
+- Workflow efficiency. Faster execution and a foundation for future automation.
+- Version control. My investment strategy and portfolio can now be tracked with Git.
+- Reliability. All logic lies within modules that are invisible to the user. No more accidental formula breaks!
+
+## Features
+- **Tax-Efficient Logic:** Prioritizes buying underweight assets, never selling.
+- **JSON Portfolios:** Load your custom portfolio from a simple `json` file.
+- **Proportional Scaling:** Handles contributions that are too small to fill all gaps perfectly.
+- **Modern Python:** Built with type hints, dataclasses, and a modular package structure.
+
+## Installation
+
+Install the tool directly from PyPI:
+
+```bash
+pip install portfolio-rebalancer-cli
+```
+
+## Usage 
+
+1. **Configure your portfolio:**
+   Create a `portfolio.json` file in your current directory using the following format, adding asset classes and adjusting according to your portfolio:
+
+    ```json
+    {
+      "assets": [
+        {
+          "name": "US Total Stock",
+          "target_allocation": 0.60,
+          "current_balance": 6000.00
+        },
+        {
+          "name": "International Stock",
+          "target_allocation": 0.30,
+          "current_balance": 2000.00
+        },
+        {
+          "name": "Bond Market",
+          "target_allocation": 0.10,
+          "current_balance": 2000.00
+        }
+      ]
+    }
+    ```
+
+2. **Run the rebalancer:**
+
+    * **Default Mode** (looks for `portfolio.json` in current folder):
+      ```bash
+      rebalance --contribution 1000
+      ```
+
+    * **Custom File Mode**:
+      ```bash
+      rebalance --contribution 1000 --file my_custom_portfolio.json
+      ```
+
+## Development & Testing
+
+If you want to contribute or run the tests:
+
+```bash
+git clone https://github.com/aaronCruise/Portfolio-Rebalancer.git
+cd Portfolio-Rebalancer
+pip install -e .
+pytest
+```

portfolio_rebalancer_cli-0.1.0/portfolio_rebalancer_cli.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: portfolio-rebalancer-cli
+Version: 0.1.0
+Summary: A CLI tool for contribution-only portfolio rebalancing.
+Author-email: Aaron Cruz <aaron.m.cruz@rutgers.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aaronCruise/Portfolio-Rebalancer
+Project-URL: Bug Tracker, https://github.com/aaronCruise/Portfolio-Rebalancer/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest>=8.0.0
+Dynamic: license-file
+
+# Portfolio Rebalancer
+
+A CLI tool designed to help investors maintain their target asset allocation through contribution-only rebalancing.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aaronCruise/Portfolio-Rebalancer/main/images/output_example.png" alt="output_example"/>
+</p>
+
+This project was built using **Gemini CLI** to explore AI-driven development for architectural designs, scaffolding, and code generation.
+
+## Motivation
+I originally managed my investments and rebalancing through a spreadsheet. I ported the logic to a CLI tool to achieve:
+- Workflow efficiency. Faster execution and a foundation for future automation.
+- Version control. My investment strategy and portfolio can now be tracked with Git.
+- Reliability. All logic lies within modules that are invisible to the user. No more accidental formula breaks!
+
+## Features
+- **Tax-Efficient Logic:** Prioritizes buying underweight assets, never selling.
+- **JSON Portfolios:** Load your custom portfolio from a simple `json` file.
+- **Proportional Scaling:** Handles contributions that are too small to fill all gaps perfectly.
+- **Modern Python:** Built with type hints, dataclasses, and a modular package structure.
+
+## Installation
+
+Install the tool directly from PyPI:
+
+```bash
+pip install portfolio-rebalancer-cli
+```
+
+## Usage 
+
+1. **Configure your portfolio:**
+   Create a `portfolio.json` file in your current directory using the following format, adding asset classes and adjusting according to your portfolio:
+
+    ```json
+    {
+      "assets": [
+        {
+          "name": "US Total Stock",
+          "target_allocation": 0.60,
+          "current_balance": 6000.00
+        },
+        {
+          "name": "International Stock",
+          "target_allocation": 0.30,
+          "current_balance": 2000.00
+        },
+        {
+          "name": "Bond Market",
+          "target_allocation": 0.10,
+          "current_balance": 2000.00
+        }
+      ]
+    }
+    ```
+
+2. **Run the rebalancer:**
+
+    * **Default Mode** (looks for `portfolio.json` in current folder):
+      ```bash
+      rebalance --contribution 1000
+      ```
+
+    * **Custom File Mode**:
+      ```bash
+      rebalance --contribution 1000 --file my_custom_portfolio.json
+      ```
+
+## Development & Testing
+
+If you want to contribute or run the tests:
+
+```bash
+git clone https://github.com/aaronCruise/Portfolio-Rebalancer.git
+cd Portfolio-Rebalancer
+pip install -e .
+pytest
+```

portfolio_rebalancer_cli-0.1.0/portfolio_rebalancer_cli.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+portfolio_rebalancer_cli.egg-info/PKG-INFO
+portfolio_rebalancer_cli.egg-info/SOURCES.txt
+portfolio_rebalancer_cli.egg-info/dependency_links.txt
+portfolio_rebalancer_cli.egg-info/entry_points.txt
+portfolio_rebalancer_cli.egg-info/requires.txt
+portfolio_rebalancer_cli.egg-info/top_level.txt
+rebalancer/__init__.py
+rebalancer/engine.py
+rebalancer/main.py
+rebalancer/models.py
+tests/test_engine.py

portfolio_rebalancer_cli-0.1.0/portfolio_rebalancer_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

portfolio_rebalancer_cli-0.1.0/portfolio_rebalancer_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rebalance = rebalancer.main:main

portfolio_rebalancer_cli-0.1.0/portfolio_rebalancer_cli.egg-info/requires.txt

@@ -0,0 +1 @@
+pytest>=8.0.0

portfolio_rebalancer_cli-0.1.0/portfolio_rebalancer_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+rebalancer

portfolio_rebalancer_cli-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "portfolio-rebalancer-cli"
+version = "0.1.0"
+authors = [
+  { name="Aaron Cruz", email="aaron.m.cruz@rutgers.edu" },
+]
+description = "A CLI tool for contribution-only portfolio rebalancing."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/aaronCruise/Portfolio-Rebalancer"
+"Bug Tracker" = "https://github.com/aaronCruise/Portfolio-Rebalancer/issues"
+
+[project.scripts]
+rebalance = "rebalancer.main:main"
+
+[tool.setuptools]
+packages = ["rebalancer"]

portfolio_rebalancer_cli-0.1.0/rebalancer/engine.py

@@ -0,0 +1,44 @@
+"""Implements the core math to calculate the recommended contribution amounts."""
+from typing import Dict
+from .models import Portfolio
+
+def calculate_rebalance(portfolio: Portfolio, contribution: float) -> Dict[str, float]:
+    """
+    Calculates how to distribute a contribution across assets to reach target allocations.
+    
+    Logic:
+    1. Calculate the 'Ideal' total value after contribution.
+    2. Calculate the 'Target Amount' for each asset based on its target %.
+    3. Calculate the 'Gap' (Target Amount - Current Balance).
+    4. If the contribution is less than the total gap, distribute it 
+       proportionally to those gaps.
+    """
+    if not portfolio.validate():
+        raise ValueError("Portfolio target allocations must sum to 1.0 (100%).")
+
+    if contribution < 0:
+        raise ValueError("Contribution must be a positive number.")
+
+    new_total_value = portfolio.total_value + contribution
+    
+    # Calculate how much we want to add to each to hit the target
+    gaps = {}
+    for asset in portfolio.assets:
+        target_amount = new_total_value * asset.target_allocation
+        gap = target_amount - asset.current_balance
+        gaps[asset.name] = max(0.0, gap) # Ignore negative gaps (sells)
+
+    total_gap = sum(gaps.values())
+   
+    # If no contribution calculated, return zeros immediately. 
+    # This is to avoid division by 0 later.
+    if total_gap == 0:
+        return {asset.name: 0.0 for asset in portfolio.assets}
+
+    # If contribution != total_gap, we scale the additions.
+    scaling_factor = contribution / total_gap
+
+    result = {}
+    for name, gap in gaps.items():
+        result[name] = round(gap * scaling_factor, 2)
+    return result

portfolio_rebalancer_cli-0.1.0/rebalancer/main.py

@@ -0,0 +1,76 @@
+"""
+Defines the entry point for the Portfolio Rebalancer CLI tool.
+
+This module parses command-line arguments, initializes configuration,
+and hands off execution to the appropriate functions.
+"""
+import argparse
+import sys
+import json
+from .models import Portfolio
+from .engine import calculate_rebalance
+
+DEFAULT_PF_PATH = "portfolio.json"
+
+def load_portfolio(file_path: str | None) -> Portfolio:
+    """Loads a portfolio from a JSON file, or a default if no path is given."""
+    file_to_load = file_path if file_path is not None else DEFAULT_PF_PATH
+    
+    try:
+        with open(file_to_load, 'r') as f:
+            data = json.load(f)
+            return Portfolio.from_dict(data)
+    except FileNotFoundError:
+        print(f"\nError: Portfolio file '{file_to_load}' not found.", file=sys.stderr)
+        print("\nTo get started:", file=sys.stderr)
+        print(f"1. Create a '{file_to_load}' file in your current directory.", file=sys.stderr)
+        print("2. Or use the --file flag to point to an existing JSON file.", file=sys.stderr)
+        print("\nSee the README for a portfolio.json template.", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError:
+        print(f"Error: The file '{file_to_load}' is not a valid JSON file.", file=sys.stderr)
+        sys.exit(1)
+    except KeyError as e:
+        print(f"Error: Missing expected key {e} in '{file_to_load}'.", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    """The main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        description="A CLI tool for contribution-only portfolio rebalancing."
+    )
+    parser.add_argument(
+        "--contribution", 
+        type=float, 
+        required=True, 
+        help="The dollar amount you are contributing."
+    )
+    parser.add_argument(
+        "--file",
+        type=str,
+        help="Optional: Path to your portfolio JSON file. Defaults to 'portfolio.json'."
+    )
+    args = parser.parse_args()
+
+    portfolio = load_portfolio(args.file)
+    
+    try:
+        recommendations = calculate_rebalance(portfolio, args.contribution)
+        # Display results
+        print("\n" + "="*40)
+        print("     PORTFOLIO REBALANCE REPORT")
+        print("="*40)
+        print(f"Current Value:  ${portfolio.total_value:,.2f}")
+        print(f"Contribution:   ${args.contribution:,.2f}")
+        print("-" * 40)
+        for name, amount in recommendations.items():
+            print(f"{name:<20}: ${amount:>12,.2f}")
+        print("-" * 40)
+        print("Status: Rebalancing Complete.\n")
+    except ValueError as e:
+        print(f"Validation Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

portfolio_rebalancer_cli-0.1.0/rebalancer/models.py

@@ -0,0 +1,37 @@
+"""Defines the classes to represent a portfolio and its components."""
+from dataclasses import dataclass, field
+
+@dataclass
+class AssetClass:
+    name: str
+    target_allocation: float  # As a decimal (ex, 0.60 for 60%)
+    current_balance: float
+
+@dataclass
+class Portfolio:
+    assets: list[AssetClass] = field(default_factory=list)
+
+    @property
+    def total_value(self) -> float:
+        """Calculates the total value across all asset classes."""
+        return sum(asset.current_balance for asset in self.assets)
+
+    def validate(self) -> bool:
+        """Ensures the portfolio is valid in that the target allocations sum to 100%."""
+        total_allocation = sum(asset.target_allocation for asset in self.assets)
+        # Using round to account for floating point math quirks
+        return round(total_allocation, 4) == 1.0
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Portfolio":
+        """Creates a Portfolio instance from a dictionary."""
+        assets = []
+        for dict_item in data.get("assets", []):
+            assets.append(
+                AssetClass(
+                    name=dict_item["name"],
+                    target_allocation=dict_item["target_allocation"],
+                    current_balance=dict_item["current_balance"]
+                )
+            )
+        return cls(assets=assets)

portfolio_rebalancer_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

portfolio_rebalancer_cli-0.1.0/tests/test_engine.py

@@ -0,0 +1,76 @@
+"""Test suite to verify the math implementation in engine.py"""
+import pytest
+from rebalancer.models import AssetClass, Portfolio
+from rebalancer.engine import calculate_rebalance
+
+def test_calculate_rebalance_perfect_fit():
+    """
+    Test case: We have enough contribution to reach the exact target.
+    Portfolio: $900 total. Target: 50/50 ($500/$500).
+    Current: A=$400, B=$500. 
+    Contribution: $100.
+    Expected: Add $100 to A, $0 to B.
+    """
+    # Arrange
+    a = AssetClass("A", 0.5, 400.0)
+    b = AssetClass("B", 0.5, 500.0)
+    portfolio = Portfolio([a, b])
+    contribution = 100.0
+
+    # Act
+    result = calculate_rebalance(portfolio, contribution)
+
+    # Assert
+    assert result["A"] == 100.0
+    assert result["B"] == 0.0
+
+def test_calculate_rebalance_proportional_scaling():
+    """
+    Test case: Contribution is NOT enough to fill the gap.
+    Portfolio: $800 total. Target: 50/50 ($400/$400)
+    Current: A=$400, B=$400.
+    Contribution: $50.
+    Expected: Both get 50% of their gap ($25 each).
+    """
+    # Arrange
+    a = AssetClass("A", 0.5, 400.0) 
+    b = AssetClass("B", 0.5, 400.0)
+    portfolio = Portfolio([a, b])
+    contribution = 50.0
+
+    # Act
+    result = calculate_rebalance(portfolio, contribution)
+
+    # Assert
+    assert result["A"] == 25.0
+    assert result["B"] == 25.0
+
+def test_zero_contribution():
+    """
+    Test case: Contribution is $0.
+    Portfolio: $800 total. Target: 50/50 ($400/$400)
+    Current: A=$400, B=$400.
+    Contribution: $0
+    Expected: Add $0 each.
+    """
+    # Arrange
+    a = AssetClass("A", 0.5, 400.0) 
+    b = AssetClass("B", 0.5, 400.0)
+    portfolio = Portfolio([a, b])
+    contribution = 0.0
+
+    # Act
+    result = calculate_rebalance(portfolio, contribution)
+
+    # Assert
+    assert result["A"] == 0.0
+    assert result["B"] == 0.0
+
+def test_invalid_contribution_raises_error():
+    """
+    Test case: Negative contribution should raise a ValueError.
+    """
+    portfolio = Portfolio([AssetClass("A", 1.0, 100.0)])
+
+    with pytest.raises(ValueError, match="Contribution must be a positive number"):
+        calculate_rebalance(portfolio, -100.0)