joselinepraveena/finops-cost-estimator-agent

Purpose and entry points

FinOps Cost Estimator is an Azure-first cost forecasting MVP. It accepts natural-language workloads or structured JSON, deterministically calculates monthly cost scenarios, and produces web, CLI, Markdown, CSV, and Excel outputs.

Primary launch paths:

• Module dispatcher: finops_estimator/__main__.py

• CLI commands (ask, estimate, serve): finops_estimator/cli.py

• HTTP/web application: finops_estimator/api.py

• Browser client: finops_estimator/web/static/index.html

Input interpretation boundary

Natural-language requests are converted into a structured workload specification before pricing. Parsing can use optional Azure OpenAI credentials, but has local parsing behavior so offline execution remains possible.

• Workload parsing and normalization: finops_estimator/parser.py

• Optional Azure OpenAI integration: finops_estimator/openai_client.py

• Domain workload, pricing, and result models: finops_estimator/models.py

The central architectural rule is enforced here and downstream: AI interprets workload intent; code, not the model, computes price arithmetic.

Deterministic estimation engine

The core calculation pipeline consumes the normalized workload model and constructs priced line items, scenario comparisons, assumptions, ranges, sensitivities, and what-if results. It covers Azure VM/AKS, Azure SQL, storage, load balancing, egress, backup, and logs.

• Primary orchestration and calculations: finops_estimator/engine.py

• Cost/result schemas shared across stages: finops_estimator/models.py

• Static fallback price data: finops_estimator/fallback_prices.py

This is the main trust boundary: all totals originate from engine logic and price records, rather than narrative generation.

Price acquisition and resilience

Live pricing is obtained from the external Azure Retail Prices API. The estimator can instead use its embedded dated catalog, explicitly via --offline or when the retail service is unavailable. FINOPS_LIVE_PRICES=0 supports deterministic non-live runs.

• Retail API client and lookup logic: finops_estimator/retail.py

• Offline catalog: finops_estimator/fallback_prices.py

• Engine integration point: finops_estimator/engine.py

Price lookup is therefore isolated from workload interpretation and scenario arithmetic.

Scenario and recommendation flow

The engine evaluates on-demand, one-year and three-year Reserved Instance, Savings Plan, and optimized options. It also supports region comparisons, SKU rightsizing, storage-tier changes, and DR-footprint changes. The resulting structured estimate feeds a narrative layer that creates an executive-facing explanation and chargeback-tag guidance.

• Scenario calculation: finops_estimator/engine.py

• Narrative generation: finops_estimator/narrative.py

• Optional model-backed explanation: finops_estimator/openai_client.py

Narrative output is downstream of calculated results and should not mutate estimates.

Delivery surfaces and exports

The CLI is the primary automation interface; serve exposes an HTTP API that backs the lightweight static conversational UI. Structured estimation output can be rendered for download or sharing.

• CLI interface: finops_estimator/cli.py

• API/server surface: finops_estimator/api.py

• Static web UI: finops_estimator/web/static/app.js

• Markdown/CSV/Excel export: finops_estimator/export.py

Runtime is Python, with optional Azure OpenAI and live Azure Retail Prices API dependencies. No later-phase integrations such as Cost Management exports, AI Search, Teams, Power BI, or RBAC/audit are present.