Makefile

# =============================================================================
# Toolchain resolution
#
# This project strictly targets Python 3.13 via the `fintech_env` pyenv virtualenv.
# We resolve every tool through the env prefix so things work whether or not
# pyenv-virtualenv auto-activation is configured in your shell.
#
# If `fintech_env` doesn't exist yet, run:
#   pyenv install -s 3.13.3
#   pyenv virtualenv 3.13.3 fintech_env
#   pyenv local fintech_env
# =============================================================================

PYENV_VENV         := fintech_env
FINTECH_ENV_PREFIX := $(shell pyenv prefix $(PYENV_VENV) 2>/dev/null)

PYTHON           := $(FINTECH_ENV_PREFIX)/bin/python
PIP              := $(PYTHON) -m pip
DBT              := $(FINTECH_ENV_PREFIX)/bin/dbt
RUFF             := $(FINTECH_ENV_PREFIX)/bin/ruff
PYTEST           := $(FINTECH_ENV_PREFIX)/bin/pytest
STREAMLIT        := $(FINTECH_ENV_PREFIX)/bin/streamlit
SPHINX_BUILD     := $(FINTECH_ENV_PREFIX)/bin/sphinx-build
SPHINX_AUTOBUILD := $(FINTECH_ENV_PREFIX)/bin/sphinx-autobuild

.PHONY: help _check-env install all-env generate dbt-deps dbt-build dbt-docs \
        analyze pipeline app docs docs-build docs-clean test lint fmt clean

# -----------------------------------------------------------------------------
# Help
# -----------------------------------------------------------------------------

help: ## Show this help
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | grep -v '^_' | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

# -----------------------------------------------------------------------------
# Environment guardrail
# -----------------------------------------------------------------------------

_check-env:
	@command -v pyenv >/dev/null 2>&1 || { \
		echo "ERROR: pyenv is not installed."; \
		echo "       Install it first: https://github.com/pyenv/pyenv#installation"; \
		exit 1; \
	}
	@test -n "$(FINTECH_ENV_PREFIX)" || { \
		echo "ERROR: pyenv virtualenv '$(PYENV_VENV)' not found."; \
		echo "       Run:"; \
		echo "         pyenv install -s 3.13.3"; \
		echo "         pyenv virtualenv 3.13.3 $(PYENV_VENV)"; \
		echo "         pyenv local $(PYENV_VENV)"; \
		exit 1; \
	}
	@$(PYTHON) -c "import sys; ok = sys.version_info[:2] == (3, 13); print(sys.version.split()[0]); sys.exit(0 if ok else 1)" >/tmp/.fintech-pyver 2>/dev/null || { \
		echo "ERROR: $(PYENV_VENV) must be Python 3.13.x. Got: $$(cat /tmp/.fintech-pyver 2>/dev/null || echo unknown)"; \
		echo "       Recreate the env:"; \
		echo "         pyenv uninstall -f $(PYENV_VENV)"; \
		echo "         pyenv install -s 3.13.3"; \
		echo "         pyenv virtualenv 3.13.3 $(PYENV_VENV)"; \
		echo "         pyenv local $(PYENV_VENV)"; \
		exit 1; \
	}
	@rm -f /tmp/.fintech-pyver

# -----------------------------------------------------------------------------
# Bootstrap
# -----------------------------------------------------------------------------

install: _check-env ## Install core + dev dependencies into fintech_env
	$(PIP) install -e ".[dev]"

all-env: _check-env ## Install ALL extras (dev + dbt + streamlit + docs) -- one-shot bootstrap
	$(PIP) install --upgrade pip
	$(PIP) install -e ".[dev,dbt,streamlit,docs]"
	@echo "Python deps installed. Fetching dbt packages..."
	cd dbt_project && DBT_PROFILES_DIR=. $(DBT) deps
	@echo
	@echo "Environment ready. Next steps:"
	@echo "  make pipeline   # generate data, build dbt marts, run analysis"
	@echo "  make app        # start the Streamlit dashboard"
	@echo "  make docs       # browse the project documentation"

# -----------------------------------------------------------------------------
# Data pipeline
# -----------------------------------------------------------------------------

generate: _check-env ## Generate synthetic personal-loan data into data/raw/
	$(PYTHON) -m python.src.generate_data

dbt-deps: _check-env ## Install dbt packages (dbt-utils)
	cd dbt_project && DBT_PROFILES_DIR=. $(DBT) deps

dbt-build: _check-env ## Run dbt build (seeds + models + tests)
	cd dbt_project && DBT_PROFILES_DIR=. $(DBT) build

dbt-docs: _check-env ## Generate and serve dbt lineage docs (port 8080)
	cd dbt_project && DBT_PROFILES_DIR=. $(DBT) docs generate && DBT_PROFILES_DIR=. $(DBT) docs serve --port 8080

analyze: _check-env ## Run Python analysis (vintage curves, forecast, simulator, churn scoring)
	$(PYTHON) -m python.src.analysis

pipeline: generate dbt-build analyze ## Full pipeline: generate + dbt build + analyze

# -----------------------------------------------------------------------------
# Streamlit dashboard
# -----------------------------------------------------------------------------

app: _check-env ## Start the Streamlit dashboard on port 8501
	$(STREAMLIT) run streamlit_app/app.py --server.port 8501

# -----------------------------------------------------------------------------
# Documentation (Sphinx)
# -----------------------------------------------------------------------------

docs: _check-env ## Build and serve docs with live reload (port 8000)
	$(SPHINX_AUTOBUILD) docs docs/_build/html --port 8000 --open-browser

docs-build: _check-env ## One-shot build of docs to docs/_build/html
	$(SPHINX_BUILD) -b html docs docs/_build/html

docs-clean: ## Remove generated documentation artifacts
	rm -rf docs/_build

# -----------------------------------------------------------------------------
# Quality
# -----------------------------------------------------------------------------

test: _check-env ## Run pytest
	$(PYTEST)

lint: _check-env ## Lint with ruff
	$(RUFF) check .

fmt: _check-env ## Format with ruff
	$(RUFF) format .

# -----------------------------------------------------------------------------
# Cleanup
# -----------------------------------------------------------------------------

clean: ## Remove generated data and dbt build artifacts
	rm -rf data/raw/*.parquet data/fintech.duckdb dbt_project/target dbt_project/dbt_packages dbt_project/logs