opencloudcosts 0.7.0__py3-none-any.whl

opencloudcosts/cache.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+_CREATE_SCHEMA = """
+CREATE TABLE IF NOT EXISTS prices (
+    cache_key   TEXT PRIMARY KEY,
+    provider    TEXT NOT NULL,
+    service     TEXT NOT NULL,
+    region      TEXT NOT NULL,
+    data        TEXT NOT NULL,   -- JSON-serialised payload
+    fetched_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_prices_lookup  ON prices(provider, service, region);
+CREATE INDEX IF NOT EXISTS idx_prices_expiry  ON prices(expires_at);
+
+CREATE TABLE IF NOT EXISTS metadata (
+    cache_key   TEXT PRIMARY KEY,
+    data        TEXT NOT NULL,
+    fetched_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_metadata_expiry ON metadata(expires_at);
+"""
+
+
+def _make_key(*parts: Any) -> str:
+    raw = json.dumps(parts, sort_keys=True, default=str)
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _expires(hours: float) -> str:
+    from datetime import timedelta
+    return (datetime.now(timezone.utc) + timedelta(hours=hours)).isoformat()
+
+
+class CacheManager:
+    def __init__(self, cache_dir: Path) -> None:
+        self._path = cache_dir / "pricing.db"
+        self._db: aiosqlite.Connection | None = None
+
+    async def initialize(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = await aiosqlite.connect(self._path)
+        self._db.row_factory = aiosqlite.Row
+        await self._db.executescript(_CREATE_SCHEMA)
+        await self._db.commit()
+        logger.info("Cache initialised at %s", self._path)
+
+    async def close(self) -> None:
+        if self._db:
+            await self._db.close()
+
+    @property
+    def db(self) -> aiosqlite.Connection:
+        if not self._db:
+            raise RuntimeError("CacheManager not initialised — call initialize() first")
+        return self._db
+
+    # ------------------------------------------------------------------
+    # Prices table
+    # ------------------------------------------------------------------
+
+    async def get_prices(
+        self,
+        provider: str,
+        service: str,
+        region: str,
+        key_extras: dict[str, Any],
+    ) -> list[dict[str, Any]] | None:
+        key = _make_key(provider, service, region, key_extras)
+        async with self.db.execute(
+            "SELECT data, expires_at FROM prices WHERE cache_key = ?", (key,)
+        ) as cur:
+            row = await cur.fetchone()
+        if row is None:
+            return None
+        if datetime.fromisoformat(row["expires_at"]) < datetime.now(timezone.utc):
+            await self.db.execute("DELETE FROM prices WHERE cache_key = ?", (key,))
+            await self.db.commit()
+            return None
+        return json.loads(row["data"])
+
+    async def set_prices(
+        self,
+        provider: str,
+        service: str,
+        region: str,
+        key_extras: dict[str, Any],
+        data: list[dict[str, Any]],
+        ttl_hours: float,
+    ) -> None:
+        key = _make_key(provider, service, region, key_extras)
+        await self.db.execute(
+            """
+            INSERT OR REPLACE INTO prices
+                (cache_key, provider, service, region, data, fetched_at, expires_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (key, provider, service, region, json.dumps(data), _now(), _expires(ttl_hours)),
+        )
+        await self.db.commit()
+
+    # ------------------------------------------------------------------
+    # Metadata table (region lists, attribute values, etc.)
+    # ------------------------------------------------------------------
+
+    async def get_metadata(self, key: str) -> Any | None:
+        async with self.db.execute(
+            "SELECT data, expires_at FROM metadata WHERE cache_key = ?", (key,)
+        ) as cur:
+            row = await cur.fetchone()
+        if row is None:
+            return None
+        if datetime.fromisoformat(row["expires_at"]) < datetime.now(timezone.utc):
+            await self.db.execute("DELETE FROM metadata WHERE cache_key = ?", (key,))
+            await self.db.commit()
+            return None
+        return json.loads(row["data"])
+
+    async def set_metadata(self, key: str, data: Any, ttl_hours: float) -> None:
+        await self.db.execute(
+            """
+            INSERT OR REPLACE INTO metadata (cache_key, data, fetched_at, expires_at)
+            VALUES (?, ?, ?, ?)
+            """,
+            (key, json.dumps(data), _now(), _expires(ttl_hours)),
+        )
+        await self.db.commit()
+
+    # ------------------------------------------------------------------
+    # Cache management
+    # ------------------------------------------------------------------
+
+    async def purge_expired(self) -> int:
+        now = _now()
+        async with self.db.execute(
+            "DELETE FROM prices WHERE expires_at < ?", (now,)
+        ) as cur:
+            prices_deleted = cur.rowcount
+        async with self.db.execute(
+            "DELETE FROM metadata WHERE expires_at < ?", (now,)
+        ) as cur:
+            meta_deleted = cur.rowcount
+        await self.db.commit()
+        return prices_deleted + meta_deleted
+
+    async def clear_all(self) -> dict[str, int]:
+        """Delete all cached prices and metadata — called on server startup."""
+        async with self.db.execute("DELETE FROM prices") as cur:
+            prices_deleted = cur.rowcount
+        async with self.db.execute("DELETE FROM metadata") as cur:
+            meta_deleted = cur.rowcount
+        await self.db.commit()
+        logger.info(
+            "Cache cleared on startup: %d price entries, %d metadata entries",
+            prices_deleted, meta_deleted,
+        )
+        return {"prices_deleted": prices_deleted, "metadata_deleted": meta_deleted}
+
+    async def clear_provider(self, provider: str) -> dict[str, int]:
+        async with self.db.execute(
+            "DELETE FROM prices WHERE provider = ?", (provider,)
+        ) as cur:
+            prices_deleted = cur.rowcount
+        async with self.db.execute(
+            "DELETE FROM metadata WHERE cache_key LIKE ?", (f"{provider}:%",)
+        ) as cur:
+            meta_deleted = cur.rowcount
+        await self.db.commit()
+        logger.info(
+            "Cleared cache for provider %s: %d price entries, %d metadata entries",
+            provider, prices_deleted, meta_deleted,
+        )
+        return {"prices_deleted": prices_deleted, "metadata_deleted": meta_deleted}
+
+    async def stats(self) -> dict[str, Any]:
+        async with self.db.execute("SELECT COUNT(*) as n FROM prices") as cur:
+            prices_count = (await cur.fetchone())["n"]
+        async with self.db.execute("SELECT COUNT(*) as n FROM metadata") as cur:
+            meta_count = (await cur.fetchone())["n"]
+        size_bytes = self._path.stat().st_size if self._path.exists() else 0
+        return {
+            "price_entries": prices_count,
+            "metadata_entries": meta_count,
+            "db_size_mb": round(size_bytes / 1024 / 1024, 2),
+            "db_path": str(self._path),
+        }

opencloudcosts/config.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="OCC_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # General
+    cache_dir: Path = Path.home() / ".cache" / "opencloudcosts"
+    cache_ttl_hours: int = 24
+    metadata_ttl_days: int = 7
+    effective_price_ttl_hours: int = 1
+    spot_cache_ttl_minutes: int = Field(default=5, description="TTL for spot price cache entries in minutes")
+    default_currency: str = "USD"
+    default_regions: list[str] = ["us-east-1", "us-west-2"]
+    max_results: int = 20
+
+    # AWS
+    aws_profile: str | None = None
+    aws_region: str = "us-east-1"
+    # Cost Explorer costs $0.01/call — opt-in only
+    aws_enable_cost_explorer: bool = False
+
+    # GCP (Phase 3)
+    gcp_project_id: str | None = None
+    gcp_billing_dataset: str | None = None
+    gcp_api_key: str | None = None
+
+    # HTTP transport (used with --transport http)
+    http_port: int = Field(default=8080, description="HTTP server port (used with --transport http)")
+    http_host: str = Field(default="127.0.0.1", description="HTTP bind address (used with --transport http)")
+    api_key: str = Field(default="", description="Optional bearer token for HTTP transport authentication")
+
+    @field_validator("cache_dir", mode="before")
+    @classmethod
+    def expand_path(cls, v: str | Path) -> Path:
+        return Path(v).expanduser()

opencloudcosts/models.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CloudProvider(str, Enum):
+    AWS = "aws"
+    GCP = "gcp"
+    AZURE = "azure"
+
+
+class PricingTerm(str, Enum):
+    ON_DEMAND = "on_demand"
+    RESERVED_1YR = "reserved_1yr"
+    RESERVED_3YR = "reserved_3yr"
+    RESERVED_1YR_PARTIAL = "reserved_1yr_partial"
+    RESERVED_1YR_ALL = "reserved_1yr_all"
+    RESERVED_3YR_PARTIAL = "reserved_3yr_partial"
+    RESERVED_3YR_ALL = "reserved_3yr_all"
+    SPOT = "spot"
+    SAVINGS_PLAN = "savings_plan"  # AWS
+    CUD_1YR = "cud_1yr"           # GCP Committed Use Discount 1yr
+    CUD_3YR = "cud_3yr"           # GCP Committed Use Discount 3yr
+    SUD = "sud"                   # GCP Sustained Use Discount
+
+
+class PriceUnit(str, Enum):
+    PER_HOUR = "per_hour"
+    PER_MONTH = "per_month"
+    PER_GB_MONTH = "per_gb_month"
+    PER_GB = "per_gb"
+    PER_IOPS_MONTH = "per_iops_month"
+    PER_REQUEST = "per_request"
+    PER_GB_SECOND = "per_gb_second"    # Lambda duration
+    PER_QUERY = "per_query"            # Route53, Athena
+    PER_UNIT = "per_unit"              # generic fallback
+
+
+class NormalizedPrice(BaseModel):
+    """Provider-agnostic pricing entry — the core data model."""
+    provider: CloudProvider
+    service: str                    # e.g. "compute", "storage", "database"
+    sku_id: str                     # provider-native SKU ID
+    product_family: str             # e.g. "Compute Instance", "Storage"
+    description: str                # human-readable
+    region: str                     # normalized region code (us-east-1, us-east1)
+    attributes: dict[str, str] = Field(default_factory=dict)
+    # ^ instance_type, vcpu, memory_gb, os, storage_type, engine, etc.
+    pricing_term: PricingTerm
+    price_per_unit: Decimal
+    unit: PriceUnit
+    currency: str = "USD"
+    effective_date: datetime | None = None
+
+    @property
+    def monthly_cost(self) -> Decimal:
+        """Convenience: monthly cost assuming 730 hrs/month."""
+        if self.unit == PriceUnit.PER_HOUR:
+            return self.price_per_unit * Decimal("730")
+        if self.unit == PriceUnit.PER_MONTH:
+            return self.price_per_unit
+        return self.price_per_unit
+
+    @property
+    def hourly_cost(self) -> Decimal:
+        if self.unit == PriceUnit.PER_HOUR:
+            return self.price_per_unit
+        if self.unit == PriceUnit.PER_MONTH:
+            return self.price_per_unit / Decimal("730")
+        return self.price_per_unit
+
+    def summary(self) -> dict[str, Any]:
+        """Compact dict for LLM consumption."""
+        from opencloudcosts.utils.regions import region_display_name
+        return {
+            "provider": self.provider.value,
+            "description": self.description,
+            "region": self.region,
+            "region_name": region_display_name(self.provider.value, self.region),
+            "term": self.pricing_term.value,
+            "price": (
+                # Use 2-significant-figure scientific notation for sub-microprice SKUs
+                # (e.g. Lambda per-request at $0.0000002 would show as "$0.000000" at 6dp).
+                # Standard 6dp for everything else.
+                f"${float(self.price_per_unit):.2e} {self.unit.value}"
+                if self.price_per_unit > 0 and self.price_per_unit < Decimal("0.0000005")
+                else f"${self.price_per_unit:.6f} {self.unit.value}"
+            ),
+            "monthly_estimate": f"${self.monthly_cost:.2f}/mo" if self.unit == PriceUnit.PER_HOUR else None,
+            **{k: v for k, v in self.attributes.items() if k in ("instanceType", "vcpu", "memory", "operatingSystem", "storage_type", "volumeType")},
+        }
+
+
+class PriceComparison(BaseModel):
+    """Result of a cross-region or cross-provider price comparison."""
+    query_description: str
+    results: list[NormalizedPrice]
+    cheapest: NormalizedPrice | None = None
+    most_expensive: NormalizedPrice | None = None
+    price_delta_pct: float | None = None   # (most_expensive - cheapest) / cheapest * 100
+
+    @classmethod
+    def from_results(cls, query: str, results: list[NormalizedPrice]) -> "PriceComparison":
+        if not results:
+            return cls(query_description=query, results=[])
+        sorted_results = sorted(results, key=lambda r: r.price_per_unit)
+        cheapest = sorted_results[0]
+        most_expensive = sorted_results[-1]
+        delta = None
+        if cheapest.price_per_unit > 0:
+            delta = float(
+                (most_expensive.price_per_unit - cheapest.price_per_unit)
+                / cheapest.price_per_unit * 100
+            )
+        return cls(
+            query_description=query,
+            results=sorted_results,
+            cheapest=cheapest,
+            most_expensive=most_expensive,
+            price_delta_pct=round(delta, 2) if delta is not None else None,
+        )
+
+
+class BomLineItem(BaseModel):
+    """A single line in a Bill of Materials."""
+    description: str
+    service: str
+    provider: CloudProvider
+    region: str
+    quantity: int
+    hours_per_month: float = 730.0
+    unit_price: NormalizedPrice
+    monthly_cost: Decimal
+    annual_cost: Decimal
+
+    @classmethod
+    def from_price(
+        cls,
+        description: str,
+        price: NormalizedPrice,
+        quantity: int,
+        hours_per_month: float = 730.0,
+        size_gb: float = 1.0,
+    ) -> "BomLineItem":
+        if price.unit == PriceUnit.PER_HOUR:
+            monthly = price.price_per_unit * Decimal(str(hours_per_month)) * quantity
+        elif price.unit == PriceUnit.PER_GB_MONTH:
+            monthly = price.price_per_unit * Decimal(str(size_gb)) * quantity
+        elif price.unit == PriceUnit.PER_MONTH:
+            monthly = price.price_per_unit * quantity
+        else:
+            monthly = price.price_per_unit * quantity
+        return cls(
+            description=description,
+            service=price.service,
+            provider=price.provider,
+            region=price.region,
+            quantity=quantity,
+            hours_per_month=hours_per_month,
+            unit_price=price,
+            monthly_cost=monthly,
+            annual_cost=monthly * 12,
+        )
+
+
+class BomEstimate(BaseModel):
+    """Total cost of ownership for a Bill of Materials."""
+    items: list[BomLineItem]
+    total_monthly: Decimal
+    total_annual: Decimal
+    currency: str = "USD"
+
+    @classmethod
+    def from_items(cls, items: list[BomLineItem], currency: str = "USD") -> "BomEstimate":
+        total_monthly = sum(i.monthly_cost for i in items)
+        return cls(
+            items=items,
+            total_monthly=total_monthly,
+            total_annual=total_monthly * 12,
+            currency=currency,
+        )
+
+
+class EffectivePrice(BaseModel):
+    """Bespoke pricing reflecting actual account discounts."""
+    base_price: NormalizedPrice          # public on-demand price
+    effective_price_per_unit: Decimal    # actual rate after discounts
+    discount_type: str                   # "RI", "SP", "CUD", "EDP", "SUD"
+    discount_pct: float                  # e.g. 35.0 for 35% off
+    commitment_term: str | None = None   # "1yr", "3yr", None for SUD/EDP
+    source: str = ""                     # "cost_explorer", "savings_plans_api", "billing_export"
+
+    @property
+    def savings_vs_on_demand(self) -> Decimal:
+        return self.base_price.price_per_unit - self.effective_price_per_unit
+
+
+class InstanceTypeInfo(BaseModel):
+    """Metadata about a compute instance type."""
+    provider: CloudProvider
+    instance_type: str
+    vcpu: int
+    memory_gb: float
+    gpu_count: int = 0
+    gpu_type: str | None = None
+    network_performance: str | None = None
+    storage: str | None = None
+    region: str
+    available: bool = True