Getting started¶

You can start in six ways. All six use the same spec format, steps, models and bundles.

Guided mode, no code v0.4

This way is for analysts. Select a template, upload a spreadsheet and answer some questions. You get a report, a sanity scorecard and what-if sliders. You need a platform that runs: the platform of your team, or make dev below.

Your first MMM in Guided mode
Run the platform v0.2

Start the API, the job queue, the sandboxed runner and the web app on your laptop with make dev. Then fit and score from the browser, the CLI, Python or HTTP.

Quickstart: zero to first model in 10 minutes
Automate an analysis v0.5

Start a gallery workflow. Examples are unit-root tests to a backtested, governed ARIMAX, VAR/VECM, a forecast bake-off and a governed MMM. Run it from the browser, with mapi workflows run --watch or with Python.

Workflow cookbook
Fit a science model v0.9

Do the analysis of a pymc-challenges notebook in the web app. Export the data with python -m mapi_plugin_science.export, upload it, fit a sci.* model and run the recipe of the case. Images, fields, maps and graphs are available.

pymc-challenges in the web app
Train a network on images v0.15

Upload a folder of images with mapi datasets upload-images, fit dl.cnn_classifier, and look at the training curves while it trains. Compare the runs on the compare page.

Deep learning
Use the library in your own process

Use import mapi_sdk in a notebook, a script or a test suite. You can validate specs, fit, score and write bundles in-process. You can also test your own plugins with the contract kit.

Your first model in Python

The library and the platform both need Python 3.12 and uv. The platform also needs Node.js 22+ with pnpm for the web app. Docker is optional (Deployment).

Install¶

From a clone (today)Into your own project (once published)

We develop the packages together in one uv workspace. Clone the repository. Then sync all the packages and the developer tools:

git clone <repository-url> modeling-api
cd modeling-api
uv sync --all-packages        # or: make install (also installs the web app)
uv run python -c "import mapi_sdk, mapi_spec; print(mapi_sdk.__version__)"

To open a notebook in the same environment, use uv run --with jupyterlab jupyter lab.

Each package is a separate distribution. Install only the packages that you need:

uv add mapi-sdk mapi-steps                 # the runtime and the built-in steps
uv add mapi-pymc                           # PyMC models
uv add mapi-sklearn                        # scikit-learn and xgboost models
uv add "mapi-sklearn[gbm]"                 # also LightGBM and CatBoost classifiers
uv add mapi-jax                            # neural networks on JAX and Flax (dl.*)
uv add "mapi-plots[recipes]"               # plot recipes (Altair, Plotly)
uv add mapi-plugin-mmm mapi-plugin-ts mapi-plugin-tabular   # the built-in models
uv add mapi-plugin-statsmodels "mapi-workflows[runtime]"    # statsmodels models, workflows
uv add mapi-plugin-science                 # science models (sci.*) and the export helper
uv add mapi-plugin-causal                  # causal models (causal.*)

Not on PyPI yet

We will publish the distributions with the first tagged release. Until then, you install from the workspace, as the first tab shows.

What each package does¶

Package	Import	What it gives you	Heavy dependencies
`mapi-spec`	`mapi_spec`	The contracts: `DataSchema`, `ModelSpec`, `ScoreRequest`, capabilities, error codes, static validation and JSON Schemas	none (pure Pydantic)
`mapi-sdk`	`mapi_sdk`	The runtime: steps, pipelines, coord plans, summaries, bundles, the in-process executor and the contract kit	xarray, numpy, zarr
`mapi-steps`	`mapi_steps`	28 built-in preprocessing steps and the split catalog	–
`mapi-pymc`	`mapi_pymc`	`PyMCModel`: you write `build()`. You get engines, diagnostics, new levels and counterfactuals.	PyMC
`mapi-sklearn`	`mapi_sklearn`	`SklearnModel`: you write `estimator()`. You get stacking, safe persistence and uncertainty.	scikit-learn, xgboost, skops; LightGBM and CatBoost (the `gbm` extra)
`mapi-jax`	`mapi_jax`	Neural networks: `dl.mlp`, `dl.cnn_classifier`, `dl.finetune_classifier` and the step `dl.embed`, with a shared trainer (guide)	JAX, Flax, Optax
`mapi-plots`	`mapi_plots`	The JSON-only plot sanitizer and templates. Recipes come with the `recipes` extra.	Altair, Plotly (extra)
`mapi-plugin-*`	`mapi_plugin_*`	Built-in models: marketing mix (`mapi-plugin-mmm`, on mmm-framework), time series, statsmodels time series (`mapi-plugin-statsmodels`), tabular, causal (`mapi-plugin-causal`: `causal.impact`, `causal.synthetic_control` and `causal.did`) and science (`mapi-plugin-science`: 15 `sci.*` models for images, fields, maps and graphs)	as above; mmm-framework, statsmodels, pymc-extras, scipy
`mapi-workflows`	`mapi_workflows`	The workflow engine, the node implementations and a local runner for notebooks (guide)	The engine has none (pure Python, safe for the control plane). The node implementations are the `runtime` extra (numpy, xarray, scipy, statsmodels and the plot recipes of `mapi-plots[recipes]`).
`mapi-conformance`	`mapi_conformance`	The conformance corpus and its runner	all of the above
`mapi-client`	`mapi_client`	A typed Python client for the HTTP API (guide)	httpx (xarray optional)
`mapi-cli`	`mapi_cli`	The `mapi` command line (guide)	typer, rich
`mapi-server`	`mapi_server`	The control plane: API, orchestrator and executors (AGPL or commercial)	FastAPI, SQLAlchemy; no numpy
`mapi-runner`	`mapi_runner`	The sandboxed run harness: supervisor and worker (AGPL or commercial)	the SDK, in the worker only
`mapi-gcs-shim`	`mapi_gcs_shim`	A local emulator of the Cloud Storage features that the platform uses	Starlette

Plugins register themselves through Python entry points (mapi.steps, mapi.models, mapi.plots). Thus mapi_sdk.default_registry() finds all the installed plugins.

Check your installation¶

uv run python -m mapi_conformance list          # the reference problems
make conformance FIXTURE=xgb_store_demand       # one of them, end to end (a few seconds)

fixture           model                    validate  fit  score   evaluate  contract  plots   expectations  metrics                                  time  result
----------------  -----------------------  --------  ---  ------  --------  --------  ------  ------------  ---------------------------------------  ----  ------
xgb_store_demand  tabular.regressor@1.0.0  ok        ok   ok 6/6  ok        ok 12/12  ok 3/3  ok            coverage_80=0.825, mape=25.3, rmse=4.59  3.3s  PASS
----------------  -----------------------  --------  ---  ------  --------  --------  ------  ------------  ---------------------------------------  ----  ------
1/1 fixtures passed in 3.3s

Where next¶

Quickstart

This page shows the platform from start to end. Use make dev and make seed. Then fit, examine and score from the browser. It takes about ten minutes.
Your first model in Python

Make a labelled dataset, write a spec and fit it. Then forecast a new store and look at the typed errors that protect you. It takes about ten minutes.
Runs and executors

Submit the same work as runs to the in-process executor. This is the protocol that the executors of the platform use.
Concepts

Dims and policies, stages and context tails, representations and bundles.
Port a model

Bring your own PyMC, scikit-learn or hand-written model.
Track and compare runs

Log metrics, params and tags to a run, and compare runs side by side.
Tutorials

Google Sheets, embedded charts, webhook receivers, budget plans, complex workflows and the science models of pymc-challenges.