karcytics-sdk 2.2.0__tar.gz → 2.4.0__tar.gz

{karcytics_sdk-2.2.0/src/karcytics_sdk.egg-info → karcytics_sdk-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karcytics-sdk
-Version: 2.2.0
+Version: 2.4.0
 Summary: Software Development Kit and CLI for Karcytics.
 Author: Kalaimaran Balasothy
 License: # PolyForm Noncommercial License 1.0.0

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "karcytics-sdk"
-version = "2.2.0"
+version = "2.4.0"
 description = "Software Development Kit and CLI for Karcytics."
 readme = "README.md"
 license = { file = "LICENSE" }

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/academy.py

@@ -21,16 +21,27 @@ string directly as its topic key.
 from __future__ import annotations
 
 import logging
+import re
 from collections.abc import Callable
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any, Protocol, runtime_checkable
 
 from .io import load_json, save_json
-from .tutorial_models import BaseStep, Course, ForcedInteractionStep, WaitForEventStep
+from .tutorial_models import (
+    QUESTION_CHECK,
+    BaseStep,
+    Course,
+    ForcedInteractionStep,
+    QuestionStep,
+    WaitForEventStep,
+)
 
 logger = logging.getLogger(__name__)
 
+# `{answer:<question_id>}` in a step's text → the learner's recorded answer.
+_ANSWER_PLACEHOLDER = re.compile(r"\{answer:([A-Za-z0-9_.-]+)\}")
+
 # Canonical topic names. These match the Hub's `KarcyticsEvent` enum member
 # names exactly (see `karcytics.core.event_bus`) so a Hub-side event bus
 # adapter can resolve them with a plain `KarcyticsEvent[topic]` lookup.
@@ -90,6 +101,13 @@ class AcademyManager:
         self.completed_courses: list[str] = []
         self.badges: list[dict[str, Any]] = []
         self.prerequisites_met: dict[str, str] = {}  # course_id -> workflow_hash
+        # course_id -> question_id -> {"choices": [...], "attempts": n, "correct": bool}.
+        # Local only (progress.json); lets a later step — even in a later
+        # course — reveal a prediction the learner made.
+        self.answers: dict[str, dict[str, dict[str, Any]]] = {}
+        # Whether the live QuestionStep has been answered (correctly, for a
+        # "check" question); next_step() won't leave it otherwise.
+        self._question_answered = False
 
         # State tracking
         self.active_course: Course | None = None
@@ -121,6 +139,7 @@ class AcademyManager:
         self.completed_courses = data.get("completed_courses", [])
         self.badges = data.get("badges", [])
         self.prerequisites_met = data.get("prerequisites_met", {})
+        self.answers = data.get("answers", {})
 
     def _save_progress(self) -> None:
         """Saves current progress to disk."""
@@ -128,6 +147,7 @@ class AcademyManager:
             "completed_courses": self.completed_courses,
             "badges": self.badges,
             "prerequisites_met": self.prerequisites_met,
+            "answers": self.answers,
         }
         try:
             save_json(str(self.progress_file), data)
@@ -167,6 +187,7 @@ class AcademyManager:
 
                     if course.steps:
                         self.current_step = course.steps[0]
+                        self._question_answered = False
                         self.active_subtask_progress = {}
                         # Subscribe immediately if the first step is a WaitForEventStep
                         if isinstance(self.current_step, WaitForEventStep):
@@ -202,6 +223,10 @@ class AcademyManager:
                 logger.warning("Cannot advance: not all sub-tasks completed.")
                 return
 
+        if isinstance(self.current_step, QuestionStep) and not self._question_answered:
+            logger.warning("Cannot advance: question not answered yet.")
+            return
+
         if isinstance(self.current_step, WaitForEventStep) and not _internal_force and specific_step_id is None:
             logger.warning(f"Cannot advance: waiting for event {self.current_step.event_name}")
             return
@@ -222,6 +247,7 @@ class AcademyManager:
             self.abandon_course()
             return
 
+        self._question_answered = False
         if next_id and next_id != "__complete__":
             self.current_step = self.active_course.get_step(next_id) if self.active_course else None
             if self.current_step:
@@ -237,6 +263,46 @@ class AcademyManager:
             self.current_step = None
             self._emit_step_changed()
 
+    # ── Questions ──────────────────────────────────────────────────────────
+
+    def record_answer(self, selected: list[int], attempts: int) -> bool:
+        """Records the learner's answer to the live `QuestionStep`.
+
+        Returns whether it answers the question (any selection answers a
+        prediction). Only a correct answer unlocks `next_step()`; every
+        answer is saved, so attempts count how many tries it took.
+        """
+        step = self.current_step
+        if not self.active_course or not isinstance(step, QuestionStep) or self.is_reviewing:
+            return False
+        correct = step.is_correct(set(selected))
+        if correct:
+            self._question_answered = True
+        if step.question_id:
+            self.answers.setdefault(self.active_course.id, {})[step.question_id] = {
+                "choices": [step.choices[i].text for i in sorted(selected)],
+                "attempts": attempts,
+                "correct": correct if step.kind == QUESTION_CHECK else None,
+            }
+            self._save_progress()
+        return correct
+
+    def recorded_answer(self, question_id: str) -> str | None:
+        """The learner's recorded answer to `question_id`, from any course."""
+        for per_course in self.answers.values():
+            entry = per_course.get(question_id)
+            if entry and entry.get("choices"):
+                return " / ".join(entry["choices"])
+        return None
+
+    def format_step_text(self, text: str) -> str:
+        """Replaces each `{answer:<question_id>}` with the recorded answer.
+
+        An unanswered placeholder becomes "(not answered)" rather than
+        leaking the raw placeholder into the bubble.
+        """
+        return _ANSWER_PLACEHOLDER.sub(lambda m: self.recorded_answer(m.group(1)) or "(not answered)", text)
+
     def complete_subtask(self, subtask_id: str) -> None:
         """Marks a sub-task as complete for the current step."""
         if not self.active_course or not isinstance(self.current_step, ForcedInteractionStep):

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/academy_driver.py

@@ -24,6 +24,7 @@ from PyQt6.QtCore import QObject, QRect, QTimer
 from PyQt6.QtWidgets import QApplication, QScrollArea, QWidget
 
 from .academy import AcademyManager
+from .tutorial_highlight import TutorialHighlight
 from .tutorial_models import (
     ActionStep,
     BranchingStep,
@@ -86,6 +87,10 @@ class AcademyStepDriver(QObject):
         self._failure_hint_shown = False
         self._was_reviewing = False
         self._last_canvas_guide_active = False
+        # In-window spotlights for targets in other windows (see _spotlight_rects).
+        self._window_highlights: dict[QWidget, TutorialHighlight] = {}
+        # Step whose targets were last scrolled into view (see _update_targets).
+        self._revealed_step_id: str | None = None
 
         self._timer = QTimer(self)
         self._timer.timeout.connect(self._tick)
@@ -468,11 +473,16 @@ class AcademyStepDriver(QObject):
                 if w and w.isVisible():
                     targets.append(w)
 
-        rects = []
-        for w in targets:
-            global_pos = w.mapToGlobal(w.rect().topLeft())
-            local_pos = self._overlay.mapFromGlobal(global_pos)
-            rects.append(QRect(local_pos, w.size()))
+        # A step's first tick with targets: scroll them into view. Otherwise one
+        # scrolled out of a sidebar is spotlit off-screen, Cyto and the bubble
+        # follow it there, and the learner sees only the dim. Once per step,
+        # so they can still scroll away afterwards. (Not before the targets
+        # exist: a popup the step points into may open a few ticks later.)
+        if targets and getattr(step, "id", None) != self._revealed_step_id:
+            self._revealed_step_id = getattr(step, "id", None)
+            _scroll_into_view(targets)
+
+        rects = self._spotlight_rects(targets)
         rects.extend(self._collect_canvas_target_rects(step))
         self._overlay.set_targets(rects)
 
@@ -488,6 +498,47 @@ class AcademyStepDriver(QObject):
                 scroll_target = scroll_area.viewport()
         self._overlay.set_scroll_target(scroll_target)
 
+    def _spotlight_rects(self, targets: list[QWidget]) -> list[QRect]:
+        """Overlay rects for `targets`; targets in other windows are framed there.
+
+        A target in the overlay's own window gets a spotlight hole as usual.
+        One inside another window — a dialog or popup, even one parented to
+        the panel (so `findChildren()` finds it) — would otherwise be
+        spotlit on the main window *underneath* that window. Those are framed
+        inside their own window by a `TutorialHighlight` instead, and that
+        window's frame becomes the overlay rect, so Cyto and the bubble steer
+        clear of the whole window rather than sitting behind it.
+        """
+        from PyQt6 import sip
+
+        # Forget windows that have since been destroyed (a closed dialog).
+        self._window_highlights = {w: h for w, h in self._window_highlights.items() if not sip.isdeleted(w)}
+        own_window = self._overlay.window()
+        rects: list[QRect] = []
+        elsewhere: dict[QWidget, list[QWidget]] = {}
+        for w in targets:
+            window = w.window()
+            if window is None or window is own_window:
+                local_pos = self._overlay.mapFromGlobal(w.mapToGlobal(w.rect().topLeft()))
+                rects.append(QRect(local_pos, w.size()))
+            else:
+                inner = elsewhere.setdefault(window, [])
+                if w is not window and w not in inner:
+                    inner.append(w)
+
+        for window, widgets in elsewhere.items():
+            highlight = self._window_highlights.get(window)
+            if highlight is None:
+                highlight = TutorialHighlight(window)
+                self._window_highlights[window] = highlight
+            highlight.show_on(widgets)
+            frame = window.frameGeometry()
+            rects.append(QRect(self._overlay.mapFromGlobal(frame.topLeft()), frame.size()))
+        for window, highlight in self._window_highlights.items():
+            if window not in elsewhere:
+                highlight.clear()
+        return rects
+
     def _find_in_other_windows(self, name: str) -> list[QWidget]:
         """Visible widgets named `name` in this process's *other* top-level
         windows — e.g. the SDK Preferences dialog, a separate window parented
@@ -549,6 +600,16 @@ class AcademyStepDriver(QObject):
         return None
 
 
+def _scroll_into_view(widgets: list[QWidget]) -> None:
+    """Scrolls each widget's nearest `QScrollArea` so it shows — last
+    first, so when they don't all fit, the first-named one wins.
+    """
+    for w in reversed(widgets):
+        area = AcademyStepDriver._find_scroll_area_ancestor(w)
+        if area is not None:
+            area.ensureWidgetVisible(w, 0, 0)
+
+
 # ── Generic Academy launch — shared by any isolated plugin's own UI trigger ──
 #
 # Originally private to `ui_daemon_runtime.py`'s Help-menu wiring. Promoted

karcytics_sdk-2.4.0/src/karcytics_sdk/plugin/question_panel.py

@@ -0,0 +1,226 @@
+"""The answer area of a `QuestionStep`, shown inside Cyto's bubble.
+
+Kept out of `tutorial_overlay.py` (already the overlay's layout, masking and
+placement engine): this is only the choices, the feedback line, and the
+check → retry → reveal logic. The overlay supplies `check`, which records the
+answer with the `AcademyManager` and says whether it was correct, and turns
+the footer's Check button into Continue when `answered` fires.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from PyQt6.QtCore import Qt, pyqtSignal
+from PyQt6.QtWidgets import (
+    QAbstractButton,
+    QButtonGroup,
+    QCheckBox,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QRadioButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .theme_fallback import theme_manager
+from .tutorial_models import QUESTION_PREDICT, QuestionStep
+
+_ROW_QSS = (
+    "QFrame#QuestionChoice {"
+    "  background-color: {BG_MEDIUM}; border: 1px solid {BORDER}; border-radius: 6px;"
+    "}"
+    'QFrame#QuestionChoice[state="selected"] { border: 1px solid {ACCENT_PRIMARY}; }'
+    'QFrame#QuestionChoice[state="wrong"] { border: 1px solid {ACCENT_DANGER}; }'
+    'QFrame#QuestionChoice[state="reveal"] { border: 2px dashed {ACCENT_SUCCESS}; }'
+    'QFrame#QuestionChoice[state="correct"] { border: 2px solid {ACCENT_SUCCESS}; }'
+    "QFrame#QuestionChoice QLabel { color: {FG_PRIMARY}; background: transparent; border: none; }"
+)
+_FEEDBACK_QSS = (
+    "QLabel#QuestionFeedback { padding: 6px 2px; color: {FG_PRIMARY}; }"
+    'QLabel#QuestionFeedback[state="wrong"] { color: {ACCENT_DANGER}; }'
+    'QLabel#QuestionFeedback[state="correct"] { color: {ACCENT_SUCCESS}; }'
+)
+_HINT = "Choose an answer first."
+_REVEAL_NOTE = "The outlined answer is correct — select it to continue."
+_MULTI_MISSING = "Not quite — at least one correct answer is still unselected."
+
+
+def _claim_wrapped_height(label: QLabel, width: int) -> None:
+    """Makes a word-wrapped label ask for all its lines at `width`.
+
+    A wrapped QLabel's sizeHint() assumes its own preferred width, not the
+    fixed one it's given here, and the bubble is sized from sizeHint() — so
+    the last line or two (a long explanation) would be clipped.
+    """
+    label.setMinimumHeight(label.heightForWidth(width))
+
+
+class _ChoiceRow(QFrame):
+    """One answer: an indicator plus a word-wrapped label; the whole row clicks."""
+
+    def __init__(self, text: str, indicator: QAbstractButton, width: int) -> None:
+        super().__init__()
+        self.setObjectName("QuestionChoice")
+        self.setCursor(Qt.CursorShape.PointingHandCursor)
+        self.indicator = indicator
+        self.label = QLabel(text)
+        self.label.setWordWrap(True)
+        self.label.setTextFormat(Qt.TextFormat.RichText)
+        row = QHBoxLayout(self)
+        row.setContentsMargins(10, 8, 10, 8)
+        row.setSpacing(8)
+        row.addWidget(indicator, 0, Qt.AlignmentFlag.AlignTop)
+        row.addWidget(self.label, 1)
+        self.setFixedWidth(width)
+        theme_manager.apply_style(self, _ROW_QSS)
+        _claim_wrapped_height(self.label, width - 20 - 8 - indicator.sizeHint().width())
+
+    def mousePressEvent(self, event) -> None:  # noqa: N802
+        if self.indicator.isEnabled():
+            # A radio button's toggle() is a no-op when already checked;
+            # click() matches what clicking the indicator itself does.
+            self.indicator.click()
+        super().mousePressEvent(event)
+
+    def set_state(self, state: str) -> None:
+        self.setProperty("state", state)
+        style = self.style()
+        if style is not None:  # re-evaluate [state=...] selectors
+            style.unpolish(self)
+            style.polish(self)
+
+
+class QuestionPanel(QWidget):
+    """Choices + feedback for one `QuestionStep`.
+
+    Signals:
+        answered: the question is answered (correctly, for a "check"
+            question) — the overlay swaps Check for Continue.
+        content_changed: feedback/reveal changed the panel's height.
+    """
+
+    answered = pyqtSignal()
+    content_changed = pyqtSignal()
+
+    def __init__(
+        self,
+        step: QuestionStep,
+        check: Callable[[list[int], int], bool],
+        width: int,
+        parent: QWidget | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.setObjectName("QuestionPanel")
+        self._step = step
+        self._check = check
+        self.attempts = 0
+        self.is_answered = False
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(6)
+
+        self._group = QButtonGroup(self)
+        self._group.setExclusive(not step.multi_select)
+        self.rows: list[_ChoiceRow] = []
+        for i, choice in enumerate(step.choices):
+            indicator: QAbstractButton = QCheckBox() if step.multi_select else QRadioButton()
+            indicator.setObjectName(f"QuestionChoiceIndicator_{i}")
+            self._group.addButton(indicator, i)
+            row = _ChoiceRow(choice.text, indicator, width)
+            indicator.toggled.connect(self._on_selection_changed)
+            self.rows.append(row)
+            layout.addWidget(row)
+
+        if step.multi_select:
+            hint = QLabel("Select all that apply.")
+            hint.setObjectName("QuestionMultiHint")
+            theme_manager.apply_style(hint, "color: {FG_SECONDARY}; font-size: 12px;")
+            layout.insertWidget(0, hint)
+
+        self.feedback = QLabel("")
+        self.feedback.setObjectName("QuestionFeedback")
+        self.feedback.setWordWrap(True)
+        self.feedback.setTextFormat(Qt.TextFormat.RichText)
+        self.feedback.setFixedWidth(width)
+        self.feedback.hide()
+        theme_manager.apply_style(self.feedback, _FEEDBACK_QSS)
+        layout.addWidget(self.feedback)
+
+    # ── Public API ──────────────────────────────────────────────────────
+
+    def selected(self) -> list[int]:
+        return [i for i, row in enumerate(self.rows) if row.indicator.isChecked()]
+
+    def submit(self) -> None:
+        """The footer's Check button: grade the current selection."""
+        if self.is_answered:
+            return
+        selection = self.selected()
+        if not selection:
+            self._show_feedback(_HINT, "")
+            return
+        self.attempts += 1
+        if self._check(selection, self.attempts):
+            self._on_answered(selection)
+        else:
+            self._on_wrong(selection)
+
+    # ── Internals ───────────────────────────────────────────────────────
+
+    def _on_selection_changed(self) -> None:
+        if self.is_answered:
+            return
+        chosen = set(self.selected())
+        revealed = self.attempts >= self._step.reveal_after_attempts
+        for i, row in enumerate(self.rows):
+            if i in chosen:
+                row.set_state("selected")
+            elif revealed and i in self._step.correct_indices:
+                row.set_state("reveal")
+            else:
+                row.set_state("")
+
+    def _on_answered(self, selection: list[int]) -> None:
+        self.is_answered = True
+        predict = self._step.kind == QUESTION_PREDICT
+        for i, row in enumerate(self.rows):
+            row.indicator.setEnabled(False)
+            row.setCursor(Qt.CursorShape.ArrowCursor)
+            if i in selection:
+                row.set_state("selected" if predict else "correct")
+        parts = [self._step.choices[i].feedback for i in selection if self._step.choices[i].feedback]
+        if self._step.explanation:
+            parts.append(self._step.explanation)
+        prefix = "" if predict else "✓ Correct. "
+        self._show_feedback(prefix + " ".join(parts), "" if predict else "correct")
+        self.answered.emit()
+
+    def _on_wrong(self, selection: list[int]) -> None:
+        correct = self._step.correct_indices
+        wrong_picks = [i for i in selection if i not in correct]
+        for i in wrong_picks:
+            self.rows[i].set_state("wrong")
+        if wrong_picks:
+            message = self._step.choices[wrong_picks[0]].feedback
+        else:  # multi-select with only correct picks, but not all of them
+            message = _MULTI_MISSING
+        if self.attempts >= self._step.reveal_after_attempts:
+            for i in correct:
+                if i not in selection:
+                    self.rows[i].set_state("reveal")
+            message = f"{message}<br><br><b>{_REVEAL_NOTE}</b>"
+        self._show_feedback(f"✗ {message}", "wrong")
+
+    def _show_feedback(self, text: str, state: str) -> None:
+        self.feedback.setText(text)
+        _claim_wrapped_height(self.feedback, self.feedback.width())
+        self.feedback.setProperty("state", state)
+        style = self.feedback.style()
+        if style is not None:
+            style.unpolish(self.feedback)
+            style.polish(self.feedback)
+        self.feedback.show()
+        self.content_changed.emit()

karcytics_sdk-2.4.0/src/karcytics_sdk/plugin/tutorial_highlight.py

@@ -0,0 +1,84 @@
+"""Academy spotlight drawn inside a window other than the overlay's own.
+
+The `TutorialOverlay` is a child of the plugin's main window and can't paint
+over a separate window. A step's target inside a dialog or popup (a Tool
+window, a non-modal QDialog…) would otherwise be spotlit on the main window
+*underneath* it — wherever the target happens to sit on screen. The
+`AcademyStepDriver` instead gives each such window one of these, which draws
+accent frames over the targets inside that window itself.
+"""
+
+from __future__ import annotations
+
+from PyQt6.QtCore import QPoint, QRect, Qt, QTimer
+from PyQt6.QtWidgets import QFrame, QWidget
+
+from .theme_fallback import theme_manager
+
+# The driver refreshes every tick (100 ms); once it stops (step changed,
+# window closed, Academy hidden) the frames disappear on their own.
+_EXPIRE_MS = 400
+_PAD = 3
+
+
+def _visible_rect(widget: QWidget) -> QRect:
+    """`widget`'s own rect clipped by every ancestor (e.g. a scroll viewport)."""
+    rect = widget.rect()
+    child, parent = widget, widget.parentWidget()
+    while parent is not None and not child.isWindow():
+        offset = widget.mapTo(parent, QPoint(0, 0))
+        rect = rect.intersected(parent.rect().translated(-offset))
+        child, parent = parent, parent.parentWidget()
+    return rect
+
+
+class TutorialHighlight:
+    """Accent frames over widgets inside `host` (a top-level window)."""
+
+    def __init__(self, host: QWidget) -> None:
+        self.host = host
+        self._frames: list[QFrame] = []
+        self._expiry = QTimer(host)
+        self._expiry.setSingleShot(True)
+        self._expiry.timeout.connect(self.clear)
+
+    @property
+    def visible_count(self) -> int:
+        return sum(1 for f in self._frames if f.isVisible())
+
+    def show_on(self, widgets: list[QWidget]) -> None:
+        """Frames exactly `widgets` (descendants of `host`); hides the rest.
+
+        Only the part of each widget that's actually on screen is framed —
+        one scrolled out of its scroll area gets no frame, rather than one
+        drawn over whatever sits where it would be (a dialog's buttons).
+        """
+        shown = [(w, r) for w in widgets if not (r := _visible_rect(w)).isEmpty()]
+        while len(self._frames) < len(shown):
+            self._frames.append(self._new_frame())
+        for frame, (widget, rect) in zip(self._frames, shown, strict=False):
+            top_left = widget.mapTo(self.host, rect.topLeft())
+            frame.setGeometry(QRect(top_left, rect.size()).adjusted(-_PAD, -_PAD, _PAD, _PAD))
+            frame.show()
+            frame.raise_()
+        for frame in self._frames[len(shown) :]:
+            frame.hide()
+        self._expiry.start(_EXPIRE_MS)
+
+    def clear(self) -> None:
+        for frame in self._frames:
+            frame.hide()
+
+    def _new_frame(self) -> QFrame:
+        frame = QFrame(self.host)
+        frame.setObjectName("TutorialHighlightFrame")
+        frame.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
+        theme_manager.apply_style(
+            frame,
+            "QFrame#TutorialHighlightFrame {"
+            "  border: 2px solid {ACCENT_PRIMARY};"
+            "  border-radius: 6px;"
+            "  background: transparent;"
+            "}",
+        )
+        return frame

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/tutorial_models.py

@@ -1,12 +1,8 @@
 """SOLID models and interfaces for the Karcytics Academy tutorial engine.
 
-Vendored from the Hub's `karcytics.core.models.tutorial_models` — these are
-pure dataclasses/interfaces with zero dependency on the Hub itself (only
-`abc`/`dataclasses`/`typing`), so a plugin building its own Academy course
-content can depend on this permanent, real copy directly rather than an
-unimportable Hub-internal path. Any plugin author writing course content
-imports from here; the Hub's own copy is the authoritative implementation
-these mirror.
+Originally vendored from the Hub; this is now the only copy. Pure
+dataclasses/interfaces with no dependency on the Hub (only
+`abc`/`dataclasses`/`typing`), so plugin course content imports from here.
 """
 
 from abc import ABC, abstractmethod
@@ -206,6 +202,86 @@ class ConsentStep(BaseStep):
     on_decline_step_id: str | None = None
 
 
+QUESTION_CHECK = "check"
+QUESTION_PREDICT = "predict"
+
+
+@dataclass
+class AnswerChoice:
+    """One answer to a `QuestionStep`.
+
+    `feedback` is shown when the learner picks this choice: for a wrong
+    choice it says *why* it's wrong (required for "check" questions), for a
+    correct one it can add a short confirmation.
+    """
+
+    text: str
+    correct: bool = False
+    feedback: str = ""
+
+
+@dataclass
+class QuestionStep(BaseStep):
+    """A question answered in Cyto's bubble; `text` is the question.
+
+    Two kinds:
+
+    - ``"check"`` (default): the learner must select the correct choice(s)
+      to continue. A wrong pick shows its feedback; after
+      `reveal_after_attempts` wrong tries the correct choice(s) are
+      outlined — they still have to select them.
+    - ``"predict"``: any answer is accepted and recorded under
+      `question_id`, so a later step can reveal it (``{answer:<id>}`` in a
+      step's text is replaced with the learner's choice, across courses).
+
+    `multi_select` makes it "select all that apply": correct only when the
+    selection is exactly the set of correct choices. `explanation` is shown
+    once answered, before Continue.
+    """
+
+    choices: list[AnswerChoice] = field(default_factory=list)
+    multi_select: bool = False
+    kind: str = QUESTION_CHECK
+    question_id: str = ""
+    explanation: str = ""
+    reveal_after_attempts: int = 2
+
+    def __post_init__(self) -> None:
+        """Rejects questions that can't be answered (or can't teach)."""
+        if self.kind not in (QUESTION_CHECK, QUESTION_PREDICT):
+            raise ValueError(f"{self.id}: kind must be 'check' or 'predict', got {self.kind!r}")
+        if len(self.choices) < 2:  # noqa: PLR2004
+            raise ValueError(f"{self.id}: a question needs at least 2 choices")
+        if self.kind == QUESTION_PREDICT:
+            if not self.question_id:
+                raise ValueError(f"{self.id}: a prediction needs a question_id to reveal it later")
+            return
+        n_correct = sum(c.correct for c in self.choices)
+        if self.multi_select and n_correct < 1:
+            raise ValueError(f"{self.id}: select-all question needs at least one correct choice")
+        if not self.multi_select and n_correct != 1:
+            raise ValueError(f"{self.id}: single-choice question needs exactly one correct choice")
+        missing = [c.text for c in self.choices if not c.correct and not c.feedback]
+        if missing:
+            raise ValueError(f"{self.id}: wrong choices need feedback explaining why: {missing}")
+
+    @property
+    def correct_indices(self) -> frozenset[int]:
+        """Indices of the correct choices (empty for a prediction)."""
+        return frozenset(i for i, c in enumerate(self.choices) if c.correct)
+
+    def is_correct(self, selected: set[int] | frozenset[int]) -> bool:
+        """Whether `selected` (choice indices) answers the question.
+
+        Any non-empty selection answers a prediction.
+        """
+        if not selected:
+            return False
+        if self.kind == QUESTION_PREDICT:
+            return True
+        return frozenset(selected) == self.correct_indices
+
+
 @dataclass
 class Course:
     """A collection of polymorphic steps representing a guided tutorial course."""
@@ -284,5 +360,9 @@ __all__ = [
     "SubplotCheckStep",
     "WaitForEventStep",
     "ConsentStep",
+    "QUESTION_CHECK",
+    "QUESTION_PREDICT",
+    "AnswerChoice",
+    "QuestionStep",
     "Course",
 ]

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/tutorial_overlay.py

@@ -41,6 +41,7 @@ from .academy import (
 from .cyto_character import CytoWidget
 from .dialogs import ask_yes_no
 from .draggable import DraggableMixin
+from .question_panel import QuestionPanel
 from .theme_fallback import Colors, theme_manager
 from .tutorial_models import (
     BaseStep,
@@ -49,6 +50,7 @@ from .tutorial_models import (
     ForcedInteractionStep,
     InfoStep,
     InteractionStep,
+    QuestionStep,
     SubplotCheckStep,
     VerificationStep,
     WaitForEventStep,
@@ -137,6 +139,8 @@ class TutorialOverlay(QWidget):
         self.setAttribute(Qt.WidgetAttribute.WA_NoSystemBackground, True)
 
         self.target_rects: list[QRect] = []
+        # The live QuestionStep's answer panel, if any (see _render_question).
+        self.question_panel: QuestionPanel | None = None
         # The widget a step's allow_scroll=True should forward wheel events
         # to (see set_scroll_target()/wheelEvent()) — set by AcademyStepDriver
         # from the ancestor QScrollArea of the step's own target widget(s),
@@ -442,6 +446,10 @@ class TutorialOverlay(QWidget):
             self.cyto.apply_theme()
 
     def _update_text_rendering(self, text: str) -> None:
+        # `{answer:<id>}` placeholders → the learner's recorded answers.
+        format_text = getattr(self._academy_manager, "format_step_text", None)
+        if callable(format_text):
+            text = format_text(text)
         import re
 
         # Replace newlines with <br>
@@ -666,6 +674,10 @@ class TutorialOverlay(QWidget):
             self.btn_next.hide()
             self._render_checklist(step)
 
+        elif isinstance(step, QuestionStep):
+            self.btn_next.hide()
+            self._render_question(step)
+
         elif isinstance(step, SubplotCheckStep):
             self.btn_next.show()
             self.btn_next.setText("Confirm Subplot")
@@ -1223,6 +1235,59 @@ class TutorialOverlay(QWidget):
         if remaining_count == 0 and not getattr(self.current_step, "auto_advance_when_complete", False):
             self.btn_next.show()
 
+    def _render_question(self, step: QuestionStep) -> None:
+        """Choices in the bubble; Check in the footer, then Continue once answered."""
+        manager = self._academy_manager
+        panel = QuestionPanel(
+            step,
+            check=lambda selection, attempts: manager.record_answer(selection, attempts),
+            width=CONTENT_WIDTH,
+        )
+        self.question_panel = panel
+        self.dynamic_content.addWidget(panel)
+
+        self._clear_buttons()
+        self.btn_layout.addStretch()
+        self.btn_layout.addWidget(self.btn_previous)
+        self._show_previous_button()
+        btn_check = QPushButton("Check answer")
+        btn_check.setObjectName("QuestionCheckButton")
+        theme_manager.apply_style(
+            btn_check,
+            "background-color: {ACCENT_PRIMARY}; color: white; border: none; border-radius: 4px; padding: 6px 12px; font-weight: bold;",
+        )
+        btn_check.setCursor(Qt.CursorShape.PointingHandCursor)
+        btn_check.clicked.connect(panel.submit)
+        self.btn_layout.addWidget(btn_check)
+        btn_check.show()  # see _render_consent_options
+
+        def _on_answered() -> None:
+            btn_check.clicked.disconnect()
+            btn_check.setObjectName("QuestionContinueButton")
+            btn_check.setText("Let's find out →" if step.kind == "predict" else "Continue →")
+            btn_check.clicked.connect(lambda _checked=False: manager.next_step())
+
+        panel.answered.connect(_on_answered)
+        panel.content_changed.connect(self._on_question_content_changed)
+
+    def _on_question_content_changed(self) -> None:
+        """Feedback appeared or grew: re-fit the bubble and re-punch the mask.
+
+        Once now and once on the next event-loop turn: the panel's own layout
+        only settles after its pending LayoutRequest, and fitting to the stale
+        size hint squeezes the choices and clips the explanation's last lines.
+        """
+        self._refit_for_question()
+        QTimer.singleShot(0, self._refit_for_question)
+
+    def _refit_for_question(self) -> None:
+        if not self._is_alive():
+            return
+        self._force_resize()
+        if not self._user_positioned:
+            self._reposition_cyto_and_bubble(getattr(self, "target_rects", []))
+        self._update_mask()
+
     def _render_branching_options(self, options: dict) -> None:
         """Render branching-option buttons that advance to their selected tutorial steps.
 
@@ -1379,12 +1444,16 @@ class TutorialOverlay(QWidget):
         self._update_mask()
 
     def _clear_dynamic_content(self) -> None:
+        self.question_panel = None
         # Stop any running WaitForEventStep pulse timer
         if hasattr(self, "_wait_pulse_timer") and self._wait_pulse_timer.isActive():
             self._wait_pulse_timer.stop()
         while self.dynamic_content.count():
             item = self.dynamic_content.takeAt(0)
             if item.widget():
+                # Hidden now; deleteLater() waits for the event loop to come
+                # back round, and until then it would still paint in the bubble.
+                item.widget().hide()
                 item.widget().deleteLater()
 
     def _force_resize(self) -> None:

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0/src/karcytics_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karcytics-sdk
-Version: 2.2.0
+Version: 2.4.0
 Summary: Software Development Kit and CLI for Karcytics.
 Author: Kalaimaran Balasothy
 License: # PolyForm Noncommercial License 1.0.0

{karcytics_sdk-2.2.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk.egg-info/SOURCES.txt

@@ -64,6 +64,7 @@ src/karcytics_sdk/plugin/manifest.py
 src/karcytics_sdk/plugin/manifest_parser.py
 src/karcytics_sdk/plugin/menu_builder.py
 src/karcytics_sdk/plugin/preferences.py
+src/karcytics_sdk/plugin/question_panel.py
 src/karcytics_sdk/plugin/ribbon.py
 src/karcytics_sdk/plugin/runtime_services.py
 src/karcytics_sdk/plugin/security_parser.py
@@ -71,6 +72,7 @@ src/karcytics_sdk/plugin/signals.py
 src/karcytics_sdk/plugin/state.py
 src/karcytics_sdk/plugin/theme_fallback.py
 src/karcytics_sdk/plugin/toast.py
+src/karcytics_sdk/plugin/tutorial_highlight.py
 src/karcytics_sdk/plugin/tutorial_models.py
 src/karcytics_sdk/plugin/tutorial_overlay.py
 src/karcytics_sdk/plugin/ui_daemon_runtime.py