-
Notifications
You must be signed in to change notification settings - Fork 1
CSV Import Reference
File: core/csv_import.py
The CSV import is a last-mile parser, not an ETL pipeline. Drop in a platform's standard export; the parser handles encoding, delimiter, totals-row filtering, and KPI composition.
- Sniffs encoding — UTF-8 → UTF-8-BOM → Latin-1.
-
Sniffs delimiter —
,→;→\t. -
Filters totals rows — Google's
Total --, Meta's summary rows, etc. - Composes canonical KPIs from raw columns with a documented rationale per platform.
-
Returns an audit trail —
CSVParseResultcarries per- component values, the operator used, any fallback taken, and any warning. Nothing is silently merged.
Each canonical KPI declares one of:
| Operator | Meaning |
|---|---|
sum |
Sum of components (e.g. Facebook engagement = reactions + comments + shares + saves) |
first |
First non-null component (used for unambiguous single-source KPIs) |
max |
Max of components (overlapping metrics) |
mean |
Average of components (rare; one rate KPI) |
When the broken-out columns aren't in the export, the parser falls back to the platform's bundled metric (e.g. Meta's "Post engagement"). When this happens:
- The result carries a prominent warning about double-count risk
- The audit trail records which fallback was taken
An older Meta export with only an Engagement Rate column (no
individual count breakouts) is still parsed: engagement count is
derived as rate × awareness_count. A warning surfaces so the
user can replace with proper breakouts if they re-export.
The "Customise composition" panel lets a marketer re-weight components per platform — count saves 3× because they're high-intent, reactions 0.5×, exclude follower-gain entirely, etc. Overrides apply per-platform per-session.
Every parsed CSV returns:
- Per-component raw values
- The operator applied
- The composed canonical value
- Any fallback or override
This shows up in the "Show parsing detail" expander in Step 3. The whole composition is reviewable; nothing is hidden in code.