cost-intel 0.1.0__py3-none-any.whl

cost_intel/__init__.py

@@ -0,0 +1,3 @@
+"""Cost Intelligence — AI spending tracker with cost-quality correlation."""
+
+__version__ = "0.1.0"

cost_intel/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m cost_intel`."""
+
+from cost_intel.cli import app
+
+if __name__ == "__main__":
+    app()

cost_intel/adapters/__init__.py

@@ -0,0 +1 @@
+"""Quality score import adapters."""

cost_intel/adapters/braintrust.py

@@ -0,0 +1,67 @@
+"""Braintrust adapter — import quality scores via the Braintrust REST API."""
+
+from typing import Optional
+
+import httpx
+
+from cost_intel.quality import import_score
+
+
+def import_from_api(
+    api_key: str,
+    project_id: str,
+    experiment_id: Optional[str] = None,
+    source: str = "braintrust",
+    base_url: str = "https://api.braintrust.dev/v1",
+) -> int:
+    """Fetch quality scores from Braintrust and import them.
+
+    Args:
+        api_key: Braintrust API key (sent as ``Authorization: Bearer``).
+        project_id: Braintrust project identifier.
+        experiment_id: Optional experiment id. If omitted, all
+            experiments under the project are imported.
+        source: Provenance label written to ``quality_scores.source``.
+        base_url: Braintrust API base URL.
+
+    Returns:
+        Count of imported rows.
+    """
+    headers = {"Authorization": f"Bearer {api_key}"}
+    count = 0
+
+    with httpx.Client(base_url=base_url, headers=headers, timeout=30) as client:
+        if experiment_id:
+            exp_ids = [experiment_id]
+        else:
+            resp = client.get(f"/projects/{project_id}/experiments")
+            resp.raise_for_status()
+            experiments = resp.json().get("data", [])
+            exp_ids = [exp["id"] for exp in experiments]
+
+        for eid in exp_ids:
+            resp = client.get(f"/experiments/{eid}/events")
+            resp.raise_for_status()
+            events = resp.json().get("data", [])
+
+            for event in events:
+                run_id = event.get("run_id") or event.get("id")
+                scores = event.get("scores", {})
+                if not run_id or not scores:
+                    continue
+                score_val = scores.get("quality") or scores.get("score")
+                if score_val is None:
+                    numeric = [
+                        v for v in scores.values() if isinstance(v, (int, float))
+                    ]
+                    score_val = numeric[0] if numeric else None
+                if score_val is not None:
+                    import_score(
+                        run_id=str(run_id),
+                        score=float(score_val),
+                        source=source,
+                        eval_dimensions=scores if len(scores) > 1 else None,
+                    )
+                    count += 1
+
+    return count

cost_intel/adapters/eval_harness.py

@@ -0,0 +1,53 @@
+"""Eval Harness adapter — import quality scores from a SQLite database."""
+
+import sqlite3
+
+from cost_intel.quality import import_score
+
+
+def import_from_db(
+    db_path: str,
+    source: str = "eval_harness",
+    run_id_column: str = "run_id",
+    score_column: str = "score",
+) -> int:
+    """Read scores from an Eval Harness SQLite DB and import them.
+
+    The adapter tries the ``results`` table first, then ``eval_results``
+    as a fallback. Returns ``0`` if neither table exists.
+
+    Args:
+        db_path: Filesystem path to the Eval Harness database.
+        source: Provenance label written to ``quality_scores.source``.
+        run_id_column: Name of the column holding the run id.
+        score_column: Name of the column holding the score.
+
+    Returns:
+        Count of imported rows.
+    """
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    rows: list = []
+    try:
+        try:
+            rows = conn.execute(
+                f"SELECT {run_id_column}, {score_column} FROM results"
+            ).fetchall()
+        except sqlite3.OperationalError:
+            try:
+                rows = conn.execute(
+                    f"SELECT {run_id_column}, {score_column} FROM eval_results"
+                ).fetchall()
+            except sqlite3.OperationalError:
+                return 0
+    finally:
+        conn.close()
+
+    count = 0
+    for row in rows:
+        run_id = str(row[run_id_column]) if row[run_id_column] else None
+        score = float(row[score_column]) if row[score_column] is not None else None
+        if run_id and score is not None:
+            import_score(run_id=run_id, score=score, source=source)
+            count += 1
+    return count

cost_intel/alerts.py

@@ -0,0 +1,134 @@
+"""Budget alert dispatch — Slack webhook + SMTP email."""
+
+import smtplib
+from email.mime.text import MIMEText
+from typing import Any
+
+import httpx
+
+from cost_intel.budget import get_budget_status
+from cost_intel.config import load_config
+
+
+def send_slack_alert(webhook_url: str, message: str) -> bool:
+    """Send alert to Slack via incoming webhook.
+
+    Args:
+        webhook_url: Slack incoming webhook URL.
+        message: Plain text body for the Slack message.
+
+    Returns:
+        True on HTTP 200 response, False otherwise (including empty URL
+        or any exception).
+    """
+    if not webhook_url:
+        return False
+    try:
+        resp = httpx.post(
+            webhook_url,
+            json={"text": message},
+            timeout=10.0,
+        )
+        return resp.status_code == 200
+    except Exception:
+        return False
+
+
+def send_email_alert(
+    smtp_host: str,
+    smtp_from: str,
+    recipients: list[str],
+    subject: str,
+    body: str,
+) -> bool:
+    """Send alert via SMTP.
+
+    Args:
+        smtp_host: SMTP server hostname.
+        smtp_from: Sender address.
+        recipients: List of recipient addresses.
+        subject: Email subject.
+        body: Plain text email body.
+
+    Returns:
+        True on success, False if smtp_host or recipients are empty,
+        or on any exception.
+    """
+    if not smtp_host or not recipients:
+        return False
+    try:
+        msg = MIMEText(body)
+        msg["Subject"] = subject
+        msg["From"] = smtp_from
+        msg["To"] = ", ".join(recipients)
+
+        with smtplib.SMTP(smtp_host) as server:
+            server.sendmail(smtp_from, recipients, msg.as_string())
+        return True
+    except Exception:
+        return False
+
+
+def _build_alert_message(status: dict[str, Any]) -> str:
+    """Build a human-readable alert message from a budget status dict."""
+    return (
+        "⚠️ Cost Intelligence Budget Alert\n"
+        f"Budget: ${status['monthly']:.2f}/month\n"
+        f"Spent: ${status['spent']:.2f} ({status['percent_used']:.1f}%)\n"
+        f"Remaining: ${status['remaining']:.2f}\n"
+        f"Alert threshold: {status['alert_threshold']}%"
+    )
+
+
+def check_and_alert() -> dict[str, Any]:
+    """Check budget status and dispatch alerts when threshold is reached.
+
+    Reads ``slack_webhook_url``, ``smtp_host``, ``smtp_from``, and
+    ``alert_recipients`` from config and routes the alert message to each
+    configured channel.
+
+    Returns:
+        Dict with keys ``triggered`` (bool), ``alert_sent`` (bool), and
+        ``message`` (str). ``alert_sent`` is True when at least one
+        channel reported a successful dispatch.
+    """
+    result: dict[str, Any] = {
+        "triggered": False,
+        "alert_sent": False,
+        "message": "",
+    }
+
+    status = get_budget_status()
+    if not status["budget_set"]:
+        return result
+
+    if status["percent_used"] < status["alert_threshold"]:
+        return result
+
+    message = _build_alert_message(status)
+    result["triggered"] = True
+    result["message"] = message
+
+    cfg = load_config()
+    slack_webhook_url = cfg.get("slack_webhook_url", "") or ""
+    smtp_host = cfg.get("smtp_host", "") or ""
+    smtp_from = cfg.get("smtp_from", "") or ""
+    recipients = cfg.get("alert_recipients", []) or []
+
+    any_sent = False
+    if slack_webhook_url:
+        any_sent = send_slack_alert(slack_webhook_url, message) or any_sent
+    if smtp_host and recipients:
+        any_sent = (
+            send_email_alert(
+                smtp_host=smtp_host,
+                smtp_from=smtp_from,
+                recipients=list(recipients),
+                subject="Cost Intelligence Budget Alert",
+                body=message,
+            )
+            or any_sent
+        )
+
+    result["alert_sent"] = any_sent
+    return result

cost_intel/budget.py

@@ -0,0 +1,74 @@
+"""Budget management — set, status, and alert tracking."""
+
+from cost_intel.db import connect
+
+
+def set_budget(monthly: float, alert_threshold: int = 80) -> None:
+    """Set the monthly budget and alert threshold.
+
+    Args:
+        monthly: Monthly budget in USD.
+        alert_threshold: Percentage at which to trigger alerts (0-100).
+    """
+    with connect() as conn:
+        conn.execute(
+            "INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)",
+            ("monthly_budget", str(monthly)),
+        )
+        conn.execute(
+            "INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)",
+            ("alert_threshold", str(alert_threshold)),
+        )
+
+
+def get_budget_status() -> dict:
+    """Get current budget status including spending.
+
+    Returns:
+        Dict with budget_set, monthly, alert_threshold, spent,
+        remaining, percent_used.
+    """
+    with connect() as conn:
+        budget_row = conn.execute(
+            "SELECT value FROM config WHERE key = ?",
+            ("monthly_budget",),
+        ).fetchone()
+        threshold_row = conn.execute(
+            "SELECT value FROM config WHERE key = ?",
+            ("alert_threshold",),
+        ).fetchone()
+
+    if budget_row is None:
+        return {
+            "budget_set": False,
+            "monthly": None,
+            "alert_threshold": None,
+            "spent": 0.0,
+            "remaining": None,
+            "percent_used": 0.0,
+        }
+
+    monthly = float(budget_row["value"])
+    alert_threshold = int(threshold_row["value"]) if threshold_row else 80
+
+    # Calculate current month spending
+    with connect() as conn:
+        spent_row = conn.execute(
+            "SELECT COALESCE(SUM(call_cost), 0) as spent "
+            "FROM cost_run_calls crc "
+            "JOIN cost_runs cr ON crc.run_id = cr.run_id "
+            "WHERE cr.started_at >= date('now', 'start of month')"
+        ).fetchone()
+    spent = float(spent_row["spent"]) if spent_row else 0.0
+
+    remaining = max(0.0, monthly - spent)
+    percent_used = (spent / monthly * 100) if monthly > 0 else 0.0
+
+    return {
+        "budget_set": True,
+        "monthly": monthly,
+        "alert_threshold": alert_threshold,
+        "spent": round(spent, 2),
+        "remaining": round(remaining, 2),
+        "percent_used": round(percent_used, 1),
+    }