Allow unlocking personality editing from Settings (v0.3.4)

The app ships LOCKED to the receptionist profile (Personality Studio Apply returns profile_locked) so a live lobby robot can't have its flow broken at runtime. But an owner had no way to experiment without editing config.py, and the studio UI invited edits it then blocked — which confused testers.

Now the lock is env-driven with a safe default: config.profile_locked() = locked unless RECEPTION_PROFILE_UNLOCK=true. Exposed as a restart-required enum dropdown under Settings -> Advanced (default 'locked') with an info tooltip. Unlock and the Personality Studio's Save / Apply / Use-on-startup all work. Gates updated in config, console (persist + startup re-apply), and the apply/list endpoints. Default stays locked, so lobby deployments are unaffected.

Docs: .env.example + README document RECEPTION_PROFILE_UNLOCK and the Gmail email backend (EMAIL_BACKEND/GMAIL_*).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -11,9 +11,19 @@ HF_HOME=./cache
 # Hugging Face token for accessing datasets/models
 HF_TOKEN=
 
-# Profile selection (ignored when LOCKED_PROFILE is set in config.py)
+# Profile selection (ignored while the profile is locked — see below)
 # REACHY_MINI_CUSTOM_PROFILE="example"
 
+# ---- Personality lock ----
+# The app ships LOCKED to the receptionist profile so a live lobby robot
+# can't have its reception flow swapped or broken at runtime (the dashboard's
+# Personality Studio shows the editor but Apply is disabled). On a unit you
+# own and want to experiment with, set this to true to UNLOCK editing: then
+# Advanced -> Personality studio's Save / Apply / "Use on startup" all work.
+# Restart required. Leave locked for production. Also togglable from the
+# dashboard: Settings -> Advanced.
+# RECEPTION_PROFILE_UNLOCK=false
+
 # Skip loading .env if you prefer environment-only configuration.
 # REACHY_MINI_SKIP_DOTENV=1
 
@@ -26,11 +36,26 @@ HF_TOKEN=
 # This is convenient for downloaded tools used with built-in/default profiles.
 # AUTOLOAD_EXTERNAL_TOOLS=1
 
-# Resend transactional email API for the send_email tool.
+# ---- Email delivery (host notifications) ----
+# The send_email tool delivers via EITHER Gmail SMTP or Resend, chosen by
+# EMAIL_BACKEND. Leave EMAIL_BACKEND unset to auto-detect: Gmail if its creds
+# are set, else Resend, else outbox-only (recorded in the dashboard's Mailbox
+# Out panel, but nothing leaves the robot). Also configurable from the
+# dashboard: Settings.
+# EMAIL_BACKEND=gmail          # or "resend"
+
+# -- Gmail SMTP (delivers to ANY recipient — no domain to verify) --
+# Needs a Google App Password (16 chars) with 2-Step Verification enabled:
+# https://myaccount.google.com/apppasswords  (spaces in the password are OK)
+# GMAIL_ADDRESS=you@gmail.com
+# GMAIL_APP_PASSWORD=abcd efgh ijkl mnop
+# GMAIL_FROM_NAME=Reachy Reception
+
+# -- Resend (transactional HTTP API) --
 # Get a free API key at https://resend.com/api-keys (3000 emails/month free).
-# Without RESEND_API_KEY, send_email writes to the in-memory outbox only
-# (visible in the dashboard's Mailbox Out panel, but nothing actually leaves
-# the robot).
+# Without RESEND_API_KEY (and no Gmail creds), send_email writes to the
+# in-memory outbox only (visible in the dashboard's Mailbox Out panel, but
+# nothing actually leaves the robot).
 #
 # RESEND_FROM defaults to "onboarding@resend.dev" — Resend's sandbox sender
 # that ONLY delivers to the email address registered on your Resend account.

README.md

@@ -78,7 +78,7 @@ The welcome banner on first launch tells you which keys are missing. Click each
 | Setting | Why | Where to get it |
 |---|---|---|
 | `GEMINI_API_KEY` | Voice (default backend) | [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) — free tier works |
-| `RESEND_API_KEY` | Send emails to hosts | [resend.com](https://resend.com) — free 3000 emails/month |
+| Email delivery | Notify hosts a visitor arrived | **Gmail** — a [Google App Password](https://myaccount.google.com/apppasswords) (delivers to anyone, no domain setup) — or **Resend** ([resend.com](https://resend.com), free 3000/mo). Without either, emails are recorded in the dashboard's Mailbox Out only |
 | `RECEPTION_ICS_URL` | Read today's appointments | Google Calendar → Settings → **Secret address in iCal format** |
 
 ### Optional
@@ -88,7 +88,10 @@ The welcome banner on first launch tells you which keys are missing. Click each
 | `VOICE_BACKEND` | Switch between `gemini` (default) and `openai` |
 | `GEMINI_LIVE_VOICE` | Pick a voice — Puck, Charon, Kore, Aoede, etc. |
 | `OPENAI_API_KEY` | Required only if `VOICE_BACKEND=openai` |
-| `RESEND_FROM` | Sender address — defaults to Resend's sandbox sender (delivers only to your Resend account); set to `reception@yourdomain.com` after verifying your domain at Resend |
+| `EMAIL_BACKEND` | `gmail` or `resend` — unset auto-detects (prefers Gmail if its creds are set) |
+| `GMAIL_ADDRESS` / `GMAIL_APP_PASSWORD` | Send via your Gmail/Workspace account (16-char [App Password](https://myaccount.google.com/apppasswords), 2-Step Verification on); `GMAIL_FROM_NAME` sets the display name |
+| `RESEND_FROM` | Resend sender address — defaults to Resend's sandbox sender (delivers only to your Resend account); set to `reception@yourdomain.com` after verifying your domain at Resend |
+| `RECEPTION_PROFILE_UNLOCK` | `true` unlocks personality editing (Advanced → Personality studio). **Default locked** — keep it locked on a production lobby robot so the reception flow can't be changed at runtime |
 | `FACE_TTL_DAYS` | How long a registered face is remembered (default 90 days) |
 | `VISITOR_LOG_RETENTION_DAYS` | How long visit records are kept (default 365 days) |
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reachy_mini_receptionist"
-version = "0.3.3"
+version = "0.3.4"
 description = "Reachy Mini AI receptionist app with realtime voice, guest recognition, and dashboard tools."
 readme = "README.md"
 requires-python = ">=3.10"

src/reachy_mini_receptionist/config.py

@@ -34,6 +34,19 @@ def _env_flag(name: str, default: bool = False) -> bool:
     return default
 
 
+def profile_locked() -> bool:
+    """Whether profile switching / prompt-applying is currently locked.
+
+    The app ships LOCKED to ``LOCKED_PROFILE`` for production safety so a
+    live receptionist can't have its reception flow swapped at runtime. A
+    user who owns the installed app can UNLOCK it from the dashboard Settings
+    by setting ``RECEPTION_PROFILE_UNLOCK=true`` (restart required). Once
+    unlocked, the Personality Studio's Save / Apply / "Use on startup" all
+    work and they can craft their own personalities.
+    """
+    return LOCKED_PROFILE is not None and not _env_flag("RECEPTION_PROFILE_UNLOCK", default=False)
+
+
 def _collect_profile_names(profiles_root: Path) -> set[str]:
     """Return profile folder names from a profiles root directory."""
     if not profiles_root.exists() or not profiles_root.is_dir():
@@ -122,7 +135,13 @@ class Config:
     _tools_directory_env = os.getenv("REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY")
     TOOLS_DIRECTORY = Path(_tools_directory_env) if _tools_directory_env else None
     AUTOLOAD_EXTERNAL_TOOLS = _env_flag("AUTOLOAD_EXTERNAL_TOOLS", default=False)
-    REACHY_MINI_CUSTOM_PROFILE = LOCKED_PROFILE or os.getenv("REACHY_MINI_CUSTOM_PROFILE")
+    # Startup profile: forced to the locked profile while locked. Once the
+    # owner unlocks (RECEPTION_PROFILE_UNLOCK=true) honour their saved choice,
+    # still defaulting to the receptionist profile when they haven't picked one.
+    if profile_locked():
+        REACHY_MINI_CUSTOM_PROFILE = LOCKED_PROFILE or os.getenv("REACHY_MINI_CUSTOM_PROFILE")
+    else:
+        REACHY_MINI_CUSTOM_PROFILE = os.getenv("REACHY_MINI_CUSTOM_PROFILE") or LOCKED_PROFILE
 
     logger.debug(f"Custom Profile: {REACHY_MINI_CUSTOM_PROFILE}")
 
@@ -199,7 +218,7 @@ def set_custom_profile(profile: str | None) -> None:
     This ensures modules that read `config` and code that inspects the
     environment see a consistent value.
     """
-    if LOCKED_PROFILE is not None:
+    if profile_locked():
         return
     try:
         config.REACHY_MINI_CUSTOM_PROFILE = profile

src/reachy_mini_receptionist/console.py

@@ -22,7 +22,7 @@ from scipy.signal import resample
 
 from reachy_mini import ReachyMini
 from reachy_mini.media.media_manager import MediaBackend
-from reachy_mini_receptionist.config import LOCKED_PROFILE, config
+from reachy_mini_receptionist.config import config, profile_locked
 from reachy_mini_receptionist.openai_realtime import OpenaiRealtimeHandler
 from reachy_mini_receptionist.headless_personality_ui import mount_personality_routes
 
@@ -162,7 +162,7 @@ class LocalStream:
 
     def _persist_personality(self, profile: Optional[str]) -> None:
         """Persist the startup personality to the instance .env and config."""
-        if LOCKED_PROFILE is not None:
+        if profile_locked():
             return
         selection = (profile or "").strip() or None
         try:
@@ -340,7 +340,7 @@ class LocalStream:
                             config.OPENAI_API_KEY = new_key
                         except Exception:
                             pass
-                    if LOCKED_PROFILE is None:
+                    if not profile_locked():
                         new_profile = os.getenv("REACHY_MINI_CUSTOM_PROFILE")
                         if new_profile is not None:
                             try:

src/reachy_mini_receptionist/headless_personality_ui.py

@@ -13,7 +13,7 @@ from typing import Any, Callable, Optional
 
 from fastapi import FastAPI
 
-from .config import LOCKED_PROFILE, config
+from .config import LOCKED_PROFILE, config, profile_locked
 from .openai_realtime import OpenaiRealtimeHandler
 from .headless_personality import (
     DEFAULT_OPTION,
@@ -76,12 +76,13 @@ def mount_personality_routes(
     @app.get("/personalities")
     def _list() -> dict:  # type: ignore
         choices = [DEFAULT_OPTION, *list_personalities()]
+        _locked = profile_locked()
         return {
             "choices": choices,
             "current": _current_choice(),
             "startup": _startup_choice(),
-            "locked": LOCKED_PROFILE is not None,
-            "locked_to": LOCKED_PROFILE,
+            "locked": _locked,
+            "locked_to": LOCKED_PROFILE if _locked else None,
         }
 
     @app.get("/personalities/load")
@@ -212,9 +213,14 @@ def mount_personality_routes(
         persist: Optional[bool] = None,
         request: Optional[Request] = None,
     ) -> dict:  # type: ignore
-        if LOCKED_PROFILE is not None:
+        if profile_locked():
             return JSONResponse(
-                {"ok": False, "error": "profile_locked", "locked_to": LOCKED_PROFILE},
+                {
+                    "ok": False,
+                    "error": "profile_locked",
+                    "locked_to": LOCKED_PROFILE,
+                    "hint": "Set RECEPTION_PROFILE_UNLOCK=true in Settings (restart) to edit personalities.",
+                },
                 status_code=403,
             )  # type: ignore
         loop = get_loop()

src/reachy_mini_receptionist/main.py

@@ -905,6 +905,7 @@ def _mount_dashboard_api(
         "GEMINI_LIVE_VOICE":            {"secret": False, "restart": True},
         "OPENAI_API_KEY":              {"secret": True,  "restart": True},
         "GEMINI_API_KEY":              {"secret": True,  "restart": True},
+        "RECEPTION_PROFILE_UNLOCK":    {"secret": False, "restart": True},
         "STT_DISABLE_BIAS":            {"secret": False, "restart": True},
         "STT_LANGUAGE":                {"secret": False, "restart": True},
         "EMAIL_BACKEND":               {"secret": False, "restart": False},
@@ -937,6 +938,7 @@ def _mount_dashboard_api(
             "Puck", "Charon", "Kore", "Fenrir", "Aoede", "Leda", "Orus", "Zephyr",
         },
         "STT_DISABLE_BIAS": {"true", "false"},
+        "RECEPTION_PROFILE_UNLOCK": {"true", "false"},
         "STT_LANGUAGE": {
             "en", "en-IN", "hi", "es", "fr", "de", "ja", "zh",
         },

src/reachy_mini_receptionist/static/dashboard.html

@@ -1563,6 +1563,11 @@
           { value: 'false', label: 'false — use STT bias prompt' },
           { value: 'true',  label: 'true — disable bias prompt' },
         ],
+        'RECEPTION_PROFILE_UNLOCK': [
+          { value: '',      label: '(default — locked)' },
+          { value: 'false', label: 'false — locked (receptionist protected)' },
+          { value: 'true',  label: 'true — unlock personality editing' },
+        ],
         'STT_LANGUAGE': [
           { value: '',      label: '(default — auto-detect, recommended)' },
           { value: 'en',    label: 'en — English (forces English phonemes)' },
@@ -1612,11 +1617,20 @@
       // ── Advanced settings (collapsed by default) ─────────────────
       const _ADVANCED_KEYS = new Set([
         'FACE_TTL_DAYS', 'VISITOR_LOG_RETENTION_DAYS', 'FACE_LBPH_THRESHOLD',
+        'RECEPTION_PROFILE_UNLOCK',
       ]);
 
       // ── Info tooltips per key ────────────────────────────────────
       // Shown via an ⓘ hover button next to the key name. HTML allowed.
       const _INFO_TIPS = {
+        'RECEPTION_PROFILE_UNLOCK':
+          '<strong>Unlock the robot\'s personality for editing.</strong><br>'
+          + 'The app ships <strong>locked</strong> to the receptionist profile so the '
+          + 'reception flow can\'t be broken at runtime.<br><br>'
+          + 'Set to <code>true</code> to unlock the <strong>Advanced → Personality studio</strong> '
+          + '(edit the prompt, tools, and voice; Save / Apply / Use-on-startup all work).<br><br>'
+          + '⚠️ Restart required. Leave <code>locked</code> for a production lobby robot; '
+          + 'unlock only on a unit you\'re free to experiment with.',
         'FACE_TTL_DAYS':
           '<strong>How long a registered face is kept in the guest DB.</strong><br>'
           + 'After this many days of no visit, the face is auto-deleted on next startup, '