skill-aws-bedrock-cost-tool

What this skill does

# When to use
- Analyze AWS Bedrock model costs and spending patterns
- Generate cost reports with tables and visualizations
- Track token usage and identify cost optimization opportunities

# AWS Bedrock Cost Tool Skill

## Purpose

A professional CLI tool for analyzing AWS Bedrock model costs with comprehensive reporting, visualization, and programmatic access. Provides detailed insights into model usage, token consumption, and spending trends across all Bedrock models.

## When to Use This Skill

**Use this skill when:**
- Analyzing AWS Bedrock costs for budget tracking
- Generating cost reports with tables or charts
- Investigating spending patterns and cost spikes
- Breaking down costs by model, usage type, or region
- Exporting cost data for further analysis
- Integrating cost analysis into automation scripts

**Do NOT use this skill for:**
- Real-time cost monitoring (data has 24hr delay)
- Forecasting future costs (historical analysis only)
- Non-Bedrock AWS service costs
- Modifying AWS resources or settings

## CLI Tool: aws-bedrock-cost-tool

A Python CLI tool that queries AWS Cost Explorer API to analyze Bedrock model costs with flexible reporting options.

### Installation

```bash
# Via pip from GitHub
pip install git+https://github.com/dnvriend/aws-bedrock-cost-tool.git

# Or clone and install with uv
git clone https://github.com/dnvriend/aws-bedrock-cost-tool.git
cd aws-bedrock-cost-tool
uv tool install .
```

### Prerequisites

- Python 3.14+
- AWS credentials configured
- Cost Explorer enabled in AWS account
- IAM permission: `ce:GetCostAndUsage`
- Optional: gnuplot for ASCII plots (`brew install gnuplot`)

### Quick Start

```bash
# Default JSON output (last 30 days)
aws-bedrock-cost-tool

# Quick summary
aws-bedrock-cost-tool --summary-only

# Visual table
aws-bedrock-cost-tool --table

# Complete visual report
aws-bedrock-cost-tool --all-visual
```

## Progressive Disclosure

<details>
<summary><strong>📊 Output Formats (Click to expand)</strong></summary>

### JSON Output (Default)

**Usage:**
```bash
aws-bedrock-cost-tool [--period DURATION]
```

**Output Structure:**
```json
{
  "period_start": "2025-10-21",
  "period_end": "2025-11-20",
  "total_cost": 556.80,
  "has_estimated": true,
  "models": [
    {
      "model_name": "Claude Sonnet 4.5",
      "total_cost": 556.80,
      "estimated": true,
      "usage_breakdown": [
        {
          "usage_type": "CacheReadInputTokenCount",
          "cost": 248.82,
          "quantity": 829.406,
          "estimated": true
        }
      ]
    }
  ],
  "daily_costs": [...]
}
```

**Key Fields:**
- `quantity`: Tokens in millions (M)
- `estimated`: True if costs not finalized
- `usage_breakdown`: Input/output/cache token costs
- `regional_breakdown`: Costs by AWS region (full detail only)

**Pipeline Example:**
```bash
# Filter Sonnet costs
aws-bedrock-cost-tool | jq '.models[] | select(.model_name | contains("Sonnet"))'

# Sum all input token costs
aws-bedrock-cost-tool | jq '[.models[].usage_breakdown[] | select(.usage_type | contains("InputToken")) | .cost] | add'

# Export to CSV
aws-bedrock-cost-tool | jq -r '.models[] | [.model_name, .total_cost] | @csv'
```

---

### Table Output

**Usage:**
```bash
aws-bedrock-cost-tool --table [--detail basic|standard|full]
```

**Detail Levels:**

**Basic**: Model totals only
```
╭─────────────────────┬────────────╮
│ Model               │ Total Cost │
├─────────────────────┼────────────┤
│ Claude Sonnet 4.5   │ ~$556.80   │
│ Claude Haiku 3.5    │ ~$12.34    │
╰─────────────────────┴────────────╯
```

**Standard**: Model + usage type breakdown (default)
```
### Claude Sonnet 4.5 (Total: ~$556.80)
╭───────────────────────────┬──────────┬────────────╮
│ Usage Type                │ Cost     │ Tokens (M) │
├───────────────────────────┼──────────┼────────────┤
│ CacheReadInputTokenCount  │ ~$248.82 │ 829.406    │
│ CacheWriteInputTokenCount │ ~$220.85 │ 58.893     │
│ InputTokenCount           │ ~$3.71   │ 1.236      │
│ OutputTokenCount          │ ~$82.25  │ 5.483      │
╰───────────────────────────┴──────────┴────────────╯
```

**Full**: Model + usage types + regional breakdown
```
### Claude Sonnet 4.5 (Total: ~$556.80)

Usage Breakdown:
[Same as standard]

Regional Breakdown:
╭────────┬──────────╮
│ Region │ Cost     │
├────────┼──────────┤
│ USE1   │ $345.67  │
│ EUC1   │ $211.13  │
╰────────┴──────────╯
```

**Examples:**
```bash
# Standard table (recommended)
aws-bedrock-cost-tool --table

# Basic overview
aws-bedrock-cost-tool --table --detail basic

# Full detail with regions
aws-bedrock-cost-tool --table --detail full --period 90d
```

---

### Summary Output

**Usage:**
```bash
aws-bedrock-cost-tool --summary-only
```

**Output:**
```
AWS Bedrock Cost Summary (2025-10-21 to 2025-11-20)
Total Cost: ~$556.80

Top 3 Models:
1. Claude Sonnet 4.5: ~$556.80
2. Claude Haiku 3.5: ~$12.34
3. Claude Opus 4: ~$5.67
```

**When to Use:**
- Quick cost checks
- Daily standup reports
- Budget alerts
- Scripted notifications

---

### Visual Plots

**Time Series Plot:**
```bash
aws-bedrock-cost-tool --plot-time
```

Shows daily spending trends as ASCII line chart.

**Model Bar Chart:**
```bash
aws-bedrock-cost-tool --plot-models
```

Shows cost comparison by model as horizontal bar chart.

**All Visualizations:**
```bash
aws-bedrock-cost-tool --all-visual
```

Displays: table + time series + bar chart.

**Requirements:**
- gnuplot installed: `brew install gnuplot`
- Terminal with Unicode support

</details>

<details>
<summary><strong>⚙️ Configuration & Options (Click to expand)</strong></summary>

### Time Periods

**Syntax:**
- `Nd`: N days (e.g., `7d`, `30d`, `90d`)
- `Nw`: N weeks (e.g., `1w`, `2w`, `4w`)
- `Nm`: N months (e.g., `1m`, `3m`, `6m`)

**Examples:**
```bash
# Last 7 days
aws-bedrock-cost-tool --period 7d

# Last 2 weeks
aws-bedrock-cost-tool --period 2w

# Last 3 months
aws-bedrock-cost-tool --period 3m

# Maximum: 365 days
aws-bedrock-cost-tool --period 365d
```

**Limits:**
- Minimum: 1 day
- Maximum: 365 days (enforced)

---

### AWS Profile Selection

**Environment Variable:**
```bash
export AWS_PROFILE=my-profile
aws-bedrock-cost-tool
```

**Command Line Flag:**
```bash
aws-bedrock-cost-tool --profile my-profile
```

**Precedence:**
1. `--profile` flag (highest)
2. `AWS_PROFILE` environment variable
3. Default AWS credentials

**Example:**
```bash
# Production account
aws-bedrock-cost-tool --profile prod --period 30d --table

# Development account
aws-bedrock-cost-tool --profile dev --summary-only
```

---

### Verbosity Levels

**Levels:**
- No flag: WARNING only (quiet mode)
- `-v`: INFO level (progress messages)
- `-vv`: DEBUG level (detailed logging)
- `-vvv`: TRACE level (includes boto3/urllib3 logs)

**Examples:**
```bash
# Quiet (default)
aws-bedrock-cost-tool

# Show progress
aws-bedrock-cost-tool -v

# Debugging
aws-bedrock-cost-tool -vv

# Full trace with AWS API calls
aws-bedrock-cost-tool -vvv
```

**Output:**
- Logs always go to stderr
- Data (JSON) always goes to stdout
- Allows safe piping: `aws-bedrock-cost-tool -v | jq`

---

### Detail Levels

**Basic**: Model names and total costs only
```bash
aws-bedrock-cost-tool --detail basic
```

**Standard** (default): Models + usage type breakdown
```bash
aws-bedrock-cost-tool --detail standard
```

**Full**: Models + usage types + regional costs
```bash
aws-bedrock-cost-tool --detail full
```

**Applies to:**
- JSON output
- Table output
- Summary calculations

**Does NOT apply to:**
- Plots (always use aggregated data)

</details>

<details>
<summary><strong>💻 Programmatic Usage (Click to expand)</strong></summary>

### Python Library Import

The tool can be imported as a Python library for custom integrations.

**Installation:**
```bash
pip install git+https://github.com/dnvriend/aws-bedrock-cost-tool.git
```

**Basic Usage:**
```python
from aws_bedrock_cost_tool import (
    create_cost_explorer_client,
    query_bedrock_costs,
    analyze_cost_data,
    parse_