Use the optional AI advisor

The advisor organises model evidence and recommendations. It does not establish causal identification or authorise a budget decision. Deterministic rules set a decision floor that a provider response cannot soften.

To retain local evidence without a provider call:

ai_advisor:
  enabled: true
  llm_enabled: false
  diagnostics_review_enabled: true

--no-ai-advisor disables both local and live advisor stages. Advisor absence or enabled: false also disables them. Stage 08 prepares local configuration evidence; stage 90 reviews the completed evidence. Inspect retained status fields to distinguish attempted, completed, cached and unavailable provider work.

For live review, choose provider: openrouter or provider: openai and set llm_enabled: true. The respective credential is OPENROUTER_API_KEY or OPENAI_API_KEY, supplied through the environment or ignored repository .env. Use .env.example as the configuration template. Requests may incur provider charges.

The implemented policy fixes privacy: anonymized_relative, mode: autopilot and approval: file_based. The mode name does not mean an LLM can silently rewrite and refit your model. Review pending configuration recommendations and approval artefacts before adopting changes.

The request builder uses allowlisted, anonymised evidence rather than raw outcome series and business channel names. OpenRouter requests include the configured data-collection and retention restrictions. These code controls do not establish the provider’s wider governance guarantees; inspect retained request/status evidence for the actual invocation. Never place credentials in tracked YAML or share retained artefacts without reviewing their contents.

Local and live review controls

An enabled advisor block defaults to llm_enabled: true; preserve the explicit false value in the local-only example above. Stage 08 is local preparation, whereas stage 90 can request a provider review unless deterministic rules return do_not_use. write_outputs: false returns before that call, and diagnostics_review_enabled: false disables the final stage (src/ammm/pipeline/config.py:42, src/ammm/pipeline/stages/ai_advisor.py:41, src/ammm/pipeline/stages/ai_advisor.py:88).

At this source commit, an unset model resolves to gpt-5-mini for OpenAI or openai/gpt-5.6-terra for OpenRouter. These are implementation defaults, not a claim that a provider currently offers those models. An explicit non-empty model overrides them; timeout defaults to 60 seconds (src/ammm/pipeline/config.py:68). Check current provider availability and pricing before a paid invocation.

A request sets a 3,000-output-token limit, but no currency spending cap is implemented. Retained usage comes from the provider response and can be empty; cache hits reuse a previous response without a new request. Inspect llm_call_attempted, llm_call_performed, llm_response_accepted, cache_hit, llm_call_reason, model and usage together rather than treating any one flag as a billing receipt (src/ammm/ai/advisor.py:174, src/ammm/pipeline/stages/ai_advisor.py:315).

Before enabling a provider, inspect 08_ai_advisor/evidence.json and the final 90_ai_advisor/diagnostics_evidence.json from a local-only review. The local parameter_lookup.local.json can contain original parameter labels; it is not the anonymised provider payload. OpenRouter request controls do not establish provider-wide retention guarantees (src/ammm/pipeline/stages/ai_advisor.py:168, src/ammm/ai/client.py:173).

Review a saved run locally

This template performs a new local review under the retained run’s advisor_review/ directory without refitting. Replace the example run path with your completed run; it creates review files while leaving the original model and manifest unchanged (src/ammm/ai/review.py:23).

from pathlib import Path
from ammm.ai.review import review_run

review_directory = review_run(Path("results/my_completed_run"), llm_enabled=False)
print(review_directory)

Inspect its status and rules before interpreting the narrative. An incomplete or failed model remains incomplete or failed after a successful local review.

Adopt a reviewed configuration proposal

A proposal does not change or refit the model. The advisor writes config_patch_proposal.yaml and a pending approval_request.yaml; a human must review the proposed dotted-path changes, source configuration, evidence and rules, then deliberately set the request’s status to approved (src/ammm/pipeline/stages/ai_advisor.py:341). Record the reviewer and decision note and choose fresh relative output names inside that advisor directory.

Patch paths are restricted to model prior configuration and the explicitly supported adstock/saturation class or lag-horizon paths; arbitrary sampler settings such as model.kwargs.sampler_config.draws are rejected. The path must already exist in the source mapping (src/ammm/ai/approval.py:24, src/ammm/prior_sensitivity/overrides.py:18). For example, a reviewed proposal can set model.kwargs.model_config.intercept.sigma when that prior field exists.

Only after that decision, call the materialisation interface:

from pathlib import Path
from ammm.ai import apply_approved_config_patch

# Template: the named request must already contain the reviewer's approval.
outputs = apply_approved_config_patch(
    Path("results/my_completed_run/90_ai_advisor/approval_request.yaml"),
    approved_by="model-reviewer", decision_note="Approved after evidence review",
)
print(outputs.approved_config_path, outputs.approval_record_path)

The function rejects a pending request, validates the patched configuration and writes the new configuration and approval record; it neither fits nor proves the change statistically appropriate. Relative output paths must stay inside the advisor directory. Use fresh names to preserve earlier records, because this writer is not a no-overwrite archive (src/ammm/ai/approval.py:107, src/ammm/ai/approval.py:195). Check data/calendar paths from the new file’s location, run graph validation, then request the intended refit through the normal workflow and review new diagnostics and independent-period evidence.

Implementation reference at 7cb7f20: src/ammm/pipeline/config.py:42, src/ammm/pipeline/stages/ai_advisor.py:88, src/ammm/ai/client.py:173.