AI narration
AIInsightEngine sends numerical summaries to OpenAI Chat Completions when
analysis.insights.enabled is true and OPENAI_API_KEY is available. It does not
browse, inspect campaign calendars or independently verify external events.
Project descriptions are retained as metadata but are not included in prompts.
Evidence and calls
| Output | Supplied evidence | Requested limit |
|---|---|---|
| Executive summary | Dates, observation counts, aggregate metrics, final HHI and whole-period slopes | 120 words |
| Comparative description | Aggregate metrics by query | 80 words |
| Anomaly descriptions | Up to three observations ranked by absolute z-score, with date, share and z-score | 40 words each |
| Brand profiles | Average share, standard deviation and whole-period slope | 40 words per query |
A run can make two calls plus one per query plus up to three anomaly calls.
Each call has a 600-token output limit, a 60-second request timeout and one SDK
retry. Word limits are prompt instructions, not guaranteed output constraints.
The default model is gpt-4-turbo; OPENAI_MODEL can select another model that
supports the same Chat Completions arguments. Model and account availability
must be checked separately. The provider remains OpenAI.
System prompt
All requests share SYSTEM_PROMPT in
src/analysis/ai_insights.py.
It requires concise British English and separates descriptive search patterns
from market outcomes. It prohibits invented error margins, correlations, event
explanations and unsupported causal claims. Query labels are treated as data,
not instructions. Recommendations are requests for evidence checks.
Prompt rules reduce a known failure mode; they do not certify every generated sentence. Analysts must compare the narrative with the retained numerical outputs.
Availability and failure
With insights disabled, no AI client is created and no narration is written.
With no key, the report uses a clearly labelled automated summary. Failed, empty
or truncated responses do not count as successful narration. Other calls can
still succeed. run_metadata.json records the model, successful and failed call
counts and one of disabled, automated_only, partial or generated.
Logs contain exception types rather than provider payloads. The text report uses
BRAND PROFILES; the Python return key remains recommendations for the existing
API. A PowerPoint is attempted when a summary and charts are available, including
an automated summary when no key is supplied.
Data handling
Search queries, dates and metrics are sent to OpenAI when narration is enabled.
Use only data approved for that provider. Set analysis.insights.enabled: false
for offline processing or to avoid narration calls. .env and outputs are ignored
by Git. Provider authorisation and live narrative quality are separate from the
mocked package tests.