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_at2025-07-18,active_users,11.0,count,2025-09-16T08:33:42.795407+00:002025-07-18,avg_order_value_dollars,103.8,dollars,2025-09-16T08:33:42.795407+00:002025-07-18,net_revenue_dollars,-1287.35,dollars,2025-09-16T08:33:42.795407+00:002025-07-18,new_users,11.0,count,2025-09-16T08:33:42.795407+00:002025-07-18,refunds_count,23.0,count,2025-09-16T08:33:42.795407+00:002025-07-18,repeat_users,0.0,count,2025-09-16T08:33:42.795407+00:002025-07-18,total_orders,40.0,count,2025-09-16T08:33:42.795407+00:002025-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