plotaviz 0.1.0__py3-none-any.whl

plotaviz/ui/nl_query_bar.py

@@ -0,0 +1,219 @@
+"""The natural-language query bar.
+
+Type "revenue by region over time", get a chart. The important design decision is what happens
+in between: the model returns a **chart spec**, PlotaViz validates it against the real schema,
+and then *shows the user the spec it interpreted* before drawing. The mapping is never opaque,
+and it stays editable — if the model picked the wrong column, that is one dropdown away from
+fixed rather than a reason to give up on the feature.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Signal
+from PySide6.QtWidgets import (
+    QComboBox,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QProgressBar,
+    QPushButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..core.spec import AGGREGATIONS, CHART_TYPES, ChartSpec
+
+#: Example prompts shown as placeholder text, rotated so the bar suggests what it can do.
+EXAMPLES = (
+    "revenue by region over time",
+    "how does price relate to size?",
+    "distribution of response times",
+    "average score per department",
+)
+
+
+class NLQueryBar(QWidget):
+    """Free-text input plus an editable view of the interpreted chart spec.
+
+    Signals:
+        question_asked: Emitted with the user's text when they submit a query.
+        spec_edited: Emitted with a :class:`ChartSpec` when the user tweaks the interpretation.
+        settings_requested: Emitted when the user clicks through to configure a provider.
+    """
+
+    question_asked = Signal(str)
+    spec_edited = Signal(object)
+    settings_requested = Signal()
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self._columns: list[str] = []
+        self._spec: ChartSpec | None = None
+        self._updating = False
+        self._configured = False
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(8, 6, 8, 6)
+        layout.setSpacing(6)
+
+        # --- the question row
+        row = QHBoxLayout()
+        self.input = QLineEdit(self)
+        self.input.setPlaceholderText(f"Ask for a chart — e.g. {EXAMPLES[0]}")
+        self.input.setClearButtonEnabled(True)
+        self.input.returnPressed.connect(self._submit)
+        self.ask_button = QPushButton("Ask", self)
+        self.ask_button.clicked.connect(self._submit)
+        row.addWidget(self.input, stretch=1)
+        row.addWidget(self.ask_button)
+        layout.addLayout(row)
+
+        self.busy = QProgressBar(self)
+        self.busy.setRange(0, 0)
+        self.busy.setTextVisible(False)
+        self.busy.setMaximumHeight(3)
+        self.busy.hide()
+        layout.addWidget(self.busy)
+
+        self.status = QLabel("", self)
+        self.status.setWordWrap(True)
+        self.status.setStyleSheet("color: palette(mid); font-size: 11px;")
+        self.status.hide()
+        layout.addWidget(self.status)
+
+        # --- the interpreted spec, editable
+        self.interpretation = QFrame(self)
+        self.interpretation.setFrameShape(QFrame.Shape.StyledPanel)
+        interp_layout = QHBoxLayout(self.interpretation)
+        interp_layout.setContentsMargins(8, 4, 8, 4)
+
+        caption = QLabel("Interpreted as", self.interpretation)
+        caption.setStyleSheet("color: palette(mid); font-size: 11px;")
+        interp_layout.addWidget(caption)
+
+        self.chart_combo = self._combo(CHART_TYPES)
+        self.x_combo = self._combo([])
+        self.y_combo = self._combo([])
+        self.color_combo = self._combo([])
+        self.agg_combo = self._combo(("none", *AGGREGATIONS))
+
+        for label, combo in (
+            ("chart", self.chart_combo),
+            ("x", self.x_combo),
+            ("y", self.y_combo),
+            ("colour", self.color_combo),
+            ("aggregate", self.agg_combo),
+        ):
+            tag = QLabel(label, self.interpretation)
+            tag.setStyleSheet("color: palette(mid); font-size: 11px;")
+            interp_layout.addWidget(tag)
+            interp_layout.addWidget(combo)
+
+        interp_layout.addStretch(1)
+        self.interpretation.hide()
+        layout.addWidget(self.interpretation)
+
+    def _combo(self, values: object) -> QComboBox:
+        """Build a combo box wired to emit an edited spec."""
+        combo = QComboBox(self)
+        combo.addItems([str(v) for v in values])  # type: ignore[arg-type]
+        combo.currentIndexChanged.connect(self._on_edited)
+        return combo
+
+    # ------------------------------------------------------------------ state
+
+    def set_columns(self, columns: list[str]) -> None:
+        """Populate the column dropdowns for the current dataset."""
+        self._columns = list(columns)
+        self._updating = True
+        for combo in (self.x_combo, self.y_combo, self.color_combo):
+            combo.clear()
+            combo.addItem("none")
+            combo.addItems(self._columns)
+        self._updating = False
+
+    def set_enabled_for_provider(self, configured: bool, provider_name: str = "") -> None:
+        """Enable or disable the bar depending on whether an LLM provider is set up.
+
+        Disabled is the honest state when there is no provider — the rest of PlotaViz works
+        offline, but turning free text into a chart genuinely needs a model.
+        """
+        self._configured = configured
+        self.input.setEnabled(configured)
+        self.ask_button.setEnabled(configured)
+        if configured:
+            provider = f" via {provider_name}" if provider_name else ""
+            self.input.setPlaceholderText(f"Ask for a chart{provider} — e.g. {EXAMPLES[0]}")
+            self.status.hide()
+        else:
+            self.input.setPlaceholderText("Set up an LLM provider to ask for charts in words")
+            self.show_status(
+                "No LLM provider is configured, so the query bar is off. Chart recommendations "
+                "work without one. Configure a provider in Settings, or install Ollama to keep "
+                "everything on this machine."
+            )
+
+    def set_busy(self, busy: bool) -> None:
+        """Show or hide the indeterminate progress strip and lock the input while waiting."""
+        self.busy.setVisible(busy)
+        enabled = self._configured and not busy
+        self.input.setEnabled(enabled)
+        self.ask_button.setEnabled(enabled)
+
+    def show_status(self, message: str, *, error: bool = False) -> None:
+        """Show a status or error line under the input."""
+        self.status.setText(message)
+        self.status.setStyleSheet(
+            "color: #C0392B; font-size: 11px;" if error else "color: palette(mid); font-size: 11px;"
+        )
+        self.status.show()
+
+    def show_spec(self, spec: ChartSpec) -> None:
+        """Display the interpreted spec so the mapping is visible and editable."""
+        self._spec = spec
+        self._updating = True
+
+        self.chart_combo.setCurrentText(spec.chart)
+        self.x_combo.setCurrentText(spec.x or "none")
+        self.y_combo.setCurrentText(spec.y or "none")
+        self.color_combo.setCurrentText(spec.color or "none")
+        self.agg_combo.setCurrentText(spec.agg or "none")
+
+        self._updating = False
+        self.interpretation.show()
+        if spec.why:
+            self.show_status(spec.why)
+
+    def hide_interpretation(self) -> None:
+        """Collapse the interpreted-spec row."""
+        self.interpretation.hide()
+
+    # ------------------------------------------------------------------ signals
+
+    def _submit(self) -> None:
+        """Emit the user's question."""
+        question = self.input.text().strip()
+        if question:
+            self.question_asked.emit(question)
+
+    def _on_edited(self, *_: object) -> None:
+        """Emit a spec reflecting the user's manual tweak to the interpretation."""
+        if self._updating or self._spec is None:
+            return
+
+        def value(combo: QComboBox) -> str | None:
+            text = combo.currentText()
+            return None if text == "none" else text
+
+        edited = self._spec.copy(
+            chart=self.chart_combo.currentText(),
+            x=value(self.x_combo),
+            y=value(self.y_combo),
+            color=value(self.color_combo),
+            agg=value(self.agg_combo),
+            source="user",
+            why="Adjusted by you.",
+        )
+        self._spec = edited
+        self.spec_edited.emit(edited)

plotaviz/ui/settings_dialog.py

@@ -0,0 +1,313 @@
+"""Settings — LLM provider, API keys, and performance thresholds.
+
+The key handling here is the part worth reading. Keys go into the **OS keyring** and nowhere
+else: not into a config file, not into the session, not into the window's own state after the
+dialog closes. The field shows a masked placeholder when a key is already stored, so the user can
+tell it is set without the value being displayed or re-read.
+
+The consent checkbox is not decoration. Nothing is sent to a remote provider until it is ticked,
+and the Ollama path skips the question entirely because nothing leaves the machine.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QSettings
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QComboBox,
+    QDialog,
+    QDialogButtonBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QSpinBox,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..core.llm import PROVIDERS, OllamaProvider, delete_api_key, get_api_key, set_api_key
+from ..core.loader import DEFAULT_LARGE_FILE_MB
+from ..core.plotter import MAX_POINTS
+
+#: Placeholder shown when a key is already in the keyring. The real value is never displayed.
+_STORED_PLACEHOLDER = "•" * 24
+
+_PROVIDER_LABELS = {
+    "anthropic": "Anthropic (Claude)",
+    "openai": "OpenAI",
+    "gemini": "Google Gemini",
+    "ollama": "Ollama (local — nothing leaves this machine)",
+}
+
+
+class SettingsDialog(QDialog):
+    """Configures the LLM provider and performance thresholds.
+
+    Args:
+        parent: Parent widget.
+        settings: The app's ``QSettings``. Non-secret preferences are stored here; keys are not.
+    """
+
+    def __init__(self, parent: QWidget | None = None, *, settings: QSettings | None = None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("PlotaViz settings")
+        self.setMinimumWidth(560)
+        self._settings = settings or QSettings("plotaviz", "plotaviz")
+
+        layout = QVBoxLayout(self)
+
+        # ------------------------------------------------------------------ LLM
+        llm_box = QGroupBox("LLM assistance (optional)", self)
+        llm_form = QFormLayout(llm_box)
+
+        intro = QLabel(
+            "PlotaViz recommends charts on its own, offline, with no provider configured. "
+            "A model adds two things: a second opinion when the ranking is close, and the "
+            "natural-language query bar.",
+            llm_box,
+        )
+        intro.setWordWrap(True)
+        intro.setStyleSheet("color: palette(mid); font-size: 11px;")
+        llm_form.addRow(intro)
+
+        self.provider_combo = QComboBox(llm_box)
+        self.provider_combo.addItem("None — use the local engine only", "")
+        for name in PROVIDERS:
+            self.provider_combo.addItem(_PROVIDER_LABELS.get(name, name), name)
+        self.provider_combo.currentIndexChanged.connect(self._on_provider_changed)
+        llm_form.addRow("Provider", self.provider_combo)
+
+        self.model_combo = QComboBox(llm_box)
+        self.model_combo.setEditable(True)
+        llm_form.addRow("Model", self.model_combo)
+
+        key_row = QHBoxLayout()
+        self.key_edit = QLineEdit(llm_box)
+        self.key_edit.setEchoMode(QLineEdit.EchoMode.Password)
+        self.key_edit.setPlaceholderText("Paste an API key")
+        self.clear_key_button = QPushButton("Forget key", llm_box)
+        self.clear_key_button.clicked.connect(self._forget_key)
+        key_row.addWidget(self.key_edit, stretch=1)
+        key_row.addWidget(self.clear_key_button)
+        llm_form.addRow("API key", key_row)
+
+        key_note = QLabel(
+            "Keys are stored in your operating system's keychain, never in a config file, a "
+            "session file, or this project's folder.",
+            llm_box,
+        )
+        key_note.setWordWrap(True)
+        key_note.setStyleSheet("color: palette(mid); font-size: 11px;")
+        llm_form.addRow("", key_note)
+
+        self.host_edit = QLineEdit(llm_box)
+        self.host_edit.setPlaceholderText("http://localhost:11434")
+        llm_form.addRow("Ollama host", self.host_edit)
+
+        self.consent_check = QCheckBox(
+            "Allow sending column names, summary statistics, and up to 5 sample rows", llm_box
+        )
+        self.consent_check.setToolTip(
+            "The dataset itself is never uploaded. Only schema and statistics are sent, and only "
+            "when you ask for a suggestion."
+        )
+        llm_form.addRow("Consent", self.consent_check)
+
+        self.status_label = QLabel("", llm_box)
+        self.status_label.setWordWrap(True)
+        llm_form.addRow("", self.status_label)
+
+        test_button = QPushButton("Test connection", llm_box)
+        test_button.clicked.connect(self._test_connection)
+        llm_form.addRow("", test_button)
+
+        layout.addWidget(llm_box)
+
+        # ------------------------------------------------------------------ performance
+        perf_box = QGroupBox("Performance", self)
+        perf_form = QFormLayout(perf_box)
+
+        self.large_file_spin = QSpinBox(perf_box)
+        self.large_file_spin.setRange(10, 20_000)
+        self.large_file_spin.setSingleStep(50)
+        self.large_file_spin.setSuffix(" MB")
+        self.large_file_spin.setToolTip(
+            "Files above this size are read with polars and profiled on a sample."
+        )
+        perf_form.addRow("Use the fast reader above", self.large_file_spin)
+
+        self.max_points_spin = QSpinBox(perf_box)
+        self.max_points_spin.setRange(1_000, 2_000_000)
+        self.max_points_spin.setSingleStep(10_000)
+        self.max_points_spin.setGroupSeparatorShown(True)
+        self.max_points_spin.setToolTip(
+            "Scatter and line charts above this many points are downsampled. Raising it past "
+            "about 100,000 will make the interactive view sluggish."
+        )
+        perf_form.addRow("Downsample charts above", self.max_points_spin)
+
+        self.static_check = QCheckBox(
+            "Always use the static renderer (no interactive view)", perf_box
+        )
+        self.static_check.setToolTip(
+            "Useful on machines without QtWebEngine, or when you prefer matplotlib output."
+        )
+        perf_form.addRow("Renderer", self.static_check)
+
+        layout.addWidget(perf_box)
+
+        buttons = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Save | QDialogButtonBox.StandardButton.Cancel, self
+        )
+        buttons.accepted.connect(self._save)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+        self._load()
+
+    # ------------------------------------------------------------------ load / save
+
+    def _load(self) -> None:
+        """Populate the dialog from QSettings and the keyring."""
+        provider = str(self._settings.value("llm/provider", "") or "")
+        index = self.provider_combo.findData(provider)
+        self.provider_combo.setCurrentIndex(max(0, index))
+
+        self.host_edit.setText(
+            str(self._settings.value("llm/ollama_host", "http://localhost:11434"))
+        )
+        self.consent_check.setChecked(self._settings.value("llm/consent", False, type=bool))
+        self.large_file_spin.setValue(
+            int(self._settings.value("performance/large_file_mb", DEFAULT_LARGE_FILE_MB))
+        )
+        self.max_points_spin.setValue(
+            int(self._settings.value("performance/max_points", MAX_POINTS))
+        )
+        self.static_check.setChecked(
+            self._settings.value("performance/prefer_static", False, type=bool)
+        )
+
+        self._on_provider_changed()
+        model = str(self._settings.value("llm/model", "") or "")
+        if model:
+            self.model_combo.setCurrentText(model)
+
+    def _save(self) -> None:
+        """Write settings, and put any newly entered key into the keyring."""
+        provider = str(self.provider_combo.currentData() or "")
+        self._settings.setValue("llm/provider", provider)
+        self._settings.setValue("llm/model", self.model_combo.currentText().strip())
+        self._settings.setValue("llm/ollama_host", self.host_edit.text().strip())
+        self._settings.setValue("llm/consent", self.consent_check.isChecked())
+        self._settings.setValue("performance/large_file_mb", self.large_file_spin.value())
+        self._settings.setValue("performance/max_points", self.max_points_spin.value())
+        self._settings.setValue("performance/prefer_static", self.static_check.isChecked())
+
+        key = self.key_edit.text().strip()
+        if provider and key and key != _STORED_PLACEHOLDER:
+            try:
+                set_api_key(provider, key)
+            except Exception as exc:
+                self.status_label.setText(str(exc))
+                self.status_label.setStyleSheet("color: #C0392B;")
+                return
+
+        self._settings.sync()
+        self.accept()
+
+    # ------------------------------------------------------------------ interaction
+
+    def _on_provider_changed(self, *_: object) -> None:
+        """Update the model list, key field, and consent state for the chosen provider."""
+        provider = str(self.provider_combo.currentData() or "")
+        is_ollama = provider == "ollama"
+        needs_key = bool(provider) and not is_ollama
+
+        self.key_edit.setEnabled(needs_key)
+        self.clear_key_button.setEnabled(needs_key)
+        self.host_edit.setEnabled(is_ollama)
+        self.consent_check.setEnabled(needs_key)
+
+        self.model_combo.clear()
+        if provider:
+            cls = PROVIDERS[provider]
+            self.model_combo.addItems(list(cls.available_models))
+            self.model_combo.setCurrentText(cls.default_model)
+
+        if needs_key:
+            stored = get_api_key(provider)
+            self.key_edit.setText(_STORED_PLACEHOLDER if stored else "")
+            self.status_label.setText(
+                "A key is stored in your keychain." if stored else "No key stored yet."
+            )
+            self.status_label.setStyleSheet("color: palette(mid); font-size: 11px;")
+        elif is_ollama:
+            self.key_edit.clear()
+            self.consent_check.setChecked(True)
+            self.status_label.setText(
+                "Ollama runs locally. No API key and no network access are needed, and no data "
+                "leaves this machine."
+            )
+            self.status_label.setStyleSheet("color: #1F7A5C; font-size: 11px;")
+        else:
+            self.key_edit.clear()
+            self.status_label.setText(
+                "PlotaViz will use its own rules engine. Everything except the natural-language "
+                "query bar works normally."
+            )
+            self.status_label.setStyleSheet("color: palette(mid); font-size: 11px;")
+
+    def _forget_key(self) -> None:
+        """Delete the stored key for the selected provider."""
+        provider = str(self.provider_combo.currentData() or "")
+        if not provider:
+            return
+        delete_api_key(provider)
+        self.key_edit.clear()
+        self.status_label.setText("Key removed from your keychain.")
+        self.status_label.setStyleSheet("color: palette(mid); font-size: 11px;")
+
+    def _test_connection(self) -> None:
+        """Check the provider looks usable without sending any data."""
+        provider = str(self.provider_combo.currentData() or "")
+        if not provider:
+            self.status_label.setText(
+                "No provider selected — the local engine is always available."
+            )
+            self.status_label.setStyleSheet("color: palette(mid); font-size: 11px;")
+            return
+
+        if provider == "ollama":
+            client = OllamaProvider(host=self.host_edit.text().strip() or "http://localhost:11434")
+            if client.is_running():
+                models = client.list_models()
+                listed = ", ".join(models[:5]) if models else "no models pulled yet"
+                self.status_label.setText(f"Ollama is running. Models: {listed}")
+                self.status_label.setStyleSheet("color: #1F7A5C; font-size: 11px;")
+            else:
+                self.status_label.setText(
+                    f"No Ollama server answered at {client.host}. Start it with `ollama serve`."
+                )
+                self.status_label.setStyleSheet("color: #C0392B; font-size: 11px;")
+            return
+
+        typed = self.key_edit.text().strip()
+        has_key = bool(typed and typed != _STORED_PLACEHOLDER) or bool(get_api_key(provider))
+        if has_key:
+            self.status_label.setText(
+                "A key is available. It is checked for real the first time you ask for a "
+                "suggestion."
+            )
+            self.status_label.setStyleSheet("color: #1F7A5C; font-size: 11px;")
+        else:
+            self.status_label.setText("No API key for this provider yet.")
+            self.status_label.setStyleSheet("color: #C0392B; font-size: 11px;")
+
+    # ------------------------------------------------------------------ results
+
+    def provider_name(self) -> str:
+        """The provider the user selected, or an empty string for local-only."""
+        return str(self.provider_combo.currentData() or "")