gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/ui/cue_cards.py

@@ -0,0 +1,214 @@
+"""Cue Cards — a launch-time feature tour for gBuilder.
+
+A simple card deck: each card shows a real screenshot of the feature (curated portions of
+the actual UI, generated by scripts/gen_cue_shots.py into assets/cue/<kind>.png), a title,
+and a short explanation. Navigate with the ‹ / › arrows or the keyboard. "Don't show at
+launch" + the Settings Help tab control whether it auto-opens; reopen from Help → Feature
+Tour.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from PySide6.QtCore import QRectF, Qt
+from PySide6.QtGui import QColor, QFont, QPainter, QPixmap
+from PySide6.QtWidgets import (
+    QCheckBox, QDialog, QHBoxLayout, QLabel, QPushButton, QVBoxLayout, QWidget,
+)
+from .theme.manager import sp as _sp
+
+_CUE_DIR = Path(__file__).resolve().parent / "assets" / "cue"
+
+
+def _theme_slug(name: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", (name or "dark").lower()) or "dark"
+
+
+def _cue_candidates(cue_dir: Path, slug: str, dark: bool, kind: str) -> list[Path]:
+    """Screenshot search order: the running theme's own shots first, then its
+    light/dark *family* (so Sand/Blue/Green reuse the Light set), then dark, then
+    a legacy flat file."""
+    family = "dark" if dark else "light"
+    return [cue_dir / slug / f"{kind}.png",
+            cue_dir / family / f"{kind}.png",
+            cue_dir / "dark" / f"{kind}.png",
+            cue_dir / f"{kind}.png"]
+
+
+# Each card: art kind (-> assets/cue/<kind>.png), title, body. Order = tour order.
+FEATURE_CARDS = [
+    ("welcome", "Welcome to gBuilder",
+     "Design real networks and cloud systems by drawing them, then run them as live Docker "
+     "containers. Take the tour with the ‹ / › arrows (or your keyboard)."),
+    ("canvas", "Build by drawing",
+     "Drag elements from the palette onto the canvas and connect them with a right-drag. The "
+     "diagram you draw is the system — GINI compiles it into a real runtime when you Run."),
+    ("wizard", "X-ray & the AI Wizard",
+     "Unsure what connects to what? Long-press an element to see its valid neighbours as "
+     "ghosts, or state a goal and the Wizard walks you through building it, one tap at a time."),
+    ("run", "Run on real Docker",
+     "Press Run and your topology launches as real containers — a C router, switches, "
+     "Kubernetes, databases and more. Badges turn green; double-click an element to log in."),
+    ("cost", "The GINI $ cost meter",
+     "A live 'cloud bill' ticks up while the lab runs, split by category, so pay-as-you-go is "
+     "tangible. Edit the per-hour rates under Settings → Pricing."),
+    ("metrics", "Live metrics",
+     "Select a running element and open the Live tab to watch its CPU, memory, throughput and "
+     "latency in real time — the same telemetry that feeds the dashboard."),
+    ("cloud", "Cloud services & VPCs",
+     "Drop managed services — databases, caches, queues, object storage — as real containers, "
+     "and group them in a VPC box. Each VPC becomes its own isolated network."),
+    ("serverless", "Serverless functions",
+     "Add a Function and write a Python handler in the inspector. Invoke it there to see the "
+     "response, and Deploy code changes without restarting the rest of the lab."),
+    ("router", "Program the router",
+     "Open the Router Lab on any router to build its packet-processing pipeline and run real "
+     "CLI commands against the live gRouter."),
+    ("ai", "Ask GINI",
+     "Ask in plain English. GINI builds, explains warnings, traces packet paths and guides you "
+     "with the Wizard — and it still helps even with no local LLM connected."),
+    ("settings", "Make it yours",
+     "Settings (Ctrl+,) is organized into tabs — Appearance, Networking, GINI AI, Naming and "
+     "Pricing. Reopen this tour any time from Help → Feature Tour."),
+]
+
+
+def _qcolor(spec) -> QColor:
+    if isinstance(spec, QColor):
+        return spec
+    if isinstance(spec, str) and spec.startswith("rgba("):
+        n = [int(float(x)) for x in spec[5:-1].split(",")]
+        return QColor(n[0], n[1], n[2], n[3] if len(n) > 3 else 255)
+    return QColor(spec)
+
+
+class CardArt(QWidget):
+    """Shows the current card's screenshot, scaled to fit (keeping aspect), centered."""
+
+    def __init__(self, theme) -> None:
+        super().__init__()
+        self.theme = theme
+        self._pix: QPixmap | None = None
+        self._kind = "welcome"
+        self.setMinimumHeight(320)
+
+    def set_kind(self, kind: str) -> None:
+        self._kind = kind
+        # prefer the screenshot for the running theme; fall back within the light/dark
+        # family (so Sand/Blue/Green reuse the Light shots), then dark, then legacy flat
+        slug = _theme_slug(self.theme.theme.name)
+        pix = QPixmap()
+        for cand in _cue_candidates(_CUE_DIR, slug, self.theme.theme.dark, kind):
+            if cand.exists():
+                pix = QPixmap(str(cand))
+                if not pix.isNull():
+                    break
+        self._pix = pix if not pix.isNull() else None
+        self.update()
+
+    def paintEvent(self, _e) -> None:
+        t = self.theme.theme
+        p = QPainter(self)
+        p.setRenderHint(QPainter.SmoothPixmapTransform, True)
+        p.setRenderHint(QPainter.Antialiasing, True)
+        r = QRectF(self.rect())
+        p.fillRect(r, _qcolor(getattr(t, "panel", t.bg)))
+        if self._pix is not None and not self._pix.isNull():
+            # fit the full-resolution pixmap into the available area keeping aspect, and let
+            # the painter scale it straight to device pixels — pre-scaling to logical size
+            # first would throw away resolution and blur on Retina/HiDPI displays.
+            avail = r.adjusted(12, 12, -12, -12)
+            pw, ph = self._pix.width(), self._pix.height()
+            s = min(avail.width() / pw, avail.height() / ph)
+            tw, th = pw * s, ph * s
+            target = QRectF(r.center().x() - tw / 2, r.center().y() - th / 2, tw, th)
+            p.drawPixmap(target, self._pix, QRectF(0, 0, pw, ph))
+        else:                                          # graceful fallback if an image is missing
+            p.setPen(_qcolor(getattr(t, "muted", t.text)))
+            f = QFont(); f.setPointSize(_sp(13)); p.setFont(f)
+            p.drawText(r, Qt.AlignCenter, self._kind)
+        p.end()
+
+
+class CueCards(QDialog):
+    """The card-deck dialog. `persist` is called after the user changes the launch pref."""
+
+    def __init__(self, parent, theme, settings, cards=FEATURE_CARDS, persist=None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("gBuilder — Feature Tour")
+        self.setModal(True)
+        self.setMinimumSize(760, 660)
+        self.theme = theme
+        self.settings = settings
+        self._cards = list(cards)
+        self._persist = persist or (lambda: None)
+        self._i = 0
+
+        t = theme.theme
+        self.setStyleSheet(
+            f"QDialog {{ background: {_color(t.bg)}; }}"
+            f"QLabel {{ color: {_color(t.text)}; }}"
+            f"QLabel#Body {{ color: {_color(getattr(t, 'muted', t.text))}; font-size: 15px; }}")
+
+        lay = QVBoxLayout(self)
+        lay.setContentsMargins(20, 20, 20, 16)
+        lay.setSpacing(12)
+        self.art = CardArt(theme)
+        lay.addWidget(self.art, 1)
+        self.title = QLabel()
+        tf = QFont(); tf.setBold(True); tf.setPointSize(_sp(21))
+        self.title.setFont(tf)
+        lay.addWidget(self.title)
+        self.body = QLabel(); self.body.setObjectName("Body"); self.body.setWordWrap(True)
+        self.body.setMinimumHeight(74)
+        lay.addWidget(self.body)
+
+        footer = QHBoxLayout()
+        self.dont = QCheckBox("Don't show at launch")
+        self.dont.setChecked(not settings.show_help_on_launch)
+        self.dont.toggled.connect(self._on_dont)
+        footer.addWidget(self.dont)
+        footer.addStretch(1)
+        self.back = QPushButton("‹ Back"); self.back.clicked.connect(lambda: self._go(-1))
+        self.count = QLabel(); self.count.setObjectName("Body")
+        self.next = QPushButton("Next ›"); self.next.clicked.connect(lambda: self._go(1))
+        done = QPushButton("Done"); done.setObjectName("Accent"); done.clicked.connect(self.accept)
+        for w in (self.back, self.count, self.next, done):
+            footer.addWidget(w)
+        lay.addLayout(footer)
+
+        self._show_card()
+
+    # -- navigation --------------------------------------------------------- #
+    def _go(self, delta: int) -> None:
+        self._i = max(0, min(len(self._cards) - 1, self._i + delta))
+        self._show_card()
+
+    def _show_card(self) -> None:
+        kind, title, body = self._cards[self._i]
+        self.art.set_kind(kind)
+        self.title.setText(title)
+        self.body.setText(body)
+        self.count.setText(f"{self._i + 1} / {len(self._cards)}")
+        self.back.setEnabled(self._i > 0)
+        self.next.setEnabled(self._i < len(self._cards) - 1)
+
+    def keyPressEvent(self, e) -> None:
+        if e.key() in (Qt.Key_Right, Qt.Key_Space):
+            self._go(1)
+        elif e.key() == Qt.Key_Left:
+            self._go(-1)
+        elif e.key() == Qt.Key_Escape:
+            self.accept()
+        else:
+            super().keyPressEvent(e)
+
+    # -- preference --------------------------------------------------------- #
+    def _on_dont(self, checked: bool) -> None:
+        self.settings.show_help_on_launch = not checked
+        self._persist()
+
+
+def _color(spec) -> str:
+    return _qcolor(spec).name()

gini/ui/dashboard.py

@@ -0,0 +1,222 @@
+"""The analytics strip below the Console — a live GINI $ "cloud bill".
+
+Every billable element you place is a rented resource (see domain/pricing.py). While a
+lab runs, this panel accrues `rate/hr × elapsed` in GINI $ so students *feel* cloud
+pay-as-you-go. It also shows a per-category cost breakdown and resource counts. Real
+performance telemetry (latency/throughput) is deliberately left to Grafana — the
+"Open Grafana" button jumps to the running dashboard when one is on the canvas.
+"""
+from __future__ import annotations
+
+import time
+
+from PySide6.QtCore import Qt, QTimer, Signal
+from PySide6.QtWidgets import (
+    QFrame, QHBoxLayout, QLabel, QPushButton, QVBoxLayout, QWidget,
+)
+
+from ..domain.pricing import CATEGORY_ORDER
+
+# category -> theme accent-token key (for the little coloured cost chips)
+_CAT_ACCENT = {"Compute": "purple", "Serverless": "pink", "Kubernetes": "cyan",
+               "Networking": "blue", "Services": "teal", "Observability": "amber"}
+
+
+class Dashboard(QWidget):
+    """Compact, short cost/analytics panel. Driven by the main window:
+    `set_estimate()` on every topology change, `start()`/`stop()` on run/stop."""
+
+    open_grafana_requested = Signal()
+
+    def __init__(self, theme, parent=None) -> None:
+        super().__init__(parent)
+        self.theme = theme                       # ThemeManager
+        self._rate = 0.0                          # GINI $/hr currently billed
+        self._count = 0
+        self._by_cat: dict[str, dict] = {}
+        self._accrued = 0.0                      # GINI $ accrued this session
+        self._running = False
+        self._start: float | None = None
+        self._grafana_url: str | None = None
+        self.setMaximumHeight(104)
+
+        root = QHBoxLayout(self)
+        root.setContentsMargins(14, 8, 14, 8)
+        root.setSpacing(18)
+
+        self.total_lbl = self._value("GINI $ 0.00")
+        self.total_lbl.setObjectName("DashTotal")
+        root.addLayout(self._metric(self.total_lbl, "session cost"))
+        self.rate_lbl = self._value("0.00")
+        root.addLayout(self._metric(self.rate_lbl, "GINI $ / hr"))
+        self.elapsed_lbl = self._value("—")
+        root.addLayout(self._metric(self.elapsed_lbl, "elapsed"))
+        self.count_lbl = self._value("0")
+        root.addLayout(self._metric(self.count_lbl, "resources"))
+        self.rps_lbl = self._value("—")
+        root.addLayout(self._metric(self.rps_lbl, "req/s · lab"))
+
+        sep = QFrame(); sep.setFrameShape(QFrame.VLine); sep.setObjectName("DashSep")
+        root.addWidget(sep)
+
+        # cost breakdown by category (coloured chips)
+        bd = QVBoxLayout(); bd.setSpacing(2)
+        bd.addWidget(self._caption("COST BREAKDOWN"))
+        self.cats_lbl = QLabel("—")
+        self.cats_lbl.setTextFormat(Qt.RichText)
+        self.cats_lbl.setObjectName("DashChips")
+        bd.addWidget(self.cats_lbl)
+        root.addLayout(bd)
+
+        root.addStretch(1)
+
+        right = QVBoxLayout(); right.setSpacing(4); right.setAlignment(Qt.AlignVCenter)
+        self.bill_lbl = self._caption("● not running — projected rate")
+        self.bill_lbl.setObjectName("DashState")
+        right.addWidget(self.bill_lbl, alignment=Qt.AlignRight)
+        self.grafana_btn = QPushButton("Open Grafana")
+        self.grafana_btn.setObjectName("DashGrafana")
+        self.grafana_btn.setCursor(Qt.PointingHandCursor)
+        self.grafana_btn.setEnabled(False)
+        self.grafana_btn.setToolTip("Latency & throughput live in Grafana — add a "
+                                    "Dashboards element to your topology.")
+        self.grafana_btn.clicked.connect(self.open_grafana_requested.emit)
+        right.addWidget(self.grafana_btn, alignment=Qt.AlignRight)
+        root.addLayout(right)
+
+        self._tick = QTimer(self)
+        self._tick.setInterval(1000)
+        self._tick.timeout.connect(self._on_tick)
+
+        if hasattr(theme, "themeChanged"):
+            theme.themeChanged.connect(self._restyle)
+        self._restyle()
+        self._render()
+
+    # -- small builders ----------------------------------------------------- #
+    def _value(self, text: str) -> QLabel:
+        lbl = QLabel(text); lbl.setObjectName("DashValue")
+        return lbl
+
+    def _caption(self, text: str) -> QLabel:
+        lbl = QLabel(text); lbl.setObjectName("DashCaption")
+        return lbl
+
+    def _metric(self, value: QLabel, caption: str) -> QVBoxLayout:
+        box = QVBoxLayout(); box.setSpacing(1)
+        box.addWidget(value)
+        box.addWidget(self._caption(caption))
+        return box
+
+    # -- public API (called by the main window) ----------------------------- #
+    def set_estimate(self, bill: dict) -> None:
+        """Update the projected rate/breakdown from the current canvas (idle preview)."""
+        self._rate = float(bill.get("rate_per_hr", 0.0))
+        self._count = int(bill.get("count", 0))
+        self._by_cat = dict(bill.get("by_category", {}))
+        self._render()
+
+    def reset(self) -> None:
+        """Zero the session meter — used when a different project is loaded so the sticker
+        doesn't carry the previous experiment's accrued bill."""
+        self._accrued = 0.0
+        self._running = False
+        self._start = None
+        self._tick.stop()
+        self._render()
+
+    def start(self, rate_per_hr: float) -> None:
+        """Begin billing: reset the meter and accrue at `rate_per_hr`."""
+        self._rate = float(rate_per_hr)
+        self._accrued = 0.0
+        self._running = True
+        self._start = time.monotonic()
+        if not self._tick.isActive():
+            self._tick.start()
+        self._render()
+
+    def stop(self) -> None:
+        """Freeze the meter at the final session cost (kept on screen until next run)."""
+        if self._running and self._start is not None:
+            self._accrued = self._rate * (time.monotonic() - self._start) / 3600.0
+        self._running = False
+        self._tick.stop()
+        self._render()
+
+    def set_grafana_url(self, url: str | None) -> None:
+        self._grafana_url = url
+        self.grafana_btn.setEnabled(bool(url))
+
+    def set_fabric(self, totals: dict) -> None:
+        """Lab-wide app metrics from the cloud fabric (request rate, services up)."""
+        if totals and totals.get("services_total"):
+            rps = totals.get("rps", 0.0)
+            up, tot = totals.get("services_up", 0), totals.get("services_total", 0)
+            self.rps_lbl.setText(f"{rps:,.0f}")
+            self.rps_lbl.setToolTip(f"{up}/{tot} services up")
+        else:
+            self.rps_lbl.setText("—")
+
+    def grafana_url(self) -> str | None:
+        return self._grafana_url
+
+    # -- internals ---------------------------------------------------------- #
+    def _on_tick(self) -> None:
+        if self._running and self._start is not None:
+            self._accrued = self._rate * (time.monotonic() - self._start) / 3600.0
+        self._render()
+
+    @staticmethod
+    def _fmt_elapsed(secs: float) -> str:
+        s = int(secs)
+        h, rem = divmod(s, 3600)
+        m, s = divmod(rem, 60)
+        return f"{h:d}:{m:02d}:{s:02d}" if h else f"{m:02d}:{s:02d}"
+
+    def _render(self) -> None:
+        self.total_lbl.setText(f"GINI $ {self._accrued:,.2f}")
+        self.rate_lbl.setText(f"{self._rate:,.2f}")
+        self.count_lbl.setText(str(self._count))
+        if self._running and self._start is not None:
+            self.elapsed_lbl.setText(self._fmt_elapsed(time.monotonic() - self._start))
+            self.bill_lbl.setText("● billing — accruing live")
+        else:
+            self.elapsed_lbl.setText("—")
+            self.bill_lbl.setText("○ not running — projected rate")
+
+        t = self.theme.theme
+        chips = []
+        for cat in CATEGORY_ORDER:
+            d = self._by_cat.get(cat)
+            if not d:
+                continue
+            col = t.accent_for(_CAT_ACCENT.get(cat, "blue"))
+            chips.append(
+                f'<span style="color:{col};font-weight:600">{cat}</span> '
+                f'<span style="color:{t.text}">{d["rate"]:,.0f}</span>'
+                f'<span style="color:{t.faint}">/hr·{d["count"]}</span>')
+        self.cats_lbl.setText(
+            ' &nbsp;&nbsp; '.join(chips) if chips
+            else '<span style="color:%s">no billable resources yet</span>' % t.faint)
+
+    def _restyle(self) -> None:
+        t = self.theme.theme
+        from .theme.manager import sp
+        self.setStyleSheet(f"""
+            QLabel#DashValue {{ color: {t.text}; font-size: {sp(17)}px; font-weight: 700; }}
+            QLabel#DashTotal {{ color: {t.accent}; font-size: {sp(18)}px; font-weight: 800; }}
+            QLabel#DashCaption {{ color: {t.faint}; font-size: {sp(9)}px;
+                                  letter-spacing: 0.4px; text-transform: uppercase; }}
+            QLabel#DashChips {{ font-size: {sp(12)}px; }}
+            QLabel#DashState {{ color: {t.muted}; font-size: {sp(10)}px; }}
+            QFrame#DashSep {{ color: {t.line2}; }}
+            QPushButton#DashGrafana {{
+                background: {t.accent_soft}; color: {t.accent2};
+                border: 1px solid {t.accent2}; border-radius: 6px;
+                padding: 4px 12px; font-weight: 600; }}
+            QPushButton#DashGrafana:disabled {{
+                background: transparent; color: {t.faint};
+                border: 1px solid {t.line2}; }}
+            QPushButton#DashGrafana:hover:enabled {{ background: {t.accent2}; color: white; }}
+        """)
+        self._render()