docs: Add --estimate-cost feature documentation and bump version to 0.1.26

- Add --estimate-cost CLI example in Command Line Usage section
- Add comprehensive Cost Estimation section explaining 3-tier scenarios
- Document Conservative (P50), Average (Mean), Worst Case (P95) ratios
- Update CHANGELOG.md with v0.1.26 release notes
- Bump version in pyproject.toml from 0.1.25 to 0.1.26

Author: Emasoft

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to APIAS (API Auto Scraper) will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.26] - 2025-12-02
+
+### New Features
+- Add `--estimate-cost` CLI flag for cost estimation before processing by @Emasoft
+- Add 3-tier cost estimation: Conservative (P50), Average (Mean), Worst Case (P95) by @Emasoft
+- Add model comparison display showing costs across all supported models by @Emasoft
+- Add interactive menu after cost estimation (proceed/change model/exit) by @Emasoft
+
+### Configuration
+- Add COST_RATIO_CONSERVATIVE, COST_RATIO_AVERAGE, COST_RATIO_WORST_CASE constants by @Emasoft
+- Add MODEL_PRICING dictionary with per-model input/output costs per 1M tokens by @Emasoft
+- Add estimate_tokens(), estimate_cost(), get_cost_estimates() functions in config.py by @Emasoft
+
+### Testing
+- Add TestCostEstimation class with 8 new tests for cost estimation functions by @Emasoft
+
+### Documentation
+- Add --estimate-cost usage example to README Command Line Usage section by @Emasoft
+- Add comprehensive Cost Estimation section in README explaining scenarios by @Emasoft
+
 ## [0.1.25] - 2025-12-02
 
 ### DRY Principle Compliance (Terminal Utilities)

README.md

@@ -77,6 +77,9 @@ apias --url https://example.com --mode batch
 # Limit how many pages to scrape
 apias --url https://example.com --mode batch --limit 50
 
+# Estimate costs before processing (no API calls made)
+apias --url https://example.com --mode batch --estimate-cost
+
 # Use a configuration file
 apias --url https://example.com --config apias_config.yaml
 ```
@@ -225,6 +228,45 @@ limit: 100
 
 ---
 
+#### `--estimate-cost` - Preview API Costs Before Processing
+
+Before committing to a full extraction, you can estimate costs without making any OpenAI API calls:
+
+```bash
+apias --url https://example.com --mode batch --estimate-cost
+```
+
+This will:
+1. Scrape all pages (respecting `--limit` if set)
+2. Calculate total input tokens from page content
+3. Display three cost scenarios based on real-world usage data:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Cost Estimation                          │
+├─────────────────────────────────────────────────────────────┤
+│ Input Tokens: 1,234,567                                     │
+├─────────────────────────────────────────────────────────────┤
+│ Scenario        │ Output Tokens │ Input Cost │ Total Cost   │
+├─────────────────┼───────────────┼────────────┼──────────────┤
+│ Conservative    │     716,249   │    $0.06   │    $0.35     │
+│ Average         │   2,271,603   │    $0.06   │    $0.97     │
+│ Worst Case      │  14,592,582   │    $0.06   │    $5.90     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Cost Scenarios Explained:**
+
+| Scenario | Output Ratio | Description |
+|----------|-------------|-------------|
+| **Conservative** | 0.58x input | P50 median - half of jobs cost this or less |
+| **Average** | 1.84x input | Mean across all extractions |
+| **Worst Case** | 11.82x input | P95 - only 5% of jobs exceed this |
+
+> **Tip**: The Conservative estimate is typically accurate for well-structured API documentation. Use the Worst Case estimate for budget planning with complex or messy HTML.
+
+---
+
 ### Quick Reference: Common Configurations
 
 #### For Small Websites (< 50 pages)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apias"
-version = "0.1.25"
+version = "0.1.26"
 description = "AI powered API documentation scraper and converter"
 readme = "README.md"
 requires-python = ">=3.10"