# LiteLLM to CloudZero ETL Tool
Transform LiteLLM database data into CloudZero AnyCost CBF format for cost tracking and analysis.
## Features
- Extract usage data from LiteLLM PostgreSQL database
- Transform data into CloudZero Billing Format (CBF)
- Analysis mode with beautiful terminal output using Rich
- Multiple output options: CSV files or direct CloudZero API streaming
- Built with modern Python tools: uv, ruff, pytest, polars, httpx
## Installation
### From PyPI (Recommended)
```bash
# Install with uv (recommended)
uv add litellm-cz-etl
# Or install with pip
pip install litellm-cz-etl
```
### From Source
```bash
git clone <repository-url>
cd litellm-cz-etl
uv sync
```
## Configuration
ll2cz supports configuration files to avoid repeating common settings. You can store your database connection, CloudZero API credentials, and other settings in `~/.ll2cz/config.yml`.
### Create Configuration File
```bash
# Create an example configuration file
ll2cz config example
# Check current configuration status
ll2cz config status
```
This creates `~/.ll2cz/config.yml` with the following structure:
```yaml
database_url: postgresql://user:password@host:5432/litellm_db
cz_api_key: your-cloudzero-api-key
cz_connection_id: your-connection-id
```
### Configuration Priority
CLI arguments always take priority over configuration file values:
1. **CLI arguments** (highest priority)
2. **Configuration file** (`~/.ll2cz/config.yml`)
3. **Default values** (lowest priority)
### CLI Commands
```bash
# Show version
ll2cz --version
# Show help
ll2cz --help
# Configuration management
ll2cz config example # Create example config file
ll2cz config status # Show current config status
ll2cz config edit # Interactively edit configuration
```
## Usage
### Transform Mode
Transform LiteLLM data to CloudZero CBF format:
```bash
# Display data on screen (formatted table)
ll2cz transform --input "postgresql://user:pass@host:5432/litellm_db" --screen
# Export to CSV file
ll2cz transform --input "postgresql://user:pass@host:5432/litellm_db" --output data.csv
# Limit records for screen display
ll2cz transform --screen --limit 25
```
### Transmit Mode
Send data directly to CloudZero AnyCost API:
```bash
# Send today's data
ll2cz transmit day
# Send specific day's data (DD-MM-YYYY format)
ll2cz transmit day 15-01-2024
# Send current month's data
ll2cz transmit month
# Send specific month's data (MM-YYYY format)
ll2cz transmit month 01-2024
# Send all available data (batched by day)
ll2cz transmit all
# Test mode - show payloads without sending (5 records only)
ll2cz transmit day --test
# Use append mode (sum operation instead of replace_hourly)
ll2cz transmit day --append
# Specify timezone for date handling
ll2cz transmit day --timezone "US/Eastern"
# Limit number of records to process
ll2cz transmit month --limit 1000
```
### Analysis Mode
Analyze your LiteLLM database data:
```bash
# General data analysis
ll2cz analyze data --limit 10000
# Show raw table data
ll2cz analyze data --show-raw --table all
# Show specific table only
ll2cz analyze data --show-raw --table user
# CZRN (CloudZero Resource Name) analysis
ll2cz analyze czrn --limit 10000
# Spend analysis
ll2cz analyze spend --limit 10000
# Database schema analysis
ll2cz analyze schema --output schema_docs.md
# Force refresh cache
ll2cz analyze data --force-refresh
# Save analysis to JSON
ll2cz analyze data --json analysis.json
```
### Cache Management
Manage local data cache for offline operation:
```bash
# Check cache status (local only)
ll2cz cache status
# Check cache status with remote server verification
ll2cz cache status --remote-check
# Clear local cache
ll2cz cache clear
# Force refresh cache from server
ll2cz cache refresh
```
## Data Transformation
The tool transforms LiteLLM usage logs into CloudZero's CBF format with the following mappings:
- `spend` → `cost`
- `total_tokens` → `usage_quantity`
- `model`, `user_id`, `call_type` → `dimensions`
- `metadata` fields → additional `dimensions`
- Duration calculated from `startTime` and `endTime`
## Technology Stack
This project follows modern Python best practices:
- **Python 3.12** - Latest Python version
- **uv** - Fast Python package manager
- **Polars** - High-performance DataFrames (instead of pandas)
- **httpx** - Modern HTTP client (instead of requests)
- **Rich** - Beautiful terminal output and formatting
- **Typer** - Modern CLI framework with rich help formatting
- **PyYAML** - YAML configuration file support
- **Pathlib** - Modern filesystem path operations
- **pytest** - Testing framework
- **ruff** - Fast Python linter and formatter
## Development
```bash
# Setup development environment
uv sync --dev
# Run tests
uv run pytest
# Run linting
uv run ruff check src/ tests/
# Fix linting issues
uv run ruff check --fix src/ tests/
# Build package
uv build
```
## Requirements
- Python ≥ 3.12
- PostgreSQL database with LiteLLM data
- CloudZero API key and connection ID (for streaming mode)
## License
Apache 2.0 - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "ll2cz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "litellm, cloudzero, etl, cost-management, billing",
"author": "Erik Peterson",
"author_email": "Erik Peterson <erik@cloudzero.com>",
"download_url": "https://files.pythonhosted.org/packages/81/29/3b1ccc4fe1b002ffc2426144d0a80277d3f3cc4f8fed9160ef2aafe938e8/ll2cz-0.3.0.tar.gz",
"platform": null,
"description": "# LiteLLM to CloudZero ETL Tool\n\nTransform LiteLLM database data into CloudZero AnyCost CBF format for cost tracking and analysis.\n\n## Features\n\n- Extract usage data from LiteLLM PostgreSQL database\n- Transform data into CloudZero Billing Format (CBF)\n- Analysis mode with beautiful terminal output using Rich\n- Multiple output options: CSV files or direct CloudZero API streaming\n- Built with modern Python tools: uv, ruff, pytest, polars, httpx\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install with uv (recommended)\nuv add litellm-cz-etl\n\n# Or install with pip\npip install litellm-cz-etl\n```\n\n### From Source\n\n```bash\ngit clone <repository-url>\ncd litellm-cz-etl\nuv sync\n```\n\n## Configuration\n\nll2cz supports configuration files to avoid repeating common settings. You can store your database connection, CloudZero API credentials, and other settings in `~/.ll2cz/config.yml`.\n\n### Create Configuration File\n\n```bash\n# Create an example configuration file\nll2cz config example\n\n# Check current configuration status\nll2cz config status\n```\n\nThis creates `~/.ll2cz/config.yml` with the following structure:\n\n```yaml\ndatabase_url: postgresql://user:password@host:5432/litellm_db\ncz_api_key: your-cloudzero-api-key\ncz_connection_id: your-connection-id\n```\n\n### Configuration Priority\n\nCLI arguments always take priority over configuration file values:\n\n1. **CLI arguments** (highest priority)\n2. **Configuration file** (`~/.ll2cz/config.yml`)\n3. **Default values** (lowest priority)\n\n### CLI Commands\n\n```bash\n# Show version\nll2cz --version\n\n# Show help\nll2cz --help\n\n# Configuration management\nll2cz config example # Create example config file\nll2cz config status # Show current config status\nll2cz config edit # Interactively edit configuration\n```\n\n## Usage\n\n### Transform Mode\n\nTransform LiteLLM data to CloudZero CBF format:\n\n```bash\n# Display data on screen (formatted table)\nll2cz transform --input \"postgresql://user:pass@host:5432/litellm_db\" --screen\n\n# Export to CSV file\nll2cz transform --input \"postgresql://user:pass@host:5432/litellm_db\" --output data.csv\n\n# Limit records for screen display\nll2cz transform --screen --limit 25\n```\n\n### Transmit Mode\n\nSend data directly to CloudZero AnyCost API:\n\n```bash\n# Send today's data\nll2cz transmit day\n\n# Send specific day's data (DD-MM-YYYY format)\nll2cz transmit day 15-01-2024\n\n# Send current month's data\nll2cz transmit month\n\n# Send specific month's data (MM-YYYY format)\nll2cz transmit month 01-2024\n\n# Send all available data (batched by day)\nll2cz transmit all\n\n# Test mode - show payloads without sending (5 records only)\nll2cz transmit day --test\n\n# Use append mode (sum operation instead of replace_hourly)\nll2cz transmit day --append\n\n# Specify timezone for date handling\nll2cz transmit day --timezone \"US/Eastern\"\n\n# Limit number of records to process\nll2cz transmit month --limit 1000\n```\n\n### Analysis Mode\n\nAnalyze your LiteLLM database data:\n\n```bash\n# General data analysis\nll2cz analyze data --limit 10000\n\n# Show raw table data\nll2cz analyze data --show-raw --table all\n\n# Show specific table only\nll2cz analyze data --show-raw --table user\n\n# CZRN (CloudZero Resource Name) analysis\nll2cz analyze czrn --limit 10000\n\n# Spend analysis\nll2cz analyze spend --limit 10000\n\n# Database schema analysis\nll2cz analyze schema --output schema_docs.md\n\n# Force refresh cache\nll2cz analyze data --force-refresh\n\n# Save analysis to JSON\nll2cz analyze data --json analysis.json\n```\n\n### Cache Management\n\nManage local data cache for offline operation:\n\n```bash\n# Check cache status (local only)\nll2cz cache status\n\n# Check cache status with remote server verification\nll2cz cache status --remote-check\n\n# Clear local cache\nll2cz cache clear\n\n# Force refresh cache from server\nll2cz cache refresh\n```\n\n## Data Transformation\n\nThe tool transforms LiteLLM usage logs into CloudZero's CBF format with the following mappings:\n\n- `spend` \u2192 `cost`\n- `total_tokens` \u2192 `usage_quantity`\n- `model`, `user_id`, `call_type` \u2192 `dimensions`\n- `metadata` fields \u2192 additional `dimensions`\n- Duration calculated from `startTime` and `endTime`\n\n## Technology Stack\n\nThis project follows modern Python best practices:\n\n- **Python 3.12** - Latest Python version\n- **uv** - Fast Python package manager\n- **Polars** - High-performance DataFrames (instead of pandas)\n- **httpx** - Modern HTTP client (instead of requests)\n- **Rich** - Beautiful terminal output and formatting\n- **Typer** - Modern CLI framework with rich help formatting\n- **PyYAML** - YAML configuration file support\n- **Pathlib** - Modern filesystem path operations\n- **pytest** - Testing framework\n- **ruff** - Fast Python linter and formatter\n\n## Development\n\n```bash\n# Setup development environment\nuv sync --dev\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check src/ tests/\n\n# Fix linting issues\nuv run ruff check --fix src/ tests/\n\n# Build package\nuv build\n```\n\n## Requirements\n\n- Python \u2265 3.12\n- PostgreSQL database with LiteLLM data\n- CloudZero API key and connection ID (for streaming mode)\n\n## License\n\nApache 2.0 - see LICENSE file for details.",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Transform LiteLLM database data into CloudZero AnyCost CBF format",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/Cloudzero/cloudzero-litellm-etl/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Cloudzero/cloudzero-litellm-etl/blob/main/README.md",
"Homepage": "https://github.com/Cloudzero/cloudzero-litellm-etl",
"Issues": "https://github.com/Cloudzero/cloudzero-litellm-etl/issues",
"Repository": "https://github.com/Cloudzero/cloudzero-litellm-etl.git"
},
"split_keywords": [
"litellm",
" cloudzero",
" etl",
" cost-management",
" billing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf216f739a83d6d629930fbd3c81a83b22832ee7cc0ce87769794591e94236c2",
"md5": "241a3224863f0f8624d1978948b62031",
"sha256": "221f484eb6039f85c24928938d53dfcf529224170ce646a07ed2154e1c6efab2"
},
"downloads": -1,
"filename": "ll2cz-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "241a3224863f0f8624d1978948b62031",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 59446,
"upload_time": "2025-07-24T22:25:09",
"upload_time_iso_8601": "2025-07-24T22:25:09.164614Z",
"url": "https://files.pythonhosted.org/packages/cf/21/6f739a83d6d629930fbd3c81a83b22832ee7cc0ce87769794591e94236c2/ll2cz-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "81293b1ccc4fe1b002ffc2426144d0a80277d3f3cc4f8fed9160ef2aafe938e8",
"md5": "84d5abeb8dc16c556be735ca61bd0171",
"sha256": "e2649b1f096af32bdc698cdbf924fa1d7db0e5962fcad7cdaddcdf025eb7f0dd"
},
"downloads": -1,
"filename": "ll2cz-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "84d5abeb8dc16c556be735ca61bd0171",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 50174,
"upload_time": "2025-07-24T22:25:10",
"upload_time_iso_8601": "2025-07-24T22:25:10.690307Z",
"url": "https://files.pythonhosted.org/packages/81/29/3b1ccc4fe1b002ffc2426144d0a80277d3f3cc4f8fed9160ef2aafe938e8/ll2cz-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 22:25:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Cloudzero",
"github_project": "cloudzero-litellm-etl",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ll2cz"
}
JSON
