Configuration
src.config.schema.Config defines the contract. Only project and queries
are required at the top level. Unknown fields are rejected at every level.
The complete example runs with defaults.
Supported fields
| Field | Default | Contract |
|---|---|---|
project.name | Required | Non-empty display name without path separators |
project.description | Empty string | Retained metadata; not supplied to the AI prompts |
project.output_dir | ./outputs | Output path relative to the working directory |
data_source.provider | serpapi | Only implemented provider |
data_source.api_key_env | SERPAPI_KEY | Environment variable containing the provider key |
queries | Required | One to five objects with query and label |
queries[].query | Required | Non-empty, unique term without the provider comma separator |
queries[].label | Required | Non-empty, unique display label |
parameters.geo | GB | Region supplied to SerpAPI; empty string requests worldwide |
parameters.date_range | today 12-m | Non-empty date expression supplied to SerpAPI |
parameters.smoothing_period | 3 | Integer at least 1; observed rows, not calendar months |
analysis.insights.enabled | true | Enable narration; missing key yields an automated summary |
analysis.trend_thresholds.rising_threshold | 0.1 | Strictly positive, at most 10; percentage points per observation |
analysis.trend_thresholds.falling_threshold | -0.1 | At least -10 and strictly negative; same units |
analysis.share_validation_tolerance | 0.1 | 0 to 5 percentage points for the arithmetic share-sum check |
visualization.theme | professional | Only implemented theme |
visualization.dpi | 300 | Integer at least 72 |
options.retry_attempts | 3 | Non-negative; retries after the initial SerpAPI request |
options.retry_delay | 5 | Initial SerpAPI backoff in seconds; at least 1 |
options.log_level | INFO | DEBUG, INFO, WARNING, ERROR or CRITICAL; case-insensitive |
The smoothing period controls a trailing mean of interest, the momentum lookback and rolling share volatility. It does not resample data. The line chart displays raw interest; the trailing mean is an additional CSV column when the window exceeds one.
Environment
| Variable | Purpose |
|---|---|
SERPAPI_KEY | Required by the default provider configuration |
OPENAI_API_KEY | Optional OpenAI authentication |
OPENAI_MODEL | Optional compatible Chat Completions model; default gpt-4-turbo |
load_config loads .env beside the YAML file. Existing process values win.
The direct Config constructor validates settings without loading credentials.
Model availability is account-dependent. See AI narration.
Removed inactive settings
Older YAML files accepted these settings without implementing their behaviour. Remove them before using this candidate. Unsupported fields now raise a configuration error rather than giving the impression that they were applied.
| Removed setting | Actual capability |
|---|---|
parameters.granularity | Provider resolution is retained |
analysis.metrics | The pipeline computes its fixed metric set; no seasonality estimator |
analysis.insights.auto_detect_anomalies | Descriptive anomaly flags are always calculated |
analysis.insights.confidence_threshold | The anomaly rule uses absolute z-score greater than 2.5; no confidence level |
queries[].color or colour | Fixed chart palette |
visualization.charts | Four fixed PNG charts; custom charts remain available through Python methods |
reporting | CSV, PNG, optional text and conditional PowerPoint only; no HTML, PDF or Excel report engine |
options.cache_enabled, cache_ttl, parallel_requests | One comparison request, retries, no local cache or request parallelism |
No statistical uncertainty can be created by relaxing the share-sum tolerance. All-zero dates remain invalid regardless of tolerance.
See outputs for filenames and troubleshooting for validation failures.