Skip to content

Public API Map

Use this page to decide which import surface is the intended boundary and which modules are deeper implementation detail.

Import tiers

Tier 1: preferred stable entrypoints

These are the default imports to reach for in user-facing docs, examples, and new agent work unless you need a deeper workflow seam.

Area Preferred imports
Package-wide top level from cranalytics import ... for the curated workflow functions already re-exported in src/cranalytics/__init__.py
Vintage cranalytics.vintage; prefer run_vintage_analysis_session() for end-to-end comparison/validation and drop to lower-level fitters or smoothers only when you need a narrower step
Visualization cranalytics.viz
Loss Forecasting cranalytics.loss_forecasting
Portfolio / metrics cranalytics.portfolio, cranalytics.metrics
Predictive modeling top-level run_predictive_modeling_session() for the end-to-end workflow; use the narrower predictive_* modules when you only need one concern such as training, scoring, or backtesting
Rollforward workflow cranalytics.rollforward_workflow, cranalytics.rollforward_readiness
CLI cranalytics.cli

Tier 2: workflow-local public modules

These are still legitimate imports, but they are workflow-specific rather than package-wide defaults.

  • cranalytics.vintage_fitting
  • cranalytics.vintage_smoothing
  • cranalytics.vintage_validation
  • cranalytics.vintage_transforms
  • cranalytics.vintage_wide
  • cranalytics.predictive_targets
  • cranalytics.predictive_modeling
  • cranalytics.predictive_backtest
  • cranalytics.predictive_session
  • cranalytics.forecasting_bridge
  • cranalytics.early_performance
  • cranalytics.loan_history
  • cranalytics.loan_history_contract
  • cranalytics.loan_snapshot
  • cranalytics.loan_snapshot_contract
  • cranalytics.model_development
  • cranalytics.score_monitoring
  • cranalytics.transition
  • cranalytics.survival
  • cranalytics.survival_flows
  • cranalytics.rollforward_workflow
  • cranalytics.rollforward_readiness
  • cranalytics.rollforward_backtest
  • cranalytics.rollforward_contract

Use these when you are already inside the workflow and need a more precise edit target than the top-level facade provides.

Tier 3: internal coordination modules

Treat these as internal unless the public seam clearly does not expose the behavior you need to change.

  • src/cranalytics/_rollforward_session.py
  • src/cranalytics/_rollforward_workflow_session.py
  • src/cranalytics/_rollforward_readiness_session.py
  • src/cranalytics/_rollforward_splitting.py
  • src/cranalytics/_helpers.py
  • src/cranalytics/governance_models.py

Practical guidance for agents

  • Start at the public workflow boundary first, then descend only as far as needed.
  • If you are changing behavior visible to callers, prefer tests at the workflow boundary over tests that lock internal helper structure.
  • Keep src/cranalytics/__init__.py as a compatibility and discovery surface, not the primary implementation target.
  • If a new symbol is useful only inside one workflow, add it to that workflow module instead of widening the top-level import surface by default.
  • Keep src/cranalytics/governance_models.py internal. It owns non-DataFrame metadata validation only and must not become a competing public validation boundary.

Current top-level export shape

src/cranalytics/__init__.py intentionally gathers multiple workflows into one namespace. That makes discovery easy for users, but it also means agents should use this page and the Module Map to distinguish:

  • stable top-level convenience imports
  • workflow-specific public modules
  • internal orchestration helpers