plutus-agent 0.2.0__py3-none-any.whl

plutus_agent/__init__.py

@@ -0,0 +1,39 @@
+"""Plutus — the billing layer for AI agents.
+
+Self-hosted, Stripe-integrated usage metering and prepaid-credit billing for
+LLM / AI-agent spend. Multi-tenant (organizations → workspaces → users), meters
+usage per workspace / provider / task-type, depletes prepaid credits as calls
+route through, and serves a dark-themed real-time dashboard at :8420.
+
+Everything except Stripe works fully offline. State lives in SQLite
+(``~/.plutus/plutus.db`` by default); configuration in ``~/.plutus/config.yaml``.
+
+This package is the *monetization engine*. The original credit monitor and
+runway router (``plutus.py`` / ``plutus_route.py`` at the repo root) remain the
+live FinOps tools; the engine bridges to them via ``plutus_agent.bridge`` rather
+than importing them, so the two can ship and run independently.
+"""
+
+__version__ = "0.2.0"
+__product__ = "Plutus"
+__tagline__ = "The billing layer for AI agents."
+__company__ = "Perseus Computing LLC"
+__homepage__ = "https://perseus.observer/plutus/"
+__default_port__ = 8420
+
+__all__ = [
+    "__version__",
+    "__product__",
+    "__tagline__",
+    "__default_port__",
+    "Meter",
+]
+
+
+def __getattr__(name):
+    # Lazy export so `from plutus_agent import Meter` works without importing
+    # the world at package-load time.
+    if name == "Meter":
+        from .client import Meter
+        return Meter
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

plutus_agent/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m plutus_agent`` → the CLI."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

plutus_agent/alerts.py

@@ -0,0 +1,116 @@
+"""Alerts — email notifications for low balance and budget caps.
+
+Alerts are *raised* during metering (``metering._check_thresholds`` logs them to
+``alerts_log``). This module is the *delivery* side: it picks up undelivered
+alerts and emails them via SMTP. It is offline-safe — with alerts disabled or
+SMTP unconfigured, :func:`send_pending` runs as a dry run, returning what *would*
+be sent without touching the network, and leaves the alerts marked undelivered.
+"""
+from __future__ import annotations
+
+import smtplib
+import ssl
+from email.message import EmailMessage
+from typing import Optional
+
+from . import db
+
+
+def pending(conn, org_id: str) -> list[dict]:
+    rows = conn.execute(
+        "SELECT * FROM alerts_log WHERE org_id=? AND delivered=0 ORDER BY ts",
+        (org_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _mark_delivered(conn, alert_id: str) -> None:
+    conn.execute("UPDATE alerts_log SET delivered=1 WHERE id=?", (alert_id,))
+    conn.commit()
+
+
+def _build_message(alert: dict, from_addr: str, to_addrs: list[str],
+                   org_name: str) -> EmailMessage:
+    kind = alert["kind"].replace("_", " ").title()
+    msg = EmailMessage()
+    msg["Subject"] = f"[Plutus] {kind} — {org_name}"
+    msg["From"] = from_addr
+    msg["To"] = ", ".join(to_addrs)
+    msg.set_content(
+        f"{alert['message']}\n\n"
+        f"Organization: {org_name}\n"
+        f"Alert type:   {alert['kind']}\n\n"
+        f"— Plutus, the billing layer for AI agents\n"
+        f"  https://perseus.observer/plutus/\n"
+    )
+    return msg
+
+
+def send_pending(conn, cfg: dict, org_id: str,
+                 force: bool = False) -> dict:
+    """Deliver undelivered alerts for an org. Returns a summary.
+
+    ``force`` bypasses the ``alerts.enabled`` gate (used by ``plutus alerts
+    --test``). SMTP is still required to actually send; without it this is a dry
+    run.
+    """
+    acfg = cfg.get("alerts", {})
+    org = db.get_org(conn, org_id)
+    org_name = org["name"] if org else org_id
+    items = pending(conn, org_id)
+    if not items:
+        return {"sent": 0, "dry_run": False, "pending": 0, "detail": "nothing pending"}
+
+    enabled = acfg.get("enabled") or force
+    to_addrs = acfg.get("to_addrs") or []
+    smtp_host = acfg.get("smtp_host") or ""
+    can_send = bool(enabled and smtp_host and to_addrs)
+
+    if not can_send:
+        reason = []
+        if not enabled:
+            reason.append("alerts.enabled is false")
+        if not smtp_host:
+            reason.append("no smtp_host")
+        if not to_addrs:
+            reason.append("no to_addrs")
+        return {
+            "sent": 0, "dry_run": True, "pending": len(items),
+            "would_send": [a["message"] for a in items],
+            "detail": "dry run — " + "; ".join(reason),
+        }
+
+    from_addr = acfg.get("from_addr", "plutus@perseus.observer")
+    port = int(acfg.get("smtp_port", 587))
+    user = acfg.get("smtp_user") or ""
+    password = acfg.get("smtp_password") or ""
+
+    sent = 0
+    errors = []
+    try:
+        ctx = ssl.create_default_context()
+        with smtplib.SMTP(smtp_host, port, timeout=20) as server:
+            server.ehlo()
+            if port in (587,):
+                server.starttls(context=ctx)
+                server.ehlo()
+            if user:
+                server.login(user, password)
+            for a in items:
+                try:
+                    server.send_message(_build_message(a, from_addr, to_addrs, org_name))
+                    _mark_delivered(conn, a["id"])
+                    sent += 1
+                except Exception as e:  # one bad alert shouldn't sink the rest
+                    errors.append(f"{a['id']}: {e}")
+    except Exception as e:
+        return {"sent": sent, "dry_run": False, "pending": len(items) - sent,
+                "error": str(e)}
+    return {"sent": sent, "dry_run": False, "pending": len(items) - sent,
+            "errors": errors or None}
+
+
+def check_and_notify(conn, cfg: dict, org_id: Optional[str] = None) -> list[dict]:
+    """Convenience for cron: deliver pending alerts for one or all orgs."""
+    org_ids = [org_id] if org_id else [o["id"] for o in db.list_orgs(conn)]
+    return [{"org_id": oid, **send_pending(conn, cfg, oid)} for oid in org_ids]

plutus_agent/billing/__init__.py

@@ -0,0 +1,8 @@
+"""Billing — Stripe integration (optional, test-mode friendly)."""
+from .stripe_client import (
+    StripeClient,
+    BillingError,
+    handle_webhook_event,
+)
+
+__all__ = ["StripeClient", "BillingError", "handle_webhook_event"]

plutus_agent/billing/stripe_client.py

@@ -0,0 +1,262 @@
+"""Stripe client — Checkout for prepaid credits + Pro subscription, Customer
+Portal, and webhook handling.
+
+Stripe is **optional**. With no secret key the client reports ``available ==
+False`` and every method raises :class:`BillingError` with a clear message, so
+the dashboard can show a "connect Stripe to enable billing" state while every
+non-Stripe feature keeps working offline. With a *test-mode* key
+(``sk_test_...``) the full flow works end-to-end against Stripe's test
+environment.
+
+Two purchase paths:
+
+* **Prepaid credits** — a one-time Checkout Session (``mode=payment``) for a
+  chosen dollar amount. On ``checkout.session.completed`` we top up the org's
+  credit ledger by the amount paid.
+* **Pro plan** — a subscription Checkout Session (``mode=subscription``) against
+  the configured Price. Subscription lifecycle webhooks move the org between the
+  ``pro`` and ``free`` tiers.
+
+Webhook handling is **idempotent**: every event id is recorded in
+``stripe_events`` and never applied twice.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .. import db
+
+
+class BillingError(RuntimeError):
+    pass
+
+
+def _load_stripe():
+    try:
+        import stripe  # type: ignore
+        return stripe
+    except ImportError:
+        return None
+
+
+class StripeClient:
+    def __init__(self, cfg: dict):
+        self.cfg = cfg or {}
+        self.billing = self.cfg.get("billing", {})
+        self.secret = self.billing.get("stripe_secret_key") or ""
+        self.publishable = self.billing.get("stripe_publishable_key") or ""
+        self.webhook_secret = self.billing.get("stripe_webhook_secret") or ""
+        self.currency = (self.billing.get("currency") or "usd").lower()
+        self._stripe = _load_stripe()
+        if self._stripe and self.secret:
+            self._stripe.api_key = self.secret
+
+    # ------------------------------------------------------------- status ---
+    @property
+    def available(self) -> bool:
+        return bool(self._stripe and self.secret)
+
+    @property
+    def test_mode(self) -> bool:
+        return self.secret.startswith("sk_test_")
+
+    def status(self) -> dict:
+        if not self._stripe:
+            mode = "offline (stripe SDK not installed)"
+        elif not self.secret:
+            mode = "offline (no API key)"
+        elif self.test_mode:
+            mode = "test mode"
+        else:
+            mode = "live mode"
+        return {
+            "available": self.available,
+            "test_mode": self.test_mode,
+            "mode": mode,
+            "publishable_key": self.publishable,
+            "has_pro_price": bool(self.billing.get("stripe_price_pro")),
+        }
+
+    def _require(self):
+        if not self._stripe:
+            raise BillingError(
+                "Stripe SDK not installed. `pip install stripe` to enable billing."
+            )
+        if not self.secret:
+            raise BillingError(
+                "No Stripe key configured. Set billing.stripe_secret_key or "
+                "the STRIPE_SECRET_KEY env var."
+            )
+
+    # ----------------------------------------------------------- customer ---
+    def ensure_customer(self, conn, org_id: str) -> str:
+        """Get-or-create a Stripe customer for an org; persist the id."""
+        self._require()
+        org = db.get_org(conn, org_id)
+        if org is None:
+            raise BillingError(f"unknown org {org_id}")
+        if org["stripe_customer_id"]:
+            return org["stripe_customer_id"]
+        owner = conn.execute(
+            "SELECT email FROM users WHERE org_id=? ORDER BY created_at LIMIT 1",
+            (org_id,),
+        ).fetchone()
+        cust = self._stripe.Customer.create(
+            name=org["name"],
+            email=owner["email"] if owner else None,
+            metadata={"plutus_org_id": org_id},
+        )
+        db.set_stripe_customer(conn, org_id, cust["id"])
+        return cust["id"]
+
+    # ----------------------------------------------------------- checkout ---
+    def credit_checkout(self, conn, org_id: str, amount_usd: float) -> dict:
+        """One-time Checkout Session to buy ``amount_usd`` of prepaid credit."""
+        self._require()
+        if amount_usd <= 0:
+            raise BillingError("amount must be positive")
+        customer = self.ensure_customer(conn, org_id)
+        session = self._stripe.checkout.Session.create(
+            mode="payment",
+            customer=customer,
+            line_items=[{
+                "price_data": {
+                    "currency": self.currency,
+                    "unit_amount": int(round(amount_usd * 100)),
+                    "product_data": {
+                        "name": "Plutus prepaid credit",
+                        "description": f"${amount_usd:,.2f} of agent spend credit",
+                    },
+                },
+                "quantity": 1,
+            }],
+            success_url=self.billing.get("success_url", ""),
+            cancel_url=self.billing.get("cancel_url", ""),
+            metadata={"plutus_org_id": org_id, "kind": "credit",
+                      "amount_usd": f"{amount_usd:.2f}"},
+        )
+        return {"id": session["id"], "url": session["url"]}
+
+    def pro_checkout(self, conn, org_id: str) -> dict:
+        """Subscription Checkout Session for the $20/mo Pro plan."""
+        self._require()
+        price = self.billing.get("stripe_price_pro")
+        if not price:
+            raise BillingError(
+                "No Pro price configured. Set billing.stripe_price_pro to the "
+                "Stripe Price ID for the $20/mo plan."
+            )
+        customer = self.ensure_customer(conn, org_id)
+        session = self._stripe.checkout.Session.create(
+            mode="subscription",
+            customer=customer,
+            line_items=[{"price": price, "quantity": 1}],
+            success_url=self.billing.get("success_url", ""),
+            cancel_url=self.billing.get("cancel_url", ""),
+            metadata={"plutus_org_id": org_id, "kind": "subscription"},
+        )
+        return {"id": session["id"], "url": session["url"]}
+
+    def portal(self, conn, org_id: str, return_url: Optional[str] = None) -> dict:
+        """Stripe Customer Portal session for self-serve billing management."""
+        self._require()
+        customer = self.ensure_customer(conn, org_id)
+        session = self._stripe.billing_portal.Session.create(
+            customer=customer,
+            return_url=return_url or self.billing.get("success_url", ""),
+        )
+        return {"url": session["url"]}
+
+    # ------------------------------------------------------------ webhook ---
+    def construct_event(self, payload: bytes, sig_header: str):
+        """Verify + parse a webhook payload into a Stripe event object."""
+        self._require()
+        if not self.webhook_secret:
+            raise BillingError("No webhook secret configured "
+                               "(billing.stripe_webhook_secret).")
+        return self._stripe.Webhook.construct_event(
+            payload, sig_header, self.webhook_secret
+        )
+
+
+# --------------------------------------------------------- webhook applying ---
+def handle_webhook_event(conn, event: dict) -> dict:
+    """Apply a verified Stripe event to the database (idempotent).
+
+    ``event`` is a dict-like Stripe Event (``event["type"]``, ``event["data"]
+    ["object"]``, ``event["id"]``). Returns a small summary for logging.
+    """
+    event_id = event.get("id", "")
+    etype = event.get("type", "")
+    if event_id and db.stripe_event_seen(conn, event_id):
+        return {"status": "duplicate", "type": etype, "id": event_id}
+
+    obj = (event.get("data") or {}).get("object") or {}
+    result = {"status": "ignored", "type": etype, "id": event_id}
+
+    if etype == "checkout.session.completed":
+        result = _apply_checkout_completed(conn, obj)
+    elif etype in ("customer.subscription.created", "customer.subscription.updated"):
+        result = _apply_subscription_change(conn, obj)
+    elif etype == "customer.subscription.deleted":
+        result = _apply_subscription_deleted(conn, obj)
+
+    if event_id:
+        db.mark_stripe_event(conn, event_id, etype)
+    result.setdefault("type", etype)
+    result.setdefault("id", event_id)
+    return result
+
+
+def _org_from_metadata_or_customer(conn, obj) -> Optional[str]:
+    meta = obj.get("metadata") or {}
+    org_id = meta.get("plutus_org_id")
+    if org_id and db.get_org(conn, org_id):
+        return org_id
+    customer = obj.get("customer")
+    if customer:
+        row = db.org_by_stripe_customer(conn, customer)
+        if row:
+            return row["id"]
+    return None
+
+
+def _apply_checkout_completed(conn, obj) -> dict:
+    org_id = _org_from_metadata_or_customer(conn, obj)
+    if not org_id:
+        return {"status": "no_org", "detail": "could not map checkout to an org"}
+    meta = obj.get("metadata") or {}
+    kind = meta.get("kind")
+    if kind == "credit" or obj.get("mode") == "payment":
+        amount = meta.get("amount_usd")
+        if amount is not None:
+            usd = float(amount)
+        else:
+            usd = float(obj.get("amount_total") or 0) / 100.0
+        row = db.add_ledger(conn, org_id, usd, "topup",
+                            reason="Stripe checkout", stripe_ref=obj.get("id"))
+        return {"status": "credited", "org_id": org_id, "amount_usd": usd,
+                "balance_after": float(row["balance_after"])}
+    if kind == "subscription" or obj.get("mode") == "subscription":
+        db.set_org_tier(conn, org_id, "pro")
+        return {"status": "subscribed", "org_id": org_id, "tier": "pro"}
+    return {"status": "ignored", "org_id": org_id}
+
+
+def _apply_subscription_change(conn, obj) -> dict:
+    org_id = _org_from_metadata_or_customer(conn, obj)
+    if not org_id:
+        return {"status": "no_org"}
+    status = obj.get("status")
+    tier = "pro" if status in ("active", "trialing", "past_due") else "free"
+    db.set_org_tier(conn, org_id, tier)
+    return {"status": "tier_set", "org_id": org_id, "tier": tier,
+            "subscription_status": status}
+
+
+def _apply_subscription_deleted(conn, obj) -> dict:
+    org_id = _org_from_metadata_or_customer(conn, obj)
+    if not org_id:
+        return {"status": "no_org"}
+    db.set_org_tier(conn, org_id, "free")
+    return {"status": "downgraded", "org_id": org_id, "tier": "free"}

plutus_agent/bridge.py

@@ -0,0 +1,32 @@
+"""Bridge to the live runway monitor (repo-root ``plutus.py``).
+
+Decoupled by design: rather than importing the production monitor (which has its
+own module-level paths and is pulled to the Hermes host independently), the
+engine shells out to it for ``--json`` exactly as ``plutus_route.py`` does. If
+the monitor isn't configured or fails, the dashboard simply omits the live
+provider-runway panel — the rest of Plutus works fully offline.
+"""
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import sys
+
+
+def runway(monitor_cfg: dict) -> dict | None:
+    """Return the monitor's ``collect()`` JSON, or ``None`` if unavailable."""
+    if not monitor_cfg or not monitor_cfg.get("enabled"):
+        return None
+    cmd = monitor_cfg.get("command", "").strip()
+    if not cmd:
+        return None
+    try:
+        argv = shlex.split(cmd) + ["--json"]
+        out = subprocess.run(argv, capture_output=True, text=True, timeout=30)
+        if out.returncode != 0 or not out.stdout.strip():
+            return None
+        return json.loads(out.stdout)
+    except Exception as e:  # never let the bridge break the dashboard
+        sys.stderr.write(f"plutus: monitor bridge unavailable: {e}\n")
+        return None