# ll2cz - 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 or SQLite database
- Transform data into CloudZero Billing Format (CBF)
- **Cost comparison analysis** between SpendLogs and user tables (v0.4.0+)
- **Dual data source support** with `--source` option: transaction-level SpendLogs or daily aggregated user tables
- **SQLite support** for testing and offline analysis (v0.6.1+)
- 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 ll2cz
# Or install with pip
pip install ll2cz
```
### From Source
```bash
git clone https://github.com/Cloudzero/cloudzero-litellm-toolkit.git
cd cloudzero-litellm-toolkit
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) - PostgreSQL
ll2cz transform --input "postgresql://user:pass@host:5432/litellm_db" --screen
# Display data on screen - SQLite
ll2cz transform --input "sqlite://path/to/litellm.sqlite" --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
# Refresh cache from server (use cache commands)
ll2cz cache 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
```
## Testing with SQLite
For testing and development, you can use SQLite instead of PostgreSQL:
```bash
# Create a test SQLite database with sample data
python scripts/create_test_sqlite.py
# Use the test database
ll2cz transmit all --test --input "sqlite://test.sqlite"
```
The test database includes:
- Sample organizations, teams, and users
- API keys with realistic naming
- 30 days of usage data
- Multiple model providers (OpenAI, Anthropic, etc.)
## Requirements
- Python ≥ 3.12
- PostgreSQL or SQLite 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.9",
"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/de/3c/140199e9479c1639a45796ebdc907e80e47190cb4866b71886f4743b4e2f/ll2cz-0.6.2.tar.gz",
"platform": null,
"description": "# ll2cz - 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 or SQLite database\n- Transform data into CloudZero Billing Format (CBF)\n- **Cost comparison analysis** between SpendLogs and user tables (v0.4.0+)\n- **Dual data source support** with `--source` option: transaction-level SpendLogs or daily aggregated user tables\n- **SQLite support** for testing and offline analysis (v0.6.1+)\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 ll2cz\n\n# Or install with pip\npip install ll2cz\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/Cloudzero/cloudzero-litellm-toolkit.git\ncd cloudzero-litellm-toolkit\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) - PostgreSQL\nll2cz transform --input \"postgresql://user:pass@host:5432/litellm_db\" --screen\n\n# Display data on screen - SQLite\nll2cz transform --input \"sqlite://path/to/litellm.sqlite\" --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# Refresh cache from server (use cache commands)\nll2cz cache 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## Testing with SQLite\n\nFor testing and development, you can use SQLite instead of PostgreSQL:\n\n```bash\n# Create a test SQLite database with sample data\npython scripts/create_test_sqlite.py\n\n# Use the test database\nll2cz transmit all --test --input \"sqlite://test.sqlite\"\n```\n\nThe test database includes:\n- Sample organizations, teams, and users\n- API keys with realistic naming\n- 30 days of usage data\n- Multiple model providers (OpenAI, Anthropic, etc.)\n\n## Requirements\n\n- Python \u2265 3.12\n- PostgreSQL or SQLite 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.6.2",
"project_urls": {
"Changelog": "https://github.com/Cloudzero/cloudzero-litellm-toolkit/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Cloudzero/cloudzero-litellm-toolkit/blob/main/README.md",
"Homepage": "https://github.com/Cloudzero/cloudzero-litellm-toolkit",
"Issues": "https://github.com/Cloudzero/cloudzero-litellm-toolkit/issues",
"Repository": "https://github.com/Cloudzero/cloudzero-litellm-toolkit.git"
},
"split_keywords": [
"litellm",
" cloudzero",
" etl",
" cost-management",
" billing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "341332a48d3d1a792d3c879d4748ceef9333f83cab8ad41b8b719c79b5780a28",
"md5": "5ea853e3bdd9a3c5e416ced95285ff24",
"sha256": "fd8f8d030c02533600d1f627a9938dc8a5a917060542d42da58cb3aac7245fab"
},
"downloads": -1,
"filename": "ll2cz-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ea853e3bdd9a3c5e416ced95285ff24",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 90032,
"upload_time": "2025-07-29T02:28:34",
"upload_time_iso_8601": "2025-07-29T02:28:34.719656Z",
"url": "https://files.pythonhosted.org/packages/34/13/32a48d3d1a792d3c879d4748ceef9333f83cab8ad41b8b719c79b5780a28/ll2cz-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "de3c140199e9479c1639a45796ebdc907e80e47190cb4866b71886f4743b4e2f",
"md5": "42121617f94a70bc18cee1e1701f3ea9",
"sha256": "9af8c022b6690dc7f79037e8350e90d11e96c1570117b23e5d1a779c3ce2ba64"
},
"downloads": -1,
"filename": "ll2cz-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "42121617f94a70bc18cee1e1701f3ea9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 73527,
"upload_time": "2025-07-29T02:28:36",
"upload_time_iso_8601": "2025-07-29T02:28:36.027162Z",
"url": "https://files.pythonhosted.org/packages/de/3c/140199e9479c1639a45796ebdc907e80e47190cb4866b71886f4743b4e2f/ll2cz-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 02:28:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Cloudzero",
"github_project": "cloudzero-litellm-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ll2cz"
}
JSON
