The Model Garden & Atelier

Author a custom Bayesian model once, prove it against an oracle compatibility suite, publish it to your organization — and let every analyst fit, interrogate, and report on it through the agent without ever touching the kernel.

Most bespoke marketing-science work dies in a notebook. A methodologist builds a clever structural model for a particular client question, it produces one result deck, and the code is never reused — there is no safe way to put a hand-rolled PyMC model into a shared application, and no guarantee it behaves like a first-class model once it gets there. The Model Garden is the answer to that: a governed, versioned registry of custom Bayesian models, and the Atelier is the in-app IDE where you write, test, document, and publish them. A published model becomes a named asset that any project in your org can re-fit on its own data — through the same agent, the same reports, the same estimands as the built-in MMM.

Why a Model Garden

Three problems sit between a good idea in a notebook and a model an organization can rely on:

• Deployment. Putting new model code into a running application normally means a code review, a release, and a redeploy of the runtime. That is far too much friction for a one-question structural model.
• Trust. A hand-rolled model might sample badly, mis-scale its outputs, or silently break the read-side metrics (ROI, decomposition) that downstream tools expect. Without a quality bar, nobody can safely reuse it.
• Reuse. Even a good model is stranded if there's no catalog, no versioning, and no way for a teammate on another project to find and run it.

The Model Garden removes all three. A model is loaded by reference, not by redeploying code; it must pass a compatibility suite before it can be marked tested; and it lives in an org-scoped, versioned registry that the agent can search. The mechanism that makes the first point work is a small piece of provenance called the garden_ref:

# A garden_ref — embedded in a session spec and in saved-model metadata.
# It is just enough to reconstruct the exact authored class on load.
garden_ref = {
    "name": "awareness_structural_mmm",
    "version": 3,
    "source_path": "…/garden/awareness_structural_mmm/v3/model.py",
    "class_name": "AwarenessStructuralMMM",
    "contract_version": "1.0",
}

When the agent fits a model, it reads spec["garden_ref"], the kernel imports the exact authored class from source_path, and the fit proceeds. The application runtime never needs the model's code baked in — authors ship science, not infrastructure. If the source is ever missing, the loader degrades gracefully to the base BayesianMMM rather than failing the session.

The business value of a growing library

Every model that clears the bar and gets published is a permanent, governed, documented asset — and because the agent can discover and run it, the value of authoring one accrues to every future analyst session. The library compounds.

Using a registered model with the agent

For an analyst, a custom model is no different from a built-in one. You talk to the agent in plain language; it calls the right tools; the model fits and reports. Here is the whole flow.

What is actually happening under those tool calls:

1. Discover — list_garden_models returns the org's catalog (name, version, status, compatibility score, docs).
2. Load — load_garden_model stages the model into the session: it copies the source into the workspace, sets spec["garden_ref"], and applies the model's recommended_fit to the inference settings.
3. Fit — fit_mmm_model reads the spec and dispatches to the kernel, where the build step resolves the garden class from garden_ref, validates any model_params against the model's config schema, wires the declared likelihood and estimands, and fits the bespoke subclass.
4. Interrogate — get_estimands realizes the model's declared estimands post-fit (mean, HDI, units, probability of being positive/profitable). Standard read-ops — ROI, decomposition, adstock, saturation, diagnostics — work on a garden model with no special-casing.
5. Report — reporting is family-aware: an MMM model gets the full marketing report; a non-MMM family gets its family-specific section (factor loadings, class profiles) plus its declared estimands, chosen automatically by the model's kind.

Agent tools at a glance

The Atelier — an IDE for models

The Atelier is a Jupyter-like workspace for authoring, testing, and publishing models, opened from the Model Garden page. The layout is a three-column grid:

• Left (collapsible) — the registry. Every model your org has, with a version picker and lifecycle status chips.
• Center — three tabs. Code (a Monaco editor with framework completions and a copilot side-panel), Docs (a markdown editor with live preview), and Notebook (Jupyter-like cells you run against real data).
• Right (collapsible) — two tabs. Compatibility (the tier-by-tier test report and fit-quality score) and About (class name, contract version, docs, and status history).

The authoring loop in the UI

1. New model. The Code editor seeds a CustomMMM starter; name the model.
2. Write & check. Edit the subclass; use Format (Ruff) and Validate (a static AST lint that surfaces Problems) from the toolbar — alongside Wrap, Minimap, font zoom, fullscreen, and the Copilot toggle.
3. Ask the copilot. The inline Bayesian-modelling assistant streams answers; Apply to editor merges a suggested code block straight into the buffer.
4. Document. Write the model's markdown docs in the Docs tab with live preview.
5. Register. Register draft stores the source (AST-validated, not executed) as version 1, status draft.
6. Demo on real data. In the Notebook tab, upload a CSV (it auto-binds as df), add code cells, and run them against the live editor buffer to sanity-check the model. An errored cell offers Diagnose with copilot, which rewrites the failing cell — or the model source — for you.
7. Prove. Run compatibility test streams the tier report; on a clean blocking pass the model auto-promotes to tested and a Publish button appears.
8. Publish. An admin/owner clicks Publish; the version becomes immutable and loadable by every project in the org.

The lifecycle is always visible as status chips:

Building a model

For authors, the contract is deliberately small. You subclass one base class, override the graph, and declare what the model measures. Everything else — fitting, serialization, estimand evaluation, reporting — is inherited.

The minimal skeleton

Subclass CustomMMM (a thin, documented marker over BayesianMMM that stamps the contract version). The one method you almost always override is _build_model; keep the standard constructor signature so the agent can swap your class in for the built-in one.

from mmm_framework.garden import CustomMMM


class MyStructuralMMM(CustomMMM):
    """One-paragraph statement of WHAT this model assumes and WHY.

    State the identification strategy here: the priors, any sign
    constraints, and the fixed structural pattern. A consumer who fits
    this model on their data is inheriting these assumptions.
    """

    def _build_model(self):
        # Your PyMC graph. Register every reported quantity as a named
        # Deterministic, in ORIGINAL KPI scale. For MMM models, alias
        # coefficients / carryover / saturation to the PARAM_PREFIXES
        # (beta_, adstock_alpha_, sat_half_,
        # sat_slope_) so the reporting helpers can find them.
        ...

Before you register, you can prove the structure statically — no PyMC, no fit — and then run the full suite. These are the real, importable entry points an author uses locally:

from mmm_framework.garden import CustomMMM, validate_class, run_compatibility_check

# Static, PyMC-free structural check (empty list == OK):
problems = validate_class(MyStructuralMMM)

# Full nine-tier suite — fits on synthetic worlds, never raises:
report = run_compatibility_check(MyStructuralMMM)

Config & likelihood

Two axes let a model carry its own settings and its own observation model without forking the framework.

Settable parameters. Instead of magic numbers, declare a class attribute CONFIG_SCHEMA — a pydantic.BaseModel of defaulted, constrained, described fields. The agent validates the caller's model_params against it, passes them to your constructor, and reads them as self.model_params; the serializer round-trips them; and the schema is exported as JSON Schema to drive a UI form.

Observation model. A model declares its likelihood family and reads it in _build_model. The built-in additive dispatch handles Gaussian families (NORMAL, STUDENT_T) byte-identically; a non-Gaussian KPI (a survey count, a bounded rate) owns its observation node — the additive base raises NotImplementedError for non-Gaussian on purpose, so count/bounded models write their own.

from mmm_framework.config import LikelihoodConfig
from mmm_framework.config.enums import LikelihoodFamily, LinkFunction

Available families: NORMAL, STUDENT_T, LOGNORMAL, BINOMIAL, BETA_BINOMIAL, POISSON, NEGATIVE_BINOMIAL, and BETA.

Declaring estimands

A model's DEFAULT_ESTIMANDS are the named quantities it surfaces through the estimand engine — what the agent reports and what the report renders. They are the model's measurement contract: document what the model measures with declared estimands, not just prose.

For MMM channel quantities you reference the built-ins by name — e.g. "contribution_roi", "marginal_roas", "contribution". For latent quantities (a fit index, a named scalar, a class size) you build an Estimand with a public registry helper:

from mmm_framework.estimands.registry import latent_scalar, fit_index, factor_loading

Each is gated by a HAS_LATENT:<var> capability, so it cleanly returns an unsupported status (never an exception) on a model that doesn't carry the variable. If your estimands scale with config — say one class-size estimand per class — override _default_estimands() to build them dynamically.

Non-MMM families

The same pipeline supports genuinely non-marketing-mix Bayesian families. A model opts out of the MMM-only gates by declaring a non-"mmm" kind:

class BayesianCFA(CustomMMM):
    __garden_model_kind__ = "cfa"          # opt out of channel / beta / scaling gates

    def _prepare_data(self):
        # Assemble your observed indicators; then set the model-agnostic
        # attributes the inherited fit + serializer read:
        self.channel_names = []            # empty list (not None) signals "no channels"
        # … n_obs, y_mean=0, y_std=1, _media_raw_max={}, time_idx, etc.
        ...

    def _build_model(self):
        ...                                # your latent-variable graph

With channel_names = [] the contract recognizes the family and skips the channel, beta_<channel>, scaling, and ops-smoke checks; the core requirements (a real fit, a posterior with chain/draw dims, your own declared estimands) still apply. The estimand engine auto-exposes every posterior variable as a HAS_LATENT:<var> capability, so fit_index(…), latent_scalar(…), and factor_loading(…) just work, and the family-agnostic report renders your summary table plus your declared estimands.

Worked examples to fork

Three complete, tested models ship in the repository under examples/garden_models/. Each is a good starting point:

The deep specifications live in technical-docs/: custom-model-config.md (config + likelihood), estimands.md (the estimand subsystem), and non-mmm-families.md (the CFA/LCA contract).

The compatibility contract

A garden model has to behave like a first-class model, so it is checked at three points and then exercised end-to-end on synthetic worlds with known ground truth.

Three validation stages

The one truly required method is fit() — it must run and leave a fitted trace (an ArviZ InferenceData with a posterior group). The recommended methods (predict, sample_channel_contributions, compute_component_decomposition) each unlock read-ops; their absence must degrade gracefully, not raise. Required attributes are split into a model-agnostic base set and an MMM-only set, so non-MMM families carry only the base.

The nine tiers

run_compatibility_check runs nine tiers and never raises — each tier reports passed / skipped / detail independently. Seven are blocking: a clean pass on all of them is what auto-promotes draft → tested.

The gate that decides which checks apply is is_mmm_model(): a model is treated as an MMM unless it explicitly declares a non-"mmm" __garden_model_kind__. Promotion to tested is automatic on a clean blocking pass; promotion to published is always a deliberate human decision.

Documenting a model — best practices

A garden model is a scientific claim that other people will inherit. Documentation is not an afterthought; several surfaces carry it, and the agent and reports read them directly.

• The class docstring states the why and the identification strategy — priors, sign constraints, fixed structural patterns. A consumer fitting your model is accepting these assumptions, so name them.
• CONFIG_SCHEMA field metadata (defaults, constraints, descriptions) becomes validated params, a serialized round-trip, and the UI's params form. Put every tunable here rather than in magic numbers.
• DEFAULT_ESTIMANDS is the machine-readable statement of what the model measures — it is what the agent surfaces and the report renders.
• The markdown docs page (the Docs tab) is the human narrative. It is editable in place on a draft or tested version, and immutable once published — to change a published model's docs or source, register a new version.
• A summary method for any matrix-valued quantity (e.g. factor_loadings_summary(), class_profile_summary()) gives the family-agnostic report a table to render.

Governance & security

The registry is built so an organization can accept models from many authors without trusting their code on the application process, and so published results stay reproducible.

• Host-safe registration. Registering a model AST-validates the source (it detects the class name and the declared kind) and never executes it on the host. Untrusted author code runs only kernel-side — a sandboxed subprocess or container in the hosted profile — during test and fit.
• Roles. Registering, linting, and testing are analyst+; publishing and deleting are admin/owner. Publishing is the one human gate that matters.
• Org scoping. Models are shared across all projects in an org (the sharing boundary is the org, not the project), so a published model is immediately reusable everywhere in the tenant.
• Immutability & audit. Versions are monotonic per (org, name); a published version is frozen; a status history is appended (never overwritten); and a saved model carries its garden_ref, so any result traces back to the exact class. To change a published model, register a new version. Retire with deprecate, which preserves history — deletion is only for drafts and deprecated versions.

The REST governance surface

The Atelier UI and the agent tools share one governed REST surface. The blocks below are illustrative routes, not a runnable client.

A parallel set of notebook routes backs the Atelier's Notebook tab — get/put the notebook doc, upload a dataset (auto-binds as df), and run cells as non-blocking jobs.

The manifest

Each registered version carries a manifest of advisory, additive discovery metadata. It powers the UI and the catalog; the authoritative source of a model's capabilities is always the runtime model itself, not the manifest.

The growing ecosystem

Put the pieces together and you get a flywheel. A methodologist authors a model in the Atelier with copilot assistance; the compatibility suite proves it is well-behaved; an admin publishes it; and from that moment it is one chat turn away from being fitted, interrogated, and reported on by any analyst on any project in the org — on their own data, with full provenance.

Because non-MMM families ride the same contract, the catalog is not limited to marketing mix: factor models, segmentation models, and structural awareness models extend it without a second system. Every published model raises the leverage of every future session, and the lower the authoring cost — copilot, notebook diagnosis, a small contract — the more experts can contribute. That is the point of the garden: a library that gets more valuable the more it grows.

Get started

The fastest path from curiosity to a published model:

1. Read the three example models under examples/garden_models/ — awareness_structural_mmm.py, bayesian_cfa.py, bayesian_lca.py — and fork the closest one.
2. Open the Atelier, paste it into the Code tab, and tweak the structure with the copilot.
3. Upload a dataset in the Notebook tab and sanity-check the fit on real data.
4. Run the compatibility test; fix anything that isn't green.
5. Write the docs, register, and — once tested — ask an admin to publish.

uv run python scripts/seed_atelier_demo.py          # real MAP fits (~10s)
uv run python scripts/seed_atelier_demo.py --fast   # no MCMC (seconds)