Python KPI job

A minimal KPI computation system that computes 8 key performance indicators from SQLite data.

🚀 Quick Start

# Install dependencies
make install

# Seed database with synthetic data
make seed

# Run KPI job
make run

📊 Computed KPIs

1. total_orders - Count of orders created on the date
2. total_revenue_dollars - Sum of paid/captured orders
3. avg_order_value_dollars - Average order value
4. refunds_count - Count of refunded/chargeback orders
5. new_users - Count of users who signed up on the date
6. active_users - Count of unique users with orders on the date
7. net_revenue_dollars - Total revenue minus refunds
8. repeat_users - Count of repeat users

💻 Usage

# Basic usage
python -m kpi_job.main --date 2025-07-18

# With options
python -m kpi_job.main --date 2025-07-18 --verbose --dry-run

# Using the installed CLI
kpi --date 2025-07-18 --verbose

📁 Project Structure

python-kpi/
├── kpi_job/
│   ├── __init__.py     # Package init
│   ├── main.py         # Main CLI
│   ├── models.py       # Data models
│   └── seed.py         # Data seeding
├── data/               # SQLite database
├── artifacts/          # Generated KPI CSV files
├── pyproject.toml      # Project configuration
├── Makefile           # Development commands
└── README.md          # This file

🔧 Development

# Install in development mode
make install

# Test installation
make test

# Clean up
make clean

📈 Sample Output

date,kpi_name,kpi_value,unit,computed_at
2025-07-18,active_users,11.0,count,2025-09-16T08:33:42.795407+00:00
2025-07-18,avg_order_value_dollars,103.8,dollars,2025-09-16T08:33:42.795407+00:00
2025-07-18,net_revenue_dollars,-1287.35,dollars,2025-09-16T08:33:42.795407+00:00
2025-07-18,new_users,11.0,count,2025-09-16T08:33:42.795407+00:00
2025-07-18,refunds_count,23.0,count,2025-09-16T08:33:42.795407+00:00
2025-07-18,repeat_users,0.0,count,2025-09-16T08:33:42.795407+00:00
2025-07-18,total_orders,40.0,count,2025-09-16T08:33:42.795407+00:00
2025-07-18,total_revenue_dollars,4151.94,dollars,2025-09-16T08:33:42.795407+00:00

✨ Features

• ✅ Click CLI - Easy command-line interface
• ✅ Pandas Processing - Efficient data manipulation
• ✅ SQLite Storage - Lightweight database
• ✅ CSV Output - Standard artifact format
• ✅ Dollar Calculations - Revenue in dollars
• ✅ Synthetic Data - Built-in test data generation

🎯 Use it for

• Prototyping KPI systems
• Learning data processing with Python
• Quick deployments where simplicity matters
• Proof of concepts and demos
• Educational purposes