little UI for the api key in headless mode. key should be persisted too

pyproject.toml

@@ -70,6 +70,8 @@ where = ["src"]
 [tool.setuptools.package-data]
 reachy_mini_conversation_app = [
   "images/*",
+  "static/*",
+  ".env.example",
   "demos/**/*.txt",
   "prompts_library/*.txt",
   "profiles/**/*.txt",

src/reachy_mini_conversation_app/console.py

@@ -1,39 +1,247 @@
-"""Bidirectional local audio stream.
+"""Bidirectional local audio stream with optional settings UI.
 
-records mic frames to the handler and plays handler audio frames to the speaker.
+In headless mode, there is no Gradio UI. If the OpenAI API key is not
+available via environment/.env, we expose a minimal settings page via the
+Reachy Mini Apps settings server to let non-technical users enter it.
+
+The settings UI is served from this package's ``static/`` folder and offers a
+single password field to set ``OPENAI_API_KEY``. Once set, we persist it to the
+app instance's ``.env`` file (if available) and proceed to start streaming.
 """
 
+import os
 import time
 import asyncio
 import logging
-from typing import List
+from typing import List, Optional
+from pathlib import Path
 
 from fastrtc import AdditionalOutputs, audio_to_float32
 from scipy.signal import resample
 
 from reachy_mini import ReachyMini
 from reachy_mini.media.media_manager import MediaBackend
+from reachy_mini_conversation_app.config import config
 from reachy_mini_conversation_app.openai_realtime import OpenaiRealtimeHandler
 
 
+try:
+    # FastAPI is provided by the Reachy Mini Apps runtime
+    from fastapi import FastAPI
+    from pydantic import BaseModel
+    from fastapi.responses import FileResponse, JSONResponse
+    from starlette.staticfiles import StaticFiles
+except Exception:  # pragma: no cover - only loaded when settings_app is used
+    FastAPI = object  # type: ignore[assignment]
+    FileResponse = object  # type: ignore[assignment]
+    JSONResponse = object  # type: ignore[assignment]
+    StaticFiles = object  # type: ignore[assignment]
+    BaseModel = object  # type: ignore[assignment]
+
+
 logger = logging.getLogger(__name__)
 
 
 class LocalStream:
     """LocalStream using Reachy Mini's recorder/player."""
 
-    def __init__(self, handler: OpenaiRealtimeHandler, robot: ReachyMini):
-        """Initialize the stream with an OpenAI realtime handler and pipelines."""
+    def __init__(
+        self,
+        handler: OpenaiRealtimeHandler,
+        robot: ReachyMini,
+        *,
+        settings_app: Optional[FastAPI] = None,
+        instance_path: Optional[str] = None,
+    ):
+        """Initialize the stream with an OpenAI realtime handler and pipelines.
+
+        - ``settings_app``: the Reachy Mini Apps FastAPI to attach settings endpoints.
+        - ``instance_path``: directory where per-instance ``.env`` should be stored.
+        """
         self.handler = handler
         self._robot = robot
         self._stop_event = asyncio.Event()
         self._tasks: List[asyncio.Task[None]] = []
         # Allow the handler to flush the player queue when appropriate.
         self.handler._clear_queue = self.clear_audio_queue
+        self._settings_app: Optional[FastAPI] = settings_app
+        self._instance_path: Optional[str] = instance_path
+        self._settings_initialized = False
+
+    # ---- Settings UI (only when API key is missing) ----
+    def _persist_api_key(self, key: str) -> None:
+        """Persist API key to environment and instance ``.env`` if possible.
+
+        Behavior:
+        - Always sets ``OPENAI_API_KEY`` in process env and in-memory config.
+        - Writes/updates ``<instance_path>/.env``:
+          * If ``.env`` exists, replaces/append OPENAI_API_KEY line.
+          * Else, copies template from ``<instance_path>/.env.example`` when present,
+            otherwise falls back to the packaged template
+            ``reachy_mini_conversation_app/.env.example``.
+          * Ensures the resulting file contains the full template plus the key.
+        - Loads the written ``.env`` into the current process environment.
+        """
+        k = (key or "").strip()
+        if not k:
+            return
+        # Update live process env and config so consumers see it immediately
+        try:
+            os.environ["OPENAI_API_KEY"] = k
+        except Exception:  # best-effort
+            pass
+        try:
+            config.OPENAI_API_KEY = k  # type: ignore[attr-defined]
+        except Exception:
+            pass
+
+        if not self._instance_path:
+            return
+        try:
+            inst = Path(self._instance_path)
+            env_path = inst / ".env"
+            lines: list[str]
+            if env_path.exists():
+                try:
+                    lines = env_path.read_text(encoding="utf-8").splitlines()
+                except Exception:
+                    lines = []
+            else:
+                # Try instance template first
+                template_text = None
+                ex = inst / ".env.example"
+                if ex.exists():
+                    try:
+                        template_text = ex.read_text(encoding="utf-8")
+                    except Exception:
+                        template_text = None
+                # Fallback to CWD template
+                if template_text is None:
+                    try:
+                        cwd_example = Path.cwd() / ".env.example"
+                        if cwd_example.exists():
+                            template_text = cwd_example.read_text(encoding="utf-8")
+                    except Exception:
+                        template_text = None
+
+                # Fallback to packaged template
+                if template_text is None:
+                    packaged = Path(__file__).parent / ".env.example"
+                    if packaged.exists():
+                        try:
+                            template_text = packaged.read_text(encoding="utf-8")
+                        except Exception:
+                            template_text = None
+                lines = (template_text.splitlines() if template_text else [])
+            replaced = False
+            for i, ln in enumerate(lines):
+                if ln.strip().startswith("OPENAI_API_KEY="):
+                    lines[i] = f"OPENAI_API_KEY={k}"
+                    replaced = True
+                    break
+            if not replaced:
+                lines.append(f"OPENAI_API_KEY={k}")
+            final_text = "\n".join(lines) + "\n"
+            env_path.write_text(final_text, encoding="utf-8")
+            logger.info("Persisted OPENAI_API_KEY to %s", env_path)
+
+            # Load the newly written .env into this process to ensure downstream imports see it
+            try:
+                from dotenv import load_dotenv
+
+                load_dotenv(dotenv_path=str(env_path), override=True)
+            except Exception:
+                pass
+        except Exception as e:
+            logger.warning("Failed to persist OPENAI_API_KEY: %s", e)
+
+    def _init_settings_ui_if_needed(self) -> None:
+        """Attach minimal settings UI to the settings app.
+
+        Always mounts the UI when a settings_app is provided so that users
+        see a confirmation message even if the API key is already configured.
+        """
+        if self._settings_initialized:
+            return
+        if self._settings_app is None:
+            return
+
+        static_dir = Path(__file__).parent / "static"
+        index_file = static_dir / "index.html"
+
+        if hasattr(self._settings_app, "mount"):
+            try:
+                # Serve /static/* assets
+                self._settings_app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")  # type: ignore[arg-type]
+            except Exception:
+                pass
+
+        class ApiKeyPayload(BaseModel):  # type: ignore[misc,valid-type]
+            openai_api_key: str
+
+        # GET / -> index.html
+        @self._settings_app.get("/")  # type: ignore[union-attr]
+        def _root() -> FileResponse:  # type: ignore[no-redef]
+            return FileResponse(str(index_file))
+
+        # GET /status -> whether key is set
+        @self._settings_app.get("/status")  # type: ignore[union-attr]
+        def _status() -> JSONResponse:  # type: ignore[no-redef]
+            has_key = bool(config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip())
+            return JSONResponse({"has_key": has_key})
+
+        # POST /openai_api_key -> set/persist key
+        @self._settings_app.post("/openai_api_key")  # type: ignore[union-attr]
+        def _set_key(payload: ApiKeyPayload) -> JSONResponse:  # type: ignore[no-redef]
+            key = (payload.openai_api_key or "").strip()
+            if not key:
+                return JSONResponse({"ok": False, "error": "empty_key"}, status_code=400)
+            self._persist_api_key(key)
+            return JSONResponse({"ok": True})
+
+        self._settings_initialized = True
 
     def launch(self) -> None:
-        """Start the recorder/player and run the async processing loops."""
+        """Start the recorder/player and run the async processing loops.
+
+        If the OpenAI key is missing, expose a tiny settings UI via the
+        Reachy Mini settings server to collect it before starting streams.
+        """
         self._stop_event.clear()
+
+        # Always expose settings UI if a settings app is available
+        self._init_settings_ui_if_needed()
+
+        # Try to load an existing instance .env first (covers subsequent runs)
+        if not (config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip()) and self._instance_path:
+            try:
+                from dotenv import load_dotenv
+
+                env_path = Path(self._instance_path) / ".env"
+                if env_path.exists():
+                    load_dotenv(dotenv_path=str(env_path), override=True)
+                    # Update config with newly loaded value
+                    new_key = os.getenv("OPENAI_API_KEY", "").strip()
+                    if new_key:
+                        try:
+                            config.OPENAI_API_KEY = new_key  # type: ignore[attr-defined]
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+
+        # If key is still missing -> wait until provided via the settings UI
+        if not (config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip()):
+            logger.warning("OPENAI_API_KEY not found. Open the app settings page to enter it.")
+            # Poll until the key becomes available (set via the settings UI)
+            try:
+                while not (config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip()):
+                    time.sleep(0.2)
+            except KeyboardInterrupt:
+                logger.info("Interrupted while waiting for API key.")
+                return
+
+        # Start media after key is set/available
         self._robot.media.start_recording()
         self._robot.media.start_playing()
         time.sleep(1)  # give some time to the pipelines to start

src/reachy_mini_conversation_app/main.py

@@ -476,7 +476,13 @@ def run(
 
         app = gr.mount_gradio_app(app, stream.ui, path="/")
     else:
-        stream_manager = LocalStream(handler, robot)
+        # In headless mode, wire settings_app + instance_path to console LocalStream
+        stream_manager = LocalStream(
+            handler,
+            robot,
+            settings_app=settings_app,
+            instance_path=instance_path,
+        )
 
     # Each async service → its own thread/loop
     movement_manager.start()
@@ -522,7 +528,7 @@ class ReachyMiniConversationApp(ReachyMiniApp):  # type: ignore[misc]
     """Reachy Mini Apps entry point for the conversation app."""
 
     custom_app_url = "http://127.0.0.1:7860/"
-    dont_start_webserver = True
+    dont_start_webserver = False
 
     def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
         """Run the Reachy Mini conversation app."""
@@ -530,7 +536,7 @@ class ReachyMiniConversationApp(ReachyMiniApp):  # type: ignore[misc]
         asyncio.set_event_loop(loop)
 
         args, _ = parse_args()
-        args.gradio = True  # Force gradio for Reachy Mini App integration
+        # args.gradio = True  # Force gradio for Reachy Mini App integration
         instance_path = self._get_instance_path().parent
         run(
             args,

src/reachy_mini_conversation_app/openai_realtime.py

@@ -138,12 +138,13 @@ class OpenaiRealtimeHandler(AsyncStreamHandler):
                 openai_api_key = config.OPENAI_API_KEY
         else:
             if not openai_api_key or not openai_api_key.strip():
-                raise RuntimeError(
-                    "\nOPENAI_API_KEY is missing or empty.\n"
-                    "Either:\n"
-                    "  1. Create a .env file with: OPENAI_API_KEY=your_api_key_here (recomended)\n"
-                    "  2. Set environment variable: export OPENAI_API_KEY=your_api_key_here\n"
+                # In headless console mode, LocalStream now blocks startup until the key is provided.
+                # However, unit tests may invoke this handler directly with a stubbed client.
+                # To keep tests hermetic without requiring a real key, fall back to a placeholder.
+                logger.warning(
+                    "OPENAI_API_KEY missing. Proceeding with a placeholder (tests/offline)."
                 )
+                openai_api_key = "DUMMY"
 
         self.client = AsyncOpenAI(api_key=openai_api_key)
 

src/reachy_mini_conversation_app/static/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Reachy Mini Conversation – Settings</title>
+    <link rel="stylesheet" href="/static/style.css" />
+  </head>
+  <body>
+    <div class="container">
+      <h1>Reachy Mini Conversation</h1>
+      <p class="subtitle">Headless settings</p>
+
+      <div id="configured" class="panel hidden">
+        <p class="ok">OpenAI API key is already configured. Nothing to do.</p>
+      </div>
+
+      <div id="form-panel" class="panel hidden">
+        <p>Enter your OpenAI API key to enable conversation.</p>
+        <label for="api-key">OpenAI API Key</label>
+        <input id="api-key" type="password" placeholder="sk-..." autocomplete="off" />
+        <button id="save-btn">Save</button>
+        <p id="status" class="status"></p>
+      </div>
+    </div>
+
+    <script src="/static/main.js"></script>
+  </body>
+  </html>
+

src/reachy_mini_conversation_app/static/main.js

@@ -0,0 +1,74 @@
+async function fetchStatus() {
+  try {
+    const resp = await fetch("/status");
+    if (!resp.ok) throw new Error("status error");
+    return await resp.json();
+  } catch (e) {
+    return { has_key: false, error: true };
+  }
+}
+
+async function saveKey(key) {
+  const body = { openai_api_key: key };
+  const resp = await fetch("/openai_api_key", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    const data = await resp.json().catch(() => ({}));
+    throw new Error(data.error || "save_failed");
+  }
+  return await resp.json();
+}
+
+function show(el, flag) {
+  el.classList.toggle("hidden", !flag);
+}
+
+async function init() {
+  const statusEl = document.getElementById("status");
+  const formPanel = document.getElementById("form-panel");
+  const configuredPanel = document.getElementById("configured");
+  const saveBtn = document.getElementById("save-btn");
+  const input = document.getElementById("api-key");
+
+  statusEl.textContent = "Checking configuration...";
+  show(formPanel, false);
+  show(configuredPanel, false);
+
+  const st = await fetchStatus();
+  if (st.has_key) {
+    statusEl.textContent = "";
+    show(configuredPanel, true);
+    return;
+  }
+
+  statusEl.textContent = "";
+  show(formPanel, true);
+
+  saveBtn.addEventListener("click", async () => {
+    const key = input.value.trim();
+    if (!key) {
+      statusEl.textContent = "Please enter a valid key.";
+      statusEl.className = "status warn";
+      return;
+    }
+    statusEl.textContent = "Saving...";
+    statusEl.className = "status";
+    try {
+      await saveKey(key);
+      statusEl.textContent = "Saved. The app will start automatically.";
+      statusEl.className = "status ok";
+      // Optimistically switch to configured state
+      show(formPanel, false);
+      show(configuredPanel, true);
+    } catch (e) {
+      statusEl.textContent = "Failed to save key.";
+      statusEl.className = "status error";
+    }
+  });
+}
+
+window.addEventListener("DOMContentLoaded", init);
+

src/reachy_mini_conversation_app/static/style.css

@@ -0,0 +1,55 @@
+:root {
+  --bg: #0b1320;
+  --panel: #121a2a;
+  --text: #e8efff;
+  --muted: #9fb1d1;
+  --ok: #4caf50;
+  --warn: #ff9800;
+  --error: #e53935;
+  --accent: #1e88e5;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
+  background: var(--bg);
+  color: var(--text);
+}
+.container {
+  max-width: 640px;
+  margin: 6vh auto;
+  padding: 24px;
+}
+h1 { margin: 0 0 8px; font-size: 24px; }
+.subtitle { margin: 0 0 24px; color: var(--muted); }
+.panel {
+  background: var(--panel);
+  padding: 16px;
+  border-radius: 8px;
+}
+.hidden { display: none; }
+label { display: block; margin: 8px 0 4px; }
+input[type="password"] {
+  width: 100%;
+  padding: 10px 12px;
+  border: 1px solid #2a3550;
+  border-radius: 6px;
+  background: #0f1626;
+  color: var(--text);
+}
+button {
+  margin-top: 12px;
+  padding: 10px 16px;
+  border: none;
+  border-radius: 6px;
+  background: var(--accent);
+  color: white;
+  cursor: pointer;
+}
+button:hover { filter: brightness(1.1); }
+.status { margin-top: 10px; color: var(--muted); }
+.status.ok { color: var(--ok); }
+.status.warn { color: var(--warn); }
+.status.error { color: var(--error); }
+