aiuse 2.1.0__py3-none-any.whl

aiuse/__init__.py

@@ -0,0 +1,3 @@
+"""Aggregate provider quotas and flag use-it-or-lose-it allotments."""
+
+__version__ = "2.1.0"

aiuse/__main__.py

@@ -0,0 +1,3 @@
+from aiuse.cli import main
+
+raise SystemExit(main())

aiuse/ai_stub.py

@@ -0,0 +1,13 @@
+"""Compatibility stub: ``ai`` invokes the same entrypoint as ``aiuse``."""
+
+from __future__ import annotations
+
+
+def main() -> int:
+    from aiuse.cli import main as aiuse_main
+
+    return aiuse_main()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aiuse/analysis/__init__.py

@@ -0,0 +1,5 @@
+"""Use-it-or-lose-it quota analysis."""
+
+from .use_or_lose import analyze_use_or_lose
+
+__all__ = ["analyze_use_or_lose"]

aiuse/analysis/history.py

@@ -0,0 +1,355 @@
+"""Snapshot persistence and consumption-rate learning (Phase 4 — experimental)."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from aiuse.models import Snapshot, utcnow
+
+_DEFAULT_SNAPSHOT_DIR = "~/.cache/aiuse/snapshots"
+_DEFAULT_RETENTION_DAYS = 90
+_DEFAULT_MIN_SNAPSHOTS = 2
+_DEFAULT_LOOKBACK_DAYS = 7
+
+
+def snapshot_dir() -> Path:
+    return Path(os.path.expanduser(_DEFAULT_SNAPSHOT_DIR))
+
+
+def save_snapshot(snapshot: Snapshot, alerts: list[Any]) -> Path:
+    path = snapshot_dir()
+    path.mkdir(parents=True, exist_ok=True)
+    path.chmod(0o700)
+    # Microseconds keep same-second runs unique and still sort lexicographically.
+    ts = snapshot.collected_at.strftime("%Y-%m-%dT%H%M%S.%fZ")
+    filepath = path / f"{ts}.json"
+    n = 1
+    while filepath.exists():
+        filepath = path / f"{ts}-{n}.json"
+        n += 1
+    payload = {
+        "collected_at": snapshot.collected_at.isoformat(),
+        "accounts": [a.to_dict() for a in snapshot.accounts],
+        "alerts": [a.to_dict() for a in alerts],
+    }
+    text = json.dumps(payload, indent=2, default=str) + "\n"
+    fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(text)
+    return filepath
+
+
+def load_recent_snapshots(
+    *, retention_days: int = _DEFAULT_RETENTION_DAYS, max_count: int = 30
+) -> list[dict[str, Any]]:
+    directory = snapshot_dir()
+    if not directory.is_dir():
+        return []
+    cutoff = utcnow() - timedelta(days=retention_days)
+    snapshots: list[dict[str, Any]] = []
+    for entry in sorted(directory.iterdir(), reverse=True):
+        if not entry.is_file() or not entry.suffix.lower() == ".json":
+            continue
+        try:
+            data = json.loads(entry.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        ts_str = data.get("collected_at")
+        if ts_str:
+            try:
+                collected = datetime.fromisoformat(ts_str)
+                if collected.tzinfo is None:
+                    collected = collected.replace(tzinfo=timezone.utc)
+                if collected < cutoff:
+                    continue
+            except ValueError:
+                continue
+        snapshots.append(data)
+        if len(snapshots) >= max_count:
+            break
+    return snapshots
+
+
+def _account_window_key(account: dict[str, Any], window: dict[str, Any]) -> str:
+    provider = str(account.get("provider", "")).lower()
+    acct = str(account.get("account", "")).lower()
+    label = str(window.get("label", "")).lower()
+    resets = window.get("resets_at") or ""
+    return f"{provider}|{acct}|{label}|{resets}"
+
+
+def compute_learned_burn_rates(
+    *,
+    current: Snapshot,
+    retention_days: int = _DEFAULT_RETENTION_DAYS,
+    min_snapshots: int = _DEFAULT_MIN_SNAPSHOTS,
+) -> dict[str, tuple[float, int]]:
+    """Return ``{'provider:duration_kind': (avg_fraction_per_day, sample_count)}``.
+
+    ``avg_fraction_per_day`` is remaining-percent consumed per day / 100
+    (e.g. 0.30 means ~30% of the window per day).
+
+    Pairs are weighted by elapsed time so multi-minute noise does not dominate
+    day-scale samples. Snapshot pairs that straddle a window reset contribute a
+    reconstructed tail-of-cycle point instead of being dropped.
+    """
+    history = load_recent_snapshots(retention_days=retention_days)
+    if len(history) < min_snapshots:
+        return {}
+
+    provider_window_burns: dict[str, list[tuple[float, float]]] = {}
+
+    now = utcnow()
+    for prev_data in history:
+        ts_str = prev_data.get("collected_at", "")
+        try:
+            prev_time = datetime.fromisoformat(ts_str)
+            if prev_time.tzinfo is None:
+                prev_time = prev_time.replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+
+        time_delta_days = max(0.01, (now - prev_time).total_seconds() / 86400.0)
+        if time_delta_days > retention_days:
+            continue
+        # Weight by elapsed days (capped at 1) so 3-minute pairs barely matter.
+        weight = min(time_delta_days, 1.0)
+
+        for prev_account in prev_data.get("accounts") or []:
+            provider = str(prev_account.get("provider", "")).lower()
+            for prev_window in prev_account.get("windows") or []:
+                prev_remaining = prev_window.get("remaining_percent")
+                if prev_remaining is None:
+                    prev_remaining = _remaining_from_used(prev_window.get("used_percent"))
+                if prev_remaining is None:
+                    continue
+                try:
+                    prev_remaining_f = float(prev_remaining)
+                except (TypeError, ValueError):
+                    continue
+
+                current_remaining = _find_current_remaining(
+                    current, prev_account, prev_window, match_resets=True
+                )
+                burn_rate: float | None = None
+                pair_weight = weight
+
+                if current_remaining is not None:
+                    consumed = prev_remaining_f - current_remaining
+                    if consumed > 0:
+                        burn_rate = consumed / time_delta_days
+                    elif current_remaining > prev_remaining_f:
+                        # Same resets_at match but remaining rose — ignore.
+                        continue
+                    else:
+                        continue
+                else:
+                    # No same-cycle match: try same label (possible reset).
+                    loose = _find_current_remaining(
+                        current, prev_account, prev_window, match_resets=False
+                    )
+                    if loose is None or loose <= prev_remaining_f:
+                        continue
+                    # Reset between snapshots: attribute remaining at prev as
+                    # consumption closed out over prev → previous resets_at.
+                    resets_raw = prev_window.get("resets_at")
+                    days_to_reset = time_delta_days
+                    if resets_raw:
+                        try:
+                            resets_at = datetime.fromisoformat(str(resets_raw).replace("Z", "+00:00"))
+                            if resets_at.tzinfo is None:
+                                resets_at = resets_at.replace(tzinfo=timezone.utc)
+                            if prev_time < resets_at <= now:
+                                days_to_reset = max(0.01, (resets_at - prev_time).total_seconds() / 86400.0)
+                        except ValueError:
+                            pass
+                    burn_rate = prev_remaining_f / days_to_reset
+                    pair_weight = min(days_to_reset, 1.0)
+
+                if burn_rate is None:
+                    continue
+                window_minutes = prev_window.get("window_minutes")
+                duration_key = _duration_key(window_minutes)
+                if duration_key:
+                    pk = f"{provider}:{duration_key}"
+                    provider_window_burns.setdefault(pk, []).append((burn_rate, pair_weight))
+
+    rates: dict[str, tuple[float, int]] = {}
+    for pk, burns in provider_window_burns.items():
+        if len(burns) < 2:
+            continue
+        total_w = sum(w for _, w in burns)
+        if total_w <= 0:
+            continue
+        avg_burn_pct = sum(b * w for b, w in burns) / total_w
+        rates[pk] = (avg_burn_pct / 100.0, len(burns))
+    return rates
+
+
+def compute_learned_flexibility(
+    *,
+    current: Snapshot,
+    retention_days: int = _DEFAULT_RETENTION_DAYS,
+    min_snapshots: int = _DEFAULT_MIN_SNAPSHOTS,
+) -> dict[str, float]:
+    rates = compute_learned_burn_rates(
+        current=current,
+        retention_days=retention_days,
+        min_snapshots=min_snapshots,
+    )
+    return {k: _burn_rate_to_flexibility(rate * 100.0) for k, (rate, _n) in rates.items()}
+
+
+def _burn_rate_to_flexibility(burn_rate_pct_per_day: float) -> float:
+    if burn_rate_pct_per_day >= 80:
+        return 1.0
+    if burn_rate_pct_per_day >= 40:
+        return 0.7 + 0.3 * (burn_rate_pct_per_day - 40) / 40
+    if burn_rate_pct_per_day >= 10:
+        return 0.25 + 0.45 * (burn_rate_pct_per_day - 10) / 30
+    if burn_rate_pct_per_day >= 2:
+        return 0.05 + 0.20 * (burn_rate_pct_per_day - 2) / 8
+    return 0.0
+
+
+def merge_learned_flexibility(
+    base_flex: float,
+    provider: str,
+    duration_kind: str | None,
+    learned: dict[str, float],
+) -> float:
+    if not duration_kind or not learned:
+        return base_flex
+    key = f"{provider.lower().replace(' ', '-')}:{duration_kind}"
+    learned_flex = learned.get(key)
+    # Exact provider match only — never blend another provider's rate for the
+    # same duration bucket (Grok weekly ≠ Codex weekly).
+    if learned_flex is None:
+        return base_flex
+    return 0.3 * learned_flex + 0.7 * base_flex
+
+
+def chronic_waste_summary(
+    *,
+    current: Snapshot,
+    retention_days: int = _DEFAULT_RETENTION_DAYS,
+) -> list[dict[str, Any]]:
+    history = load_recent_snapshots(retention_days=retention_days)
+    if len(history) < _DEFAULT_MIN_SNAPSHOTS:
+        return []
+
+    # samples: list of (resets_at_key, remaining) — at most one per cycle
+    wasted: dict[str, dict[str, Any]] = {}
+
+    for prev_data in history[:7]:
+        ts_str = prev_data.get("collected_at", "")
+        try:
+            prev_time = datetime.fromisoformat(ts_str)
+            if prev_time.tzinfo is None:
+                prev_time = prev_time.replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+
+        for prev_account in prev_data.get("accounts") or []:
+            provider = str(prev_account.get("provider", "")).lower()
+            for prev_window in prev_account.get("windows") or []:
+                window_minutes = prev_window.get("window_minutes")
+                if not window_minutes or window_minutes > 360:
+                    continue
+                prev_remaining = prev_window.get("remaining_percent")
+                if prev_remaining is None:
+                    prev_remaining = _remaining_from_used(prev_window.get("used_percent"))
+                if prev_remaining is None:
+                    continue
+
+                key = f"{provider}:{prev_window.get('label', '')}"
+                resets_key = str(prev_window.get("resets_at") or "") or f"unknown:{ts_str}"
+                bucket = wasted.setdefault(
+                    key,
+                    {
+                        "provider": provider,
+                        "label": prev_window.get("label", ""),
+                        "by_reset": {},  # resets_at -> remaining (most recent wins)
+                    },
+                )
+                # history is newest-first; keep first sample per resets_at
+                if resets_key not in bucket["by_reset"]:
+                    bucket["by_reset"][resets_key] = float(prev_remaining)
+
+    result: list[dict[str, Any]] = []
+    for key, data in wasted.items():
+        by_reset: dict[str, float] = data["by_reset"]
+        if len(by_reset) < 2:
+            continue
+        samples = list(by_reset.values())
+        avg = sum(samples) / len(samples)
+        result.append(
+            {
+                "provider": data["provider"],
+                "label": data["label"],
+                "avg_remaining_pct": round(avg, 1),
+                "sample_count": len(samples),
+            }
+        )
+    result.sort(key=lambda x: x["avg_remaining_pct"], reverse=True)
+    return result
+
+
+def _remaining_from_used(used: Any) -> float | None:
+    if used is None:
+        return None
+    try:
+        return max(0.0, 100.0 - float(used))
+    except (TypeError, ValueError):
+        return None
+
+
+def _find_current_remaining(
+    snapshot: Snapshot,
+    prev_account: dict[str, Any],
+    prev_window: dict[str, Any],
+    *,
+    match_resets: bool = True,
+) -> float | None:
+    prev_provider = str(prev_account.get("provider", "")).lower()
+    prev_account_id = str(prev_account.get("account", "")).lower()
+    prev_label = str(prev_window.get("label", "")).lower()
+    prev_resets = prev_window.get("resets_at") or ""
+
+    for acc in snapshot.accounts:
+        if acc.provider.lower() != prev_provider:
+            continue
+        if (acc.account or "").lower() != prev_account_id:
+            continue
+        for w in acc.windows:
+            if w.label.lower() != prev_label:
+                continue
+            if match_resets and prev_resets:
+                w_resets = w.resets_at.isoformat() if w.resets_at else ""
+                if w_resets != prev_resets:
+                    continue
+            val = w.remaining()
+            if val is not None:
+                return val
+            return _remaining_from_used(w.used_percent)
+    return None
+
+
+def _duration_key(window_minutes: Any) -> str | None:
+    if window_minutes is None:
+        return None
+    try:
+        m = int(window_minutes)
+    except (TypeError, ValueError):
+        return None
+    if m <= 360:
+        return "5h"
+    if m <= 10080:
+        return "weekly"
+    if m <= 44640:
+        return "monthly"
+    return None

aiuse/analysis/pace.py

@@ -0,0 +1,117 @@
+"""Pure pace-math for Phase 2 scoring (not wired into analyze_use_or_lose yet)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from aiuse.models import PaceProfile, QuotaWindow, classify_window_minutes, nominal_window_minutes
+
+
+def compute_pace(
+    window: QuotaWindow,
+    *,
+    now: datetime,
+    learned_rate_per_day: float | None = None,  # fraction/day, e.g. 0.30 == 30%/day
+    learned_sample_count: int = 0,
+    e_min: float = 0.05,
+) -> PaceProfile | None:
+    remaining = window.remaining()
+    if remaining is None:
+        return None
+    used_fraction = (100.0 - remaining) / 100.0
+
+    kind = classify_window_minutes(window.window_minutes)
+    duration_minutes = window.window_minutes or nominal_window_minutes(kind)
+    confidence = "measured" if window.window_minutes else ("inferred" if duration_minutes else "low")
+
+    if not window.resets_at or not duration_minutes:
+        return PaceProfile(
+            elapsed_fraction=None,
+            used_fraction=used_fraction,
+            pace_ratio=None,
+            projected_used_fraction=None,
+            projected_waste_fraction=None,
+            projected_waste_usd=None,
+            projected_exhaust_at=None,
+            confidence="low",
+        )
+
+    t_left_days = max(0.0, (window.resets_at - now).total_seconds() / 86400.0)
+    d_days = duration_minutes / 1440.0
+    elapsed = min(1.0, max(0.0, 1.0 - t_left_days / d_days))
+
+    r_now = used_fraction / (max(elapsed, e_min) * d_days)  # fraction/day
+    if learned_rate_per_day is not None and learned_sample_count > 0:
+        lam = learned_sample_count / (learned_sample_count + 2.0)
+        r_hat = (1 - lam) * r_now + lam * learned_rate_per_day
+    else:
+        r_hat = r_now
+
+    projected_used = min(1.0, used_fraction + r_hat * t_left_days)
+    waste = 1.0 - projected_used
+    exhaust_at = now + timedelta(days=(1.0 - used_fraction) / r_hat) if r_hat > 1e-9 else None
+
+    return PaceProfile(
+        elapsed_fraction=elapsed,
+        used_fraction=used_fraction,
+        pace_ratio=used_fraction / max(elapsed, e_min),
+        projected_used_fraction=projected_used,
+        projected_waste_fraction=waste,
+        projected_waste_usd=None,  # filled in by the caller once it knows the plan price
+        projected_exhaust_at=exhaust_at,
+        confidence=confidence,
+    )
+
+
+def classify_pace(
+    pace: PaceProfile,
+    *,
+    resets_at: datetime | None,
+    waste_alert_fraction: float,
+    min_elapsed_fraction: float,
+    conserve_min_lead_hours: float,
+    has_learned_rate: bool,
+) -> str:
+    """Returns 'conserve' | 'burn' | 'on_pace' | 'unknown'."""
+    if pace.projected_waste_fraction is None and pace.projected_exhaust_at is None:
+        return "unknown"
+    # Too early in the window (no learned rate) → do not trust burn/conserve yet.
+    if (
+        pace.elapsed_fraction is not None
+        and pace.elapsed_fraction < min_elapsed_fraction
+        and not has_learned_rate
+    ):
+        return "on_pace"
+    if pace.projected_exhaust_at and resets_at:
+        if pace.projected_exhaust_at < resets_at - timedelta(hours=conserve_min_lead_hours):
+            return "conserve"
+    if pace.projected_waste_fraction is None:
+        return "unknown"
+    if pace.projected_waste_fraction >= waste_alert_fraction:
+        return "burn"
+    return "on_pace"
+
+def governing_partition(windows: list[QuotaWindow]) -> tuple[QuotaWindow | None, list[QuotaWindow]]:
+    """Longest-duration window with usable remaining() governs; the rest are children.
+
+    When durations tie (e.g. Cursor Included/Auto/API all monthly), prefer a
+    window whose label looks like the overall included bar, then list order.
+    """
+    scored = [
+        (
+            w.window_minutes
+            or nominal_window_minutes(classify_window_minutes(w.window_minutes))
+            or 0,
+            0 if "included" in (w.label or "").casefold() else 1,
+            w,
+        )
+        for w in windows
+        if w.remaining() is not None
+    ]
+    if not scored:
+        return None, list(windows)
+    # Longest minutes first; among ties, included (rank 0) before others.
+    scored.sort(key=lambda pair: (-pair[0], pair[1]))
+    governing = scored[0][2]
+    children = [w for w in windows if w is not governing]
+    return governing, children