es_advise: Grounded AI Advice for Event Study Results

In EventStudy: Event Study Analysis

Grounded AI Advice for Event Study Results

Description

Produces a grounded Advice S3 object by routing through a task-type dispatch, calling an optional LLM provider, parsing the JSON response, and running the runtime grounding guard – which drops any recommendation whose evidence[] cites a diagnostic key absent from the computed diagnostics or a value mismatching beyond numeric tolerance.

Usage

es_advise(
  diagnostics,
  task_type,
  provider = NULL,
  model = NULL,
  section_hint = NULL,
  ...
)

Arguments

diagnostics	An es_diagnostics object returned by es_diagnostics().
task_type	Character. One of "interpret", "recommend_stat", "recommend_model", "flag_robustness", "design_discussion", "report_writing".
provider	An optional provider R6 object (from provider()). Required for LLM-only task types. When NULL and task type is KB-based, falls back to the Phase 5 offline path.
model	Optional character model identifier. Reserved for forward compatibility: the effective model is the one the provider was constructed with (see provider()), so set the model there. Accepted here without error so calling code can pass it, but it does not override the provider's configured model.
section_hint	Optional character scalar naming the report section to scope the narrative to (e.g. "exec_summary", "results", "robustness"). NULL (default) leaves the prompt byte-identical to its pre-Phase-18 form. Only applied for the "report_writing" task type.
...	Additional arguments (currently ignored; reserved for future use).

Details

Grounding guarantee: Every returned recommendation is provably tied to a value the package actually computed (es_diagnostics()). The guard is enforced in R, independent of the prompt (ADV-04).

Task type routing:

recommend_stat, flag_robustness

No provider: returns the Phase 5 es_advice object (offline KB path – deterministic, is_deterministic = TRUE). With provider: KB produces grounded evidence[], LLM adds prose; returns an Advice object (is_deterministic = FALSE).

interpret, recommend_model, design_discussion, report_writing

LLM-required: stop() when provider = NULL (ADV-06). With provider: LLM produces full advice; guard runs.

Failure discipline: Any provider failure, malformed JSON, or empty response degrades to one warning() + an empty Advice object – never a crash, never a fabricated result (mirrors .handle_degenerate()).

Value

For KB task types without a provider: an es_advice S3 object (Phase 5 offline path, is_deterministic = TRUE). For all other paths: an Advice S3 object with fields source, is_deterministic, task_type, interpretation, recommendations, caveats, n_dropped.

See Also

es_diagnostics, recommend_stat, flag_robustness, provider, run_event_study

Other eventstudy-advisor: AnthropicProvider, CustomProvider, OpenAICompatProvider, ProviderBase, es_diagnostics(), es_kb(), flag_robustness(), provider(), recommend_stat()

Examples

# Offline KB path (no LLM, no network, no credentials):

data(dieselgate)
task    <- EventStudyTask$new(dieselgate$firm, dieselgate$index, dieselgate$request)
task    <- run_event_study(task, ParameterSet$new())
diag    <- es_diagnostics(task)
advice_kb <- es_advise(diag, task_type = "recommend_stat")
print(advice_kb)   # es_advice S3


# LLM-grounded path (requires a network connection and provider credentials):
## Not run: 
p         <- provider("openai")
advice    <- es_advise(diag, task_type = "recommend_stat", provider = p)
print(advice)      # Advice S3 with grounding guarantee

## End(Not run)

EventStudy documentation built on Oct. 31, 2026, 1:07 a.m.