SmurphCast 📈 1.0.1

SmurphCast is the first open-source forecasting library designed explicitly for percentages: churn, click-through, conversion, retention & rate-based KPIs. Lightweight ✅, explainable ✅, production-ready ✅—and it runs on a laptop CPU.

Why another forecasting library?

Modern teams track hundreds of tiny percentages—they spike on Black Friday, dip during outages, and never exceed 100%. Classic tools (ARIMA, Prophet, deep nets) either ignore those hard bounds or explode with gradient issues.

SmurphCast was born inside a growth-marketing team frustrated with:

• Unbounded predictions (> 100% CTR 😩)
• Brittle seasonality when data is bi-weekly, quarterly, or irregular
• Needing to babysit half a dozen libraries for every experiment

So we distilled the playbook that actually worked into one cohesive package.

✨ Key reasons you'll love SmurphCast

A brief history of the internal models

The result: four specialised forecasters + one meta-model that systematically outperforms any single approach on marketing KPI datasets.

Installation

pip install smurphcast      # PyPI release

# Dev install
git clone https://github.com/yourhandle/smurphcast.git
cd smurphcast
pip install -e .[dev]       # tests, ruff, black, hatch

SmurphCast requires Python ≥ 3.9 and no GPU.

0-minute quick-start

import pandas as pd
from smurphcast.pipeline import ForecastPipeline

df = pd.read_csv("examples/churn_example.csv", parse_dates=["ds"])

# Auto picks the best model & stacking weights
pipe = ForecastPipeline(model_name="auto").fit(df, horizon=3)

print(pipe.predict())         # point forecast
print(pipe.predict_interval(.9))  # 90% PI if supported
pipe.save("smurf.pkl")        # deploy anywhere (dill)

CLI:

smurphcast fit examples/churn_example.csv --horizon 3 --model auto --save best.pkl

Architecture 🔧

Raw CSV  --> validator / outlier scrub
   |
   v      --> logit / log / Box-Cox transforms
Features  
   |
   v      --> Fourier + calendar dummies + lags + rolls
Base models     additive | gbm | qgbm | esrnn  (all CPU)
   |
   v      inverse-MAE blend  +   NNLS stacking
AutoSelect

Everything communicates via the ForecastPipeline interface, so you can slot in custom models or swap the feature generator without touching the rest.

Documentation & API

• Full docs: https://smurphcast.readthedocs.io
• Quick cheatsheet: docs/api.md

Sample data

The wheel ships with tiny toy CSVs (smurphcast.data.*) so you can run the docs offline. Larger examples stay in examples/ to keep installs lean.

Roadmap 🗺️

• Optuna integration for AutoSelector hyper-tuning
• Holiday / event regressor interface
• Group-by support for many related series (panel KPIs)
• Prophet-style component plots on every model

Contributing

• Fork & create a feature branch
• Hatch run pytest - all tests must pass
• Follow ruff & black (pre-commit hooks included)
• Open a PR – descriptive title, before/after numbers if performance related

We happily accept new feature generators, models, and docs!

License

Code released under the MIT License. Sample data are synthetic and MIT-licensed as well.

© 2025 SmurphCast Contributors – built with 💻, 📊 and a bit of 💙 for tiny percentages.