yenwealth 0.1.0__tar.gz

yenwealth-0.1.0/.github/workflows/continuous_integration.yaml

@@ -0,0 +1,19 @@
+name: Continuous integration
+on: [push]
+
+jobs:
+  run_commit_stage:
+    runs-on: ubuntu-26.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+      - name: install dependencies
+        run: |
+          pip install -e ".[dev]"
+      - name: run tests
+        run: pytest ./tests
+      - name: run static code analysis
+        run: pycodestyle ./src ./tests

yenwealth-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+*.code-workspace

yenwealth-0.1.0/LICENSE

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

yenwealth-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: yenwealth
+Version: 0.1.0
+Summary: Financial planning tools for individuals living in Japan
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: beartype
+Requires-Dist: pydantic
+Requires-Dist: returns
+Provides-Extra: dev
+Requires-Dist: pycodestyle; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yenwealth
+Financial planning tools for individuals living in Japan
+
+Work in progress. Please come again later. 

yenwealth-0.1.0/README.md

@@ -0,0 +1,4 @@
+# yenwealth
+Financial planning tools for individuals living in Japan
+
+Work in progress. Please come again later. 

yenwealth-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yenwealth"
+version = "0.1.0"
+description = "Financial planning tools for individuals living in Japan"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+dependencies = [
+    "beartype",
+    "pydantic",
+    "returns"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pycodestyle",
+    "pytest",
+]

yenwealth-0.1.0/setup.cfg

@@ -0,0 +1,2 @@
+[pycodestyle]
+max-line-length = 120

yenwealth-0.1.0/src/yenwealth/constants.py

@@ -0,0 +1,4 @@
+import decimal
+
+MILLION = 10**6
+YEN = decimal.Decimal("1")

yenwealth-0.1.0/src/yenwealth/investments.py

@@ -0,0 +1,502 @@
+"""
+Module with investment logic
+"""
+
+import collections
+import copy
+import decimal
+import logging
+
+import beartype
+import pydantic
+import returns.maybe
+
+from . import constants
+from . import utilities
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+@beartype.beartype
+class OrdinaryInvestmentAccount:
+
+    def __init__(
+        self,
+        principal: decimal.Decimal,
+        gain: decimal.Decimal,
+        investment_return_rate: decimal.Decimal,
+        capital_gain_tax_rate: decimal.Decimal
+    ):
+
+        self.investment_return_rate = investment_return_rate
+        self.capital_gain_tax_rate = capital_gain_tax_rate
+        self.principal = principal
+        self.gain = gain
+
+    @property
+    def portfolio_value(self) -> decimal.Decimal:
+        return self.principal + self.gain
+
+    def deposit(self, amount: decimal.Decimal):
+
+        if amount < 0:
+            raise ValueError(f"Deposit amount should be non-negative, got {amount}")
+
+        self.principal += amount
+
+    def advance_one_year(self):
+
+        self.gain += self.investment_return_rate * (self.principal + self.gain)
+
+    def withdraw(self, desired_cash: decimal.Decimal):
+
+        if desired_cash < 0:
+            raise ValueError(f"Withdrawal value should be non-negative, got {desired_cash}")
+
+        if desired_cash > self.portfolio_value:
+            raise ValueError(
+                f"Withdrawal value {desired_cash} exceeds portfolio value {self.portfolio_value}"
+            )
+
+        gain_ratio = self.gain / self.portfolio_value
+
+        # Calculate gross amount needed to liquidate
+        gross_withdrawal = desired_cash / (1 - (gain_ratio * self.capital_gain_tax_rate))
+
+        if gross_withdrawal > self.portfolio_value:
+            raise ValueError(
+                f"Gross withdrawal value {gross_withdrawal} needed to realize desired cash "
+                f"{desired_cash} exceeds portfolio value {self.portfolio_value}"
+            )
+
+        # Proportional splits
+        principal_withdrawn = gross_withdrawal * (1 - gain_ratio)
+        gain_withdrawn = gross_withdrawal * gain_ratio
+
+        # Deduct proportionally from remaining balances
+        self.principal -= principal_withdrawn
+        self.gain -= gain_withdrawn
+
+    @property
+    def max_cash_withdrawal(self) -> decimal.Decimal:
+
+        return (self.portfolio_value - (self.capital_gain_tax_rate * self.gain)) \
+            .quantize(constants.YEN, decimal.ROUND_DOWN)
+
+
+@beartype.beartype
+class IdecoInvestmentAccount:
+
+    def __init__(self, portfolio_value: decimal.Decimal, investment_return_rate: decimal.Decimal):
+
+        self.investment_return_rate = investment_return_rate
+        self.portfolio_value = portfolio_value
+
+        self.max_annual_contribution = decimal.Decimal("0.276") * constants.MILLION
+        self.max_deposit_age = 65
+        self.minimum_withdrawal_start_age = 60
+        self.maximum_withdrawal_start_age = 75
+
+        self.max_tax_free_lump_sum = decimal.Decimal("17.8") * constants.MILLION
+
+        self.has_started_drawing_pension = False
+        self.maybe_pension_period_in_years: returns.maybe.Maybe[int] = returns.maybe.Nothing
+        self.maybe_pension_schema_start_age: returns.maybe.Maybe[int] = returns.maybe.Nothing
+        self.pension_payout_ages: list[int] = []
+
+    def deposit(self, amount: decimal.Decimal, age: int):
+
+        if age >= self.max_deposit_age:
+            raise ValueError(f"Deposit age {age} exceeds maximum allowed deposit age of {self.max_deposit_age}")
+
+        if amount < 0:
+            raise ValueError(f"Deposit amount should be non-negative, got {amount}")
+
+        if amount > self.max_annual_contribution:
+            raise ValueError(
+                f"Deposit amount {amount} exceeds maximum allowed contribution of {self.max_annual_contribution}")
+
+        self.portfolio_value += amount
+
+    def advance_one_year(self):
+
+        self.portfolio_value = self.portfolio_value * (1 + self.investment_return_rate)
+
+    def withdraw_tax_free_lump_sum(self) -> decimal.Decimal:
+
+        amount_withdrawn = min(self.portfolio_value, self.max_tax_free_lump_sum)
+        self.portfolio_value -= amount_withdrawn
+        return amount_withdrawn
+
+    def start_pension_scheme(self, start_age: int, period_in_years: int):
+
+        if start_age < self.minimum_withdrawal_start_age or start_age > self.maximum_withdrawal_start_age:
+            raise ValueError(f"Age {start_age} outside of valid withdrawal start age")
+
+        self.has_started_drawing_pension = True
+        self.maybe_pension_period_in_years = returns.maybe.Some(period_in_years)
+        self.maybe_pension_schema_start_age = returns.maybe.Some(start_age)
+
+    def withdraw_pension(self, age: int) -> decimal.Decimal:
+
+        if self.has_started_drawing_pension is False:
+            raise ValueError("pension scheme not initialized")
+
+        if self.maybe_pension_schema_start_age is returns.maybe.Nothing:
+            raise ValueError("pension schema start age not initialized")
+
+        if self.maybe_pension_period_in_years is returns.maybe.Nothing:
+            raise ValueError("pension period not initialized")
+
+        pension_schema_start_age = self.maybe_pension_schema_start_age.unwrap()
+        pension_period_in_years = self.maybe_pension_period_in_years.unwrap()
+
+        # Check that paid pension history exists for all years between start age and age below this
+        if sorted(self.pension_payout_ages) != list(range(pension_schema_start_age, age)):
+            raise ValueError("missing pension withdrawal for same ages")
+
+        if age > pension_schema_start_age + pension_period_in_years:
+            raise ValueError("iDeCo pension scheme finished")
+
+        withdrawal_proportion = 1 / (pension_period_in_years - len(self.pension_payout_ages))
+
+        withdrawal = self.portfolio_value * decimal.Decimal(withdrawal_proportion)
+        self.portfolio_value -= withdrawal
+        self.pension_payout_ages.append(age)
+
+        return withdrawal
+
+
+@beartype.beartype
+class OldNisaAccount:
+    """
+    Old NISA account that no longer allows deposit, and requires investments to be withdrawn within 20 years
+    from when they were made.
+    """
+
+    def __init__(self, year_to_portfolio_map: dict[int, decimal.Decimal], investment_return_rate: decimal.Decimal):
+
+        self.year_to_portfolio_map = copy.deepcopy(year_to_portfolio_map)
+        self.investment_return_rate = investment_return_rate
+
+    def advance_one_year(self, year: int):
+
+        for investment_year in self.year_to_portfolio_map.keys():
+
+            if investment_year + 20 < year:
+                raise ValueError(f"nisa investment for year {investment_year} must be liquidated")
+
+            self.year_to_portfolio_map[investment_year] = \
+                self.year_to_portfolio_map[investment_year] * (1 + self.investment_return_rate)
+
+    @property
+    def portfolio_value(self) -> decimal.Decimal:
+
+        return decimal.Decimal(sum(self.year_to_portfolio_map.values()))
+
+    def withdraw_for_year(self, portfolio_year: int, desired_cash: decimal.Decimal):
+        """
+        Withdraw from portfolio established on portfolio_year
+        """
+
+        portfolio_value = self.year_to_portfolio_map[portfolio_year]
+
+        if portfolio_value < desired_cash:
+            raise ValueError(f"Portfolio value for {portfolio_year} is not large enough")
+
+        self.year_to_portfolio_map[portfolio_year] -= desired_cash
+
+    def withdraw(self, desired_cash: decimal.Decimal):
+        """
+        Withdraw from portfolio in order of oldest to newest
+        """
+
+        if desired_cash < 0:
+            raise ValueError(f"Withdrawal value should be non-negative, got {desired_cash}")
+
+        if desired_cash > self.portfolio_value:
+            raise ValueError(
+                f"Withdrawal value {desired_cash} exceeds portfolio value {self.portfolio_value}"
+            )
+
+        total_withdrawal = decimal.Decimal("0")
+
+        for investment_year in sorted(self.year_to_portfolio_map.keys()):
+
+            withdrawal_from_year = min(desired_cash - total_withdrawal, self.year_to_portfolio_map[investment_year])
+
+            self.withdraw_for_year(portfolio_year=investment_year, desired_cash=withdrawal_from_year)
+            total_withdrawal += withdrawal_from_year
+
+            if total_withdrawal == desired_cash:
+                return
+
+
+@beartype.beartype
+class NisaAccount:
+    """
+    NISA account
+    """
+
+    def __init__(
+        self,
+        principal: decimal.Decimal,
+        gain: decimal.Decimal,
+        investment_return_rate: decimal.Decimal
+    ):
+
+        self.annual_deposit_limit = decimal.Decimal("3.6") * constants.MILLION
+        self.total_deposit_limit = decimal.Decimal("18") * constants.MILLION
+
+        if principal > self.total_deposit_limit:
+            raise ValueError(f"Principal {principal} exceeds total deposit limit of {self.total_deposit_limit}")
+
+        self.principal = principal
+        self.gain = gain
+        self.investment_return_rate = investment_return_rate
+
+        self.year_to_deposit_map = collections.defaultdict(decimal.Decimal)
+
+    @property
+    def portfolio_value(self) -> decimal.Decimal:
+        return self.principal + self.gain
+
+    def deposit(self, amount: decimal.Decimal, year: int):
+
+        if amount < 0:
+            raise ValueError(f"Deposit amount should be non-negative, got {amount}")
+
+        if self.principal + amount > self.total_deposit_limit:
+
+            message = f"With deposit {amount}, principal would exceed total deposit limit of {self.total_deposit_limit}"
+            raise ValueError(message)
+
+        deposit_for_target_year = self.year_to_deposit_map[year]
+
+        if deposit_for_target_year + amount > self.annual_deposit_limit:
+            message = (
+                f"With deposit {amount}, annual deposit limit of {self.annual_deposit_limit} would be exceeded. "
+                f"Current deposit for year {year} is {deposit_for_target_year}"
+            )
+            raise ValueError(message)
+
+        self.year_to_deposit_map[year] += amount
+        self.principal += amount
+
+    def advance_one_year(self):
+
+        self.gain += self.investment_return_rate * (self.principal + self.gain)
+
+    def withdraw(self, desired_amount: decimal.Decimal):
+
+        if desired_amount > self.portfolio_value:
+            raise ValueError(f"Desired amount {desired_amount} exceeds portfolio value {self.portfolio_value}")
+
+        gain_ratio = self.portfolio_value / self.principal
+
+        principal_withdrawn = desired_amount / gain_ratio
+
+        self.principal -= principal_withdrawn
+        self.gain -= desired_amount - principal_withdrawn
+
+
+class IdecoPolicy(pydantic.BaseModel):
+    withdrawal_start_age: int
+    withdrawal_period_in_years: int
+
+
+class InvestmentPolicy(pydantic.BaseModel):
+    ideco: IdecoPolicy
+
+
+@beartype.beartype
+class InvestmentManager:
+
+    def __init__(
+        self,
+        ordinary_investment_account: OrdinaryInvestmentAccount,
+        ideco_investment_account: IdecoInvestmentAccount,
+        old_nisa_account: OldNisaAccount,
+        nisa_account: NisaAccount,
+        investment_policy: InvestmentPolicy,
+        start_age: int,
+        start_year: int
+    ):
+        """
+        Constructor
+
+        Args:
+            start_age (int): age of the person for whom investments are managed at simulation start.
+            start_year (int): year at which simulation started.
+        """
+
+        self.ordinary_investment_account = ordinary_investment_account
+        self.ideco_investment_account = ideco_investment_account
+        self.old_nisa_account = old_nisa_account
+        self.nisa_account = nisa_account
+        self.investment_policy = investment_policy
+        self.start_age = start_age
+        self.start_year = start_year
+
+    @property
+    def portfolio_value(self) -> decimal.Decimal:
+        return \
+            self.ordinary_investment_account.portfolio_value + \
+            self.ideco_investment_account.portfolio_value + \
+            self.old_nisa_account.portfolio_value + \
+            self.nisa_account.portfolio_value
+
+    def advance_one_year(self, year):
+
+        self.ordinary_investment_account.advance_one_year()
+        self.ideco_investment_account.advance_one_year()
+        self.old_nisa_account.advance_one_year(year)
+        self.nisa_account.advance_one_year()
+
+    def deposit(self, amount: decimal.Decimal, age: int):
+
+        if amount < 0:
+            raise ValueError(f"Deposit amount should be non-negative, got {amount}")
+
+        if amount == 0:
+            return
+
+        if age < self.ideco_investment_account.max_deposit_age:
+
+            amount_deposited_to_ideco = min(amount, self.ideco_investment_account.max_annual_contribution)
+            self.ideco_investment_account.deposit(amount=amount_deposited_to_ideco, age=age)
+            amount -= amount_deposited_to_ideco
+
+            LOGGER.debug(
+                f"Deposited {utilities.format_million_yen(amount_deposited_to_ideco)} to iDeCo account")
+
+        if self.nisa_account.principal < self.nisa_account.total_deposit_limit:
+
+            current_year = self.start_year + age - self.start_age
+
+            amount_deposited_to_nisa = min(
+                self.nisa_account.total_deposit_limit - self.nisa_account.principal,
+                self.nisa_account.annual_deposit_limit - self.nisa_account.year_to_deposit_map[current_year],
+                amount
+            )
+
+            self.nisa_account.deposit(amount_deposited_to_nisa, current_year)
+            amount -= amount_deposited_to_nisa
+
+            LOGGER.debug(
+                f"Deposited {utilities.format_million_yen(amount_deposited_to_nisa)} to NISA account")
+
+        if amount > 0:
+
+            self.ordinary_investment_account.deposit(amount)
+            LOGGER.debug(
+                f"Deposited {utilities.format_million_yen(amount)} to ordinary investment account")
+
+    def withdraw(self, desired_cash: decimal.Decimal) -> decimal.Decimal:
+
+        desired_cash = desired_cash.quantize(constants.YEN, decimal.ROUND_UP)
+
+        if desired_cash < 0:
+            raise ValueError(f"Withdrawal value should be non-negative, got {desired_cash}")
+
+        total_cash_withdrawn = decimal.Decimal("0")
+
+        # Establish how much to withdraw from ordinary account
+        withdrawal_from_ordinary_account = min(
+            desired_cash - total_cash_withdrawn,
+            self.ordinary_investment_account.max_cash_withdrawal
+        ).quantize(constants.YEN, rounding=decimal.ROUND_DOWN)
+
+        if withdrawal_from_ordinary_account > 0:
+
+            self.ordinary_investment_account.withdraw(withdrawal_from_ordinary_account)
+            total_cash_withdrawn += withdrawal_from_ordinary_account
+
+        withdrawal_from_old_nisa = min(
+            desired_cash - total_cash_withdrawn,
+            self.old_nisa_account.portfolio_value
+        ).quantize(constants.YEN, rounding=decimal.ROUND_UP)
+
+        if withdrawal_from_old_nisa > 0:
+
+            self.old_nisa_account.withdraw(withdrawal_from_old_nisa)
+            total_cash_withdrawn += withdrawal_from_old_nisa
+
+        # Establish how much to withdraw from NISA
+        withdrawal_from_nisa = min(
+            desired_cash - total_cash_withdrawn,
+            self.nisa_account.portfolio_value
+        ).quantize(constants.YEN, rounding=decimal.ROUND_UP)
+
+        if withdrawal_from_nisa > 0:
+
+            self.nisa_account.withdraw(withdrawal_from_nisa)
+            total_cash_withdrawn += withdrawal_from_nisa
+
+        if total_cash_withdrawn < desired_cash:
+
+            raise ValueError(f"Not enough funds to withdraw {desired_cash}")
+
+        return total_cash_withdrawn
+
+    def optimize_investments(self, age: int):
+        """
+        Optimize investments based on the investment policy.
+        """
+
+        current_year = self.start_year + (age - self.start_age)
+
+        # Check if any old nisa account portfolio has to be liquidated
+        if (current_year - 20) in self.old_nisa_account.year_to_portfolio_map.keys():
+
+            portfolio_value = self.old_nisa_account.year_to_portfolio_map.pop(current_year - 20)
+            self.ordinary_investment_account.deposit(portfolio_value)
+
+            LOGGER.debug(
+                f"Moved {utilities.format_million_yen(portfolio_value)} from old NISA account "
+                f"for year {current_year - 20} to ordinary investment account"
+            )
+
+        # Check if we should do lump withdrawal from iDeCo
+        if age == self.investment_policy.ideco.withdrawal_start_age:
+
+            tax_free_lump_sum = self.ideco_investment_account.withdraw_tax_free_lump_sum()
+            self.ordinary_investment_account.deposit(tax_free_lump_sum)
+
+            LOGGER.debug(
+                f"Withdrew tax-free lump sum of {utilities.format_million_yen(tax_free_lump_sum)} "
+                "from iDeCo account")
+
+        if self.nisa_account.principal < self.nisa_account.total_deposit_limit:
+
+            nisa_deposit = min(
+                self.nisa_account.total_deposit_limit - self.nisa_account.principal,
+                self.nisa_account.annual_deposit_limit,
+                self.ordinary_investment_account.max_cash_withdrawal
+            )
+
+            self.ordinary_investment_account.withdraw(nisa_deposit)
+            self.nisa_account.deposit(nisa_deposit, self.start_year + age - self.start_year)
+
+            LOGGER.debug(
+                f"Moved {utilities.format_million_yen(nisa_deposit)} "
+                "from ordinary investment account to NISA account"
+            )
+
+    def get_portfolio_summary(self) -> dict[str, decimal.Decimal]:
+
+        return {
+            "ordinary_investment_account": self.ordinary_investment_account.portfolio_value,
+            "ideco_investment_account": self.ideco_investment_account.portfolio_value,
+            "old_nisa_account": self.old_nisa_account.portfolio_value,
+            "nisa_account": self.nisa_account.portfolio_value,
+            "total_portfolio_value": self.portfolio_value
+        }
+
+    def get_formatted_portfolio_summary_description(self) -> str:
+
+        return "\n".join(
+            f"{key}: {value / constants.MILLION:.3f} mln yen"
+            for key, value in self.get_portfolio_summary().items()
+        )

yenwealth-0.1.0/src/yenwealth/utilities.py

@@ -0,0 +1,12 @@
+"""
+Module with utilities
+"""
+
+import decimal
+
+
+def format_million_yen(value: float | int | decimal.Decimal) -> str:
+    """
+    Format a value in million yen
+    """
+    return f"{decimal.Decimal(str(value)) / 10**6:.2f} million yen"

yenwealth-0.1.0/tests/test_investments.py

@@ -0,0 +1,516 @@
+import decimal
+import math
+
+import pytest
+
+import yenwealth.investments
+
+
+class TestOrdinaryInvestmentAccount:
+    """
+    Test for OrdinaryInvestmentAccount
+    """
+
+    def test_value_of_portfolio_without_investments(self):
+
+        assert yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("0"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2")
+        ).portfolio_value == decimal.Decimal("0")
+
+    def test_value_of_portfolio_with_investments(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2"))
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("1000"), rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, decimal.Decimal("0"), rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, decimal.Decimal("1000"), rel_tol=1e-2)
+
+        investment_account.deposit(decimal.Decimal("10"))
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("1010"), rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, decimal.Decimal("0"), rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, decimal.Decimal("1010"), rel_tol=1e-2)
+
+    def test_advancement_of_portfolio_value_over_time(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2")
+        )
+
+        investment_account.advance_one_year()
+
+        assert math.isclose(investment_account.principal, 1000, rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, 100, rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, 1100, rel_tol=1e-2)
+
+        investment_account.advance_one_year()
+
+        assert math.isclose(investment_account.principal, 1000, rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, 210, rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, 1210, rel_tol=1e-2)
+
+        investment_account.deposit(amount=decimal.Decimal("1000"))
+
+        assert math.isclose(investment_account.principal, 2000, rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, 210, rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, 2210, rel_tol=1e-2)
+
+        investment_account.advance_one_year()
+
+        assert math.isclose(investment_account.principal, 2000, rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, 431, rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, 2431, rel_tol=1e-2)
+
+    def test_withdraw_over_portfolio_value(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2"))
+
+        with pytest.raises(ValueError):
+            investment_account.withdraw(desired_cash=decimal.Decimal("2000"))
+
+    def test_withdraw(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2")
+        )
+
+        investment_account.advance_one_year()
+        investment_account.advance_one_year()
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("1000"), rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, decimal.Decimal("210"), rel_tol=1e-2)
+        assert math.isclose(investment_account.portfolio_value, decimal.Decimal("1210"), rel_tol=1e-2)
+
+        investment_account.withdraw(desired_cash=decimal.Decimal("500"))
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("571.9178"), rel_tol=1e-4)
+        assert math.isclose(investment_account.gain, decimal.Decimal("120.1027"), rel_tol=1e-4)
+        assert math.isclose(investment_account.portfolio_value, decimal.Decimal("692.0205"), rel_tol=1e-4)
+
+    def test_withdrawing_zero(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2")
+        )
+
+        investment_account.advance_one_year()
+        investment_account.advance_one_year()
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("1000"), rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, decimal.Decimal("210"), rel_tol=1e-2)
+
+        investment_account.withdraw(desired_cash=decimal.Decimal("0"))
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("1000"), rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, decimal.Decimal("210"), rel_tol=1e-2)
+
+    def test_withdrawing_negative_amount(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2"))
+
+        with pytest.raises(ValueError):
+            investment_account.withdraw(desired_cash=decimal.Decimal("-100"))
+
+    def test_max_cash_withdrawal(self):
+
+        investment_account = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("1000"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1"),
+            capital_gain_tax_rate=decimal.Decimal("0.2")
+        )
+
+        investment_account.advance_one_year()
+        investment_account.advance_one_year()
+
+        assert math.isclose(investment_account.principal, decimal.Decimal("1000"), rel_tol=1e-2)
+        assert math.isclose(investment_account.gain, decimal.Decimal("210"), rel_tol=1e-2)
+
+        assert investment_account.max_cash_withdrawal == decimal.Decimal("1168")
+
+
+class TestIdecoInvestmentAccount:
+
+    def test_withdrawing_pensions_without_initializing_it_first(self):
+
+        ideco = yenwealth.investments.IdecoInvestmentAccount(
+            portfolio_value=decimal.Decimal("100"),
+            investment_return_rate=decimal.Decimal("0")
+        )
+
+        with pytest.raises(ValueError):
+            ideco.withdraw_pension(70)
+
+    def test_withdrawing_pensions(self):
+
+        period_in_years = 5
+
+        ideco = yenwealth.investments.IdecoInvestmentAccount(
+            portfolio_value=decimal.Decimal("100"),
+            investment_return_rate=decimal.Decimal("0")
+        )
+
+        ideco.start_pension_scheme(
+            start_age=70,
+            period_in_years=period_in_years
+        )
+
+        # First withdrawal
+        portfolio_value_before_withdrawal = ideco.portfolio_value
+        amount = ideco.withdraw_pension(age=70)
+        assert abs(amount - (portfolio_value_before_withdrawal / 5)) < decimal.Decimal("0.001")
+
+        # Second withdrawal
+        portfolio_value_before_withdrawal = ideco.portfolio_value
+        amount = ideco.withdraw_pension(age=71)
+        assert abs(amount - (portfolio_value_before_withdrawal / 4)) < decimal.Decimal("0.001")
+
+        # Third withdrawal
+        portfolio_value_before_withdrawal = ideco.portfolio_value
+        amount = ideco.withdraw_pension(age=72)
+        assert abs(amount - (portfolio_value_before_withdrawal / 3)) < decimal.Decimal("0.001")
+
+        # # Fourth withdrawal
+        portfolio_value_before_withdrawal = ideco.portfolio_value
+        amount = ideco.withdraw_pension(age=73)
+        assert abs(amount - (portfolio_value_before_withdrawal / 2)) < decimal.Decimal("0.001")
+
+        # Last withdrawal
+        portfolio_value_before_withdrawal = ideco.portfolio_value
+        amount = ideco.withdraw_pension(age=74)
+        assert abs(amount - portfolio_value_before_withdrawal) < decimal.Decimal("0.001")
+
+        assert ideco.portfolio_value == decimal.Decimal("0")
+
+
+class TestOldNisaAccount:
+
+    def test_advance_one_year(self):
+
+        nisa = yenwealth.investments.OldNisaAccount(
+            year_to_portfolio_map={
+                2020: decimal.Decimal("100"),
+                2021: decimal.Decimal("50")
+            },
+            investment_return_rate=decimal.Decimal("0.1")
+        )
+
+        nisa.advance_one_year(2025)
+
+        assert abs(nisa.year_to_portfolio_map[2020] - decimal.Decimal(110)) < decimal.Decimal("0.001")
+        assert abs(nisa.year_to_portfolio_map[2021] - decimal.Decimal(55)) < decimal.Decimal("0.001")
+
+    def test_advance_one_year_over_twenty_years_for_any_investment(self):
+
+        nisa = yenwealth.investments.OldNisaAccount(
+            year_to_portfolio_map={
+                2020: decimal.Decimal("100"),
+                2021: decimal.Decimal("50")
+            },
+            investment_return_rate=decimal.Decimal("0.1")
+        )
+
+        with pytest.raises(ValueError):
+            nisa.advance_one_year(2041)
+
+    def test_withdraw_for_invalid_year(self):
+
+        nisa = yenwealth.investments.OldNisaAccount(
+            year_to_portfolio_map={
+                2020: decimal.Decimal("100"),
+                2021: decimal.Decimal("50")
+            },
+            investment_return_rate=decimal.Decimal("0.1")
+        )
+
+        with pytest.raises(KeyError):
+            nisa.withdraw_for_year(portfolio_year=2022, desired_cash=decimal.Decimal("10"))
+
+    def test_valid_withdraw_for_year(self):
+
+        nisa = yenwealth.investments.OldNisaAccount(
+            year_to_portfolio_map={
+                2020: decimal.Decimal("100"),
+                2021: decimal.Decimal("50")
+            },
+            investment_return_rate=decimal.Decimal("0.1")
+        )
+
+        nisa.withdraw_for_year(portfolio_year=2020, desired_cash=decimal.Decimal("10"))
+
+        assert nisa.year_to_portfolio_map[2020] == decimal.Decimal("90")
+
+    def test_withdraw(self):
+
+        nisa = yenwealth.investments.OldNisaAccount(
+            year_to_portfolio_map={
+                2020: decimal.Decimal("100"),
+                2021: decimal.Decimal("50")
+            },
+            investment_return_rate=decimal.Decimal("0.1")
+        )
+
+        nisa.withdraw(desired_cash=decimal.Decimal("120"))
+
+        assert nisa.year_to_portfolio_map[2020] == decimal.Decimal("0")
+        assert nisa.year_to_portfolio_map[2021] == decimal.Decimal("30")
+
+
+class TestNisaAccount:
+
+    def test_initial_deposit_over_max_limit(self):
+
+        with pytest.raises(ValueError):
+
+            yenwealth.investments.NisaAccount(
+                principal=decimal.Decimal("20") * yenwealth.constants.MILLION,
+                gain=decimal.Decimal("0"),
+                investment_return_rate=decimal.Decimal("0")
+            )
+
+    def test_deposit_over_annual_limit(self):
+
+        nisa = yenwealth.investments.NisaAccount(
+            principal=decimal.Decimal("0"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0")
+        )
+
+        # Within limit
+        nisa.deposit(amount=decimal.Decimal("2_000_000"), year=2025)
+
+        with pytest.raises(ValueError):
+
+            # Over limit for targer year
+            nisa.deposit(amount=decimal.Decimal("2_000_000"), year=2025)
+
+    def test_deposit(self):
+
+        nisa = yenwealth.investments.NisaAccount(
+            principal=decimal.Decimal("0"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0")
+        )
+
+        nisa.deposit(amount=decimal.Decimal("2_000_000"), year=2025)
+
+        assert nisa.principal == decimal.Decimal("2_000_000")
+        assert nisa.year_to_deposit_map[2025] == decimal.Decimal("2_000_000")
+        assert nisa.portfolio_value == decimal.Decimal("2_000_000")
+
+        nisa.deposit(amount=decimal.Decimal("1_000_000"), year=2025)
+
+        assert nisa.principal == decimal.Decimal("3_000_000")
+        assert nisa.year_to_deposit_map[2025] == decimal.Decimal("3_000_000")
+        assert nisa.portfolio_value == decimal.Decimal("3_000_000")
+
+        nisa.deposit(amount=decimal.Decimal("1_000_000"), year=2026)
+
+        assert nisa.principal == decimal.Decimal("4_000_000")
+        assert nisa.year_to_deposit_map[2025] == decimal.Decimal("3_000_000")
+        assert nisa.year_to_deposit_map[2026] == decimal.Decimal("1_000_000")
+        assert nisa.portfolio_value == decimal.Decimal("4_000_000")
+
+    def test_advance_one_year(self):
+
+        nisa = yenwealth.investments.NisaAccount(
+            principal=decimal.Decimal("100"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.1")
+        )
+
+        nisa.advance_one_year()
+
+        assert nisa.principal == decimal.Decimal("100")
+        assert nisa.gain == decimal.Decimal("10")
+        assert nisa.portfolio_value == decimal.Decimal("110")
+
+        nisa.deposit(amount=decimal.Decimal("50"), year=2025)
+
+        assert nisa.principal == decimal.Decimal("150")
+        assert nisa.gain == decimal.Decimal("10")
+        assert nisa.portfolio_value == decimal.Decimal("160")
+
+        nisa.advance_one_year()
+
+        assert nisa.principal == decimal.Decimal("150")
+        assert nisa.gain == decimal.Decimal("26")
+        assert nisa.portfolio_value == decimal.Decimal("176")
+
+    def test_withdrawal_over_portolio_value(self):
+
+        nisa = yenwealth.investments.NisaAccount(
+            principal=decimal.Decimal("100"),
+            gain=decimal.Decimal("100"),
+            investment_return_rate=decimal.Decimal("0")
+        )
+
+        with pytest.raises(ValueError):
+
+            nisa.withdraw(decimal.Decimal("210"))
+
+    def test_withdrawal(self):
+
+        initial_principal = decimal.Decimal("100")
+        initial_portfolio_value = decimal.Decimal("200")
+
+        nisa = yenwealth.investments.NisaAccount(
+            principal=initial_principal,
+            gain=initial_portfolio_value - initial_principal,
+            investment_return_rate=decimal.Decimal("0")
+        )
+
+        assert nisa.principal == initial_principal
+        assert nisa.gain == decimal.Decimal("100")
+        assert nisa.portfolio_value == initial_portfolio_value
+
+        desired_amount = decimal.Decimal("50")
+
+        nisa.withdraw(desired_amount)
+
+        assert nisa.portfolio_value == decimal.Decimal("150")
+        assert nisa.gain == decimal.Decimal("75")
+        assert nisa.principal == decimal.Decimal("75")
+
+
+class TestInvestmentPolicy:
+
+    def test_construction_with_valid_data(self):
+
+        policy = yenwealth.investments.InvestmentPolicy.model_validate(
+            {
+                "ideco": {
+                    "withdrawal_start_age": 75,
+                    "withdrawal_period_in_years": 20
+                }
+            }
+        )
+
+        assert policy.ideco.withdrawal_start_age == 75
+        assert policy.ideco.withdrawal_period_in_years == 20
+
+
+class TestInvestmentManager:
+
+    @pytest.fixture
+    def investment_manager(self):
+
+        # 1. Ordinary Account: 0 principal, 0 gain, 0 tax for simple math
+        ordinary = yenwealth.investments.OrdinaryInvestmentAccount(
+            principal=decimal.Decimal("0"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.05"),
+            capital_gain_tax_rate=decimal.Decimal("0.20")
+        )
+
+        # 2. iDeCo Account: 0 initial portfolio
+        ideco = yenwealth.investments.IdecoInvestmentAccount(
+            portfolio_value=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.05")
+        )
+
+        # 3. Old NISA Account: empty year map
+        old_nisa = yenwealth.investments.OldNisaAccount(
+            year_to_portfolio_map={},
+            investment_return_rate=decimal.Decimal("0.05")
+        )
+
+        # 4. NISA Account: 0 principal, 0 gain
+        nisa = yenwealth.investments.NisaAccount(
+            principal=decimal.Decimal("0"),
+            gain=decimal.Decimal("0"),
+            investment_return_rate=decimal.Decimal("0.05")
+        )
+
+        # 5. Investment Policy: Withdrawal starts at age 75 for 20 years
+        policy = yenwealth.investments.InvestmentPolicy(
+            ideco=yenwealth.investments.IdecoPolicy(
+                withdrawal_start_age=75,
+                withdrawal_period_in_years=20
+            )
+        )
+
+        return yenwealth.investments.InvestmentManager(
+            ordinary_investment_account=ordinary,
+            ideco_investment_account=ideco,
+            old_nisa_account=old_nisa,
+            nisa_account=nisa,
+            investment_policy=policy,
+            start_age=30,
+            start_year=2024
+        )
+
+    def test_deposit_priority(self, investment_manager):
+
+        # Deposit 5,000,000 Yen at age 30
+        # Expected order: iDeCo (max 276,000) -> NISA (max 3,600,000) -> Ordinary (rest: 1,124,000)
+        investment_manager.deposit(amount=decimal.Decimal("5_000_000"), age=30)
+
+        assert investment_manager.ideco_investment_account.portfolio_value == decimal.Decimal("276_000")
+        assert investment_manager.nisa_account.principal == decimal.Decimal("3_600_000")
+        assert investment_manager.ordinary_investment_account.principal == decimal.Decimal("1_124_000")
+
+    def test_withdraw_priority(self, investment_manager):
+
+        # Setup initial balances directly
+        investment_manager.ordinary_investment_account.principal = decimal.Decimal("1_000_000")
+        investment_manager.old_nisa_account.year_to_portfolio_map = {2010: decimal.Decimal("500_000")}
+        investment_manager.nisa_account.principal = decimal.Decimal("2_000_000")
+
+        # Withdraw 2,000,000 Yen
+        # Expected order: Ordinary (1,000,000) -> Old NISA (500,000) -> NISA (500,000)
+        withdrawn = investment_manager.withdraw(desired_cash=decimal.Decimal("2_000_000"))
+
+        assert withdrawn == decimal.Decimal("2_000_000")
+        assert investment_manager.ordinary_investment_account.portfolio_value == decimal.Decimal("0")
+        assert investment_manager.old_nisa_account.portfolio_value == decimal.Decimal("0")
+        assert investment_manager.nisa_account.portfolio_value == decimal.Decimal("1_500_000")
+
+    def test_optimize_investments_old_nisa_liquidation(self, investment_manager):
+
+        # Current year = start_year (2024) + age (50) - start_age (30) = 2044
+        # 20 years prior = 2024. Populate Old NISA portfolio for 2024
+        investment_manager.old_nisa_account.year_to_portfolio_map = {2024: decimal.Decimal("1_000_000")}
+
+        investment_manager.optimize_investments(age=50)
+
+        # 2024 Old NISA portfolio should be removed and moved into NISA Account
+        assert 2024 not in investment_manager.old_nisa_account.year_to_portfolio_map
+        assert investment_manager.nisa_account.principal == decimal.Decimal("1_000_000")
+
+    def test_optimize_investments_ideco_lump_sum_and_nisa_topup(self, investment_manager):
+
+        investment_manager.ideco_investment_account.portfolio_value = decimal.Decimal("10_000_000")
+
+        # Set age to policy withdrawal_start_age (75)
+        investment_manager.optimize_investments(age=75)
+
+        # 1. iDeCo 10M transferred to Ordinary Account tax-free
+        # 2. Ordinary Account then transfers 3.6M (annual limit) to NISA Account
+        assert investment_manager.ideco_investment_account.portfolio_value == decimal.Decimal("0")
+        assert investment_manager.nisa_account.principal == decimal.Decimal("3_600_000")
+        assert investment_manager.ordinary_investment_account.principal == decimal.Decimal("6_400_000")