zeno-cli 0.3.4__py3-none-any.whl

zeno_core/tlx_s.py

@@ -0,0 +1,192 @@
+"""DEPRECATED 2026-06-07 PM3 - use zeno_core.rtlx_s instead.
+
+The 10-subscale NASA-TLX-S TUI was the v0 cognitive-load probe. Research 1
+(2026-06-07 PM3) replaced it with the 5-item RTLX-S (raw NASA-TLX core +
+Supervision + Execution). New code MUST import from zeno_core.rtlx_s.
+
+This module is kept on disk so existing tests (tests/test_tlx_s.py) and
+legacy load_probe_records rows remain queryable. See docs/DEPRECATED.md.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from textual.app import App, ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Button, Input, Label
+
+SUBSCALES: tuple[tuple[str, str], ...] = (
+    (
+        "mental_demand",
+        "Mental Demand (NASA-TLX): How mentally demanding was supervising the agent crew?",
+    ),
+    (
+        "physical_demand",
+        "Physical Demand (NASA-TLX): How physically demanding was the supervision task?",
+    ),
+    (
+        "temporal_demand",
+        "Temporal Demand (NASA-TLX): How hurried or rushed was the supervision pace?",
+    ),
+    (
+        "performance",
+        "Performance (NASA-TLX): How successful were you in meeting supervision goals?",
+    ),
+    ("effort", "Effort (NASA-TLX): How hard did you have to work to supervise effectively?"),
+    (
+        "frustration",
+        "Frustration (NASA-TLX): How insecure, discouraged, irritated, stressed, "
+        "or annoyed were you?",
+    ),
+    (
+        "trust_calibration_demand",
+        "Trust Calibration Demand (SCLT): How demanding was calibrating trust in agent outputs?",
+    ),
+    (
+        "oversight_demand",
+        "Oversight Demand (SCLT): How demanding was keeping adequate oversight of all agents?",
+    ),
+    (
+        "integration_demand",
+        "Integration Demand (SCLT): How demanding was integrating outputs from multiple agents "
+        "into one coherent result?",
+    ),
+    (
+        "intervention_decision_demand",
+        "Intervention Decision Demand (SCLT): How demanding was deciding "
+        "when and how to intervene?",
+    ),
+)
+
+
+@dataclass(slots=True)
+class TLXSurveyResult:
+    skipped: bool
+    subscales: dict[str, int] | None
+    comment_hash: str | None
+    prompted_at: datetime
+    responded_at: datetime | None
+
+
+class NumericSlider(Input):
+    def __init__(self, *, value: int = 50, widget_id: str) -> None:
+        super().__init__(value=str(value), id=widget_id)
+
+    @property
+    def slider_value(self) -> int:
+        try:
+            parsed = int(float(self.value))
+        except ValueError:
+            parsed = 50
+        return max(0, min(100, parsed))
+
+
+def validate_item_wording() -> dict[str, str]:
+    return {key: wording for key, wording in SUBSCALES}
+
+
+def compute_composite_load(
+    subscales: dict[str, int], weights: dict[str, float] | None = None
+) -> float:
+    weights = weights or {key: 1.0 for key, _ in SUBSCALES}
+    weighted_sum = sum(subscales[key] * weights[key] for key, _ in SUBSCALES)
+    weight_total = sum(weights[key] for key, _ in SUBSCALES)
+    return weighted_sum / weight_total
+
+
+def compute_babysitting_tax_index(composite_load: float, n_agents_active: int) -> float:
+    return composite_load * (max(n_agents_active, 0) ** 0.7)
+
+
+def should_prompt_probe(
+    *,
+    session_duration_minutes: float,
+    sessions_since_last_probe: int,
+    probes_enabled: bool,
+    seconds_since_last_probe: float | None,
+    active_agent_runs: int,
+) -> bool:
+    if not probes_enabled:
+        return False
+    if active_agent_runs > 0:
+        return False
+    if seconds_since_last_probe is not None and seconds_since_last_probe < 30:
+        return False
+    if session_duration_minutes > 10:
+        return True
+    return sessions_since_last_probe >= 5
+
+
+class TLXSurveyApp(App[TLXSurveyResult]):
+    TITLE = "NASA-TLX-S Survey"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.prompted_at = datetime.now(tz=UTC)
+        self._sliders: dict[str, NumericSlider] = {}
+        self._comment = Input(placeholder="Optional one-line comment")
+
+    def compose(self) -> ComposeResult:
+        yield Label("Rate each item from 0 to 100.")
+        with Vertical():
+            for key, wording in SUBSCALES:
+                yield Label(wording)
+                slider = NumericSlider(value=50, widget_id=f"slider-{key}")
+                self._sliders[key] = slider
+                yield slider
+        yield self._comment
+        yield Button("Submit", id="submit")
+        yield Button("Skip", id="skip", variant="warning")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "skip":
+            self.exit(
+                TLXSurveyResult(
+                    skipped=True,
+                    subscales=None,
+                    comment_hash=None,
+                    prompted_at=self.prompted_at,
+                    responded_at=None,
+                )
+            )
+            return
+
+        if event.button.id == "submit":
+            comment = self._comment.value.strip()
+            comment_hash = hashlib.sha256(comment.encode("utf-8")).hexdigest() if comment else None
+            subscales = {key: self._sliders[key].slider_value for key, _ in SUBSCALES}
+            self.exit(
+                TLXSurveyResult(
+                    skipped=False,
+                    subscales=subscales,
+                    comment_hash=comment_hash,
+                    prompted_at=self.prompted_at,
+                    responded_at=datetime.now(tz=UTC),
+                )
+            )
+
+
+def run_tlx_survey_tui() -> TLXSurveyResult:
+    if not sys.stdin.isatty():
+        return TLXSurveyResult(
+            skipped=True,
+            subscales=None,
+            comment_hash=None,
+            prompted_at=datetime.now(tz=UTC),
+            responded_at=None,
+        )
+    app = TLXSurveyApp()
+    result = app.run()
+    if isinstance(result, TLXSurveyResult):
+        return result
+    return TLXSurveyResult(
+        skipped=True,
+        subscales=None,
+        comment_hash=None,
+        prompted_at=datetime.now(tz=UTC),
+        responded_at=None,
+    )

zeno_sdk/__init__.py

@@ -0,0 +1,6 @@
+"""Python SDK package."""
+
+from . import _generated, types
+from .client import Zeno
+
+__all__ = ["Zeno", "_generated", "types"]

zeno_sdk/_generated/__init__.py

@@ -0,0 +1,6 @@
+from .client import ApiError, ZenoApiClient
+
+__all__ = [
+    "ApiError",
+    "ZenoApiClient",
+]