Prior sensitivity and advisor APIs

These Python APIs expose configuration planning and retained-evidence review. Scenario expansion does not run sampling. Advisor rules and model suggestions do not establish causal identification or approve an estimator release.

Prior-sensitivity planning

Import the following types and functions from ammm.prior_sensitivity.

The policy can also be conservative_mmm, which generates scenarios for supported explicitly configured transform priors. Expansion inserts the reference when absent. The reference must have no overrides. Model-structure changes require allow_model_structure_overrides=True. Scenario names must be valid non-reserved lowercase slugs using letters, digits and underscores.

from pathlib import Path
import yaml

from ammm.prior_sensitivity import (
    expand_prior_sensitivity_scenarios,
    resolve_prior_sensitivity_config,
)

cfg = yaml.safe_load(Path("data/demo/timeseries/config.yml").read_text())
settings = resolve_prior_sensitivity_config(cfg)
resolutions = (
    expand_prior_sensitivity_scenarios(cfg, settings)
    if settings is not None
    else []
)

The writer takes a Path for output_dir. It writes a config.resolved.yaml inside each scenario directory, plus scenario_manifest.yaml and llm_safe_scenario_manifest.yaml. Runner-only roots are removed from resolved model configurations. Relative data paths remain relative strings; preserve or rebase their location before running a configuration elsewhere. Inspect the resolved configurations before launching separate fits and comparing results.

Evidence construction and rules

Import these functions and types from ammm.ai.

Evidence bundles contain task, privacy_mode, raw_values_included, channel aliases, EvidenceItem records, privacy warnings and missing_evidence. Defaults use anonymized_relative privacy mode. Review warnings about absent or unusable artefacts. The privacy check is a validation rule over the supplied bundle; it cannot certify every possible identifying detail.

from ammm.ai import (
    build_config_review_evidence,
    evaluate_evidence_rules,
    validate_evidence_privacy,
)


def review_configuration(cfg):
    evidence = build_config_review_evidence(cfg)
    issues = validate_evidence_privacy(evidence)
    return evidence, evaluate_evidence_rules(evidence), issues

Typed response contracts include AdvisorLLMResponse, AdvisorRecommendation and AdvisorConfigPatchProposal. AdvisorTask, AdvisorSeverity and AdvisorDecisionState define their labels. AdvisorRuleFinding and AdvisorRuleSummary represent deterministic rule outputs. Evidence and response models support Pydantic validation and serialisation. These local construction functions do not contact a model provider.

Parameter and saved-run review

ammm.ai.identification.build_identification_report(*, fit_dir, preflight_dir=None, diagnostics_dir=None, channels=None) returns provider evidence, a local parameter lookup and missing evidence. Its companion render_identification_markdown(report) renders a local report. Neither function fits a model or contacts a provider. Supply channels in configuration order to include provider-safe channel aliases. Supply run_dir to the diagnostics evidence builder to include the wider retained-run context.

ammm.ai.review.review_run(run_dir, *, llm_enabled=True, model=None) writes a separate review of a retained run and returns the review directory as a Path. It leaves the fitted model and run manifest unchanged. LLM calls are enabled by default; set llm_enabled=False for a local-only review. Set model to override the retained provider’s model for this review. See the diagnostics advisor guide for evidence limits, provider configuration and the command-line entry point.

Recommendations now require non-empty proposed_change, expected_result, acceptance_criterion and escalation_criterion fields. Evidence references must name supplied non-empty items. incomplete_evidence distinguishes missing required evidence from an assessed diagnostic warning.

LLM calls also require an AdvisorNarrative with findings, marketing_implications, limitations and supporting evidence_keys. AdvisorLLMResponse.narrative can be absent in automated reports or when the deterministic assessment overrides an optimistic LLM response. The main advisor_review.md contains the accepted concise LLM narrative and links to technical evidence.

Patch parsing and approval files

parse_config_patch(yaml_patch) accepts YAML text with a non-empty overrides mapping. It returns AdvisorConfigPatch or raises AdvisorPatchError for invalid syntax, structure or unsupported override paths.

from ammm.ai import parse_config_patch

patch = parse_config_patch("""
overrides:
  media.saturation.priors.beta:
    distribution: HalfNormal
    sigma: 1
""")

write_pending_approval_request(*, stage_dir, source_config_path, proposal_path, advisor_response_path, evidence_path, rules_summary_path) writes approval_request.yaml and returns its Path. The last three arguments accept None. Supply Path objects for paths. AdvisorApprovalRequest describes the file and defaults its status to pending.

apply_approved_config_patch(approval_request_path, *, approved_by=None, decision_note=None) requires a request whose status is already approved. It validates the patched model configuration and returns AdvisorApprovalResult with approved_config_path and approval_record_path. Default output names are approved_config.resolved.yaml and approval_record.yaml. Output paths must be relative and remain inside the request directory. The function writes these files; it does not run the model or perform the approval decision.

The patched source must satisfy the direct builder schema, including its restriction on runner-only roots. A valid patch object alone does not prove that the resulting model configuration is valid.

Related guides

• YAML configuration
• Advisor workflow
• Bayesian priors