{"id":49340035,"url":"https://github.com/citadel-cloud-management/ai-finops-optimization-agent","last_synced_at":"2026-04-27T03:05:00.582Z","repository":{"id":342928558,"uuid":"1175667495","full_name":"Citadel-Cloud-Management/ai-finops-optimization-agent","owner":"Citadel-Cloud-Management","description":"Multi-cloud FinOps optimization agent — cost anomaly detection, rightsizing recommendations, waste elimination","archived":false,"fork":false,"pushed_at":"2026-04-11T22:20:19.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-12T00:34:35.748Z","etag":null,"topics":["ai-agents","aws","azure","cloud-cost","cloud-costs","cost-optimization","devops","finops","gcp","multi-cloud","optimization","python","rightsizing"],"latest_commit_sha":null,"homepage":"https://citadel-cloud-management.github.io/ai-finops-optimization-agent/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Citadel-Cloud-Management.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T02:16:59.000Z","updated_at":"2026-04-11T22:39:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Citadel-Cloud-Management/ai-finops-optimization-agent","commit_stats":null,"previous_names":["kogunlowo123/ai-finops-optimization-agent","citadel-cloud-management/ai-finops-optimization-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Citadel-Cloud-Management/ai-finops-optimization-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fai-finops-optimization-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fai-finops-optimization-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fai-finops-optimization-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fai-finops-optimization-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Citadel-Cloud-Management","download_url":"https://codeload.github.com/Citadel-Cloud-Management/ai-finops-optimization-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fai-finops-optimization-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32320688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","aws","azure","cloud-cost","cloud-costs","cost-optimization","devops","finops","gcp","multi-cloud","optimization","python","rightsizing"],"created_at":"2026-04-27T03:05:00.403Z","updated_at":"2026-04-27T03:05:00.556Z","avatar_url":"https://github.com/Citadel-Cloud-Management.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Python](https://img.shields.io/badge/Python-3.11+-blue?logo=python\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-MIT-green)\n![GitHub release](https://img.shields.io/github/v/release/kogunlowo123/ai-finops-optimization-agent)\n\n# AI FinOps Optimization Agent\n\nA Python agent that analyzes cloud costs across AWS, Azure, and GCP, identifies optimization opportunities including rightsizing, reserved instances, and waste elimination, and can execute recommendations with built-in safety controls.\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph Collectors[\"Cost Data Collectors\"]\n        style Collectors fill:#1a1a2e,stroke:#16213e,color:#fff\n        AWS[\"AWS Cost Explorer\u003cbr/\u003eboto3 + CloudWatch\"]\n        style AWS fill:#e36414,stroke:#0f3460,color:#fff\n        Azure[\"Azure Cost Mgmt\u003cbr/\u003eazure-mgmt SDK\"]\n        style Azure fill:#1982c4,stroke:#0f3460,color:#fff\n        GCP[\"GCP Billing\u003cbr/\u003eBigQuery + Compute\"]\n        style GCP fill:#2b9348,stroke:#0f3460,color:#fff\n    end\n\n    subgraph Analyzers[\"Cost Analyzers\"]\n        style Analyzers fill:#0f3460,stroke:#16213e,color:#fff\n        Anomaly[\"Anomaly Detector\u003cbr/\u003eZ-Score + LLM\"]\n        style Anomaly fill:#e94560,stroke:#0f3460,color:#fff\n        Rightsize[\"Rightsizing\u003cbr/\u003eCPU Utilization\"]\n        style Rightsize fill:#533483,stroke:#0f3460,color:#fff\n        Reserved[\"RI/SP Advisor\u003cbr/\u003eUsage Patterns\"]\n        style Reserved fill:#e36414,stroke:#0f3460,color:#fff\n        Waste[\"Waste Finder\u003cbr/\u003eIdle + Orphaned\"]\n        style Waste fill:#1982c4,stroke:#0f3460,color:#fff\n    end\n\n    subgraph Optimizers[\"Optimization Executors\"]\n        style Optimizers fill:#1a1a2e,stroke:#16213e,color:#fff\n        Scheduler[\"Resource Scheduler\u003cbr/\u003eStart/Stop\"]\n        style Scheduler fill:#2b9348,stroke:#0f3460,color:#fff\n        Cleanup[\"Resource Cleanup\u003cbr/\u003eSafe Deletion\"]\n        style Cleanup fill:#e94560,stroke:#0f3460,color:#fff\n        Purchase[\"Reservation Purchase\u003cbr/\u003eRI/SP Buy\"]\n        style Purchase fill:#533483,stroke:#0f3460,color:#fff\n    end\n\n    subgraph Reporters[\"Reporting\"]\n        style Reporters fill:#0f3460,stroke:#16213e,color:#fff\n        Dashboard[\"Dashboard\u003cbr/\u003eJSON Export\"]\n        style Dashboard fill:#e36414,stroke:#0f3460,color:#fff\n        Slack[\"Slack Reporter\u003cbr/\u003eDaily Summaries\"]\n        style Slack fill:#2b9348,stroke:#0f3460,color:#fff\n        Email[\"Email Reporter\u003cbr/\u003eHTML + Text\"]\n        style Email fill:#1982c4,stroke:#0f3460,color:#fff\n    end\n\n    FinOps([FinOps Agent])\n    style FinOps fill:#e94560,stroke:#0f3460,color:#fff\n\n    AWS --\u003e FinOps\n    Azure --\u003e FinOps\n    GCP --\u003e FinOps\n\n    FinOps --\u003e Anomaly\n    FinOps --\u003e Rightsize\n    FinOps --\u003e Reserved\n    FinOps --\u003e Waste\n\n    Anomaly --\u003e Dashboard\n    Rightsize --\u003e Scheduler\n    Rightsize --\u003e Dashboard\n    Reserved --\u003e Purchase\n    Reserved --\u003e Dashboard\n    Waste --\u003e Cleanup\n    Waste --\u003e Dashboard\n\n    Dashboard --\u003e Slack\n    Dashboard --\u003e Email\n```\n\n## Prerequisites\n\n| Requirement | Version | Notes |\n|---|---|---|\n| Python | \u003e= 3.11 | Required for modern type hints |\n| pip | \u003e= 23.0 | For dependency installation |\n| AWS credentials | - | For AWS cost analysis (boto3-compatible) |\n| Azure credentials | - | For Azure cost analysis (service principal) |\n| GCP credentials | - | For GCP cost analysis (service account) |\n| OpenAI API key | - | For LLM-powered anomaly explanations |\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-org/ai-finops-optimization-agent.git\ncd ai-finops-optimization-agent\n\n# Create and activate a virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install with specific cloud provider support\npip install -e \".[aws]\"           # AWS only\npip install -e \".[azure]\"         # Azure only\npip install -e \".[gcp]\"           # GCP only\npip install -e \".[all-clouds]\"    # All providers\npip install -e \".[all-clouds,dev]\"  # All providers + dev tools\n\n# Configure environment variables\ncp .env.example .env\n# Edit .env with your cloud credentials and API keys\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `OPENAI_API_KEY` | Yes | - | OpenAI API key for anomaly explanations |\n| `FINOPS_PROVIDERS` | No | `aws` | Comma-separated: `aws`, `azure`, `gcp` |\n| `AWS_ACCESS_KEY_ID` | No | - | AWS access key (or use IAM role/profile) |\n| `AWS_SECRET_ACCESS_KEY` | No | - | AWS secret key |\n| `AWS_DEFAULT_REGION` | No | `us-east-1` | Default AWS region |\n| `AZURE_SUBSCRIPTION_ID` | No | - | Azure subscription ID |\n| `AZURE_TENANT_ID` | No | - | Azure AD tenant ID |\n| `AZURE_CLIENT_ID` | No | - | Azure service principal client ID |\n| `AZURE_CLIENT_SECRET` | No | - | Azure service principal secret |\n| `GCP_PROJECT_ID` | No | - | GCP project ID |\n| `GCP_BILLING_ACCOUNT_ID` | No | - | GCP billing account ID |\n| `GOOGLE_APPLICATION_CREDENTIALS` | No | - | Path to GCP service account JSON |\n| `SLACK_WEBHOOK_URL` | No | - | Slack webhook for cost reports |\n| `SMTP_HOST` | No | - | SMTP server for email reports |\n\n### FinOpsConfig Options\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `enabled_providers` | `list[CloudProvider]` | `[AWS]` | Cloud providers to analyze |\n| `cost_anomaly_threshold_percent` | `float` | `20.0` | Minimum % deviation to flag as anomaly |\n| `idle_resource_cpu_threshold` | `float` | `5.0` | CPU % below which a resource is idle |\n| `idle_resource_days` | `int` | `7` | Days of data for utilization averaging |\n| `rightsizing_headroom_percent` | `float` | `20.0` | CPU headroom buffer for rightsizing |\n| `report_currency` | `str` | `USD` | Currency for cost reports |\n\n## Usage Example\n\n```python\nfrom src.config import CloudProvider, FinOpsConfig\nfrom src.finops_agent import FinOpsAgent\n\n# Configure for AWS analysis\nconfig = FinOpsConfig.from_env()\nconfig.enabled_providers = [CloudProvider.AWS]\nconfig.cost_anomaly_threshold_percent = 15.0\n\n# Run the full analysis pipeline\nagent = FinOpsAgent(config)\nreport = agent.run_analysis()\n\n# Print summary to console\nagent.print_summary(report)\n\n# Send to Slack\nagent.send_slack_report(report)\n\n# Access detailed results\nfor rec in report.rightsizing:\n    print(f\"{rec.resource_id}: {rec.current_type} -\u003e {rec.recommended_type}\")\n    print(f\"  Savings: ${rec.monthly_savings:.2f}/month\")\n\nfor waste in report.waste:\n    print(f\"{waste.resource_id}: {waste.waste_type}\")\n    print(f\"  Cost: ${waste.estimated_monthly_cost:.2f}/month\")\n```\n\n### Running Examples\n\n```bash\n# Daily cost report with anomaly detection\npython -m examples.daily_report\n\n# Find wasted resources (idle instances, unattached volumes)\npython -m examples.find_waste\n\n# Rightsizing analysis with CPU utilization data\npython -m examples.rightsizing_analysis\n```\n\n## Step-by-Step Implementation Guide\n\n1. **Install dependencies** -- Follow the installation section. Install only the cloud provider SDKs you need using optional dependency groups (`[aws]`, `[azure]`, `[gcp]`, or `[all-clouds]`).\n\n2. **Configure cloud credentials** -- Set up authentication for each cloud provider. For AWS, use IAM roles, profiles, or access keys. For Azure, create a service principal with Cost Management Reader role. For GCP, create a service account with Billing Viewer role and export BigQuery billing data.\n\n3. **Set analysis thresholds** -- Configure `FinOpsConfig` with appropriate thresholds for your environment. Start with conservative anomaly thresholds (30%) and tighten as you tune out false positives.\n\n4. **Run initial analysis** -- Execute `agent.run_analysis()` to get a baseline view of costs, anomalies, and optimization opportunities. Review the report before enabling any automated actions.\n\n5. **Review rightsizing recommendations** -- Check CPU utilization data and recommended instance types. Validate against application requirements before acting on recommendations.\n\n6. **Set up waste cleanup** -- Use `ResourceCleanup` with `dry_run=True` first. Review the proposed actions, then switch to `dry_run=False` for automated cleanup of unattached volumes and unused IPs.\n\n7. **Configure scheduling** -- Set up `ResourceScheduler` with schedule rules for non-production resources. Tag instances with schedule identifiers and define business-hours start/stop rules.\n\n8. **Enable reporting** -- Configure Slack webhooks and/or SMTP for automated daily reports. Run the daily report example as a cron job or scheduled task.\n\n9. **Evaluate reservations** -- Review `ReservedInstanceAdvisor` recommendations for services with consistent usage. Use `ReservationPurchaser.preview_purchase()` before committing.\n\n## Documentation Links\n\n- [AWS Cost Explorer API](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-api.html) -- AWS Cost Explorer API reference for cost and usage queries.\n- [Azure Cost Management](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/) -- Azure Cost Management query API and cost analysis.\n- [GCP Cloud Billing API](https://cloud.google.com/billing/docs/reference/rest) -- GCP Billing API for programmatic cost data access.\n- [FinOps Framework](https://www.finops.org/framework/) -- The FinOps Foundation framework for cloud financial management best practices.\n\n## Project Structure\n\n```\nai-finops-optimization-agent/\n├── src/\n│   ├── finops_agent.py        # Main agent orchestrating the full pipeline\n│   ├── config.py              # Multi-cloud configuration management\n│   ├── collectors/\n│   │   ├── aws_costs.py       # AWS Cost Explorer + EC2 + CloudWatch\n│   │   ├── azure_costs.py     # Azure Cost Management + Compute + Monitor\n│   │   └── gcp_costs.py       # GCP Billing (BigQuery) + Compute Engine\n│   ├── analyzers/\n│   │   ├── anomaly_detector.py    # Z-score anomaly detection + LLM explanations\n│   │   ├── rightsizing.py         # Instance rightsizing recommendations\n│   │   ├── reserved_advisor.py    # RI/Savings Plan advisor\n│   │   └── waste_finder.py        # Idle/orphaned resource detection\n│   ├── optimizers/\n│   │   ├── scheduler.py      # Start/stop scheduling for non-prod\n│   │   ├── cleanup.py        # Safe resource cleanup with dry-run\n│   │   └── reservation.py    # RI/SP purchase with approval workflow\n│   └── reporters/\n│       ├── dashboard.py       # JSON dashboard data generator\n│       ├── slack_reporter.py  # Slack webhook cost reports\n│       └── email_reporter.py  # HTML/text email cost reports\n├── examples/\n│   ├── daily_report.py        # Daily cost report example\n│   ├── find_waste.py          # Waste detection example\n│   └── rightsizing_analysis.py # Rightsizing analysis example\n├── requirements.txt\n├── pyproject.toml\n├── LICENSE\n└── CHANGELOG.md\n```\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitadel-cloud-management%2Fai-finops-optimization-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcitadel-cloud-management%2Fai-finops-optimization-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitadel-cloud-management%2Fai-finops-optimization-agent/lists"}