aws-cost-calculator-cli 1.5.1__tar.gz

aws_cost_calculator_cli-1.5.1/COST_CALCULATION_METHODOLOGY.md

@@ -0,0 +1,130 @@
+# AWS Cost Calculation Methodology
+
+## Formula Overview
+
+The cost calculator computes a **daily rate** and **annual projection** for AWS spend across multiple accounts using a standardized methodology that matches the AWS Cost Explorer console.
+
+## What's Included
+
+### Operational Costs
+- **All AWS services** billed under `BILLING_ENTITY = "AWS"`
+- **Metric:** Net Amortized Cost
+- **Accounts:** Multiple linked AWS accounts
+- **Date Range:** 30-day rolling window, offset by 2 days from calculation date
+
+### Support Costs
+- **AWS Support fees** from the 1st of the month containing the end date
+- **Allocation:** 50% allocation (÷2)
+- **Distribution:** Divided by days in the support month (e.g., 31 for October)
+
+## What's Excluded
+
+1. **Tax** - Excluded via `RECORD_TYPE != "Tax"`
+2. **Marketplace Services** - Excluded via `BILLING_ENTITY = "AWS"` filter
+   - Third-party SaaS subscriptions
+   - Marketplace software licenses
+   - Non-AWS vendor services
+3. **Support** - Excluded from operational costs, calculated separately
+
+## Calculation Steps
+
+### Step 1: Date Range Calculation
+```
+Today = Calculation date (e.g., Nov 4, 2025)
+Offset = 2 days (default)
+Window = 30 days (default)
+
+End Date = Today - Offset = Nov 2, 2025
+Start Date = End Date - Window = Oct 3, 2025
+
+Analysis Period: Oct 3 - Nov 2, 2025 (30 days)
+```
+
+### Step 2: Operational Cost Calculation
+```
+Total Operational Cost = Sum of daily Net Amortized Costs
+  WHERE:
+    - Linked Account IN [configured accounts]
+    - Billing Entity = "AWS"
+    - Record Type NOT IN ["Tax", "Support"]
+    - Date BETWEEN Start Date AND End Date
+
+Days in Support Month = Days in month containing End Date (e.g., 31 for October)
+
+Daily Operational = Total Operational Cost ÷ Days in Support Month
+```
+
+**Note:** We divide by the days in the support month (31 for October), NOT the window size (30 days). This matches the AWS console calculation.
+
+### Step 3: Support Cost Calculation
+```
+Support Date = 1st of month containing End Date (e.g., Nov 1 for Oct 3-Nov 2 period)
+
+Support Cost = Net Amortized Cost on Support Date
+  WHERE:
+    - Linked Account IN [configured accounts]
+    - Record Type = "Support"
+    - Date = Support Date
+
+Support Per Day = (Support Cost ÷ 2) ÷ Days in Support Month
+```
+
+**Rationale:** Support is charged on the 1st of each month for the previous month's usage. For an October analysis, we use the November 1st support charge (which reflects October usage based on September costs).
+
+### Step 4: Final Calculation
+```
+Daily Rate = Daily Operational + Support Per Day
+
+Annual Projection = Daily Rate × 365
+```
+
+## Example Calculation
+
+**Analysis Period:** Oct 3 - Nov 2, 2025
+
+```
+Total Operational Cost:     $450,000.00
+Days in October:            31
+Daily Operational:          $450,000.00 ÷ 31 = $14,516.13
+
+Support (Nov 1):            $15,000.00
+Support Per Day:            ($15,000.00 ÷ 2) ÷ 31 = $241.94
+
+Daily Rate:                 $14,516.13 + $241.94 = $14,758.07
+Annual Projection:          $14,758.07 × 365 = $5,386,695
+```
+
+## Key Principles
+
+1. **Consistency:** Always use the same filters and methodology
+2. **Accuracy:** Match AWS Cost Explorer console calculations exactly
+3. **Transparency:** All costs are Net Amortized (includes RI/SP discounts)
+4. **Allocation:** Support can be split between entities (default 50/50)
+5. **Timeliness:** Use T-2 offset to ensure data completeness
+
+## Validation
+
+To validate the calculation:
+1. Open AWS Cost Explorer console
+2. Set date range to the analysis period
+3. Filter by your linked accounts
+4. Set Billing Entity = AWS
+5. Exclude Tax and Support
+6. Compare total: Should match "Total Operational Cost"
+7. Daily average in console ÷ 31 days should match "Daily Operational"
+
+## CLI Usage
+
+```bash
+# Default calculation (today - 2 days, 30-day window)
+cc calculate --profile myprofile
+
+# Specific start date
+cc calculate --profile myprofile --start-date 2025-11-04
+
+# Custom offset and window
+cc calculate --profile myprofile --offset 2 --window 30
+
+# JSON output
+cc calculate --profile myprofile --json-output
+```

aws_cost_calculator_cli-1.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cost Optimization Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aws_cost_calculator_cli-1.5.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include COST_CALCULATION_METHODOLOGY.md

aws_cost_calculator_cli-1.5.1/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: aws-cost-calculator-cli
+Version: 1.5.1
+Summary: AWS Cost Calculator CLI - Calculate daily and annual AWS costs across multiple accounts
+Home-page: https://github.com/yourusername/cost-calculator
+Author: Cost Optimization Team
+Author-email: 
+Project-URL: Documentation, https://github.com/yourusername/cost-calculator/blob/main/README.md
+Keywords: aws cost calculator billing optimization cloud
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: boto3>=1.26.0
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# AWS Cost Calculator (cc)
+
+A CLI tool to quickly calculate AWS costs across multiple accounts.
+
+## Installation
+
+```bash
+cd ~/cost-calculator
+pip install -e .
+```
+
+## Quick Start
+
+### 1. Login to AWS SSO
+
+```bash
+aws sso login --profile my_aws_profile
+```
+
+**Note:** You need to do this before running cost calculations. The SSO session typically lasts 8-12 hours.
+
+### 2. Initialize a profile
+
+```bash
+cc init --profile myprofile \
+  --aws-profile my_aws_profile \
+  --accounts "123456789012,234567890123,345678901234"
+```
+
+### 3. Calculate costs
+
+```bash
+# Default: Today minus 2 days, going back 30 days
+cc calculate --profile myprofile
+
+# Specific start date
+cc calculate --profile myprofile --start-date 2025-11-04
+
+# Custom offset and window
+cc calculate --profile myprofile --offset 2 --window 30
+
+# JSON output
+cc calculate --profile myprofile --json-output
+```
+
+### 4. Analyze cost trends
+
+```bash
+# Analyze last 3 weeks (default)
+cc trends --profile myprofile
+
+# Analyze more weeks
+cc trends --profile myprofile --weeks 5
+
+# Custom output file
+cc trends --profile myprofile --output weekly_trends.md
+
+# JSON output
+cc trends --profile myprofile --json-output
+```
+
+### 5. List profiles
+
+```bash
+cc list-profiles
+```
+
+## How It Works
+
+### Date Calculation
+- **Start Date**: Defaults to today, or specify with `--start-date`
+- **Offset**: Days to go back from start date (default: 2)
+- **Window**: Number of days to analyze (default: 30)
+
+Example: If today is Nov 4, 2025:
+- With offset=2, window=30: Analyzes Oct 3 - Nov 2 (30 days)
+
+### Cost Calculation
+1. **Operational Costs**: Sum of daily costs ÷ window days
+2. **Support Allocation**: 
+   - Gets support cost from the analysis month
+   - Divides by 2 (50% allocation)
+   - Divides by days in that month
+3. **Daily Rate**: Operational + Support per day
+4. **Annual Projection**: Daily rate × 365
+
+### Filters Applied
+- **Billing Entity**: AWS only (excludes marketplace)
+- **Excluded**: Tax, Support (calculated separately)
+- **Metric**: Net Amortized Cost
+
+## Configuration
+
+Profiles are stored in: `~/.config/cost-calculator/profiles.json`
+
+Example:
+```json
+{
+  "myprofile": {
+    "aws_profile": "my_aws_profile",
+    "accounts": ["123456789012", "234567890123", "345678901234"]
+  }
+}
+```
+
+## Examples
+
+```bash
+# Quick daily check
+cc calculate --profile myprofile
+
+# Historical analysis
+cc calculate --profile myprofile --start-date 2025-10-01
+
+# Export to JSON for processing
+cc calculate --profile myprofile --json-output > costs.json
+
+# Different window size
+cc calculate --profile myprofile --window 60
+
+# Weekly cost trends analysis
+cc trends --profile myprofile
+
+# Analyze last 8 weeks
+cc trends --profile myprofile --weeks 8
+
+# Monthly cost trends analysis
+cc monthly --profile myprofile
+
+# Analyze last 12 months
+cc monthly --profile myprofile --months 12
+
+# Drill down into specific service
+cc drill --profile myprofile --service "EC2 - Other"
+
+# Drill down into specific account
+cc drill --profile myprofile --account 123456789012
+
+# Drill down into service within account
+cc drill --profile myprofile --service "EC2 - Other" --account 123456789012
+```
+
+## Trends Report
+
+The `trends` command generates a markdown report with **two types of analysis**:
+
+### 1. Week-over-Week (WoW)
+Compares each week to the previous week - good for catching immediate spikes and changes.
+
+### 2. Trailing 30-Day (T-30)
+Compares each week to the same week 4 weeks ago - filters out noise and shows sustained trends.
+
+**Features:**
+- **Service-level aggregation**: Shows total cost per service (not individual usage types)
+- **Top 10 Increases/Decreases**: For each comparison period
+- **Total rows**: Sum of top 10 changes for quick assessment
+- **Filters**: Only shows changes >$10 and >5%
+
+Example output:
+```
+Week of Oct 19 → Week of Oct 26 (WoW)
+  Increases: 4, Decreases: 10
+  Top: EC2 - Other (+$949.12)
+
+Week of Oct 26 vs Week of Sep 28 (T-30)
+  Increases: 10, Decreases: 10
+  Top: EC2 - Other (+$886.39)
+```
+
+The report is saved to `cost_trends.md` by default and includes:
+- Service name
+- Previous/baseline cost
+- Current cost
+- Change amount and percentage
+- Total of top 10 changes
+
+## Monthly Report
+
+The `monthly` command generates month-over-month cost comparisons:
+
+**Features:**
+- **Service-level aggregation**: Shows total cost per service
+- **Calendar month comparisons**: October vs September, September vs August, etc.
+- **Top 10 Increases/Decreases**: For each month comparison
+- **Total rows**: Sum of top 10 changes
+- **Filters**: Only shows changes >$50 and >5%
+
+Example output:
+```
+October 2025 → November 2025
+  Increases: 1, Decreases: 10
+  Top: Savings Plans for AWS Compute usage (+$231,161.46)
+```
+
+The report is saved to `monthly_trends.md` by default.
+
+## Drill-Down Analysis
+
+The `drill` command allows you to investigate cost changes at different levels of detail:
+
+**Funnel Approach:**
+1. **Start broad:** `cc trends` → See EC2 costs up $1000
+2. **Drill by service:** `cc drill --service "EC2 - Other"` → See which accounts
+3. **Drill deeper:** `cc drill --service "EC2 - Other" --account 123` → See usage types
+
+**Features:**
+- **Week-over-week cost analysis**: Compare costs between consecutive weeks
+- **Month-over-month cost analysis**: Compare costs between consecutive months
+- **Drill-down analysis**: Analyze costs by service, account, or usage type
+- **Pandas aggregations**: Time series analysis with sum, avg, std across all weeks
+- **Volatility detection**: Identify services with high cost variability and outliers
+- **Trend detection**: Auto-detect increasing/decreasing cost patterns
+- **Search & filter**: Find services by pattern or cost threshold
+- **Profile management**: CRUD operations for account profiles in DynamoDB
+- **Markdown reports**: Generate formatted reports
+- **JSON output**: Machine-readable output for automation
+- **Lambda API backend**: Serverless backend with pandas/numpy support
+
+Example output:
+```
+# Drill by service
+cc drill --profile myprofile --service "EC2 - Other"
+
+Showing top accounts:
+Week of Oct 19 → Week of Oct 26
+  Increases: 3, Decreases: 2
+  Top: 887649220066 (+$450.23)
+```
+
+The report is saved to `drill_down.md` by default.
+
+## Output
+
+```
+Analyzing: 2025-10-03 to 2025-11-02 (30 days)
+AWS Profile: my_aws_profile
+Accounts: 3
+
+Fetching cost data...
+Fetching support costs...
+============================================================
+Period: 2025-10-03 to 2025-11-02
+Days analyzed: 30
+============================================================
+Total operational cost: $450,000.00
+Daily operational: $14,516.13
+Support (month): $15,000.00
+Support per day (÷2÷days): $241.94
+============================================================
+DAILY RATE: $14,758.07
+ANNUAL PROJECTION: $5,386,695
+============================================================
+```

aws_cost_calculator_cli-1.5.1/README.md

@@ -0,0 +1,253 @@
+# AWS Cost Calculator (cc)
+
+A CLI tool to quickly calculate AWS costs across multiple accounts.
+
+## Installation
+
+```bash
+cd ~/cost-calculator
+pip install -e .
+```
+
+## Quick Start
+
+### 1. Login to AWS SSO
+
+```bash
+aws sso login --profile my_aws_profile
+```
+
+**Note:** You need to do this before running cost calculations. The SSO session typically lasts 8-12 hours.
+
+### 2. Initialize a profile
+
+```bash
+cc init --profile myprofile \
+  --aws-profile my_aws_profile \
+  --accounts "123456789012,234567890123,345678901234"
+```
+
+### 3. Calculate costs
+
+```bash
+# Default: Today minus 2 days, going back 30 days
+cc calculate --profile myprofile
+
+# Specific start date
+cc calculate --profile myprofile --start-date 2025-11-04
+
+# Custom offset and window
+cc calculate --profile myprofile --offset 2 --window 30
+
+# JSON output
+cc calculate --profile myprofile --json-output
+```
+
+### 4. Analyze cost trends
+
+```bash
+# Analyze last 3 weeks (default)
+cc trends --profile myprofile
+
+# Analyze more weeks
+cc trends --profile myprofile --weeks 5
+
+# Custom output file
+cc trends --profile myprofile --output weekly_trends.md
+
+# JSON output
+cc trends --profile myprofile --json-output
+```
+
+### 5. List profiles
+
+```bash
+cc list-profiles
+```
+
+## How It Works
+
+### Date Calculation
+- **Start Date**: Defaults to today, or specify with `--start-date`
+- **Offset**: Days to go back from start date (default: 2)
+- **Window**: Number of days to analyze (default: 30)
+
+Example: If today is Nov 4, 2025:
+- With offset=2, window=30: Analyzes Oct 3 - Nov 2 (30 days)
+
+### Cost Calculation
+1. **Operational Costs**: Sum of daily costs ÷ window days
+2. **Support Allocation**: 
+   - Gets support cost from the analysis month
+   - Divides by 2 (50% allocation)
+   - Divides by days in that month
+3. **Daily Rate**: Operational + Support per day
+4. **Annual Projection**: Daily rate × 365
+
+### Filters Applied
+- **Billing Entity**: AWS only (excludes marketplace)
+- **Excluded**: Tax, Support (calculated separately)
+- **Metric**: Net Amortized Cost
+
+## Configuration
+
+Profiles are stored in: `~/.config/cost-calculator/profiles.json`
+
+Example:
+```json
+{
+  "myprofile": {
+    "aws_profile": "my_aws_profile",
+    "accounts": ["123456789012", "234567890123", "345678901234"]
+  }
+}
+```
+
+## Examples
+
+```bash
+# Quick daily check
+cc calculate --profile myprofile
+
+# Historical analysis
+cc calculate --profile myprofile --start-date 2025-10-01
+
+# Export to JSON for processing
+cc calculate --profile myprofile --json-output > costs.json
+
+# Different window size
+cc calculate --profile myprofile --window 60
+
+# Weekly cost trends analysis
+cc trends --profile myprofile
+
+# Analyze last 8 weeks
+cc trends --profile myprofile --weeks 8
+
+# Monthly cost trends analysis
+cc monthly --profile myprofile
+
+# Analyze last 12 months
+cc monthly --profile myprofile --months 12
+
+# Drill down into specific service
+cc drill --profile myprofile --service "EC2 - Other"
+
+# Drill down into specific account
+cc drill --profile myprofile --account 123456789012
+
+# Drill down into service within account
+cc drill --profile myprofile --service "EC2 - Other" --account 123456789012
+```
+
+## Trends Report
+
+The `trends` command generates a markdown report with **two types of analysis**:
+
+### 1. Week-over-Week (WoW)
+Compares each week to the previous week - good for catching immediate spikes and changes.
+
+### 2. Trailing 30-Day (T-30)
+Compares each week to the same week 4 weeks ago - filters out noise and shows sustained trends.
+
+**Features:**
+- **Service-level aggregation**: Shows total cost per service (not individual usage types)
+- **Top 10 Increases/Decreases**: For each comparison period
+- **Total rows**: Sum of top 10 changes for quick assessment
+- **Filters**: Only shows changes >$10 and >5%
+
+Example output:
+```
+Week of Oct 19 → Week of Oct 26 (WoW)
+  Increases: 4, Decreases: 10
+  Top: EC2 - Other (+$949.12)
+
+Week of Oct 26 vs Week of Sep 28 (T-30)
+  Increases: 10, Decreases: 10
+  Top: EC2 - Other (+$886.39)
+```
+
+The report is saved to `cost_trends.md` by default and includes:
+- Service name
+- Previous/baseline cost
+- Current cost
+- Change amount and percentage
+- Total of top 10 changes
+
+## Monthly Report
+
+The `monthly` command generates month-over-month cost comparisons:
+
+**Features:**
+- **Service-level aggregation**: Shows total cost per service
+- **Calendar month comparisons**: October vs September, September vs August, etc.
+- **Top 10 Increases/Decreases**: For each month comparison
+- **Total rows**: Sum of top 10 changes
+- **Filters**: Only shows changes >$50 and >5%
+
+Example output:
+```
+October 2025 → November 2025
+  Increases: 1, Decreases: 10
+  Top: Savings Plans for AWS Compute usage (+$231,161.46)
+```
+
+The report is saved to `monthly_trends.md` by default.
+
+## Drill-Down Analysis
+
+The `drill` command allows you to investigate cost changes at different levels of detail:
+
+**Funnel Approach:**
+1. **Start broad:** `cc trends` → See EC2 costs up $1000
+2. **Drill by service:** `cc drill --service "EC2 - Other"` → See which accounts
+3. **Drill deeper:** `cc drill --service "EC2 - Other" --account 123` → See usage types
+
+**Features:**
+- **Week-over-week cost analysis**: Compare costs between consecutive weeks
+- **Month-over-month cost analysis**: Compare costs between consecutive months
+- **Drill-down analysis**: Analyze costs by service, account, or usage type
+- **Pandas aggregations**: Time series analysis with sum, avg, std across all weeks
+- **Volatility detection**: Identify services with high cost variability and outliers
+- **Trend detection**: Auto-detect increasing/decreasing cost patterns
+- **Search & filter**: Find services by pattern or cost threshold
+- **Profile management**: CRUD operations for account profiles in DynamoDB
+- **Markdown reports**: Generate formatted reports
+- **JSON output**: Machine-readable output for automation
+- **Lambda API backend**: Serverless backend with pandas/numpy support
+
+Example output:
+```
+# Drill by service
+cc drill --profile myprofile --service "EC2 - Other"
+
+Showing top accounts:
+Week of Oct 19 → Week of Oct 26
+  Increases: 3, Decreases: 2
+  Top: 887649220066 (+$450.23)
+```
+
+The report is saved to `drill_down.md` by default.
+
+## Output
+
+```
+Analyzing: 2025-10-03 to 2025-11-02 (30 days)
+AWS Profile: my_aws_profile
+Accounts: 3
+
+Fetching cost data...
+Fetching support costs...
+============================================================
+Period: 2025-10-03 to 2025-11-02
+Days analyzed: 30
+============================================================
+Total operational cost: $450,000.00
+Daily operational: $14,516.13
+Support (month): $15,000.00
+Support per day (÷2÷days): $241.94
+============================================================
+DAILY RATE: $14,758.07
+ANNUAL PROJECTION: $5,386,695
+============================================================
+```