Public API reference
Use public imports and model properties. Underscore-prefixed modules now own
many implementations, but their extraction does not make them stable entry
points. The table links definitions for inspection; import
BudgetOptimizationResult through ammm.mmm, not its private defining module.
This reference was checked against 7cb7f20b357f23ee1683670953c7dd0092fa2084.
For examples and interpretation, start with the user guide.
| Interface | Purpose | Definition |
|---|---|---|
MMM | Build, fit, predict, save/load and access analysis interfaces | src/ammm/mmm/mmm.py:238 |
FixedEffectsMMM | Within-unit likelihood and fitted-unit level prediction | src/ammm/mmm/fixed_effects.py:79 |
CorrelatedRandomEffectsMMM | Experimental collapsed random-intercept likelihood | src/ammm/mmm/correlated_random_effects.py:182 |
GeometricAdstock and other adstock classes | Carryover transforms | src/ammm/mmm/components/adstock.py:348 |
LogisticSaturation and other saturation classes | Nonlinear media response | src/ammm/mmm/components/saturation.py:213 |
Prior configuration | Default model configuration and parameter dimensions | src/ammm/mmm/mmm.py:1375 |
Scaling | Data-derived or fixed feature and target scales | src/ammm/mmm/scaling.py:431 |
LinkSpec | Likelihood support and response-scale contract | src/ammm/mmm/link.py:210 |
build_mmm_from_yaml | Trusted configuration to a built graph | src/ammm/mmm/builders/yaml.py:73 |
MMMYamlConfig | Typed configuration fields | src/ammm/mmm/builders/schema.py:233 |
MuEffect and IncrementalitySpec | Custom contributions, prediction updates and counterfactual registration | src/ammm/mmm/additive_effect.py:341 |
MMM.add_lift_test_measurements | Static lift calibration, identity link only | src/ammm/mmm/mmm.py:2757 |
MMM.add_cost_per_target_calibration | Aggregate CPT or target-per-cost measurement likelihood | src/ammm/mmm/mmm.py:2870 |
Incrementality | Spend-removal and marginal response contrasts | src/ammm/mmm/incrementality.py:271 |
SensitivityAnalysis | Input sweeps at retained posterior draws | src/ammm/mmm/sensitivity_analysis.py:94 |
TimeSliceCrossValidator | Rolling-origin fitting and prediction | src/ammm/mmm/time_slice_cross_validation.py:57 |
MMMSummaryFactory | Tables from fitted or predictive draws | src/ammm/mmm/summary/factory.py:60 |
BudgetOptimizer | Constrained posterior-utility optimisation | src/ammm/mmm/budget_optimizer.py:91 |
BudgetOptimizationResult | Labelled allocations and solver diagnostics; publicly exported from ammm.mmm | src/ammm/mmm/_budget_optimizer_results.py:35 |
Constraint | Custom optimisation constraints | src/ammm/mmm/constraints.py:27 |
ScenarioRecipe | Versioned current/manual scenario schema | src/ammm/mmm/scenarios.py:160 |
run_scenario_recipe | Saved runner model to immutable scenario bundle | src/ammm/mmm/scenarios.py:734 |
PriorSensitivityConfig | Planning and optional fitted-scenario policy | src/ammm/prior_sensitivity/config.py:47 |
PipelineAIAdvisorConfig | Local/provider review policy | src/ammm/pipeline/config.py:42 |
PIEModel | Separate alpha incrementality prediction model | src/ammm/pie/model.py:80 |
Common lifecycle calls
build_model(X, y)validates and builds; rebuilding clears fitted state.sample_prior_predictive(X, y, samples=..., random_seed=...)can retain prior draws.fit(X, y, method="mcmc", ...)fits the same canonical observations.sample_posterior_predictive(X, combined=False, clone_model=True, ...)keeps chain/draw axes and protects training data.save(path)andtype(model).load(path)implement the documented persistence contract.model.summary,model.plot,model.incrementalityandmodel.sensitivityexpose their distinct analysis interfaces.model.budget_optimizer(start_date, end_date, ...)creates a solver problem;model.sample_response_distribution(...)evaluates an allocation.
Arguments differ between these methods. In particular, an optimiser result is not a response Dataset, an input sweep is not prior sensitivity, and calling a builder does not run the full retained-output pipeline.
Constructor and operation boundaries
MMM requires date/channel names and adstock/saturation instances. Optional
constructor defaults include target y, no panel dimensions, no controls or
seasonality, adstock_first=True, identity link and both time-variation switches
false (src/ammm/mmm/mmm.py:377). The default scaling and likelihood priors are
specified in model contracts; use that page
before eliciting parameter values.
| Operation | Inputs and return | Failure / state contract |
|---|---|---|
build_model(X, y) | Labelled finite data; constructs graph, returns no fitted posterior | Named Series must match target; rebuilding clears graph-bound calibration |
sample_prior_predictive(X, y, ...) | Returned prior-predictive dataset; original-scale deterministics reside in idata["prior"] | Build with real targets before later fitting; inspect registered variables |
fit(X, y, method="mcmc", ...) | Retains and returns an xarray DataTree | Fitting a prior-only placeholder requires rebuilding; backend kwargs remain backend-specific |
sample_posterior_predictive(X, ...) | Dataset with requested variables; combined=True merges sample axes by default | Require fitted posterior, valid future coordinates and explicit history choice |
save(fname), load(fname) | Persist/restore model and inference groups | Loader validates format and canonical training data; unsupported older files require original runtime or refit |
| Calibration methods | Built ordinary identity-link graph and labelled study inputs; return the model | Calibrate before fit; cost calibration requires original-scale channel registration; FE/CRE reject |
| Summary facade | pandas tables by default with coordinate keys and interval endpoints | Missing components/groups fail; interval method depends on retained sample axes |
| Incrementality facade | Posterior DataArray for an explicit spend contrast | Media-dependent effects must declare their dependency; history/units define the estimand |
| Budget optimiser | Labelled allocation and solver result in BudgetOptimizationResult | Bounds/constraints must be valid; default failed solves raise; FE/CRE reject |
Sources: src/ammm/mmm/_mmm_graph.py:182, src/ammm/model_builder.py:630,
src/ammm/mmm/mmm.py:1709, src/ammm/mmm/mmm.py:2299,
src/ammm/mmm/persistence.py:62, src/ammm/mmm/_mmm_calibration.py:171,
src/ammm/mmm/summary/factory.py:240, src/ammm/mmm/incrementality.py:271,
src/ammm/mmm/budget_optimizer.py:704.
Exported names and call signatures
This static inventory covers every explicit export in ammm, ammm.mmm,
ammm.pipeline, ammm.pie, ammm.prior_sensitivity, ammm.ai and
ammm.mmm.builders at the reviewed commit. Signatures show parameter names and
actual defaults; annotations are omitted for readability. Keyword-only arguments
follow *; <factory> denotes a fresh field value created per instance,
not a literal argument to pass. A class call constructs its instance, not a fitted result; validation,
dimensions and numerical assumptions remain part of the linked task contract.
An abstract base class or protocol is an extension interface, not a complete model.
Modules group further definitions. Explicit exports are discoverable entry points; underscore-prefixed implementations remain internal, even where a public export is implemented in one. Other non-exported orchestration helpers are implementation interfaces and should not be used as substitutes for a documented model operation.
ammm
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
__version__ | '4.0.3' | Package value. | src/ammm/__init__.py:23 |
mmm | module | Import the module for its supporting interfaces. | src/ammm/mmm/__init__.py:1 |
pie | module | Import the module for its supporting interfaces. | src/ammm/pie/__init__.py:1 |
r2d2 | module | Import the module for its supporting interfaces. | src/ammm/r2d2.py:1 |
terms | module | Import the module for its supporting interfaces. | src/ammm/terms.py:1 |
ammm.mmm
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
preprocessing | module | Import the module for its supporting interfaces. | src/ammm/mmm/preprocessing.py:1 |
validating | module | Import the module for its supporting interfaces. | src/ammm/mmm/validating.py:1 |
ControlMuEffect | (*, data_vars, prefix, prior=Prior("Normal", mu=0, sigma=2)) | Effect that applies a user-configurable prior to each control variable. | src/ammm/mmm/additive_effect.py:579 |
DataVarMuEffect | (*, data_vars, prefix) | MuEffect that reads its data from the xarray Dataset. | src/ammm/mmm/additive_effect.py:433 |
IncrementalitySpec | (*, additional_carryover_lags=None, evaluation_mode='auto') | Declaration that an effect may take part in incrementality analysis. | src/ammm/mmm/additive_effect.py:274 |
MediaMuEffect | (*, data_vars, prefix, media_transformation, channel_dim='channel') | Effect that applies a media transformation to a data variable. | src/ammm/mmm/additive_effect.py:484 |
BudgetOptimizationResult | (budgets, scipy_result, optimized_vars=<factory>, spend_var_names=<factory>, callback_info=None) | Result of BudgetOptimizer.allocate_budget. | src/ammm/mmm/_budget_optimizer_results.py:34 |
BudgetOptimizer | (*, num_periods, model, idata, adstock_periods=0, carry_in_periods=0, channel_scales=1.0, spend_vars=<factory>, spend_var_scales=<factory>, optimizable_vars=<factory>, response_variable='total_media_contribution_original_scale', utility_function=average_response, budgets_to_optimize=None, constraints=(), budget_distribution_over_period=None, cost_per_unit=None, compile_kwargs=None, frozen_deterministics=None, channel_data_var='channel_data', channel_contribution_var='channel_contribution', date_dim='date') | A class for optimising budget allocation in a marketing mix model. | src/ammm/mmm/budget_optimizer.py:91 |
merge_inference_data | (idatas, prefixes=None, *, merge_on='channel_data', use_every_n_draw=1) | Merge multiple xarray.DataTree objects with per-model prefixes. | src/ammm/mmm/_budget_optimizer_merge.py:37 |
merge_models_and_idata | (models, idatas, *, prefixes=None, merge_on='channel_data', use_every_n_draw=1) | Merge multiple PyMC models and their DataTree objects in one call. | src/ammm/mmm/_budget_optimizer_merge.py:227 |
AdstockTransformation | (l_max, normalize=True, mode='After', priors=None, prefix=None) | Subclass for all adstock functions. | src/ammm/mmm/components/adstock.py:73 |
BinomialAdstock | (l_max, normalize=True, mode='After', priors=None, prefix=None) | Wrapper around the binomial adstock function. | src/ammm/mmm/components/adstock.py:303 |
DelayedAdstock | (l_max, normalize=True, mode='After', priors=None, prefix=None, parametrization=None) | Wrapper around delayed adstock function. | src/ammm/mmm/components/adstock.py:441 |
GeometricAdstock | (l_max, normalize=True, mode='After', priors=None, prefix=None, parametrization=None) | Wrapper around geometric adstock function. | src/ammm/mmm/components/adstock.py:347 |
NoAdstock | (l_max, normalize=True, mode='After', priors=None, prefix=None) | Wrapper around no adstock transformation. | src/ammm/mmm/components/adstock.py:670 |
WeibullCDFAdstock | (l_max, normalize=True, mode='After', priors=None, prefix=None) | Wrapper around weibull adstock with CDF function. | src/ammm/mmm/components/adstock.py:617 |
WeibullPDFAdstock | (l_max, normalize=True, mode='After', priors=None, prefix=None) | Wrapper around weibull adstock with PDF function. | src/ammm/mmm/components/adstock.py:564 |
HillSaturation | (priors=None, prefix=None) | Wrapper around Hill saturation function. | src/ammm/mmm/components/saturation.py:440 |
HillSaturationSigmoid | (priors=None, prefix=None) | Wrapper around Hill saturation sigmoid function. | src/ammm/mmm/components/saturation.py:487 |
InverseScaledLogisticSaturation | (priors=None, prefix=None) | Wrapper around inverse scaled logistic saturation function. | src/ammm/mmm/components/saturation.py:255 |
LogisticSaturation | (priors=None, prefix=None) | Wrapper around logistic saturation function. | src/ammm/mmm/components/saturation.py:212 |
LogSaturation | (priors=None, prefix=None) | Logarithmic saturation for log-log models. | src/ammm/mmm/components/saturation.py:581 |
MichaelisMentenSaturation | (priors=None, prefix=None) | Wrapper around Michaelis-Menten saturation function. | src/ammm/mmm/components/saturation.py:396 |
NoSaturation | (priors=None, prefix=None) | Wrapper around linear saturation function. | src/ammm/mmm/components/saturation.py:635 |
RootSaturation | (priors=None, prefix=None) | Wrapper around Root saturation function. | src/ammm/mmm/components/saturation.py:538 |
SaturationTransformation | (priors=None, prefix=None) | Subclass for all saturation transformations. | src/ammm/mmm/components/saturation.py:109 |
TanhSaturation | (priors=None, prefix=None) | Wrapper around tanh saturation function. | src/ammm/mmm/components/saturation.py:299 |
TanhSaturationBaselined | (priors=None, prefix=None) | Wrapper around tanh saturation function. | src/ammm/mmm/components/saturation.py:343 |
MonthlyFourier | (*, n_order, days_in_period=30.4375, prefix='fourier', prior=Prior("Laplace", mu=0, b=1), variable_name=None) | Monthly fourier seasonality. | src/ammm/mmm/fourier.py:881 |
WeeklyFourier | (*, n_order, days_in_period=7, prefix='fourier', prior=Prior("Laplace", mu=0, b=1), variable_name=None) | Weekly fourier seasonality. | src/ammm/mmm/fourier.py:945 |
YearlyFourier | (*, n_order, days_in_period=365.25, prefix='fourier', prior=Prior("Laplace", mu=0, b=1), variable_name=None) | Yearly fourier seasonality. | src/ammm/mmm/fourier.py:816 |
HSGP | (*, m, X=None, X_mid=None, dims, transform=None, demeaned_basis=False, ls, eta, L, centered=False, drop_first=True, cov_func='expquad') | HSGP component. | src/ammm/mmm/hsgp.py:299 |
CovFunc | (*values) | Supported covariance functions for the HSGP model. | src/ammm/hsgp_kwargs.py:12 |
HSGPPeriodic | (*, m, X=None, X_mid=None, dims, transform=None, demeaned_basis=False, ls, scale, cov_func='periodic', period) | HSGP component for periodic data. | src/ammm/mmm/hsgp.py:801 |
PeriodicCovFunc | (*values) | Supported covariance functions for the HSGP model. | src/ammm/mmm/hsgp.py:795 |
SoftPlusHSGP | (*, m, X=None, X_mid=None, dims, transform=None, demeaned_basis=False, ls, eta, L, centered=False, drop_first=True, cov_func='expquad') | HSGP with softplus transformation. | src/ammm/mmm/hsgp.py:1147 |
approx_hsgp_hyperparams | (x, x_center, lengthscale_range, cov_func) | Use heuristics for minimum m and c values. | src/ammm/mmm/_hsgp_priors.py:87 |
create_complexity_penalizing_prior | (*, alpha=0.1, lower=1.0) | Create prior that penalizes complexity for GP lengthscale. | .venv/lib/python3.12/site-packages/pydantic/_internal/_validate_call.py:16 |
create_constrained_inverse_gamma_prior | (*, upper, lower=1.0, mass=0.9) | Create a lengthscale prior for the HSGP model. | src/ammm/mmm/_hsgp_priors.py:59 |
create_eta_prior | (mass=0.05, upper=1.0) | Create prior for the variance. | src/ammm/mmm/_hsgp_priors.py:160 |
create_m_and_L_recommendations | (X, X_mid, ls_lower=1.0, ls_upper=None, cov_func='expquad') | Create recommendations for the number of basis functions based on the data. | src/ammm/mmm/_hsgp_priors.py:177 |
HolidayEventEffect | (*, df_events, prefix, effect, reference_date='2025-01-01', date_dim_name='date', provenance) | Per-event holiday effect with retained calendar provenance. | src/ammm/mmm/holidays.py:27 |
HolidayPooledEffect | (*, holidays_df, provenance, prefix='holiday', effect_size_prior=<factory>, date_dim_name='date') | Estimate one coefficient for a binary pooled-holiday regressor. | src/ammm/mmm/holidays.py:109 |
HolidayProphetEffect | (*, holidays_df, provenance, profile_df=None, prefix='holiday', effect_size_prior=<factory>, date_dim_name='date', group_dim_names=(), geo_dim_name=None, yearly_seasonality=True, weekly_seasonality=False, daily_seasonality=False) | Apply a frozen Prophet-derived holiday profile as one MMM component. | src/ammm/mmm/holidays.py:184 |
Incrementality | (model, idata=None, data=None) | Incrementality and counterfactual analysis for MMM models. | src/ammm/mmm/incrementality.py:271 |
FancyLinearRegression | (**mmm_kwargs) | Create wrapper around MMM for a linear regression model. | src/ammm/mmm/linear_regression.py:9 |
LinearTrend | (*, priors=<factory>, dims=None, n_changepoints=10, include_intercept=False, prefix='') | LinearTrend class. | src/ammm/mmm/linear_trend.py:64 |
MediaConfig | (name, columns, media_transformation) | Configuration for a media transformation to certain media channels. | src/ammm/mmm/media_transformation.py:239 |
MediaConfigList | (media_configs) | Wrapper for a list of media configurations to apply to media data. | src/ammm/mmm/media_transformation.py:298 |
MediaTransformation | (adstock, saturation, adstock_first, dims=None) | Wrapper for applying adstock and saturation transformation to media data. | src/ammm/mmm/media_transformation.py:97 |
MMM | (*, date_column, channel_columns, target_column='y', adstock, saturation, time_varying_intercept=False, time_varying_media=False, dims=None, scaling=None, model_config=None, sampler_config=None, control_columns=None, yearly_seasonality=None, adstock_first=True, dag=None, treatment_nodes=None, outcome_node=None, link='identity', cost_per_unit=None) | Marketing Mix Model class for estimating the impact of marketing channels on a target variable. | src/ammm/mmm/mmm.py:238 |
CorrelatedRandomEffectsMMM | (*, unit, date_column, channel_columns, adstock, saturation, target_column='y', **kwargs) | Fit a shared-slope MMM with an exact collapsed random unit intercept. | src/ammm/mmm/correlated_random_effects.py:182 |
FixedEffectsMMM | (*, unit, date_column, channel_columns, adstock, saturation, target_column='y', **kwargs) | Fit shared MMM slopes through an exact unit fixed-effects likelihood. | src/ammm/mmm/fixed_effects.py:79 |
FixedEffectsEstimabilityReport | (basis, reference_parameter_source, unit, n_units, n_periods, variables, within_sum_squares, matrix_rank, singular_values) | Record the deterministic FE reference-design screen. | src/ammm/mmm/fixed_effects.py:60 |
within_contrast_matrix | (period_count) | Return the orthonormal Helmert matrix that removes one unit mean. | src/ammm/mmm/fixed_effects.py:37 |
CurrentScenarioSpec | (*, name, start_date, end_date, scenario_id=None, scenario_type='current', history_policy='observed_window', post_window_carryover_policy='not_applicable') | Select a factual contribution window from retained posterior draws. | src/ammm/mmm/scenarios.py:97 |
DataArraySpec | (*, dims, coords, values) | Represent a labelled xarray data array in YAML-safe values. | src/ammm/mmm/scenarios.py:43 |
ManualAllocationScenarioSpec | (*, name, start_date, end_date, scenario_id=None, scenario_type='manual_allocation', allocation, allocation_unit='total_horizon_spend', include_last_observations=False, include_carryover=True, noise_level=0.0, history_policy='no_observed_history', post_window_carryover_policy='included') | Define a total-horizon allocation for every fitted unit and channel. | src/ammm/mmm/scenarios.py:105 |
ScenarioRecipe | (*, scenario_contract_version='1', estimand='posterior_media_contribution_original_scale', scenarios) | Define one immutable, versioned collection of scenario requests. | src/ammm/mmm/scenarios.py:160 |
evaluate_scenario_recipe | (model, recipe) | Evaluate a recipe without refitting or reading external training data. | src/ammm/mmm/scenarios.py:487 |
load_scenario_recipe | (path) | Load and validate a versioned YAML scenario recipe. | src/ammm/mmm/scenarios.py:207 |
run_scenario_recipe | (*, model_path, recipe_path, output_dir) | Evaluate a YAML recipe against one retained fitted model artefact. | src/ammm/mmm/scenarios.py:734 |
OptimizationVariable | () | One named, contiguous segment of the flat decision vector. | src/ammm/mmm/optimization_variables.py:119 |
OptimizationVariables | (variables, flat_name='budgets_flat', flat_dim='budgets_flat') | The complete decision vector: an ordered list of variables. | src/ammm/mmm/optimization_variables.py:656 |
MMMPlotSuiteFacade | (data) | Namespace container for the MMM plotting API. | src/ammm/mmm/plotting/suite.py:15 |
preprocessing_method_X | (method) | Tag a method as a preprocessing method for the X data. | src/ammm/mmm/preprocessing.py:33 |
preprocessing_method_y | (method) | Tag a method as a preprocessing method for the y data. | src/ammm/mmm/preprocessing.py:55 |
DataDerivedScaling | (*, dims, method) | Scale by a statistic of the data, computed at fit time. | src/ammm/mmm/scaling.py:123 |
FixedScaling | (*, dims, value) | Use a user-supplied constant that stays the same across model refreshes. | src/ammm/mmm/scaling.py:169 |
Scaling | (*, target, channel) | Scaling configuration for the MMM. | src/ammm/mmm/scaling.py:431 |
VariableScaling | (*, dims) | Abstract base for scaling a variable. | src/ammm/mmm/scaling.py:82 |
SensitivityAnalysis | (pymc_model, idata, dims=()) | SensitivityAnalysis class is used to perform counterfactual analysis on MMM’s. | src/ammm/mmm/sensitivity_analysis.py:94 |
TimeSliceCrossValidationResult | (X_train, y_train, X_test, y_test, idata, mmm=None) | Container for the results of one time-slice CV step. | src/ammm/mmm/time_slice_cross_validation.py:30 |
TimeSliceCrossValidator | (n_init, forecast_horizon, date_column, step_size=1, sampler_config=None) | Time-Slice Cross Validator for Media Mix Models (MMM). | src/ammm/mmm/time_slice_cross_validation.py:57 |
MMMBuilder | (*args, **kwargs) | Protocol for objects that can build MMM models. | src/ammm/mmm/types.py:13 |
validation_method_X | (method) | Tag a method as a validation method for the predictor columns. | src/ammm/mmm/validating.py:75 |
validation_method_y | (method) | Tag a method as a validation method for the target column. | src/ammm/mmm/validating.py:67 |
ammm.pipeline
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
PipelineAIAdvisorConfig | (*, enabled=False, provider='openrouter', mode='autopilot', privacy='anonymized_relative', approval='file_based', write_outputs=True, llm_enabled=True, diagnostics_review_enabled=True, model=None, timeout_seconds=60) | Configure deterministic and optional live AI-advisor stages. | src/ammm/pipeline/config.py:42 |
PipelineRunConfig | (config_path, output_dir, run_name, ai_advisor=None, sampler=<factory>, method=None, disabled_stages=frozenset(), sample_counts=<factory>, quick=False) | Resolved invocation settings for one structured run. | src/ammm/pipeline/config.py:16 |
RunManifest | (schema_version, run_name, timestamp, config_path, output_dir, config_sha256, status='pending', model_class=None, data=<factory>, overrides=<factory>, stages=<factory>, warnings=<factory>, error=None, finished_at=None) | Record the lifecycle and evidence of one immutable pipeline run. | src/ammm/pipeline/manifest.py:39 |
StageManifest | (directory, status='pending', started_at=None, finished_at=None, artifacts=<factory>, warnings=<factory>, error=None) | Record one pipeline stage and its retained artefacts. | src/ammm/pipeline/manifest.py:26 |
ammm.pie
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
PIEModel | (*, pre_determined_features, post_determined_features, target_column='y', use_post_determined_features=True, standard_error_column=None, model_config=None, sampler_config=None) | Predicted Incrementality by Experimentation model. | src/ammm/pie/model.py:80 |
ammm.prior_sensitivity
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
PriorSensitivityConfig | (*, enabled=True, reference='reference', scenario_policy='manual', allow_model_structure_overrides=False, fit_scenarios=False, robustness_tolerance=0.2, scenarios=<factory>) | Configure a retained prior-sensitivity scenario plan. | src/ammm/prior_sensitivity/config.py:47 |
PriorSensitivityScenario | (*, description=None, reason=None, overrides=<factory>) | Declare one controlled configuration variation. | src/ammm/prior_sensitivity/config.py:30 |
ScenarioResolution | (name, description, reason, classification, overrides, config) | One validated, executable sensitivity scenario. | src/ammm/prior_sensitivity/scenarios.py:24 |
expand_prior_sensitivity_scenarios | (config, settings) | Expand declared and policy-generated sensitivity scenarios. | src/ammm/prior_sensitivity/scenarios.py:36 |
write_prior_sensitivity_scenarios | (*, output_dir, config, settings) | Write resolved configs and full and anonymised scenario manifests. | src/ammm/prior_sensitivity/scenarios.py:66 |
ammm.ai
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
AdvisorApprovalRequest | (*, status='pending', source_config_path, proposal_path, approved_config_path='approved_config.resolved.yaml', approval_record_path='approval_record.yaml', advisor_response_path=None, evidence_path=None, rules_summary_path=None, approved_by=None, decision_note=None) | Pending or approved file-based request for one advisor patch. | src/ammm/ai/approval.py:43 |
AdvisorApprovalResult | (approved_config_path, approval_record_path) | Materialized approval outputs. | src/ammm/ai/approval.py:60 |
AdvisorConfigPatch | (*, overrides=<factory>) | Validated file-based advisor patch. | src/ammm/ai/approval.py:24 |
AdvisorConfigPatchProposal | (*, proposed=False, rationale='No config patch proposed.', yaml_patch=None) | Optional AI-authored config patch proposal. | src/ammm/ai/schemas.py:74 |
AdvisorDecisionState | (*values) | Final decision-readiness state for an advisor run. | src/ammm/ai/schemas.py:23 |
AdvisorEvidenceBundle | (*, task, privacy_mode='anonymized_relative', raw_values_included=False, channels=<factory>, evidence=<factory>, warnings=<factory>, missing_evidence=<factory>) | Privacy-safe evidence payload for one advisor call. | src/ammm/ai/evidence.py:62 |
AdvisorLLMResponse | (*, summary, narrative=None, decision_state, recommendations=<factory>, config_patch_proposal=<factory>) | Structured response expected from the LLM advisor call. | src/ammm/ai/schemas.py:103 |
AdvisorPatchError | See definition; runtime signature unavailable | Raised when an advisor patch cannot be validated or approved. | src/ammm/ai/approval.py:20 |
AdvisorRecommendation | (*, priority, title, rationale, evidence_keys, proposed_change, expected_result, acceptance_criterion, escalation_criterion, assumption_effect='none', action_type) | One AI-authored advisor recommendation. | src/ammm/ai/schemas.py:45 |
AdvisorRuleFinding | (*, rule_id, severity, summary, evidence_keys=<factory>, recommended_action=None) | One deterministic advisor rule finding. | src/ammm/ai/rules.py:31 |
AdvisorRuleSummary | (*, decision_state, findings=<factory>, assessments=<factory>) | Rule findings and overall decision state for an advisor bundle. | src/ammm/ai/rules.py:54 |
AdvisorSeverity | (*values) | Severity labels for deterministic rule findings. | src/ammm/ai/schemas.py:36 |
AdvisorTask | (*values) | Supported AI advisor task types. | src/ammm/ai/schemas.py:12 |
EvidenceItem | (*, key, summary, value=None, detail=<factory>) | One compact evidence item included in an advisor bundle. | src/ammm/ai/evidence.py:51 |
EvidencePrivacyMode | (*args, **kwargs) | src/ammm/ai/__init__.py:36 | |
anonymize_channels | (channels) | Return a stable channel-name to anonymised-channel mapping. | src/ammm/ai/evidence.py:76 |
apply_approved_config_patch | (approval_request_path, *, approved_by=None, decision_note=None) | Apply an approved file-based advisor patch and write a resolved config. | src/ammm/ai/approval.py:107 |
build_config_review_evidence | (cfg, *, task='prior_config_review') | Build a privacy-safe evidence bundle from a YAML-like config mapping. | src/ammm/ai/evidence.py:84 |
build_diagnostics_review_evidence | (*, cfg, diagnostics_dir, validation_dir=None, metadata_dir=None, fit_dir=None, preflight_dir=None, run_dir=None, task='model_diagnostics_advisor') | Build a privacy-safe evidence bundle from generated diagnostics artifacts. | src/ammm/ai/evidence.py:161 |
evaluate_evidence_rules | (bundle) | Evaluate deterministic rules for one advisor evidence bundle. | src/ammm/ai/rules.py:64 |
parse_config_patch | (yaml_patch) | Parse and validate the advisor’s YAML patch format. | src/ammm/ai/approval.py:68 |
validate_evidence_privacy | (bundle, *, sensitive_terms=()) | Return privacy warnings for strings that should not be sent to an LLM. | src/ammm/ai/evidence.py:495 |
write_pending_approval_request | (*, stage_dir, source_config_path, proposal_path, advisor_response_path, evidence_path, rules_summary_path) | Write a pending approval request beside an advisor patch proposal. | src/ammm/ai/approval.py:82 |
ammm.mmm.builders
| Export | Call signature / value | Purpose | Definition |
|---|---|---|---|
MMMYamlConfig | (*, model, data=None, run=None, holidays=None, diagnostics=None, validation=None, prior_sensitivity=None, ai_advisor=None, effects=None, extra_vars=None, original_scale_vars=None, calibration=None, idata_path=None) | Schema for the top-level MMM YAML configuration. | src/ammm/mmm/builders/schema.py:233 |
build | (spec) | Instantiate the object described by spec. | src/ammm/mmm/builders/factories.py:80 |
build_mmm_from_yaml | (config_path, *, X=None, y=None, model_kwargs=None, holidays_path=None, load_idata=True) | Build an MMM model from config_path. | src/ammm/mmm/builders/yaml.py:73 |
Main method signatures
The following signatures complement the task contracts above. **kwargs is not
a promise that arbitrary options are accepted: the called sampler, plotting or
factory interface owns those values. Return annotations are available in the
cited definitions; summary methods return tables, incrementality methods return
labelled draws, and fit/predict methods follow the lifecycle table above.
| Interface | Signature | Definition |
|---|---|---|
MMM.build_model | (X, y=None, **kwargs) | src/ammm/mmm/mmm.py:1818 |
MMM.fit | (X, y=None, *, method='mcmc', progressbar=None, random_seed=None, sample_kwargs=None, **kwargs) | src/ammm/mmm/mmm.py:1731 |
MMM.sample_prior_predictive | (X, y=None, samples=None, extend_idata=True, combined=True, **kwargs) | src/ammm/mmm/mmm.py:2227 |
MMM.sample_posterior_predictive | (X=None, extend_idata=True, combined=True, include_last_observations=False, clone_model=True, **sample_posterior_predictive_kwargs) | src/ammm/mmm/mmm.py:2299 |
MMM.save | (fname, **kwargs) | src/ammm/mmm/mmm.py:925 |
MMM.load | (fname, check=True) | src/ammm/_model_builder_io.py:353 |
MMM.add_original_scale_contribution_variable | (var) | src/ammm/mmm/mmm.py:1633 |
MMM.add_mu_effect | (mu_effect) | src/ammm/mmm/mmm.py:540 |
MMM.add_lift_test_measurements | (df_lift_test, dist=Gamma, name='lift_measurements') | src/ammm/mmm/mmm.py:2757 |
MMM.add_cost_per_target_calibration | (data, calibration_data, name_prefix='cpt_calibration', *, target_column='cost_per_target', target_per_cost=False) | src/ammm/mmm/mmm.py:2870 |
MMM.budget_optimizer | (start_date, end_date, *, budgets_to_optimize=None, cost_per_unit=None, compile_kwargs=None, **kwargs) | src/ammm/mmm/mmm.py:2078 |
MMM.sample_response_distribution | (allocation_strategy, *, start_date, end_date, noise_level=0.001, additional_var_names=None, include_observation=True, include_last_observations=False, include_carryover=True, budget_distribution_over_period=None) | src/ammm/mmm/mmm.py:2168 |
MMM.sample_adstock_curve | (amount=1.0, num_samples=500, random_state=None, idata=None, *, progressbar=True) | .venv/lib/python3.12/site-packages/pydantic/_internal/_validate_call.py:2554 |
MMM.sample_saturation_curve | (max_value=1.0, num_points=100, num_samples=500, random_state=None, original_scale=True, idata=None, *, progressbar=True) | .venv/lib/python3.12/site-packages/pydantic/_internal/_validate_call.py:2416 |
Incrementality.contribution_over_spend | (frequency, start_date=None, end_date=None, include_carryover=True, num_samples=None, random_state=None, central_tendency='median') | src/ammm/mmm/incrementality.py:1265 |
Incrementality.spend_over_contribution | (frequency, start_date=None, end_date=None, include_carryover=True, num_samples=None, random_state=None, central_tendency='median') | src/ammm/mmm/incrementality.py:1354 |
Incrementality.marginal_contribution_over_spend | (frequency, start_date=None, end_date=None, include_carryover=True, num_samples=None, random_state=None, spend_increase_pct=0.01, central_tendency='median') | src/ammm/mmm/incrementality.py:1423 |
BudgetOptimizer.allocate_budget | (total_budget, budget_bounds=None, x0=None, minimize_kwargs=None, return_if_fail=False, callback=False) | src/ammm/mmm/budget_optimizer.py:704 |
MMMSummaryFactory.contributions | (hdi_probs=None, component='channel', frequency=None, output_format=None) | .venv/lib/python3.12/site-packages/pydantic/_internal/_validate_call.py:420 |
MMMSummaryFactory.roas | (hdi_probs=None, frequency=None, method='elementwise', include_carryover=True, num_samples=None, random_state=None, start_date=None, end_date=None, output_format=None) | src/ammm/mmm/summary/factory.py:473 |
MMMSummaryFactory.posterior_predictive | (hdi_probs=None, frequency=None, output_format=None) | src/ammm/mmm/summary/factory.py:358 |
MMMSummaryFactory.prior_predictive | (hdi_probs=None, frequency=None, original_scale=True, output_format=None) | src/ammm/mmm/summary/factory.py:978 |
MMMSummaryFactory.waterfall | (hdi_probs=None, dims=None, original_scale=True, output_format=None) | src/ammm/mmm/summary/factory.py:896 |
MMMSummaryFactory.channel_share_hdi | (hdi_probs=None, dims=None, original_scale=True, output_format=None) | src/ammm/mmm/summary/factory.py:944 |
MMMSummaryFactory.saturation_curves | (hdi_probs=None, output_format=None, data=None, max_value=1.0, num_points=100, num_samples=None, random_state=None, original_scale=True) | src/ammm/mmm/summary/factory.py:636 |
MMMSummaryFactory.adstock_curves | (hdi_probs=None, output_format=None, data=None, amount=1.0, num_samples=None, random_state=None) | src/ammm/mmm/summary/factory.py:730 |
ammm.mmm.builders.yaml.build_mmm_from_yaml | (config_path, *, X=None, y=None, model_kwargs=None, holidays_path=None, load_idata=True) | src/ammm/mmm/builders/yaml.py:73 |
ammm.pipeline.runner.run_pipeline | (run_config, *, repository_root, holidays_path=None, reporter=None) | src/ammm/pipeline/runner.py:156 |
ammm.pipeline.runner.validate_pipeline_config | (config_path, *, holidays_path=None) | src/ammm/pipeline/runner.py:226 |
ammm.ai.review.review_run | (run_dir, *, llm_enabled=True, model=None) | src/ammm/ai/review.py:23 |
ammm.ai.approval.apply_approved_config_patch | (approval_request_path, *, approved_by=None, decision_note=None) | src/ammm/ai/approval.py:107 |
The direct YAML builder returns a built model and can attach configured inference
data; it does not fit it. Pass load_idata=False and preloaded data for a fresh
Python fit because data-path resolution differs from the runner. run_pipeline
returns a PipelineRunResult carrying the run directory and manifest; graph
validation is a separate operation (src/ammm/mmm/builders/yaml.py:73,
src/ammm/pipeline/runner.py:108).
review_run returns a new review directory and defaults to allowing an LLM;
explicitly pass llm_enabled=False for local review. apply_approved_config_patch
returns paths to the new config and approval record and rejects an unapproved
request. Neither interface fits a model (src/ammm/ai/review.py:23,
src/ammm/ai/approval.py:107).
Use YAML fields for configuration schemas and output schemas for retained file contracts. Direct submodules contain additional helpers; contributor ownership and extension points are described in architecture.