Metadata-Version: 2.4
Name: cz-billing-generator
Version: 0.2.4
Summary: CLI tool for generating and uploading synthetic billing data to CloudZero
Author-email: CloudZero <support@cloudzero.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/cloudzero/czbillgen
Keywords: CloudZero,czbg,billing,generator,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: polars>=0.20.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=14.0.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: boto3>=1.26.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: psutil>=6.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: python-dateutil>=2.8.0

# CloudZero Billing Generator (CZBG)

A CLI tool for generating and uploading synthetic cloud billing data to CloudZero organizations. Supports multi-cloud scenarios, realistic usage patterns, and comprehensive pipeline processing from basic cost generation through Kubernetes allocation, metadata enrichment, and discount calculations.

## 🚀 Quick Start

**For CloudZero Internal Users:**

```bash
# 1. Install CZBG
pipx install cz-billing-generator

# 2. Initialize workspace  
czbg init

# 3. Most common workflow: Upload existing dataset
czbg list-datasets                           # Browse available datasets
czbg upload --config ~/.czbg/configs/upload/upload.yaml   # Upload to organizations
```

**Need help?** Start with our step-by-step guides:
- **New to CZBG?** → [Initializing CZBG](docs/workflows/01-initializing-czbg.md)
- **Uploading data?** → [Uploading an Existing Dataset](docs/workflows/02-uploading-existing-dataset.md)  
- **Creating custom data?** → [Generating a Dataset](docs/workflows/03-generating-dataset.md)

## Installation & Setup

**Prerequisites**: Python 3.10+, AWS SSO access, CloudZero API access

```bash
# Install CZBG
pipx install cz-billing-generator

# Initialize workspace (creates ~/.czbg/ with templates)
czbg init

# Follow setup guide for credentials and configuration
```

**Complete setup instructions**: [Initializing CZBG](docs/workflows/01-initializing-czbg.md)

## How It Works

CZBG uses a **6-stage pipeline** to transform basic billing data into comprehensive synthetic datasets:

```
Generate → K8s → Metadata → Usage → Discount → Upload
```

- **Generate**: Creates realistic cloud billing data from configurable templates
- **K8s**: Adds Kubernetes resource allocation and workload mapping  
- **Metadata**: Enriches data with tags, regions, and resource metadata
- **Usage**: Transforms costs into usage metrics with realistic rates
- **Discount**: Applies cloud savings plans and discount calculations
- **Upload**: Streams processed data to CloudZero organizations

**Data Storage**: All stages store results in organized S3 structure for easy access and pipeline progression.

## Common Commands

```bash
# Setup and data exploration
czbg init                           # Initialize workspace
czbg list-datasets                  # Browse available datasets
czbg data status overview           # Check reference data

# Generate custom datasets  
czbg generate run --config <file>   # Create new dataset
czbg k8s run --config <file>        # Add Kubernetes allocation
czbg metadata run --config <file>   # Add metadata enrichment
czbg usage run --config <file>      # Add usage calculations
czbg discount run --config <file>   # Add discount calculations

# Upload to CloudZero
czbg upload --config <file>         # Upload dataset to organizations
```

**Complete command reference**: [Command Documentation](docs/reference/commands.md)

## Documentation

**📖 Complete Documentation Hub**: [docs/README.md](docs/README.md)

### **Quick Links by Role:**

**🚀 New Users**  
- [Initializing CZBG](docs/workflows/01-initializing-czbg.md) - Complete setup guide

**📊 Data Consumers**  
- [Uploading an Existing Dataset](docs/workflows/02-uploading-existing-dataset.md) - Most common workflow

**🔧 Data Creators**  
- [Generating a Dataset](docs/workflows/03-generating-dataset.md) - Custom data creation

**👔 Business Stakeholders**  
- [Executive Summary](docs/EXECUTIVE_SUMMARY.md) - Strategic value and business case

**💻 Developers**  
- [Development Guide](docs/development/README.md) - Contributing and architecture

### **Key References:**
- [Command Reference](docs/reference/commands.md) - Complete CLI documentation
- [Configuration Reference](docs/reference/configuration.md) - YAML config formats  
- [Troubleshooting](docs/reference/troubleshooting.md) - Common issues and solutions

## Features

- **🌐 Multi-Cloud**: AWS, Azure, GCP, and 10+ SaaS providers
- **📊 Realistic Patterns**: Behavioral variance, anomalies, and usage trends
- **🔧 Pipeline Processing**: 6-stage data enrichment from basic costs to upload-ready
- **⚙️ Flexible Configuration**: From templates to precise custom scenarios
- **📦 Enterprise Ready**: S3 storage, AWS SSO, CloudZero API integration

## Support

- **📚 Documentation**: [Complete docs hub](docs/README.md)
- **🐛 Issues**: [GitHub Issues](https://github.com/cloudzero/cz-billing-generator/issues)  
- **💬 Internal**: CloudZero Slack #billing-generator channel
