jieyi-deng/pallas-ads/pallas-dashboard

Pallas advertising dashboard

Use the approved assets/dashboard.html, dashboard.css and dashboard.js. Keep its layout; fill it through the data contract, not by editing HTML totals or asking a model to invent insights. The flow is raw evidence → normalized daily template → code calculations → dashboard. The agent selects permitted sources, maps documented fields and explains limitations; code validates, deduplicates, calculates metrics, applies insight rules and renders the page.

1. Before first generation

Set report_language from the user's request: Chinese -> zh-CN; all other languages -> en. An explicit requested output language takes precedence with the same mapping. Pass it at the top level of build_report/pallas_command, or in dashboard.report_language when using the direct dashboard helper. Never infer it from account names, input files or the OS. The saved language covers headings, filters, charts, insights, dialogs and accessibility text. Explicit user-requested updates pass the current request's language. Unattended/scheduled updates omit the field and retain the saved language; new dashboards default to English. Keep user-supplied names/titles and evidence values unchanged. Generate new descriptive titles in the selected report language. Do not translate or replace the finished HTML manually.

Choose the route from the user's request and existing authorization; ask only for missing account/file selection or ambiguous metric definitions. Do not ask again for an already confirmed title or source. A file-only request needs no advertising-account authorization.

• Authorized accounts (default when the user requests account data): use pallas-workflow

to discover/select existing authorized accounts. Google/TikTok use live_api and a workspace connection_id; Meta uses host_capture through the signed-in official MCP, or an already operator-configured live API. Never request credentials in chat.

• Uploaded history: inspect the CSV/XLSX/JSON's date grain, IDs, units, currency, timezone,

conversion definition and available hierarchy. Map the original fields to the data contract; retain the original file and its hash. Do not substitute sample data for missing uploaded fields.

• Keep one source per platform/account, up to 12. Do not mix synthetic and real evidence.

First account generation fetches the last 90 complete days, ending yesterday in each account's timezone. history_start may explicitly override this. Newest-first reads are bounded to 31 days each, with max_windows default 12 per source; finish/resume all windows and pagination before calling the requested history complete. Persist the first history floor; subsequent updates retain older data. Uploaded history uses its actual confirmed coverage, which may be shorter or longer than 90 days. Never stretch monthly totals into daily data, fill missing dates with zero, or claim an incomplete export is a complete window.

Retrieve documented campaign/day spend, impressions and clicks, account currency/timezone, IDs/names/status/objective; request conversion, ad-group/ad-set, creative, OS and video fields only when the selected account tools actually support them. Current built-in live/capture adapters retain campaign/day traffic; richer evidence can enter through the normalized file contract. Do not claim automatic live creative/conversion fetching has been implemented. Unavailable dimensions remain empty, without allocating campaign totals to invented children.

2. Build the normalized data

For flat CSV/XLSX/JSON exports, use the bundled dashboard helper:

python /absolute/skill/scripts/dashboard.py normalize --raw /absolute/export.csv --mapping /absolute/mapping.json --output-dir /absolute/WS/dashboards/dash_main/inputs

Run with the installed Pallas runtime's Python. The script delegates to versioned runtime code; no per-run processing script is needed. Start with assets/file-mapping.json and its schema. The agent maps literal column names, declares account/window/grain and documented units; the code parses values, converts micros, derives campaign totals from complete creative leaves, validates hierarchy/duplicates and writes content-addressed raw, mapping and normalized files. Inspect returned totals against source totals, then ingest the returned data_path. Reuse the saved mapping on subsequent exports of the same shape; update only the explicit window and review any field/unit/meaning changes. No expressions, arbitrary code, silent row skipping, ratio averaging, currency guessing or parent-to-child allocation are supported. See data-contract.md for supported formats and rejection rules. Unsupported nested/ambiguous exports need a reviewed reusable adapter; explain the missing support instead of writing an untested one-off transformation and claiming equivalence.

Read data-contract.md when mapping a file or a host export. Use assets/data-template.json as the shape and assets/data-template.schema.json as the machine contract. Replace every example value with evidence; it is not a real-account fixture. One input file represents one account and a complete explicit date window. It contains:

• source metadata and raw evidence reference/hash/field mapping;
• campaign metadata and daily additive metrics, with optional documented conversion definition;
• optional complete creative/day[/OS] rows plus campaign → group → creative relationships;
• explicit campaign target CPA and preview assets only when provided.

Persist normalized inputs locally and validate with:

python -m pallas_ads.dashboard_data /absolute/path/account-window.json

Use the Pallas runtime's Python environment. Do not calculate/store CTR, CPC, CVR, CPA, ROAS, percentage deltas or prose insights in the input. Missing is null; zero is an observed zero. The validator rejects duplicate keys, broken relationships, invalid values, out-of-window rows, undocumented conversions and unreconciled parent/child totals. It does not independently prove that an agent's mapping matches the original: inspect samples and reconcile aggregate totals against the raw source before importing. Never mark a mapping verified solely because it parses.

3. Generate using the fixed template

All runtime work uses build_report(action=dashboard, dashboard={...}):

{"action":"dashboard","dashboard":{"op":"create","dashboard_id":"dash_main","title":"Advertising Performance","sources":[{"platform":"google","route":"live_api","account_id":"123","connection_id":"connection_example"}]}}

For normalized uploaded or authorized-account export evidence, use file_import and ingest the validated window (automatic fetching is not enabled for this route):

{"action":"dashboard","dashboard":{"op":"create","dashboard_id":"dash_main","title":"Advertising Performance","sources":[{"platform":"meta","route":"file_import","account_id":"123"}],"ingest":[{"source_key":"meta:123","data_path":"/absolute/path/account-window.json"}]}}

Existing confirmed CSV/XLSX dataset_id imports and Meta capture_id imports remain supported. A dataset_id import adds observed rows only: its first/last dates do not establish complete coverage, dates without rows stay unknown (not zero), and the result is partial_result with coverage_not_established; comparisons and Key Insights are withheld for those dates. Only a data_path window with complete: true (or a complete API/capture read) establishes coverage. status.json sources.<key>.coverage separates complete_windows, observed_only and unknown_within_observed_span; report these instead of a data-through date for observed-only sources. A coverage_repaired issue means older state claimed file coverage that no retained complete window supports; rows were kept and those dates are now observed-only. For Meta host_capture, run exactly the runtime's requested_reads plus account/field context, stage via source_connect_or_import(action=host_capture), then update with the capture ID. Day boundaries use the account timezone_name from that retained evidence. A read with purpose: account_timezone is a prerequisite until it is captured; never supply the computer's timezone, infer one from currency, or assume UTC. Until then (source_timezone_required or source_timezone_invalid), reads end at the last date that has ended in every timezone. Days not yet ended in the account timezone at observed_at are reported as excluded_unfinished and never become rows or coverage; re-read them after they end. Older capture state is checked once against retained captures; a coverage_repaired issue there means days read before they ended, or with no retained capture, are now observed-only until a complete capture re-reads them.

dashboards/<id>/data.json is the saved view data and the exact data embedded in the HTML. All routes converge on this file through the same code. state.json is the deduplicated update store, not an agent editing surface. Keep evidence/, rows.csv, status.json, manifest.json for local provenance and integrity. Normalized inputs are archived by content hash on import.

Data composition and calculations by section

Calculations are implemented in pallas_ads.dashboard_data and the bundled dashboard.js. Global date/account/media/currency filters apply before aggregation; sum currencies separately. Use summed numerators/denominators, never averages of row ratios.