billing-cost-prediction

Framework-agnostic cloud cost prediction engine. Strategy-based, zero dependencies.

Quick Start

from billing_cost_prediction import PredictionEngine, BillingRecord, BillingMonth, CloudProvider

engine = PredictionEngine()
records = [
    BillingRecord(
        resource_id="res-001",
        cloud_provider=CloudProvider.AZURE,
        billing_month=BillingMonth.from_string("2026-04"),
        cost=1234.56,
    ),
]
results = engine.predict(records, months=12)
for batch in results:
    for r in batch.results:
        print(f"{r.predict_month}: {r.predicted_cost:.2f} ({r.method}, confidence={r.confidence})")

Strategies

→ Strategy guide with flowcharts

Docs

• Architecture & Design — data flow, component diagram, design decisions
• Integration Guide — Django, SQL, CSV, custom strategies
• Strategy Guide — selection flowchart, tuning, per-strategy details

Roadmap

✅ Phase 1: Core Engine (done)

• Type system (BillingRecord, PredictionResult, BillingMonth, enums)
• 4 strategies: moving_average, exponential_smoothing, linear_trend, seasonal
• Back-test based confidence scoring
• Per-resource auto strategy selection
• Extensible strategy protocol (Protocol, structural subtyping)
• Unit + integration tests (95%+ coverage)
• Architecture refactoring (O(n) iteration, sort-once, build_result helper)
• Python 3.10+ support
• Architecture docs with flowcharts (Mermaid)
• Pre-commit hooks (ruff + mypy)

🔜 Phase 2: Production Readiness (next)

• PyPI publish (pip install cost-prediction)
• CI pipeline (GitHub Actions: pytest/ruff/mypy matrix)
• Coverage reporting (sticky PR comment)
• Integration guide (Django, SQL, CSV, custom strategy)

🔗 Django Integration (cross-repo)

Repo: softwareone-finops-backend

• Remove backend/prediction/prediction_model/ directory
• Remove backend/prediction/azure_views.py (dead code)
• Add cost-prediction to pyproject.toml dependencies
• Create backend/prediction/data_adapter.py (DB ↔ engine bridge)
• Rewrite task__multi_cloud_bill_predict using engine + adapter
• Change task from "delete-all + rebuild" to update_or_create upsert
• Add unique_together constraint on prediction model
• Remove unused model fields (billing_model, region, availability_zone, provider_metadata)
• Unify actual-cost queries across Alibaba/Azure in Views
• Integration tests for data_adapter, tasks, views

🔮 Phase 3: Algorithm Enhancements (done)

• ExponentialSmoothingStrategy
• CostAnomalyDetector (pre-filter anomalous months)
• StrategyEnsemble (multi-strategy voting)
• Prediction accuracy tracking (MAPE)
• Day-based billing normalization (to_daily_rates / to_monthly_rates)

Development

# install in dev mode
pip install -e ".[dev]"

# run tests
pytest -v

# lint
ruff check .
mypy .