CSV to leadership-ready KPIs
End-to-end CSV KPI workflow I can operate and extend: infer or manual column mapping, pandas-backed validation, Plotly trend and breakdown views, optional previous-period deltas, and exportable snapshot bundles for handoff. Scope stays honest—single-page Streamlit, not a BI platform.
Static portfolio wrapper; open the Streamlit host to exercise uploads, mapping presets, and exports.
Overview
Problem. Sales and marketing teams often live in spreadsheets and CSV exports. Leadership still needs a repeatable KPI read—totals, a trend, and a simple dimensional cut—without standing up a full BI program for every iteration.
Approach. A single Streamlit surface ingests a CSV (or built-in demos), normalizes dates and metrics with pandas, validates shape coverage, then renders KPI cards, a trend series, and an optional breakdown chart in Plotly. A short rule-based “what changed?” summary compares the selected range to the prior window when enabled.
Scope. The app optimizes for clarity and guardrails on small-to-medium files, not for enterprise semantic layers or scheduled warehouse pushes.
Workflow
Path from file to dashboard:
-
1
Choose data
Pick a built-in sales or marketing sample, or upload a CSV within the host’s size limits.
-
2
Map columns
Auto-detect when headers are clean; fall back to manual selection or JSON presets when the same export repeats.
-
3
Validate and filter
Parsing ratios and numeric coercion are checked before charts render; date filters scope the window shown.
-
4
Review and export
Scan KPIs and charts, then optionally export a snapshot folder and ZIP for email or slides.
Features
KPI cards
Profile-aware metrics (sales vs marketing) with optional deltas against the previous period.
Trend and breakdown
Plotly line trend plus categorical breakdown when a dimension column is available.
Column mapping and presets
Manual overrides and JSON presets reduce rework on recurring export layouts.
Validation layer
Explicit checks on dates and numerics before surfacing misleading charts.
Snapshot export
Bundle metadata, extracts, insight text, and chart images when enabled—useful for async reviews.
Optional insight wording
Rule-based narrative by default; optional OpenAI uses aggregated KPIs only when configured server-side.
Tech stack
- App shell: Streamlit (single-page orchestration)
- Data layer: pandas for typing, grouping, and validation helpers
- Charts: Plotly figures with a light template for readability
- Runtime: Python 3.11; container entry runs Streamlit on port 8501
- Optional: OpenAI client for enhanced copy—not a mandatory dependency for core charts
Deployment / live app
The canonical interactive deployment is the Streamlit host at kpi.vahdetkaratas.com. This static shell only frames the project; it does not proxy API traffic.
Source and run instructions: GitHub repository (streamlit run src/app.py, Docker optional).
Limitations
- Not a substitute for governed BI catalogs, row-level security, or scheduled enterprise ETL.
- Performance and upload caps target practical demos—not billion-row warehouses.
- Refreshing data requires a new load or interaction in the Streamlit session; there is no push pipeline here.
Why this project
It demonstrates how far you can get with a tight pandas + Streamlit loop: honest validation, charts people actually read, and exports stakeholders can file away—without overselling depth the codebase does not provide.