Morai

Table of Contents

• Morai
  • Table of Contents
  • Overview
  • Installation
    • Local Install
    • Docker Install
  • Usage
    • CLI
  • Other Tools
    • Jupyter Lab Usage
    • Logging
    • Claude Skills
    • Coverage

Overview

📖 Description:

Moirai in greek mythology are known as the fates. They are personifications of destiny. The name Morai was chosen as the package is designed to help actuaries review mortality and experience data.

📊 Dashboard:

• Dashboard
• Data Overview:
• Data Tables:
• Data CDC:

🔬 Jupyter Notebook:

• Data Process
• Exploratory
• Predictive Models
• And Others

Installation

Install

To install the base package

uv pip install morai

To install optional dependencies

uv pip install morai[dev][neural][r]

Local Install

To install, download this repository and run the following command in the environment of choice. Optional dependencies can be installed by adding [dev][neural][r] to the end of the command.

uv pip install -e .

Docker Install

The package can also be run in docker which provides a containerized environment, hosting the web dashboard.

version: "3.8"
services:
  morai:
    image: dmbymdt/morai:latest
    container_name: morai
    command: gunicorn -b 0.0.0.0:8001 --timeout 180 morai.dashboard.app:server
    restart: unless-stopped
    environment:
      MORAI_FILES_PATH: /code/morai/files # setting the files path for morai
    ports:
      - '8001:8001'
    volumes:
      - $DOCKERDIR/morai/files:/code/morai/files # mounting the files directory

Usage

CLI

CLI can be used for easier commands of python scripts for both portfolio or manager. An example of a CLI command is shown below. When running the dashboard the MORAI_FILES_PATH environment variable needs to be set to the directory where the files are stored.

morai dashboard

It also can be run locally by running below in the root directory of the repository.

python -m morai.dashboard.app

Other Tools

Jupyter Lab Usage

To have conda environments work with Jupyter Notebooks a kernel needs to be defined. This can be done defining a kernel, shown below when in the conda environment.

python -m ipykernel install --user --name=morai

If plotly images are not showing in the default set up there may need to be some extensions added to JupyterLab. The extension particularly needed is the jupyterlab-plotly extension. This is also discussed more in this issue: Plotly Issue

Logging

If wanting to get more detail in output of messages the logging can increased

from morai.utils import custom_logger
custom_logger.set_log_level("DEBUG")

Claude Skills

Project-scoped Claude Code skills live in .claude/skills/:

• model-review — A/E review for any fitted mortality model (GLM, GAM, CatBoost, Neural)
• nn-review — neural-network-specific diagnostics (SHAP, embeddings, loss curves)
• mortality-table-build — build a deliverable rate table from a fitted model

Shared actuarial reference material is in .claude/skills/_shared/.

Coverage

To see the test coverage the following command is run in the root directory.

pytest --cov=morai --cov-report=html

To test static typing

mypy morai