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

core/models/finding.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal
+
+Cloud = Literal["aws", "gcp", "azure"]
+Priority = Literal["high", "medium", "low"]
+FindingStatus = Literal["new", "recurring", "resolved"]
+
+
+@dataclass
+class ResourceFinding:
+    """
+    Universal representation of a single idle/wasteful cloud resource.
+    Produced by the agent loop, consumed by the report generator.
+    No cloud SDK imports — pure Python.
+    """
+
+    resource_id: str
+    resource_type: str  # e.g. "AWS::EC2::Instance", "AWS::RDS::DBInstance"
+    cloud: Cloud  # "aws" | "gcp" | "azure"
+    region: str
+    estimated_monthly_cost: float  # USD
+    waste_reason: str  # AI-written: why this resource is idle/wasteful
+    recommendation: str  # AI-written: specific action to take
+    priority: Priority  # AI-assigned based on cost + confidence
+    metrics_summary: dict[str, Any]  # key signals used to reach this conclusion
+    tags: dict[str, str]
+    scan_time: datetime
+    name: str | None = None
+    last_activity: datetime | None = None
+    status: FindingStatus = "new"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "resource_id": self.resource_id,
+            "resource_type": self.resource_type,
+            "cloud": self.cloud,
+            "region": self.region,
+            "name": self.name,
+            "estimated_monthly_cost": self.estimated_monthly_cost,
+            "waste_reason": self.waste_reason,
+            "recommendation": self.recommendation,
+            "priority": self.priority,
+            "metrics_summary": self.metrics_summary,
+            "tags": self.tags,
+            "last_activity": (
+                self.last_activity.isoformat() if self.last_activity else None
+            ),
+            "scan_time": self.scan_time.isoformat(),
+            "status": self.status,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], scan_time: datetime) -> ResourceFinding:
+        last_activity = None
+        if data.get("last_activity"):
+            last_activity = datetime.fromisoformat(data["last_activity"])
+
+        return cls(
+            resource_id=data["resource_id"],
+            resource_type=data["resource_type"],
+            cloud=data["cloud"],
+            region=data["region"],
+            name=data.get("name"),
+            estimated_monthly_cost=float(data["estimated_monthly_cost"]),
+            waste_reason=data["waste_reason"],
+            recommendation=data["recommendation"],
+            priority=data["priority"],
+            metrics_summary=data.get("metrics_summary", {}),
+            tags=data.get("tags", {}),
+            last_activity=last_activity,
+            scan_time=scan_time,
+            status=data.get("status", "new"),
+        )

core/reports/comparison.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from core.models.finding import ResourceFinding
+
+
+def compare_scans(
+    current_findings: list[ResourceFinding],
+    previous_report: dict[str, Any] | None,
+) -> tuple[list[ResourceFinding], dict[str, Any]]:
+    """
+    Compare current findings against a previous report and label each finding's status.
+
+    Returns:
+        (labelled_findings, diff_summary)
+        labelled_findings: current findings with status set to "new" or "recurring"
+        diff_summary: dict with new/recurring/resolved counts
+                      and resolved_resource_ids
+    """
+    if not previous_report:
+        for f in current_findings:
+            f.status = "new"
+        return current_findings, {
+            "previous_scan_id": None,
+            "new_findings": len(current_findings),
+            "recurring_findings": 0,
+            "resolved_findings": 0,
+            "resolved_resource_ids": [],
+        }
+
+    prev_resource_ids = {f["resource_id"] for f in previous_report.get("findings", [])}
+    current_resource_ids = {f.resource_id for f in current_findings}
+
+    for f in current_findings:
+        f.status = "recurring" if f.resource_id in prev_resource_ids else "new"
+
+    resolved_ids = sorted(prev_resource_ids - current_resource_ids)
+
+    new_count = sum(1 for f in current_findings if f.status == "new")
+    recurring_count = sum(1 for f in current_findings if f.status == "recurring")
+
+    return current_findings, {
+        "previous_scan_id": previous_report.get("scan_id"),
+        "new_findings": new_count,
+        "recurring_findings": recurring_count,
+        "resolved_findings": len(resolved_ids),
+        "resolved_resource_ids": resolved_ids,
+    }

core/reports/delivery.py

@@ -0,0 +1,323 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class NotificationDeliveryError(Exception):
+    """Raised when a notification provider fails to deliver."""
+
+
+class SlackDeliveryError(NotificationDeliveryError):
+    """Raised when Slack rejects the webhook payload."""
+
+
+class TeamsDeliveryError(NotificationDeliveryError):
+    """Raised when Teams rejects the webhook payload."""
+
+
+class WebhookDeliveryError(NotificationDeliveryError):
+    """Raised when a generic webhook call fails."""
+
+
+# ---------------------------------------------------------------------------
+# NotificationProvider ABC
+# ---------------------------------------------------------------------------
+
+
+class NotificationProvider(ABC):
+    @abstractmethod
+    def notify(self, payload: dict[str, Any]) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Slack
+# ---------------------------------------------------------------------------
+
+
+class SlackNotificationProvider(NotificationProvider):
+    def __init__(self, webhook_url: str | None = None) -> None:
+        from core.config import get_settings
+
+        self._url = (
+            webhook_url
+            if webhook_url is not None
+            else get_settings().report.slack_webhook_url
+        )
+
+    def notify(self, payload: dict[str, Any]) -> None:
+        if not self._url:
+            raise EnvironmentError(
+                "SLACK_WEBHOOK_URL is not set. "
+                "Export it or pass webhook_url= explicitly."
+            )
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(
+            self._url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                response_text = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raise SlackDeliveryError(
+                f"Slack webhook returned HTTP {exc.code}: {exc.reason}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise SlackDeliveryError(
+                f"Failed to reach Slack webhook: {exc.reason}"
+            ) from exc
+
+        if response_text.strip() != "ok":
+            raise SlackDeliveryError(f"Unexpected Slack response: {response_text!r}")
+
+        logger.info("slack_report_delivered")
+
+
+# ---------------------------------------------------------------------------
+# Microsoft Teams (Office 365 Incoming Webhook)
+# ---------------------------------------------------------------------------
+
+
+class TeamsNotificationProvider(NotificationProvider):
+    def __init__(self, webhook_url: str | None = None) -> None:
+        from core.config import get_settings
+
+        self._url = (
+            webhook_url
+            if webhook_url is not None
+            else get_settings().report.teams_webhook_url
+        )
+
+    def notify(self, payload: dict[str, Any]) -> None:
+        if not self._url:
+            raise EnvironmentError(
+                "TEAMS_WEBHOOK_URL is not set. "
+                "Export it or pass webhook_url= explicitly."
+            )
+        teams_payload = self._to_teams_card(payload)
+        body = json.dumps(teams_payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(
+            self._url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                resp.read()
+        except urllib.error.HTTPError as exc:
+            raise TeamsDeliveryError(
+                f"Teams webhook returned HTTP {exc.code}: {exc.reason}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise TeamsDeliveryError(
+                f"Failed to reach Teams webhook: {exc.reason}"
+            ) from exc
+
+        logger.info("teams_report_delivered")
+
+    def _to_teams_card(self, slack_payload: dict[str, Any]) -> dict[str, Any]:
+        text_parts: list[str] = []
+        for block in slack_payload.get("blocks", []):
+            if block.get("type") == "section":
+                text_obj = block.get("text", {})
+                text_parts.append(text_obj.get("text", ""))
+            elif block.get("type") == "header":
+                text_obj = block.get("text", {})
+                text_parts.append(f"**{text_obj.get('text', '')}**")
+
+        return {
+            "@type": "MessageCard",
+            "@context": "http://schema.org/extensions",
+            "summary": "Argus Cost Report",
+            "themeColor": "0076D7",
+            "title": "Argus Cost Optimization Report",
+            "text": "\n\n".join(text_parts),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Generic Webhook (HTTP POST with raw JSON)
+# ---------------------------------------------------------------------------
+
+
+class WebhookNotificationProvider(NotificationProvider):
+    def __init__(self, webhook_url: str | None = None) -> None:
+        from core.config import get_settings
+
+        self._url = (
+            webhook_url
+            if webhook_url is not None
+            else get_settings().report.webhook_url
+        )
+
+    def notify(self, payload: dict[str, Any]) -> None:
+        if not self._url:
+            raise EnvironmentError(
+                "WEBHOOK_URL is not set. " "Export it or pass webhook_url= explicitly."
+            )
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(
+            self._url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                resp.read()
+        except urllib.error.HTTPError as exc:
+            raise WebhookDeliveryError(
+                f"Webhook returned HTTP {exc.code}: {exc.reason}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise WebhookDeliveryError(
+                f"Failed to reach webhook: {exc.reason}"
+            ) from exc
+
+        logger.info("webhook_report_delivered")
+
+
+# ---------------------------------------------------------------------------
+# Provider registry + dispatcher
+# ---------------------------------------------------------------------------
+
+_PROVIDER_MAP: dict[str, type[NotificationProvider]] = {
+    "slack": SlackNotificationProvider,
+    "teams": TeamsNotificationProvider,
+    "webhook": WebhookNotificationProvider,
+}
+
+
+def build_notification_providers() -> list[NotificationProvider]:
+    raw = os.environ.get("NOTIFICATION_PROVIDER", "slack")
+    names = [n.strip().lower() for n in raw.split(",") if n.strip()]
+    providers: list[NotificationProvider] = []
+    for name in names:
+        cls = _PROVIDER_MAP.get(name)
+        if cls is None:
+            logger.warning("unknown_notification_provider", provider=name)
+            continue
+        providers.append(cls())
+    return providers
+
+
+def notify_all(payload: dict[str, Any], dry_run: bool | None = None) -> None:
+    from core.config import get_settings
+
+    resolved_dry_run = (
+        dry_run if dry_run is not None else get_settings().report.dry_run
+    )
+
+    if resolved_dry_run:
+        logger.info(
+            "dry_run_notification_skipped",
+            payload_preview=json.dumps(payload, indent=2)[:500],
+        )
+        return
+
+    providers = build_notification_providers()
+    for provider in providers:
+        try:
+            provider.notify(payload)
+        except (NotificationDeliveryError, OSError) as exc:
+            logger.error(
+                "notification_delivery_failed",
+                provider=type(provider).__name__,
+                error=str(exc),
+            )
+
+
+# ---------------------------------------------------------------------------
+# Legacy function — delegates to notify_all for backward compatibility
+# ---------------------------------------------------------------------------
+
+
+def post_to_slack(
+    payload: dict[str, Any],
+    webhook_url: str | None = None,
+    dry_run: bool | None = None,
+) -> None:
+    from core.config import get_settings
+
+    resolved_dry_run = (
+        dry_run if dry_run is not None else get_settings().report.dry_run
+    )
+
+    if resolved_dry_run:
+        logger.info(
+            "[DRY RUN] Slack payload (not sent):\n%s", json.dumps(payload, indent=2)
+        )
+        return
+
+    provider = SlackNotificationProvider(webhook_url=webhook_url)
+    provider.notify(payload)
+
+
+# ---------------------------------------------------------------------------
+# Local report saving (unchanged)
+# ---------------------------------------------------------------------------
+
+
+def save_reports_locally(
+    report: dict[str, Any],
+    base_dir: str | None = None,
+) -> str:
+    from core.config import get_settings
+    from core.reports.export import export_pdf, export_pptx, get_report_formats
+
+    resolved_dir = Path(base_dir or get_settings().report.local_report_dir)
+    now = datetime.now(tz=timezone.utc)
+    prefix = (
+        resolved_dir / report["cloud"] / now.strftime("%Y/%m/%d") / report["scan_id"]
+    )
+    prefix.parent.mkdir(parents=True, exist_ok=True)
+
+    formats = get_report_formats()
+    result_path = str(prefix)
+
+    if "json" in formats:
+        json_path = prefix.with_suffix(".json")
+        json_path.write_text(
+            json.dumps(report, indent=2, default=str), encoding="utf-8"
+        )
+        logger.info("json_report_saved", path=str(json_path))
+
+    if "html" in formats:
+        from core.reports.html import build_html_report
+
+        html_path = prefix.with_suffix(".html")
+        html_path.write_text(build_html_report(report), encoding="utf-8")
+        logger.info("html_report_saved", path=str(html_path))
+        result_path = str(html_path.resolve())
+
+    if "pdf" in formats:
+        try:
+            export_pdf(report, prefix)
+        except ImportError as exc:
+            logger.warning("pdf_export_skipped", reason=str(exc))
+
+    if "pptx" in formats:
+        try:
+            export_pptx(report, prefix)
+        except ImportError as exc:
+            logger.warning("pptx_export_skipped", reason=str(exc))
+
+    return result_path

core/reports/export.py

@@ -0,0 +1,111 @@
+"""
+Multi-format report export: PDF and PPTX.
+
+Both are optional — the libraries are only imported when the format is requested.
+Install with: pip install weasyprint python-pptx
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+def get_report_formats() -> set[str]:
+    from core.config import get_settings
+
+    return get_settings().report.formats
+
+
+def export_pdf(report: dict[str, Any], output_path: Path) -> Path:
+    try:
+        from weasyprint import HTML  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ImportError(
+            "weasyprint is required for PDF export. "
+            "Install with: pip install weasyprint"
+        ) from exc
+
+    from core.reports.html import build_html_report
+
+    html_content = build_html_report(report)
+    pdf_path = output_path.with_suffix(".pdf")
+    HTML(string=html_content).write_pdf(str(pdf_path))
+    logger.info("pdf_report_saved", path=str(pdf_path))
+    return pdf_path
+
+
+def export_pptx(report: dict[str, Any], output_path: Path) -> Path:
+    try:
+        from pptx import Presentation  # type: ignore[import-untyped]
+        from pptx.util import Inches  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ImportError(
+            "python-pptx is required for PPTX export. "
+            "Install with: pip install python-pptx"
+        ) from exc
+
+    prs = Presentation()
+    prs.slide_width = Inches(13.333)
+    prs.slide_height = Inches(7.5)
+
+    # Title slide
+    slide = prs.slides.add_slide(prs.slide_layouts[0])
+    slide.shapes.title.text = f"Argus — {report['cloud'].upper()} Waste Report"
+    slide.placeholders[1].text = (
+        f"Generated: {report['generated_at'][:10]}\n"
+        f"Total estimated waste: ${report['total_estimated_waste_usd']:,.2f}/month\n"
+        f"Findings: {report['findings_count']}"
+    )
+
+    # Executive summary slide
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    slide.shapes.title.text = "Executive Summary"
+    slide.placeholders[1].text = report.get("executive_summary", "")
+
+    # Top findings slide(s) — max 8 per slide
+    findings = report.get("findings", [])
+    chunk_size = 8
+    for i in range(0, len(findings), chunk_size):
+        chunk = findings[i : i + chunk_size]
+        slide = prs.slides.add_slide(prs.slide_layouts[1])
+        slide.shapes.title.text = (
+            f"Top Findings ({i + 1}–{i + len(chunk)} of {len(findings)})"
+        )
+        lines = []
+        for f in chunk:
+            name = f.get("name") or f["resource_id"]
+            cost = f["estimated_monthly_cost"]
+            priority = (f.get("priority") or "low").upper()
+            lines.append(
+                f"[{priority}] {name} — {f['resource_type']} — " f"${cost:,.2f}/mo"
+            )
+            lines.append(f"  → {f.get('recommendation', '')}")
+        slide.placeholders[1].text = "\n".join(lines)
+
+    # Scan metadata slide
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    slide.shapes.title.text = "Scan Details"
+    meta_lines = [
+        f"Scan ID: {report['scan_id']}",
+        f"Cloud: {report['cloud']}",
+        f"Accounts: {', '.join(report.get('accounts_scanned', []))}",
+    ]
+    if report.get("agent_input_tokens"):
+        meta_lines.append(
+            f"AI tokens: {report['agent_input_tokens']:,} in / "
+            f"{report['agent_output_tokens']:,} out"
+        )
+        meta_lines.append(
+            f"Estimated AI cost: ${report.get('estimated_agent_cost_usd', 0):.4f}"
+        )
+    slide.placeholders[1].text = "\n".join(meta_lines)
+
+    pptx_path = output_path.with_suffix(".pptx")
+    prs.save(str(pptx_path))
+    logger.info("pptx_report_saved", path=str(pptx_path))
+    return pptx_path