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 abacus.prior_sensitivity.

Symbol	Contract
`PriorSensitivityConfig`	`enabled=True`, `reference="reference"`, `scenario_policy="manual"`, `allow_model_structure_overrides=False` and named `scenarios`
`PriorSensitivityScenario`	Optional description/reason and an `overrides` mapping of dotted paths to values
`ScenarioResolution`	Resolved name, description, reason, classification, overrides and complete model configuration
`OverrideClassification`	Classifies prior changes separately from model-structure changes
`resolve_prior_sensitivity_config(cfg)`	Parse the root block; return `None` when it is absent
`classify_override_path(path)`	Classify a supported dotted path; reject unsupported paths
`classify_scenario_overrides(overrides)`	Classify the collection of override paths
`apply_overrides(cfg, overrides)`	Return a copied configuration with overrides applied
`expand_prior_sensitivity_scenarios(cfg, prior_sensitivity)`	Return validated `ScenarioResolution` objects; return an empty list when disabled
`write_prior_sensitivity_scenarios(*, output_dir, cfg, prior_sensitivity)`	Write resolved configurations and manifests; return the resolutions

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 abacus.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 abacus.ai.

Function	Result
`anonymize_channels(channels)`	Mapping from supplied names to stable aliases within that call
`build_config_review_evidence(cfg, *, task=...)`	`AdvisorEvidenceBundle` for configuration review
`build_diagnostics_review_evidence(*, cfg, diagnostics_dir, validation_dir=None, task=...)`	Evidence bundle read from retained diagnostic files
`validate_evidence_privacy(bundle, *, sensitive_terms=())`	List of detected privacy issues; an empty list means no issues detected by these checks
`evaluate_evidence_rules(bundle)`	`AdvisorRuleSummary` with decision state, findings and assessments

Evidence bundles contain task, privacy_mode, raw_values_included, channel aliases, EvidenceItem records and warnings. 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 abacus.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.

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 abacus.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.

Prior sensitivity and advisor APIs

Prior-sensitivity planning

Evidence construction and rules

Patch parsing and approval files

Related guides