owlplanner 2025.5.12__tar.gz → 2025.5.28__tar.gz

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/.github/workflows/github-actions-runtests.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.13"]
 
     steps:
     - uses: actions/checkout@v4

owlplanner-2025.5.28/.streamlit/config.toml

@@ -0,0 +1,2 @@
+[theme]
+base = "dark"

owlplanner-2025.5.28/.streamlit/fullconfig.toml

@@ -0,0 +1,330 @@
+
+[global]
+
+# By default, Streamlit displays a warning when a user sets both a widget
+# default value in the function defining the widget and a widget value via
+# the widget's key in `st.session_state`.
+
+# If you'd like to turn off this warning, set this to True.
+
+# Default: false
+# disableWidgetStateDuplicationWarning = false
+
+# If True, will show a warning when you run a Streamlit-enabled script
+# via "python my_script.py".
+
+# Default: true
+# showWarningOnDirectExecution = true
+
+
+[logger]
+
+# Level of logging for Streamlit's internal logger: "error", "warning",
+# "info", or "debug".
+
+# Default: "info"
+# level = "info"
+
+# String format for logging messages. If logger.datetimeFormat is set,
+# logger messages will default to `%(asctime)s.%(msecs)03d %(message)s`. See
+# Python's documentation for available attributes:
+# https://docs.python.org/3/library/logging.html#formatter-objects
+
+# Default: "%(asctime)s %(message)s"
+# messageFormat = "%(asctime)s %(message)s"
+
+
+[client]
+
+# Controls whether uncaught app exceptions and deprecation warnings
+# are displayed in the browser. This can be one of the following:
+
+# - "full" : In the browser, Streamlit displays app deprecation
+# warnings and exceptions, including exception types,
+# exception messages, and associated tracebacks.
+# - "stacktrace" : In the browser, Streamlit displays exceptions,
+# including exception types, generic exception messages,
+# and associated tracebacks. Deprecation warnings and
+# full exception messages will only print to the
+# console.
+# - "type" : In the browser, Streamlit displays exception types and
+# generic exception messages. Deprecation warnings, full
+# exception messages, and associated tracebacks only
+# print to the console.
+# - "none" : In the browser, Streamlit displays generic exception
+# messages. Deprecation warnings, full exception
+# messages, associated tracebacks, and exception types
+# will only print to the console.
+# - True : This is deprecated. Streamlit displays "full"
+# error details.
+# - False : This is deprecated. Streamlit displays "stacktrace"
+# error details.
+
+# Default: [ "f", "u", "l", "l",]
+# showErrorDetails = [ "f", "u", "l", "l",]
+
+# Change the visibility of items in the toolbar, options menu,
+# and settings dialog (top right of the app).
+
+# Allowed values:
+# - "auto" : Show the developer options if the app is accessed through
+# localhost or through Streamlit Community Cloud as a developer.
+# Hide them otherwise.
+# - "developer" : Show the developer options.
+# - "viewer" : Hide the developer options.
+# - "minimal" : Show only options set externally (e.g. through
+# Streamlit Community Cloud) or through st.set_page_config.
+# If there are no options left, hide the menu.
+
+# Default: "auto"
+toolbarMode = "developer"
+
+# Controls whether to display the default sidebar page navigation in a
+# multi-page app. This only applies when app's pages are defined by the
+# `pages/` directory.
+
+# Default: true
+# showSidebarNavigation = true
+
+[runner]
+
+# Allows you to type a variable or string by itself in a single line of
+# Python code to write it to the app.
+
+# Default: true
+# magicEnabled = true
+
+# Handle script rerun requests immediately, rather than waiting for script
+# execution to reach a yield point. This makes Streamlit much more
+# responsive to user interaction, but it can lead to race conditions in
+# apps that mutate session_state data outside of explicit session_state
+# assignment statements.
+
+# Default: true
+# fastReruns = true
+
+# Raise an exception after adding unserializable data to Session State.
+# Some execution environments may require serializing all data in Session
+# State, so it may be useful to detect incompatibility during development,
+# or when the execution environment will stop supporting it in the future.
+
+# Default: false
+# enforceSerializableSessionState = false
+
+# Adjust how certain 'options' widgets like radio, selectbox, and
+# multiselect coerce Enum members when the Enum class gets re-defined
+# during a script re-run. For more information, check out the docs:
+# https://docs.streamlit.io/develop/concepts/design/custom-classes#enums
+
+# Allowed values:
+# - "off": Disables Enum coercion.
+# - "nameOnly": Enum classes can be coerced if their member names match.
+# - "nameAndValue": Enum classes can be coerced if their member names AND
+# member values match.
+
+# Default: "nameOnly"
+# enumCoercion = "nameOnly"
+
+
+[server]
+
+# List of folders that should not be watched for changes.
+
+# Relative paths will be taken as relative to the current working directory.
+
+# Example: ['/home/user1/env', 'relative/path/to/folder']
+
+# Default: []
+# folderWatchBlacklist = []
+
+# Change the type of file watcher used by Streamlit, or turn it off
+# completely.
+
+# Allowed values:
+# - "auto" : Streamlit will attempt to use the watchdog module, and
+# falls back to polling if watchdog is not available.
+# - "watchdog" : Force Streamlit to use the watchdog module.
+# - "poll" : Force Streamlit to always use polling.
+# - "none" : Streamlit will not watch files.
+
+# Default: "auto"
+# fileWatcherType = "auto"
+
+# Symmetric key used to produce signed cookies. If deploying on multiple
+# replicas, this should be set to the same value across all replicas to ensure
+# they all share the same secret.
+
+# Default: randomly generated secret key.
+# cookieSecret = "b87888855015f2bb50b408cb9d958bb52ea434cc6dacdf971c9e2b4997216925"
+
+# If false, will attempt to open a browser window on start.
+
+# Default: false unless (1) we are on a Linux box where DISPLAY is unset, or
+# (2) we are running in the Streamlit Atom plugin.
+# headless = false
+
+# Automatically rerun script when the file is modified on disk.
+
+# Default: false
+# runOnSave = false
+
+# The address where the server will listen for client and browser
+# connections. Use this if you want to bind the server to a specific address.
+# If set, the server will only be accessible from this address, and not from
+# any aliases (like localhost).
+
+# Default: (unset)
+# address =
+
+# The port where the server will listen for browser connections.
+
+# Don't use port 3000 which is reserved for internal development.
+
+# Default: 8501
+# port = 8501
+
+# The base path for the URL where Streamlit should be served from.
+
+# Default: ""
+# baseUrlPath = ""
+
+# Enables support for Cross-Origin Resource Sharing (CORS) protection,
+# for added security.
+
+# If XSRF protection is enabled and CORS protection is disabled at the
+# same time, Streamlit will enable them both instead.
+
+# Default: true
+# enableCORS = true
+
+# Enables support for Cross-Site Request Forgery (XSRF) protection, for
+# added security.
+
+# If XSRF protection is enabled and CORS protection is disabled at the
+# same time, Streamlit will enable them both instead.
+
+# Default: true
+# enableXsrfProtection = true
+
+# Max size, in megabytes, for files uploaded with the file_uploader.
+
+# Default: 200
+# maxUploadSize = 200
+
+# Max size, in megabytes, of messages that can be sent via the WebSocket
+# connection.
+
+# Default: 200
+# maxMessageSize = 200
+
+# Enables support for websocket compression.
+
+# Default: false
+# enableWebsocketCompression = false
+
+# Enable serving files from a `static` directory in the running app's
+# directory.
+
+# Default: false
+# enableStaticServing = false
+
+# TTL in seconds for sessions whose websockets have been disconnected. The server
+# may choose to clean up session state, uploaded files, etc for a given session
+# with no active websocket connection at any point after this time has passed.
+
+# Default: 120
+# disconnectedSessionTTL = 120
+
+# Server certificate file for connecting via HTTPS.
+# Must be set at the same time as "server.sslKeyFile".
+
+# ['DO NOT USE THIS OPTION IN A PRODUCTION ENVIRONMENT. It has not gone through security audits or performance tests. For the production environment, we recommend performing SSL termination by the load balancer or the reverse proxy.']
+# sslCertFile =
+
+# Cryptographic key file for connecting via HTTPS.
+# Must be set at the same time as "server.sslCertFile".
+
+# ['DO NOT USE THIS OPTION IN A PRODUCTION ENVIRONMENT. It has not gone through security audits or performance tests. For the production environment, we recommend performing SSL termination by the load balancer or the reverse proxy.']
+# sslKeyFile =
+
+
+[browser]
+
+# Internet address where users should point their browsers in order to
+# connect to the app. Can be IP address or DNS name and path.
+
+# This is used to:
+# - Set the correct URL for CORS and XSRF protection purposes.
+# - Show the URL on the terminal
+# - Open the browser
+
+# Default: "localhost"
+# serverAddress = "localhost"
+
+# Whether to send usage statistics to Streamlit.
+
+# Default: true
+# gatherUsageStats = true
+
+# Port where users should point their browsers in order to connect to the
+# app.
+
+# This is used to:
+# - Set the correct URL for XSRF protection purposes.
+# - Show the URL on the terminal (part of `streamlit run`).
+# - Open the browser automatically (part of `streamlit run`).
+
+# This option is for advanced use cases. To change the port of your app, use
+# `server.Port` instead. Don't use port 3000 which is reserved for internal
+# development.
+
+# Default: whatever value is set in server.port.
+# serverPort = 8501
+
+
+[mapbox]
+
+# Configure Streamlit to use a custom Mapbox
+# token for elements like st.pydeck_chart and st.map.
+# To get a token for yourself, create an account at
+# https://mapbox.com. It's free (for moderate usage levels)!
+
+# Default: ""
+# token = ""
+
+
+[theme]
+
+# The preset Streamlit theme that your custom theme inherits from.
+# One of "light" or "dark".
+# base =
+
+# Primary accent color for interactive elements.
+# primaryColor =
+
+# Background color for the main content area.
+# backgroundColor =
+
+# Background color used for the sidebar and most interactive widgets.
+# secondaryBackgroundColor =
+
+# Color used for almost all text.
+# textColor =
+
+# The font family for all text in the app, except code blocks. One of "sans serif",
+# "serif", or "monospace".
+# To use a custom font, it needs to be added via [theme.fontFaces].
+# font =
+
+
+[secrets]
+
+# List of locations where secrets are searched. An entry can be a path to a
+# TOML file or directory path where Kubernetes style secrets are saved.
+# Order is important, import is first to last, so secrets in later files
+# will take precedence over earlier ones.
+
+# Default: [ "C:\\Users\\marti\\.streamlit\\secrets.toml", "C:\\Users\\marti\\Dropbox\\Retirement\\MyProject\\Owl\\.streamlit\\.streamlit\\secrets.toml",]
+# files = [ "C:\\Users\\marti\\.streamlit\\secrets.toml", "C:\\Users\\marti\\Dropbox\\Retirement\\MyProject\\Owl\\.streamlit\\.streamlit\\secrets.toml",]
+
+

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.5.12
+Version: 2025.5.28
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -693,9 +693,11 @@ Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: >=3.8
 Requires-Dist: matplotlib
 Requires-Dist: numpy
+Requires-Dist: odfpy
 Requires-Dist: openpyxl
 Requires-Dist: pandas
 Requires-Dist: plotly
+Requires-Dist: pulp
 Requires-Dist: scipy
 Requires-Dist: seaborn
 Requires-Dist: streamlit
@@ -712,7 +714,7 @@ Description-Content-Type: text/markdown
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a financial retirement planning tool that uses a linear programming
+Owl is a retirement financial planning tool that uses a linear programming
 optimization algorithm to provide guidance on retirement decisions
 such as contributions, withdrawals, Roth conversions, and more.
 Users can select varying return rates to perform historical back testing,

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/README.md

@@ -8,7 +8,7 @@
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a financial retirement planning tool that uses a linear programming
+Owl is a retirement financial planning tool that uses a linear programming
 optimization algorithm to provide guidance on retirement decisions
 such as contributions, withdrawals, Roth conversions, and more.
 Users can select varying return rates to perform historical back testing,

owlplanner-2025.5.28/docker/Dockerfile.build

@@ -0,0 +1,24 @@
+# docker/Dockerfile
+
+FROM python:3.13-slim
+
+WORKDIR /app
+
+RUN apt-get update; \
+    apt-get upgrade; \
+    apt-get install -y --no-install-recommends \
+        curl \
+        git \
+    ; \
+    rm -rf /var/lib/apt/lists/*
+
+COPY buildentrypoint.sh /usr/bin/entrypoint.sh
+COPY runentrypoint.sh /usr/bin/runentrypoint.sh
+
+RUN chmod 555 /usr/bin/entrypoint.sh /usr/bin/runentrypoint.sh
+
+EXPOSE 8501
+
+HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
+
+ENTRYPOINT ["/bin/bash", "/usr/bin/entrypoint.sh"]

owlplanner-2025.5.12/docker/Dockerfile → owlplanner-2025.5.28/docker/Dockerfile.run

@@ -12,20 +12,21 @@ RUN apt-get update; \
     ; \
     rm -rf /var/lib/apt/lists/*
 
-COPY fastentrypoint.sh /usr/bin/entrypoint.sh
+COPY runentrypoint.sh /usr/bin/entrypoint.sh
 
 RUN chmod 555 /usr/bin/entrypoint.sh
 
 # Build in the container for faster starts.
 RUN python -m pip install --no-cache-dir --upgrade pip
 
-RUN pip install --no-cache-dir build
+# RUN pip install --no-cache-dir build
+RUN rm -rf /app/owl
 
 RUN git clone --depth 1 https://github.com/mdlacasse/Owl.git owl
 
-RUN cd /app/owl && python -m build
-
-RUN cd /app/owl && pip install --no-cache-dir .
+RUN cd /app/owl && python -m pip install -r requirements.txt
+# RUN cd /app/owl && python -m build
+# RUN cd /app/owl && pip install --no-cache-dir .
 
 EXPOSE 8501
 

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/docker/README.md

@@ -37,10 +37,14 @@ This approach requires cloning the Owl package from GitHub,
 and having both Python and Docker installed on your computer.
 
 ##### Docker image
+There are two images you can create. One builds Owl at run time, while
+the other builds it statically in the image.
+These two approaches trade startup time for image space
+(~300 MB vs. 1.8 GB, ~22 vs. 200 sec).
 First build the Docker image from the `docker` directory:
 ```shell
 cd docker
-docker build --no-cache -t owldocker .
+docker build --no-cache -f Dockerfile.{build or run} -t owldocker .
 ```
 
 #### Running the container

owlplanner-2025.5.28/docker/buildentrypoint.sh

@@ -0,0 +1,12 @@
+#/bin/bash
+
+# Build at run time for smaller image but slower starts.
+rm -rf /app/owl
+cd /app && git clone --depth 1 https://github.com/mdlacasse/Owl.git owl
+
+export OWLDIR=/app/owl
+
+python -m pip install --no-cache-dir --upgrade pip
+cd ${OWLDIR} && python -m pip install -r requirements.txt
+
+exec /usr/bin/runentrypoint.sh

owlplanner-2025.5.28/docker/runentrypoint.sh

@@ -0,0 +1,17 @@
+#/bin/bash
+
+if ! [[ -v OWLDIR ]]; then
+    OWLDIR=/app/owl
+fi
+
+export PYTHONPATH=${OWLDIR}/src:${PYTHONPATH}
+
+echo ""
+echo "Owl is now running locally: Point your browser to http://localhost:8501"
+
+if type -P streamlit >& /dev/null; then
+    streamlit run ${OWLDIR}/ui/main.py --server.port=8501 --server.address=0.0.0.0 --browser.gatherUsageStats=false
+else
+    python3 -m streamlit run ${OWLDIR}/ui/main.py --server.port=8501 --server.address=0.0.0.0 --browser.gatherUsageStats=false
+fi
+

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/docs/owl.tex

@@ -435,7 +435,7 @@ All intermediate variables are in uppercase letters.
 	Notice that we are using return rates from the previous year.
 	The first terms on the right-hand side represent dividends generated by
         equities $(k=0)$ in the $(j=0)$ taxable savings account plus
-	half the yearly contributions. The second term account for withdrawals $w$
+	half the yearly contributions. The second term accounts for withdrawals $w$
         of equities assumed to have been purchased a year ago. 
 	It does not account for losses, but a market drop
 	would most likely result in stock purchase rather than sale.

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/examples/case_jack+jill.toml

@@ -28,7 +28,7 @@ Names = [ "Jack", "Jill",]
 ["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
-"Dividend tax rate" = 2.0
+"Dividend rate" = 1.8
 "TCJA expiration year" = 2026
 Method = "historical"
 From = 1969

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/examples/case_joe.toml

@@ -26,7 +26,7 @@ Names = [ "Joe",]
 ["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
-"Dividend tax rate" = 2.0
+"Dividend rate" = 1.8
 "TCJA expiration year" = 2026
 Method = "historical average"
 From = 1969

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/examples/case_john+sally.toml

@@ -28,7 +28,7 @@ Names = [ "John", "Sally",]
 ["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
-"Dividend tax rate" = 2.0
+"Dividend rate" = 1.8
 "TCJA expiration year" = 2026
 Method = "historical average"
 From = 1990

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/examples/case_jon+jane.toml

@@ -28,10 +28,10 @@ Names = [ "Jon", "Jane",]
 ["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
-"Dividend tax rate" = 2.0
+"Dividend rate" = 1.8
 "TCJA expiration year" = 2026
 Method = "user"
-Values = [ 10.0, 0.0, 0.0, 3.5000000000000004,]
+Values = [ 10.0, 6.0, 5.0, 3.5000000000000004,]
 From = 1928
 To = 2024
 

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/examples/case_kim+sam-bequest.toml

@@ -28,7 +28,7 @@ Names = [ "Kim", "Sam",]
 ["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 33.0
 "Long-term capital gain tax rate" = 15.0
-"Dividend tax rate" = 2.0
+"Dividend rate" = 1.8
 "TCJA expiration year" = 2026
 Method = "conservative"
 From = 1922

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/examples/case_kim+sam-spending.toml

@@ -28,7 +28,7 @@ Names = [ "Kim", "Sam",]
 ["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 33.0
 "Long-term capital gain tax rate" = 15.0
-"Dividend tax rate" = 2.0
+"Dividend rate" = 1.8
 "TCJA expiration year" = 2026
 Method = "conservative"
 From = 1922

{owlplanner-2025.5.12 → owlplanner-2025.5.28}/notebooks/template.ipynb

@@ -138,24 +138,6 @@
     "plan = owl.Plan(['Kim', 'Sam'], [YYYY, YYYY], [AA, AA], 'Kim+Sam-spending', verbose=True)"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "d1b5aabe",
-   "metadata": {},
-   "source": [
-    "By default, the starting date is today, and therefore the returns of the current year are reduced in proportion of how late we are in the year. An arbitrary date can be chosen as a starting point in the current year, using the optional parameter startDate. This will only affect the first year: the plan will still end at the end of the last year. For example, using startDate='01-01' would select January 1st, the beginning of the year. This is useful for reproducibility studies. Here is an example:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "8a106c03",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# plan = owl.Plan(['Kim', 'Sam'], [YYYY, YYYY], [AA, AA], 'Kim+Sam-spending', startDate='01-01')"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "47f309e7-0654-4f75-87b5-921167db4a6a",
@@ -204,6 +186,29 @@
     "Benificiary fractions are entered as [1, 1, 1], i.e., one for each type of account. Default is to leave everything to the living spouse."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "090914eb-78f3-4e85-bdc9-e7fa03b75aaf",
+   "metadata": {},
+   "source": [
+    "By default, the account balances are assumed to be known as of today, and amounts will be back projected to Jan 1st using the assumed return rates. An arbitrary date can be chosen as a reference point in the current year, using the optional parameter startDate. For example, using startDate='01-01' would select January 1st, the beginning of the year. This is useful for reproducibility studies. Here is an example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "49109e26-bea3-49df-8377-3343111ebfac",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plan.setAccountBalances(\n",
+    "    taxable=[XX, XX],\n",
+    "    taxDeferred=[XX, XX],\n",
+    "    taxFree=[XX, XX],\n",
+    "    startDate=\"01-01\"\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,