argus-cloud-optimizer 0.6.0__tar.gz → 0.6.1__tar.gz

{argus_cloud_optimizer-0.6.0/argus_cloud_optimizer.egg-info → argus_cloud_optimizer-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-cloud-optimizer
-Version: 0.6.0
+Version: 0.6.1
 Summary: Argus — AI Cloud Detective for AWS, GCP, and Azure
 Author-email: Vamshi Siddarth Gaddam <vamshisiddarth02@gmail.com>
 License-Expression: MIT

{argus_cloud_optimizer-0.6.0 → argus_cloud_optimizer-0.6.1/argus_cloud_optimizer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-cloud-optimizer
-Version: 0.6.0
+Version: 0.6.1
 Summary: Argus — AI Cloud Detective for AWS, GCP, and Azure
 Author-email: Vamshi Siddarth Gaddam <vamshisiddarth02@gmail.com>
 License-Expression: MIT

{argus_cloud_optimizer-0.6.0 → argus_cloud_optimizer-0.6.1}/argus_cloud_optimizer.egg-info/SOURCES.txt

@@ -120,4 +120,12 @@ entrypoints/aws_lambda.py
 entrypoints/azure_function.py
 entrypoints/cli.py
 entrypoints/cli_chat.py
-entrypoints/gcp_cloudrun.py
+entrypoints/gcp_cloudrun.py
+integrations/__init__.py
+integrations/base.py
+integrations/jira/__init__.py
+integrations/jira/client.py
+integrations/jira/formatter.py
+integrations/jira/tracker.py
+integrations/jira/webhook.py
+tests/test_packaging.py

{argus_cloud_optimizer-0.6.0 → argus_cloud_optimizer-0.6.1}/argus_cloud_optimizer.egg-info/top_level.txt

@@ -2,3 +2,4 @@ adapters
 ai
 core
 entrypoints
+integrations

argus_cloud_optimizer-0.6.1/core/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.6.1"

{argus_cloud_optimizer-0.6.0 → argus_cloud_optimizer-0.6.1}/docs/remediation/policies.md

@@ -2,6 +2,11 @@
 
 Policies are YAML files that tell Argus which findings deserve a Jira ticket and what action to propose. Argus ships 13 bundled policies; you can add your own in `config/policies/`.
 
+!!! note "Installed from PyPI?"
+    The bundled policies live in the repository's `config/policies/` folder and aren't included in the
+    `pip` package. Copy that folder (or `config/policies.example/`) into your project and set
+    `ARGUS_POLICY_DIR` to it.
+
 !!! tip "Starter templates"
     `config/policies.example/` contains three annotated example policies (EC2 stop, RDS resize, GCE stop) with inline comments explaining every field and production-safe exclude defaults. Copy them to `config/policies/` and edit to match your environment.
 

{argus_cloud_optimizer-0.6.0 → argus_cloud_optimizer-0.6.1}/docs/roadmap.md

@@ -55,6 +55,8 @@ Small, known issues in what has shipped. Not scheduled; contributions welcome.
 - **`BEDROCK_MAX_TOKENS` is ignored.** The Bedrock provider always requests up to 4096 output tokens.
 - **AWS template doesn't expose `RESOURCE_EXPLORER_REGION`.** Deployed Lambdas assume the aggregator index is in `us-east-1` unless you add the variable by hand.
 - **GCP deploy script doesn't enable the Vertex AI API** even though Vertex AI is the default provider on Cloud Run.
+- **Bundled policies aren't in the PyPI package.** `pip install` users don't get `config/policies/`; copy it from the repository (or write your own) and point `ARGUS_POLICY_DIR` at it.
+- **Docs deploys can race.** The docs workflow has no `concurrency` group, so merges landing seconds apart start parallel `mike deploy --push` runs to `gh-pages` and all but the first fail. Re-running the latest failed run fixes the site; adding a concurrency group to `.github/workflows/docs.yml` would prevent it.
 
 ---
 

argus_cloud_optimizer-0.6.1/integrations/base.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from core.remediation.models import ChangeProposal
+
+
+class ChangeTracker(ABC):
+    """
+    Integration-agnostic interface for tracking change proposals.
+
+    v1 implementation: JiraTracker (creates tickets, deduplicates via labels).
+    Future: ServiceNow, Linear, GitHub Issues — same interface, swap the class.
+    """
+
+    @abstractmethod
+    def create(self, proposal: ChangeProposal) -> str:
+        """
+        Record a change proposal and return its URL.
+
+        Implementations must:
+        - Be idempotent: same proposal on a second call returns the existing URL
+        - Update the existing record if the analysis has meaningfully changed
+        - Never raise on transient errors — log and re-raise as TrackerError
+        """
+
+    @abstractmethod
+    def close(self, url: str, reason: str) -> None:
+        """Mark a tracked item as resolved (used when a resource is gone)."""
+
+
+class TrackerError(Exception):
+    """Raised when a tracker operation fails after retries."""

argus_cloud_optimizer-0.6.1/integrations/jira/client.py

@@ -0,0 +1,116 @@
+"""
+Thin Jira REST API wrapper — no Jira SDK, plain requests.
+
+Covers only the operations Argus needs:
+  - search issues by JQL
+  - create issue
+  - add comment
+  - get issue (fetch description for snapshot extraction)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT = 15  # seconds
+
+
+class JiraClient:
+    def __init__(self, base_url: str, email: str, api_token: str) -> None:
+        self._base = base_url.rstrip("/")
+        self._auth = (email, api_token)
+        self._headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def search(self, jql: str, max_results: int = 10) -> list[dict[str, Any]]:
+        """Return list of issue dicts matching the JQL query."""
+        resp = self._get(
+            "/rest/api/3/search",
+            params={
+                "jql": jql,
+                "maxResults": max_results,
+                "fields": "summary,status,description",
+            },
+        )
+        issues: list[dict[str, Any]] = resp.get("issues", [])
+        return issues
+
+    def create_issue(self, fields: dict[str, Any]) -> dict[str, Any]:
+        """Create an issue and return the response dict (contains key + self URL)."""
+        result: dict[str, Any] = self._post(
+            "/rest/api/3/issue", json={"fields": fields}
+        )
+        return result
+
+    def add_comment(self, issue_key: str, body: str | dict[str, Any]) -> None:
+        """Add a comment to an issue. body may be plain text or an ADF dict."""
+        adf_body = body if isinstance(body, dict) else _adf_paragraph(body)
+        self._post(
+            f"/rest/api/3/issue/{issue_key}/comment",
+            json={"body": adf_body},
+        )
+
+    def get_issue(self, issue_key: str) -> dict[str, Any]:
+        """Fetch a single issue by key."""
+        return self._get(
+            f"/rest/api/3/issue/{issue_key}",
+            params={"fields": "summary,status,description"},
+        )
+
+    def issue_url(self, issue_key: str) -> str:
+        return f"{self._base}/browse/{issue_key}"
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, params: dict | None = None) -> dict[str, Any]:
+        resp = requests.get(
+            self._base + path,
+            auth=self._auth,
+            headers=self._headers,
+            params=params,
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+
+    def _post(self, path: str, json: dict | None = None) -> dict[str, Any]:
+        resp = requests.post(
+            self._base + path,
+            auth=self._auth,
+            headers=self._headers,
+            json=json,
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        if resp.content:
+            result: dict[str, Any] = resp.json()
+            return result
+        return {}
+
+
+def _adf_paragraph(text: str) -> dict[str, Any]:
+    """Wrap plain text in Atlassian Document Format (ADF) for API v3."""
+    return {
+        "version": 1,
+        "type": "doc",
+        "content": [
+            {
+                "type": "paragraph",
+                "content": [{"type": "text", "text": text}],
+            }
+        ],
+    }

argus_cloud_optimizer-0.6.1/integrations/jira/formatter.py

@@ -0,0 +1,281 @@
+"""
+Converts a ChangeProposal into Jira issue fields (ADF format).
+
+Description structure:
+  h2 Finding
+    resource details, cost, action
+  h2 Key Metrics
+    table of metrics_summary values
+  h2 Why Argus Flagged This
+    AI waste_reason
+  h2 Recommendation
+    AI recommendation
+  h2 Runbook
+    code block with CLI commands
+  h2 Policy
+    policy_id, weight, source file
+  h2 Full Report  (if report_url given)
+  --- snapshot footer (machine-readable fingerprint for diff-on-update)
+
+Snapshot fingerprint stored in description footer enables dedup and
+change detection on subsequent scans without a separate DB.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import date
+from typing import Any
+
+from core.remediation.models import ChangeProposal
+
+_SNAPSHOT_MARKER = "<!-- argus-snapshot:"
+_SNAPSHOT_END = "-->"
+
+
+def build_issue_fields(
+    proposal: ChangeProposal,
+    *,
+    project: str,
+    issue_type: str,
+    default_labels: list[str],
+    priority_map: dict[str, str],
+    dedup_label: str,
+    report_url: str | None = None,
+) -> dict[str, Any]:
+    """Return the Jira issue fields dict ready to POST to /rest/api/3/issue."""
+    f = proposal.finding
+    p = proposal.policy
+
+    summary = (
+        f"[Argus] {_action_verb(p.action)} {f.name or f.resource_id} "
+        f"(${proposal.estimated_monthly_cost_usd:.0f}/mo · {f.priority} priority)"
+    )
+
+    priority_name = priority_map.get(f.priority, "Medium")
+    labels = list(default_labels) + [
+        dedup_label,
+        f"argus-priority-{f.priority}",
+        f"argus-action-{p.action}",
+    ]
+
+    return {
+        "project": {"key": project},
+        "summary": summary,
+        "description": _build_adf_description(proposal, report_url=report_url),
+        "issuetype": {"name": issue_type},
+        "priority": {"name": priority_name},
+        "labels": labels,
+    }
+
+
+def build_update_comment(
+    proposal: ChangeProposal,
+    stored: dict[str, Any],
+) -> dict[str, Any]:
+    """ADF comment body describing what changed since the last scan."""
+    f = proposal.finding
+    current = fingerprint(proposal)
+    lines = [f"Argus re-scan update — {date.today()}"]
+
+    if stored.get("cost") != current["cost"]:
+        lines.append(f"Cost: ${stored.get('cost', '?')}/mo → ${current['cost']}/mo")
+    if stored.get("priority") != current["priority"]:
+        lines.append(f"Priority: {stored.get('priority', '?')} → {current['priority']}")
+    if stored.get("reason_hash") != current["reason_hash"]:
+        lines.append(f'AI reasoning updated: "{f.waste_reason[:160]}"')
+    lines.append(f"Proposal ID: {proposal.proposal_id}")
+
+    return _adf_paragraph("\n".join(lines))
+
+
+def fingerprint(proposal: ChangeProposal) -> dict[str, Any]:
+    """Compact snapshot of fields that trigger a comment on change.
+
+    Deliberately excludes proposal_id: it is a fresh UUID every scan, so
+    including it made every re-scan look like a change.
+    """
+    return {
+        "cost": round(proposal.estimated_monthly_cost_usd, 0),
+        "priority": proposal.finding.priority,
+        "reason_hash": hashlib.md5(
+            proposal.finding.waste_reason[:120].encode()
+        ).hexdigest()[:8],
+    }
+
+
+FINGERPRINT_KEYS = ("cost", "priority", "reason_hash")
+
+
+def snapshot_changed(stored: dict[str, Any], current: dict[str, Any]) -> bool:
+    """Compare only the fingerprint keys (ignores legacy keys such as proposal_id)."""
+    return any(stored.get(k) != current.get(k) for k in FINGERPRINT_KEYS)
+
+
+def extract_snapshot(description_text: str) -> dict[str, Any] | None:
+    """
+    Parse the argus-snapshot JSON from the issue description footer.
+    Returns None if not present (ticket created by an older version).
+    """
+    start = description_text.find(_SNAPSHOT_MARKER)
+    if start == -1:
+        return None
+    end = description_text.find(_SNAPSHOT_END, start)
+    if end == -1:
+        return None
+    raw = description_text[start + len(_SNAPSHOT_MARKER) : end].strip()
+    try:
+        result: dict[str, Any] = json.loads(raw)
+        return result
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+# ------------------------------------------------------------------
+# ADF builder
+# ------------------------------------------------------------------
+
+
+def _build_adf_description(
+    proposal: ChangeProposal,
+    report_url: str | None,
+) -> dict[str, Any]:
+    f = proposal.finding
+    p = proposal.policy
+    snap = json.dumps(fingerprint(proposal))
+
+    content: list[dict[str, Any]] = []
+
+    # h2 Finding
+    content.append(_adf_heading("Finding", level=2))
+    content.append(
+        _adf_paragraph(
+            f"Resource:  {f.name or f.resource_id}\n"
+            f"Type:      {f.resource_type}\n"
+            f"Cloud:     {f.cloud.upper()}\n"
+            f"Region:    {f.region}\n"
+            f"Cost:      ${proposal.estimated_monthly_cost_usd:.2f}/mo\n"
+            f"Priority:  {f.priority.upper()}\n"
+            f"Action:    {p.action}\n"
+            f"Proposal:  {proposal.proposal_id}"
+        )
+    )
+
+    # h2 Key Metrics (only if present)
+    if f.metrics_summary:
+        content.append(_adf_heading("Key Metrics", level=2))
+        rows = [
+            [
+                _adf_text(k),
+                _adf_text(str(round(v, 4)) if isinstance(v, float) else str(v)),
+            ]
+            for k, v in sorted(f.metrics_summary.items())
+        ]
+        content.append(_adf_table(["Metric", "Value"], rows))
+
+    # h2 Why Argus Flagged This
+    content.append(_adf_heading("Why Argus Flagged This", level=2))
+    content.append(_adf_paragraph(f.waste_reason))
+
+    # h2 Recommendation
+    content.append(_adf_heading("Recommendation", level=2))
+    content.append(_adf_paragraph(f.recommendation))
+    if proposal.resize_recommendation:
+        content.append(_adf_paragraph(f"Rightsizing: {proposal.resize_recommendation}"))
+
+    # h2 Runbook
+    content.append(_adf_heading("Runbook", level=2))
+    content.append(
+        _adf_paragraph(
+            "⚠  Human approval required. Argus does not execute these commands."
+        )
+    )
+    content.append(_adf_code_block(proposal.runbook))
+
+    # h2 Policy
+    content.append(_adf_heading("Policy", level=2))
+    content.append(
+        _adf_paragraph(
+            f"Policy ID:   {p.policy_id}\n"
+            f"Weight:      {p.weight}\n"
+            f"Source:      {p.source_file}"
+        )
+    )
+
+    # h2 Full Report
+    if report_url:
+        content.append(_adf_heading("Full Report", level=2))
+        content.append(_adf_paragraph(report_url))
+
+    # Machine-readable snapshot footer
+    content.append(_adf_paragraph(f"{_SNAPSHOT_MARKER} {snap} {_SNAPSHOT_END}"))
+
+    return {"version": 1, "type": "doc", "content": content}
+
+
+# ------------------------------------------------------------------
+# ADF node helpers
+# ------------------------------------------------------------------
+
+
+def _adf_heading(text: str, level: int) -> dict[str, Any]:
+    return {
+        "type": "heading",
+        "attrs": {"level": level},
+        "content": [{"type": "text", "text": text}],
+    }
+
+
+def _adf_paragraph(text: str) -> dict[str, Any]:
+    return {
+        "type": "paragraph",
+        "content": [{"type": "text", "text": text}],
+    }
+
+
+def _adf_code_block(text: str) -> dict[str, Any]:
+    return {
+        "type": "codeBlock",
+        "attrs": {"language": "bash"},
+        "content": [{"type": "text", "text": text}],
+    }
+
+
+def _adf_text(text: str) -> dict[str, Any]:
+    return {"type": "tableCell", "content": [_adf_paragraph(text)]}
+
+
+def _adf_table(
+    headers: list[str],
+    rows: list[list[dict[str, Any]]],
+) -> dict[str, Any]:
+    header_row = {
+        "type": "tableRow",
+        "content": [
+            {
+                "type": "tableHeader",
+                "content": [_adf_paragraph(h)],
+            }
+            for h in headers
+        ],
+    }
+    body_rows = [{"type": "tableRow", "content": row} for row in rows]
+    return {
+        "type": "table",
+        "attrs": {"isNumberColumnEnabled": False, "layout": "default"},
+        "content": [header_row, *body_rows],
+    }
+
+
+def _action_verb(action: str) -> str:
+    return {
+        "delete": "Delete",
+        "resize": "Resize",
+        "stop": "Stop",
+        "snapshot_delete": "Snapshot & delete",
+        "reduce_replicas": "Reduce replicas for",
+        "reduce_nodes": "Reduce nodes for",
+        "archive": "Archive",
+        "convert_spot": "Convert to Spot",
+    }.get(action, action.capitalize())