argus-cloud-optimizer 0.2.0__py3-none-any.whl

core/agent/prompts.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+
+def build_system_prompt(
+    cloud: str,
+    ignore_regions: list[str],
+    accounts: list[dict],
+) -> str:
+    """
+    Build the agent system prompt. Injected once per scan — not per iteration.
+    The prompt is cloud-aware but the loop logic is not.
+    """
+    regions_note = (
+        f"All regions EXCEPT: {', '.join(ignore_regions)}"
+        if ignore_regions
+        else "All regions (no exclusions)"
+    )
+    account_lines = "\n".join(
+        f"  - {a.get('name', 'unnamed')} ({a.get('id', 'unknown')})" for a in accounts
+    )
+
+    return f"""You are Argus, an intelligent cloud cost optimization agent.
+
+MISSION
+───────
+Scan the {cloud.upper()} account(s) listed below and identify ALL resources that exist
+but are not being actively used. Your goal is to find real money being wasted —
+resources paying a monthly bill with no business value being delivered.
+
+ACCOUNTS TO SCAN
+────────────────
+{account_lines}
+
+REGIONS
+───────
+{regions_note}
+
+YOUR APPROACH
+─────────────
+1. Call list_resources — returns a pre-filtered, cost-sorted inventory.
+   Each resource already includes a cost_usd field (monthly USD) if available.
+   Resources are sorted by cost descending — focus on the top entries first.
+2. Use the cost_usd values already in the list to prioritize — no need to call
+   get_cost again unless you need cost for resources not already in the list.
+3. For each candidate, call get_metrics to check actual usage over the past 90 days.
+4. Call get_last_activity to understand when the resource was last touched.
+5. Form a conclusion: is this resource idle, underutilized, or orphaned?
+6. When your analysis is complete, call submit_findings with all findings
+   ranked by cost.
+
+WHAT TO LOOK FOR
+────────────────
+- Resources with near-zero metrics (CPU, requests, connections, bytes, IOPS)
+- Resources with no recent API activity (last touched weeks or months ago)
+- Orphaned resources (no owner tags, no clear purpose)
+- Resources that are stopped/paused but still charging (volumes, reserved IPs)
+- Over-provisioned resources (large instance, near-zero load) — see RIGHT-SIZING below
+- Duplicate or redundant resources (multiple similar resources, one unused)
+
+RIGHT-SIZING RULES
+──────────────────
+When get_metrics returns an instance_type field, you have the current size and MUST
+recommend a specific target size — not a generic "consider downsizing".
+
+Decision thresholds (90-day average — never judge on a shorter window):
+
+  EC2 Instance
+    CPU < 5% AND NetworkOut < 1 GB/day  → downsize one family tier
+      e.g. m5.4xlarge → m5.2xlarge,  t3.large → t3.medium
+    CPU < 2%                             → consider Graviton equivalent
+      e.g. m5.xlarge → m7g.large (same perf, ~20% cheaper)
+
+  RDS / Aurora
+    CPU < 10% AND DatabaseConnections < 5  → downsize one class tier
+      e.g. db.r5.4xlarge → db.r5.2xlarge,  db.r5.2xlarge → db.r5.xlarge
+    multi_az: true AND CPU < 5%            → also evaluate disabling Multi-AZ
+      (Multi-AZ doubles instance cost with no benefit if the DB is barely used)
+    storage_gb severely over-allocated     → flag for gp2→gp3 conversion
+      (gp3 is same price or cheaper; also allows IOPs/throughput tuning)
+
+  ElastiCache / Redis
+    CacheHitRate > 90% AND CurrConnections < 10  → downsize one node tier
+      e.g. cache.r6g.xlarge → cache.r6g.large
+    num_cache_nodes > 1 AND traffic near-zero    → reduce replica count first
+
+  Redshift
+    CPU < 10% AND instance_count > 1  → reduce node count
+      e.g. 4× dc2.large → 2× dc2.large (halves compute cost)
+
+  OpenSearch
+    CPU < 10% AND instance_count > 2  → reduce data node count
+    dedicated_master: true AND cluster is small  → removing dedicated masters saves ~30%
+
+  Lambda
+    memory_mb >> actual peak usage  → reduce memory_mb
+      Lambda pricing is memory × duration; oversized memory wastes on every invocation
+      Rule of thumb: set memory_mb to 1.5× peak observed memory usage
+
+ALWAYS state the current instance_type, the recommended target, and estimated monthly
+savings in the recommendation field. Prefix right-sizing findings with "RIGHT-SIZE:"
+so they are visually distinct from idle/delete findings in the Slack report.
+
+PRIORITY RULES
+──────────────
+HIGH   → confirmed idle AND costs more than $20/month
+MEDIUM → likely idle OR costs $5–20/month
+LOW    → possibly idle OR costs less than $5/month
+
+EFFICIENCY RULES
+────────────────
+- Cost data is already in the list_resources result (cost_usd field) — use it directly
+- Only call get_cost if you need data for resources missing the cost_usd field
+- Don't investigate every resource — focus on the most expensive candidates first
+- Use get_last_activity to quickly rule out recently active resources
+- Resources at the bottom of the list (near-zero cost) rarely warrant investigation
+
+IMPORTANT
+─────────
+- Be thorough — don't stop after finding a few resources
+- Only call submit_findings when you are confident your analysis is complete
+- Every finding must include a specific, actionable recommendation
+- The executive_summary should be suitable for a non-technical engineering manager
+"""
+
+
+def build_tool_schemas() -> list[dict]:
+    """
+    Return the tool definitions used to register tools with the AI provider.
+    Kept here alongside the prompt so both evolve together.
+    """
+    return [
+        {
+            "name": "list_resources",
+            "description": (
+                "List ALL resources across every region, minus any in ignore_regions. "
+                "Returns resource IDs, types, regions, names, and tags. "
+                "Call this first to get a complete inventory. "
+                "Do not filter by resource type — return everything. "
+                "Omit ignore_regions or pass an empty list to scan all regions."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "ignore_regions": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "Regions to EXCLUDE from the scan. "
+                            "Leave empty to scan all regions. "
+                            "Example: ['ap-east-1', 'me-south-1']"
+                        ),
+                    }
+                },
+                "required": [],
+            },
+        },
+        {
+            "name": "get_metrics",
+            "description": (
+                "Get usage metrics for a resource over the past N days. "
+                "The adapter automatically fetches the metrics relevant to "
+                "the resource type "
+                "(CPU utilisation, network bytes, request count, IOPS, "
+                "DB connections, etc.). "
+                "You do not need to specify which metrics — just provide "
+                "the resource ID and type. "
+                "Do NOT pass a days value less than 90 — short windows "
+                "produce false positives "
+                "by missing weekly, monthly, or quarterly usage patterns."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "resource_id": {
+                        "type": "string",
+                        "description": "Resource ID or ARN",
+                    },
+                    "resource_type": {
+                        "type": "string",
+                        "description": "Resource type string (e.g. 'AWS::EC2::Instance')",
+                    },
+                    "days": {
+                        "type": "integer",
+                        "description": (
+                            "Lookback window in days. Default is 90. "
+                            "Never set below 90 — shorter windows miss quarterly patterns "
+                            "and produce false-positive idle findings."
+                        ),
+                        "default": 90,
+                    },
+                },
+                "required": ["resource_id", "resource_type"],
+            },
+        },
+        {
+            "name": "get_cost",
+            "description": (
+                "Get the actual cost in USD for one or more resources over the past N days. "
+                "ALWAYS batch multiple resource IDs into a single call — never call this "
+                "one resource at a time. Returns a dict mapping resource_id to monthly cost."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "resource_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of resource IDs. Batch as many as possible.",
+                    },
+                    "days": {
+                        "type": "integer",
+                        "description": "Lookback window in days (default: 30)",
+                        "default": 30,
+                    },
+                },
+                "required": ["resource_ids"],
+            },
+        },
+        {
+            "name": "get_last_activity",
+            "description": (
+                "Get the timestamp of the last meaningful activity for a resource "
+                "(last API call, configuration change, user interaction, etc.). "
+                "Returns an ISO8601 timestamp or null if no activity was found."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "resource_id": {
+                        "type": "string",
+                        "description": "Resource ID or ARN",
+                    },
+                    "resource_type": {
+                        "type": "string",
+                        "description": "Resource type string",
+                    },
+                },
+                "required": ["resource_id", "resource_type"],
+            },
+        },
+        {
+            "name": "submit_findings",
+            "description": (
+                "Submit your final analysis when your investigation is complete. "
+                "Include ALL idle or wasteful resources you found, ordered by estimated_monthly_cost "
+                "descending. Calling this tool ends the analysis — do not call it until you are "
+                "confident the scan is thorough."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "findings": {
+                        "type": "array",
+                        "description": "Idle/wasteful resources ordered by cost (highest first)",
+                        "items": {
+                            "type": "object",
+                            "required": [
+                                "resource_id",
+                                "resource_type",
+                                "cloud",
+                                "region",
+                                "estimated_monthly_cost",
+                                "waste_reason",
+                                "recommendation",
+                                "priority",
+                                "metrics_summary",
+                            ],
+                            "properties": {
+                                "resource_id": {"type": "string"},
+                                "resource_type": {"type": "string"},
+                                "cloud": {
+                                    "type": "string",
+                                    "enum": ["aws", "gcp", "azure"],
+                                },
+                                "region": {"type": "string"},
+                                "name": {"type": "string"},
+                                "estimated_monthly_cost": {
+                                    "type": "number",
+                                    "description": "Estimated monthly cost in USD",
+                                },
+                                "waste_reason": {
+                                    "type": "string",
+                                    "description": "Clear explanation of why this resource is idle or wasteful",
+                                },
+                                "recommendation": {
+                                    "type": "string",
+                                    "description": "Specific action: delete, downsize, tag for review, etc.",
+                                },
+                                "priority": {
+                                    "type": "string",
+                                    "enum": ["high", "medium", "low"],
+                                },
+                                "metrics_summary": {
+                                    "type": "object",
+                                    "description": "Key metric values that informed this decision",
+                                },
+                                "tags": {"type": "object"},
+                                "last_activity": {
+                                    "type": "string",
+                                    "description": "ISO8601 datetime of last activity, or null",
+                                },
+                            },
+                        },
+                    },
+                    "executive_summary": {
+                        "type": "string",
+                        "description": (
+                            "3–5 sentence summary for a non-technical engineering manager. "
+                            "Include: total estimated monthly waste, number of resources found, "
+                            "the most impactful finding, and the single most important action to take."
+                        ),
+                    },
+                },
+                "required": ["findings", "executive_summary"],
+            },
+        },
+    ]

core/config.py

@@ -0,0 +1,235 @@
+"""
+Centralized configuration via pydantic-settings.
+
+All environment variables are defined here with types, defaults, and validation.
+Access the singleton via ``get_settings()``. The object is built once and cached
+for the lifetime of the process.
+
+Usage::
+
+    from core.config import get_settings
+    cfg = get_settings()
+    print(cfg.ai.provider)          # "anthropic"
+    print(cfg.scan.max_resources)   # 200
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# ---------------------------------------------------------------------------
+# AI
+# ---------------------------------------------------------------------------
+
+
+class AISettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    provider: str = Field("anthropic", alias="AI_PROVIDER")
+    model: str | None = Field(None, alias="AI_MODEL")
+    temperature: float = Field(0.0, alias="AI_TEMPERATURE")
+
+    # Anthropic
+    anthropic_api_key: str | None = Field(None, alias="ANTHROPIC_API_KEY")
+    anthropic_model: str = Field(
+        "claude-sonnet-4-6", alias="ANTHROPIC_MODEL"
+    )
+
+    # Bedrock
+    bedrock_model_id: str = Field(
+        "anthropic.claude-sonnet-4-6", alias="BEDROCK_MODEL_ID"
+    )
+    bedrock_region: str = Field("us-east-1", alias="BEDROCK_REGION")
+    bedrock_max_tokens: int = Field(2048, alias="BEDROCK_MAX_TOKENS")
+
+    # Vertex AI
+    vertexai_project: str | None = Field(None, alias="VERTEXAI_PROJECT")
+    vertexai_location: str = Field("us-central1", alias="VERTEXAI_LOCATION")
+    vertexai_model: str = Field("gemini-1.5-pro-002", alias="VERTEXAI_MODEL")
+
+    # Azure OpenAI
+    azure_openai_endpoint: str | None = Field(None, alias="AZURE_OPENAI_ENDPOINT")
+    azure_openai_deployment: str = Field("gpt-4o", alias="AZURE_OPENAI_DEPLOYMENT")
+    azure_openai_api_version: str = Field(
+        "2024-10-21", alias="AZURE_OPENAI_API_VERSION"
+    )
+    azure_openai_api_key: str | None = Field(None, alias="AZURE_OPENAI_API_KEY")
+
+    def resolved_model(self, provider: str | None = None) -> str:
+        """Return the effective model name for the active (or given) provider."""
+        p = provider or self.provider
+        if self.model:
+            return self.model
+        return {
+            "anthropic": self.anthropic_model,
+            "bedrock": self.bedrock_model_id,
+            "vertexai": self.vertexai_model,
+            "azure_openai": self.azure_openai_deployment,
+        }.get(p, self.anthropic_model)
+
+
+# ---------------------------------------------------------------------------
+# AWS
+# ---------------------------------------------------------------------------
+
+
+class AWSSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    primary_region: str = Field("us-east-1", alias="PRIMARY_REGION")
+    resource_explorer_region: str | None = Field(
+        None, alias="RESOURCE_EXPLORER_REGION"
+    )
+    ignore_regions: str = Field("", alias="IGNORE_REGIONS")
+    accounts_mode: Literal["single", "multi"] = Field("single", alias="ACCOUNTS_MODE")
+    accounts_config: str = Field("", alias="ACCOUNTS_CONFIG")
+    report_s3_bucket: str = Field("", alias="REPORT_S3_BUCKET")
+
+    @property
+    def ignore_regions_list(self) -> list[str]:
+        return [r.strip() for r in self.ignore_regions.split(",") if r.strip()]
+
+    @property
+    def accounts_list(self) -> list[dict[str, str]]:
+        if not self.accounts_config:
+            return []
+        return json.loads(self.accounts_config)
+
+
+# ---------------------------------------------------------------------------
+# GCP
+# ---------------------------------------------------------------------------
+
+
+class GCPSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    project_id: str = Field("", alias="GCP_PROJECT_ID")
+    billing_bq_table: str | None = Field(None, alias="BILLING_BQ_TABLE")
+    report_gcs_bucket: str = Field("", alias="REPORT_GCS_BUCKET")
+
+
+# ---------------------------------------------------------------------------
+# Azure
+# ---------------------------------------------------------------------------
+
+
+class AzureSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    subscription_ids: str = Field("", alias="AZURE_SUBSCRIPTION_IDS")
+    log_analytics_workspace_id: str | None = Field(
+        None, alias="AZURE_LOG_ANALYTICS_WORKSPACE_ID"
+    )
+    report_storage_account: str = Field("", alias="REPORT_STORAGE_ACCOUNT")
+    report_storage_container: str = Field(
+        "argus-reports", alias="REPORT_STORAGE_CONTAINER"
+    )
+
+    @property
+    def subscription_ids_list(self) -> list[str]:
+        return [s.strip() for s in self.subscription_ids.split(",") if s.strip()]
+
+
+# ---------------------------------------------------------------------------
+# Notifications & reports
+# ---------------------------------------------------------------------------
+
+
+class ReportSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    slack_webhook_url: str = Field("", alias="SLACK_WEBHOOK_URL")
+    teams_webhook_url: str = Field("", alias="TEAMS_WEBHOOK_URL")
+    webhook_url: str = Field("", alias="WEBHOOK_URL")
+    dry_run: bool = Field(False, alias="DRY_RUN")
+    report_format: str = Field("json,html", alias="REPORT_FORMAT")
+    report_url_expiry: int = Field(604800, alias="REPORT_URL_EXPIRY")
+    local_report_dir: str = Field("local_reports", alias="LOCAL_REPORT_DIR")
+
+    @property
+    def formats(self) -> set[str]:
+        return {f.strip().lower() for f in self.report_format.split(",") if f.strip()}
+
+    @property
+    def has_any_notification_channel(self) -> bool:
+        return bool(
+            self.slack_webhook_url
+            or self.teams_webhook_url
+            or self.webhook_url
+        )
+
+
+# ---------------------------------------------------------------------------
+# Scan tuning
+# ---------------------------------------------------------------------------
+
+
+class ScanSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    max_resources: int = Field(200, alias="MAX_RESOURCES_PER_SCAN")
+    metrics_lookback_days: int = Field(90, alias="METRICS_LOOKBACK_DAYS")
+    adapter_concurrency: int = Field(10, alias="ADAPTER_CONCURRENCY")
+    max_iterations: int = Field(50, alias="MAX_AGENT_ITERATIONS")
+    llm_budget_usd: float = Field(2.0, alias="LLM_BUDGET_USD")
+    exclude_tags: str = Field("", alias="EXCLUDE_TAGS")
+    exclude_resource_types: str = Field("", alias="EXCLUDE_RESOURCE_TYPES")
+
+    @property
+    def exclude_tags_dict(self) -> dict[str, str]:
+        if not self.exclude_tags:
+            return {}
+        return json.loads(self.exclude_tags)
+
+    @property
+    def exclude_resource_types_list(self) -> list[str]:
+        return [
+            t.strip()
+            for t in self.exclude_resource_types.split(",")
+            if t.strip()
+        ]
+
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+
+class LogSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", env_file=".env", extra="ignore")
+
+    log_level: str = Field("INFO", alias="LOG_LEVEL")
+
+
+# ---------------------------------------------------------------------------
+# Top-level settings
+# ---------------------------------------------------------------------------
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    ai: AISettings = Field(default_factory=AISettings)
+    aws: AWSSettings = Field(default_factory=AWSSettings)
+    gcp: GCPSettings = Field(default_factory=GCPSettings)
+    azure: AzureSettings = Field(default_factory=AzureSettings)
+    report: ReportSettings = Field(default_factory=ReportSettings)
+    scan: ScanSettings = Field(default_factory=ScanSettings)
+    log: LogSettings = Field(default_factory=LogSettings)
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return the singleton Settings instance, built from env vars and .env file."""
+    return Settings()
+
+
+def clear_settings_cache() -> None:
+    """Clear the cached settings. Useful in tests."""
+    get_settings.cache_clear()

core/log.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+import structlog
+
+
+def configure_logging() -> None:
+    """
+    Configure structlog for the current runtime.
+
+    - JSON renderer when stdout is not a TTY (Lambda, Cloud Run, Azure Function).
+    - Pretty console renderer when running interactively (local dev / CLI).
+    - Log level controlled by LOG_LEVEL env var (default: INFO).
+
+    Call once at the top of each entrypoint before any logger is used.
+    stdlib logging is bridged so third-party libraries (boto3, google-cloud, azure)
+    also emit structured JSON.
+    """
+    level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
+
+    is_tty = sys.stdout.isatty()
+
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+    ]
+
+    if is_tty:
+        renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer()
+    else:
+        renderer = structlog.processors.JSONRenderer()
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    formatter = structlog.stdlib.ProcessorFormatter(
+        processors=[
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            renderer,
+        ],
+        foreign_pre_chain=shared_processors,
+    )
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(level)
+
+    # Suppress noisy third-party loggers
+    for noisy in ("boto3", "botocore", "urllib3", "google", "azure"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)