Output contracts
Files
Path relative to project.output_dir | Condition and contents |
|---|---|
analysis.log | Project logs |
data/provider_timeline.json | Retained interest_over_time object; excludes outer provider metadata |
run_metadata.json | Version, dependency versions, validated settings, timeline SHA-256 and AI status |
data/full_data.csv | Transformed observations and calculated metrics |
data/metrics.csv | Aggregate metrics for each query |
charts/line_trends.png | Raw interest over returned dates |
charts/area_share.png | Share evolution |
charts/bar_average.png | Whole-period average share |
charts/pie_current.png | Whole-period average share; filename retained from the existing interface |
insights.txt | Narration enabled; may contain an automated summary when AI is unavailable |
<Project_Name>_presentation.pptx | Summary and chart paths available and PowerPoint generation succeeds; spaces in project name become underscores |
The pipeline also initialises outputs/pipeline.log relative to the working
directory before it knows the project settings. Charts and PowerPoint are optional
outputs whose failures are logged. An exit code of zero does not prove that every
optional artefact was written. The pipeline overwrites matching filenames and does
not clean older optional outputs. Use a fresh directory for every retained run.
Data columns
full_data.csv includes date, query, value, share_of_search,
trend_direction, trend_slope, momentum, volatility, z_score and
is_anomaly. It also includes value_ma when smoothing_period > 1.
Dates from numeric provider timestamps use UTC without a timezone suffix.
query stores the configured display label.
metrics.csv contains query, avg_share, volatility, min_share,
max_share, total_interest and avg_interest. Empty numeric CSV cells represent
undefined values, including unavailable momentum. See the
metric definitions.
Python result
run_pipeline returns a dictionary containing:
| Key | Value |
|---|---|
dataframe | Full calculated pandas DataFrame |
period_metrics | Aggregate pandas DataFrame |
market_concentration | Final-date dictionary with hhi, concentration, num_competitors, date |
charts | Generated PNG paths, or an empty list on chart failure |
insights | Empty when disabled; otherwise summary, comparative description, optional anomaly descriptions and brand profiles |
ai_status | status; enabled runs also record model and successful/failed AI call counts |
insights uses executive_summary, competitive_insights,
anomaly_explanations when anomalies exist, and recommendations. The last key
contains descriptive brand profiles and suggested evidence checks.
The metadata hash identifies the exact retained timeline bytes. It is a provenance check, not a statistical validity test. Narrative status indicates call completion, not factual correctness. Neither data files nor documentation are uploaded by the pipeline.