superqode 2.4.6__tar.gz → 2.4.7__tar.gz

{superqode-2.4.6 → superqode-2.4.7}/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to SuperQode will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.7] - 2026-09-20
+
+### Fixed
+- SystemOne Tune now explains when `TYPESAFE_API_KEY` or the reflection provider key (OpenAI, Anthropic, Gemini) is missing, instead of Start looking like a no-op.
+
 ## [2.4.6] - 2026-09-19
 
 ### SystemOne Tune

{superqode-2.4.6 → superqode-2.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.4.6
+Version: 2.4.7
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

{superqode-2.4.6 → superqode-2.4.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.4.6"
+version = "2.4.7"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-2.4.6 → superqode-2.4.7}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.4.6"
+__version__ = "2.4.7"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

{superqode-2.4.6 → superqode-2.4.7}/src/superqode/systemone/tune.py

@@ -151,6 +151,53 @@ def default_reflection_model() -> str:
     return ""
 
 
+def reflection_api_key_env(model: str) -> str | None:
+    """Env var required for this reflection model id, when the provider is known."""
+    name = (model or "").strip().lower()
+    if not name:
+        return None
+    provider = name.split("/", 1)[0]
+    return {
+        "openai": "OPENAI_API_KEY",
+        "anthropic": "ANTHROPIC_API_KEY",
+        "gemini": "GEMINI_API_KEY",
+        "google": "GEMINI_API_KEY",
+    }.get(provider)
+
+
+def missing_tune_credentials(
+    *, reflection_lm: str = "", api_key_env: str = "TYPESAFE_API_KEY"
+) -> list[str]:
+    """Blockers that would make Start do nothing useful without a clear error."""
+    missing: list[str] = []
+    key_env = (api_key_env or "TYPESAFE_API_KEY").strip() or "TYPESAFE_API_KEY"
+    if not str(os.environ.get(key_env) or "").strip():
+        missing.append(
+            f"Set {key_env} for live Jev scoring (export {key_env}=... in this shell, then restart SuperQode)."
+        )
+    model = (reflection_lm or "").strip()
+    if not model:
+        missing.append(
+            "Choose a reflection model (provider/model), or set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY so a default can be chosen."
+        )
+    else:
+        provider_env = reflection_api_key_env(model)
+        if provider_env and not str(os.environ.get(provider_env) or "").strip():
+            missing.append(
+                f"Reflection model {model} needs {provider_env} (export {provider_env}=..., then restart SuperQode)."
+            )
+    return missing
+
+
+def format_missing_tune_credentials(missing: list[str]) -> str:
+    if not missing:
+        return ""
+    lines = ["Cannot start the experiment yet:"]
+    lines.extend(f"• {item}" for item in missing)
+    lines.append("Fix the items above, then click Start experiment again.")
+    return "\n".join(lines)
+
+
 def load_tune_pack(options: TuneOptions) -> tuple[QuestionPack, Any]:
     from superqode.harness.loader import load_harness_spec
 
@@ -457,6 +504,12 @@ def _settings(manifest: dict):
         spec=spec, explicit=None if spec else SimpleNamespace(enabled=True, client="live")
     )
     if settings.skip_client or not settings.enabled or settings.client != "live":
+        missing = missing_tune_credentials(
+            reflection_lm=str((manifest.get("options") or {}).get("reflection_lm") or ""),
+            api_key_env=getattr(settings, "api_key_env", "TYPESAFE_API_KEY"),
+        )
+        if missing:
+            raise ValueError(format_missing_tune_credentials(missing))
         raise ValueError(
             "Tune needs live Jev evaluation. Check SystemOne settings and API credentials; stub/replay cannot measure new prompts."
         )
@@ -469,10 +522,21 @@ def preflight(manifest: dict, *, check_gepa: bool = True) -> dict:
         raise ValueError(
             "Set a positive evaluation budget and a reflection limit between $0 and $1000."
         )
-    if not options.reflection_lm.strip():
-        raise ValueError(
-            "Choose a reflection model (provider/model) or configure OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY."
-        )
+    reflection = options.reflection_lm.strip()
+    # Peek at SystemOne config for the expected live key name without requiring live yet.
+    from types import SimpleNamespace
+    from superqode.harness.loader import harness_spec_from_dict
+    from superqode.systemone.config import resolve_systemone
+
+    spec = harness_spec_from_dict(manifest["harness"]) if manifest.get("harness") else None
+    probe = resolve_systemone(
+        spec=spec, explicit=None if spec else SimpleNamespace(enabled=True, client="live")
+    )
+    missing = missing_tune_credentials(
+        reflection_lm=reflection, api_key_env=getattr(probe, "api_key_env", "TYPESAFE_API_KEY")
+    )
+    if missing:
+        raise ValueError(format_missing_tune_credentials(missing))
     settings = _settings(manifest)
     if check_gepa:
         try:

{superqode-2.4.6 → superqode-2.4.7}/src/superqode/widgets/systemone_tune.py

@@ -121,12 +121,33 @@ class SystemOneTuneScreen(Screen[str | None]):
             self.query_one("#tune-cost", Input).value = str(prefs["max_reflection_cost"])
         self._refresh_support_status()
 
+    def _credential_status(self) -> str:
+        model = self._value("model") if self.is_mounted else ""
+        model = model or tune.preferred_reflection_model()
+        api_key_env = "TYPESAFE_API_KEY"
+        try:
+            from types import SimpleNamespace
+            from superqode.systemone.config import resolve_systemone
+
+            probe = resolve_systemone(
+                spec=None, explicit=SimpleNamespace(enabled=True, client="live")
+            )
+            api_key_env = getattr(probe, "api_key_env", api_key_env) or api_key_env
+        except Exception:
+            pass
+        missing = tune.missing_tune_credentials(reflection_lm=model, api_key_env=api_key_env)
+        return tune.format_missing_tune_credentials(missing)
+
     def _refresh_support_status(self) -> None:
         ready = tune.tuning_support_available()
         install_btn = self.query_one("#tune-install", Button)
         install_btn.disabled = ready
         if ready:
-            self._status("Tuning support is ready. Fill the pack and examples, then Prepare.")
+            creds = self._credential_status()
+            if creds:
+                self._status(creds)
+            else:
+                self._status("Tuning support is ready. Fill the pack and examples, then Prepare.")
         else:
             self._status(
                 "Tuning support (GEPA) is not installed yet. Click Install tuning support before Start. Prepare and labeling work without it."
@@ -230,12 +251,14 @@ class SystemOneTuneScreen(Screen[str | None]):
         else:
             options = self.manifest["options"]
             test_count = sum(row["split"] == "test" for row in self.manifest["examples"])
+            creds = self._credential_status()
             self._status(
                 f"Ready · {len(self.manifest['examples'])} reviewed examples\n"
                 f"Up to {options['max_evals']} optimization evaluations + {2 * test_count} final test evaluations.\n"
                 f"Reflection: {options['reflection_lm'] or 'not configured'} · ceiling ${options['max_reflection_cost']:.2f}. Jev usage/retries are additional.\n"
                 "Jev receives example inputs and criteria. The reflection provider also receives development examples and rationales.\n"
                 f"Saved experiment: {self.output}\nSmall demos are pilots and cannot qualify for adoption."
+                + (("\n" + creds) if creds else "")
             )
             self.query_one("#tune-start").display = True
 
@@ -260,6 +283,10 @@ class SystemOneTuneScreen(Screen[str | None]):
             return
         try:
             self._remember_preferences()
+            creds = self._credential_status()
+            if creds:
+                self._status(creds)
+                return
             if not tune.tuning_support_available():
                 self._status(
                     "Install tuning support first, then Start. No restart is usually required after Install succeeds."
@@ -272,9 +299,12 @@ class SystemOneTuneScreen(Screen[str | None]):
             )
             tune.write_json(self.output / "run.json", self.manifest)
             details = tune.preflight(self.manifest)
-        except (ValueError, OSError) as exc:
+        except (ValueError, OSError, KeyError, TypeError) as exc:
             self._status(str(exc))
             return
+        except Exception as exc:
+            self._status(f"Could not start the experiment: {exc}")
+            return
         self.cancel.clear()
         self.running = True
         self.query_one("#tune-start", Button).disabled = True

{superqode-2.4.6 → superqode-2.4.7}/src/superqode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.4.6
+Version: 2.4.7
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

{superqode-2.4.6 → superqode-2.4.7}/src/superqode.egg-info/SOURCES.txt

@@ -1067,6 +1067,7 @@ tests/test_tui_mounted.py
 tests/test_tui_onboarding.py
 tests/test_tui_smoke.py
 tests/test_tui_tool_display.py
+tests/test_tune_credentials.py
 tests/test_tune_preferences.py
 tests/test_uhp_backend.py
 tests/test_uhp_client.py

{superqode-2.4.6 → superqode-2.4.7}/tests/test_systemone_tune.py

@@ -425,6 +425,9 @@ async def test_tui_completed_run_exposes_diff_but_not_pilot_adoption(tmp_path):
 @pytest.mark.asyncio
 async def test_tui_start_worker_produces_report(tmp_path, monkeypatch):
     out = prepare(tmp_path)
+    monkeypatch.setenv("TYPESAFE_API_KEY", "typesafe-test")
+    monkeypatch.setenv("GEMINI_API_KEY", "gemini-test")
+    monkeypatch.setattr(tune, "missing_tune_credentials", lambda **kwargs: [])
     monkeypatch.setattr(tune, "tuning_support_available", lambda: True)
     monkeypatch.setattr(
         tune,

superqode-2.4.7/tests/test_tune_credentials.py

@@ -0,0 +1,46 @@
+"""Tune refuses Start with clear credential guidance."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+
+import pytest
+
+from superqode.systemone import tune
+
+
+def test_missing_typesafe_and_reflection_keys(monkeypatch):
+    monkeypatch.delenv("TYPESAFE_API_KEY", raising=False)
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    missing = tune.missing_tune_credentials(reflection_lm="")
+    text = tune.format_missing_tune_credentials(missing)
+    assert "TYPESAFE_API_KEY" in text
+    assert "reflection model" in text.lower() or "OPENAI_API_KEY" in text
+
+
+def test_missing_provider_key_for_chosen_model(monkeypatch):
+    monkeypatch.setenv("TYPESAFE_API_KEY", "typesafe-test")
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    missing = tune.missing_tune_credentials(reflection_lm="gemini/gemini-3.6-flash")
+    text = tune.format_missing_tune_credentials(missing)
+    assert "GEMINI_API_KEY" in text
+    assert "gemini/gemini-3.6-flash" in text
+
+
+def test_ready_when_keys_present(monkeypatch):
+    monkeypatch.setenv("TYPESAFE_API_KEY", "typesafe-test")
+    monkeypatch.setenv("GEMINI_API_KEY", "gemini-test")
+    assert tune.missing_tune_credentials(reflection_lm="gemini/gemini-3.6-flash") == []
+
+
+def test_preflight_surfaces_missing_keys(monkeypatch):
+    monkeypatch.delenv("TYPESAFE_API_KEY", raising=False)
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    opts = tune.TuneOptions(
+        reflection_lm="gemini/gemini-3.6-flash", max_evals=10, max_reflection_cost=1.0
+    )
+    manifest = {"options": asdict(opts), "examples": [], "harness": None}
+    with pytest.raises(ValueError, match="TYPESAFE_API_KEY|Cannot start"):
+        tune.preflight(manifest, check_gepa=False)