Redesign Rhythma as a session-led listening experience

Shift the app surface from a modulation demo toward the approved wellness-companion experience. This integrates session-led copy into the request flow, gives the UI named session outputs, and rewrites the examples and README so the product voice matches the intended audience.

Constraint: Task 3 must stay verifiable without a local gradio install
Constraint: Backend failures must not leave reassuring success copy on screen
Rejected: Pure copy polish without wiring the session fields into the output path | did not satisfy the redesign behavior
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep the session-led outputs and failure-safe copy paths aligned if later tasks expand the UI further
Tested: python -m py_compile app.py tests/test_rhythma_ui_copy.py
Tested: PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -c "import pytest; raise SystemExit(pytest.main(['tests/test_rhythma_ui_copy.py','-q','-p','no:cacheprovider']))"
Not-tested: Full live Gradio rendering in this environment because gradio is not installed locally

README.md

@@ -1,8 +1,8 @@
 ---
-title: 'Rhythma: The Living Modulation Engine'
-emoji: ⚡
+title: 'Rhythma'
+emoji: 🎧
 colorFrom: pink
-colorTo: purple
+colorTo: orange
 sdk: gradio
 sdk_version: 6.10.0
 app_file: app.py
@@ -10,11 +10,16 @@ pinned: true
 license: apache-2.0
 thumbnail: >-
   https://cdn-uploads.huggingface.co/production/uploads/64628a722a83863b97beed5e/y4bWysnsPMV2asL_LFB9X.jpeg
-short_description: 🔊Reverse Active Denial System
+short_description: An artful wellness companion for reflective listening sessions
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
+## Rhythma
+
+Rhythma is an artful wellness companion that translates a felt state into a named listening session.
+The app pairs session profiling, layered audio, and reflective copy so the experience feels closer to a guided ritual than a parameter dashboard.
+
 ## Local Development
 
 Install the dependencies, then run the Gradio app:
@@ -24,12 +29,23 @@ pip install -r requirements.txt
 python app.py
 ```
 
-Set `GROQ_API_KEY` to enable Groq-backed text classification and audio transcription.
+Set `GROQ_API_KEY` to enable Groq-backed text classification and voice-note transcription.
+
+If `gradio` is not installed locally, you can still run the focused test suite for `app.py` through the stubbed UI tests in `tests/test_rhythma_ui_copy.py`.
+
+## Session-Led Experience
+
+- The main prompt asks what you are carrying or what intention you want to hold.
+- The output surface now leads with a named session and emotional tone before the listening guidance appears.
+- `Tone Center` and `Session Pattern` can stay on automatic or be gently overridden from the session controls.
+- The output area is framed around `Your Listening Path`, `Session Reflection`, audio playback, and waveform views.
+- Example prompts now reflect a calmer, artful wellness voice rather than a technical modulation demo.
 
 ## Project Structure
 
-- `app.py`: Gradio interface and request pipeline
+- `app.py`: session-led Gradio interface and request pipeline
 - `rhythma_engine.py`: waveform generation, audio export, and visualization
-- `rhythma_analysis.py`: text/audio analysis, optional Groq integration, and result shaping
+- `rhythma_analysis.py`: text/audio analysis, optional Groq integration, and session-profile shaping
 - `rhythma.py`: compatibility facade for the public classes
 - `tests/test_rhythma_regression.py`: regression tests for the core behavior
+- `tests/test_rhythma_ui_copy.py`: focused UI-copy tests that avoid a real Gradio import

app.py

@@ -1,6 +1,9 @@
 import os
 import logging
-import gradio as gr
+try:
+    import gradio as gr
+except ModuleNotFoundError:  # pragma: no cover - local test environments may omit gradio
+    gr = None
 import matplotlib
 matplotlib.use('Agg')
 import tempfile
@@ -101,6 +104,26 @@ def normalize_rhythm_override(value):
     return value
 
 
+def build_session_copy(analysis_result):
+    analysis_result = analysis_result if isinstance(analysis_result, dict) else {}
+    profile = analysis_result.get("session_profile") or {}
+    emotional_state = analysis_result.get("emotional_state", "neutral")
+
+    session_name = profile.get("title") or f"{emotional_state.title()} Session"
+    emotional_tone = profile.get("emotional_tone") or "Measured and receptive"
+    guidance = profile.get("guidance") or "Stay with the pulse until your breath settles into its own pace."
+    reflection = profile.get("reflection") or "This session offers a gentle reset without pushing for intensity."
+
+    return {
+        "session_name": session_name,
+        "emotional_tone": emotional_tone,
+        "listening_path": f"{emotional_tone}. {guidance}",
+        "session_reflection": reflection,
+        "tone_center": profile.get("tone_center"),
+        "session_pattern": profile.get("pattern"),
+    }
+
+
 def rhythma_experience(
     input_text, audio_input,
     override_freq=None,
@@ -111,6 +134,7 @@ def rhythma_experience(
     input_text = input_text.strip() if input_text else ""
     freq_override_value = coerce_frequency(override_freq)
     analysis = analyze_input(input_text, audio_input)
+    session_copy = build_session_copy(analysis)
 
     analysis_text, audio_file, fig, waveform_image, symbolic = generate_modulated_experience(
         analysis,
@@ -122,76 +146,100 @@ def rhythma_experience(
 
     transcription = analysis.get("transcription", "") if isinstance(analysis, dict) else ""
     plot_output = fig if fig else None
-    return analysis_text, audio_file, plot_output, waveform_image, symbolic, transcription
+    listening_path = session_copy["listening_path"]
+    session_reflection = session_copy["session_reflection"]
+
+    if audio_file is None and isinstance(analysis_text, str) and analysis_text:
+        fallback_message = analysis_text or symbolic or "Session generation is unavailable right now."
+        listening_path = fallback_message
+        session_reflection = fallback_message
+
+    return (
+        f"### {session_copy['session_name']}",
+        session_copy["emotional_tone"],
+        listening_path,
+        audio_file,
+        plot_output,
+        waveform_image,
+        session_reflection,
+        transcription,
+    )
 
 # --- Create the Gradio Interface ---
 def create_interface():
-    with gr.Blocks(theme=gr.themes.Soft(), title="Rhythma: The Living Modulation Engine") as demo:
-        gr.Markdown("# Rhythma: The Living Modulation Engine")
-        gr.Markdown("### Dynamic rhythm-based sound modulation for wellbeing from Vers3Dynamics")
+    if gr is None:
+        raise ModuleNotFoundError("gradio is required to create the Rhythma interface.")
+
+    with gr.Blocks(theme=gr.themes.Soft(primary_hue="rose", secondary_hue="stone"), title="Rhythma") as demo:
+        gr.Markdown("# Rhythma")
+        gr.Markdown("### An artful wellness companion for reflective listening.")
 
         if not use_groq:
-            gr.Warning("Running with limited functionality: GROQ_API_KEY not found. "
-                       "Advanced AI analysis and audio transcription are disabled.")
+            gr.Warning(
+                "Groq analysis is unavailable. Text-led sessions still work, but live voice transcription is off."
+            )
 
         with gr.Row():
             with gr.Column(scale=1):
-                gr.Markdown("**1. Describe Your State or Intention**")
+                gr.Markdown("**1. Share what you're carrying**")
                 input_text = gr.Textbox(
-                    label="How are you feeling, or what is your intention?",
-                    placeholder="e.g., 'feeling stressed about work', 'want to relax', 'need focus'...",
-                    lines=3
+                    label="How are you feeling, or what intention would you like to hold?",
+                    placeholder="e.g., 'I need something steady before a conversation' or 'I want room to soften after a long day.'",
+                    lines=4
                 )
 
-                gr.Markdown("**Optional: Use Your Voice (Requires Groq API Key)**")
+                gr.Markdown("**Optional: add a voice note (requires Groq)**")
                 audio_input = gr.Audio(
-                    sources=["microphone"], # Prioritize microphone
-                    type="filepath", # RhythmaSymphAICore expects a filepath
-                    label="Record or Upload Audio" if use_groq else "Audio Input (Disabled)",
-                    interactive=use_groq # Disable if Groq not available
+                    sources=["microphone"],
+                    type="filepath",
+                    label="Record or Upload a Voice Note" if use_groq else "Voice Note (Disabled)",
+                    interactive=use_groq
                 )
 
-                with gr.Accordion("Advanced Settings (Optional Overrides)", open=False):
+                with gr.Accordion("Session shaping controls", open=False):
                     override_freq = gr.Slider(
                         minimum=0, maximum=1000, value=0, step=1,
-                        label="Override Frequency (Hz)",
-                        info="Leave at 0 to use automatic frequency based on analysis."
+                        label="Tone Center (Hz)",
+                        info="Leave at 0 to let Rhythma choose a tone center from your session profile."
                     )
                     override_modulation = gr.Dropdown(
                         choices=["sine", "pulse", "chirp"],
                         value="sine",
-                        label="Override Modulation Type"
+                        label="Texture Shape"
                     )
                     available_patterns = list(RhythmaModulationEngine().rhythm_configs.keys())
                     override_rhythm = gr.Dropdown(
                         choices=["Automatic"] + available_patterns,
                         value="Automatic",
-                        label="Override Rhythm Pattern",
-                        info="Leave on Automatic to use the pattern inferred from the analysis."
+                        label="Session Pattern",
+                        info="Leave on Automatic to follow the pattern inferred from your session profile."
                     )
                     duration = gr.Slider(
                         minimum=3, maximum=60, value=10, step=1,
-                        label="Duration (seconds)"
+                        label="Session Length (seconds)"
                     )
 
-                generate_button = gr.Button("Generate Rhythma Experience", variant="primary", scale=2)
+                generate_button = gr.Button("Generate Session", variant="primary", scale=2)
 
             with gr.Column(scale=2):
-                gr.Markdown("**2. Experience Your Rhythma Soundscape**")
-                analysis_output = gr.Textbox(label="Rhythma Analysis & Guidance", lines=8, interactive=False)
+                gr.Markdown("**2. Receive your listening session**")
+                gr.Markdown(
+                    "_Rhythma shapes a named listening path, then renders the audio, reflection, and waveform around it._"
+                )
+                session_name_output = gr.Markdown("### Session")
+                emotional_tone_output = gr.Markdown("Measured and receptive")
+                listening_path_output = gr.Textbox(label="Your Listening Path", lines=6, interactive=False)
                 with gr.Row():
-                    audio_output = gr.Audio(label="Modulated Audio", type="filepath", interactive=False)
-                    waveform_simple = gr.Image(label="Base Waveform", interactive=False, height=100, width=200)
-                waveform_plot = gr.Plot(label="Detailed Waveform & Spectrogram")
-                symbolic_output = gr.Textbox(label="Symbolic Interpretation", interactive=False)
-                # Conditionally visible transcription output
+                    audio_output = gr.Audio(label="Session Audio", type="filepath", interactive=False)
+                    waveform_simple = gr.Image(label="Tone Center", interactive=False, height=100, width=200)
+                waveform_plot = gr.Plot(label="Session Pattern")
+                symbolic_output = gr.Textbox(label="Session Reflection", interactive=False)
                 transcription_output = gr.Textbox(
-                    label="Transcribed Audio (If Provided)",
+                    label="Transcribed Voice Note",
                     interactive=False,
-                    visible=use_groq # Only show if Groq is potentially usable
+                    visible=use_groq
                 )
 
-        # Define button action
         generate_button.click(
             fn=rhythma_experience,
             inputs=[
@@ -200,25 +248,28 @@ def create_interface():
                 duration
             ],
             outputs=[
-                analysis_output, audio_output,
-                waveform_plot, waveform_simple, symbolic_output,
+                session_name_output, emotional_tone_output, listening_path_output,
+                audio_output, waveform_plot, waveform_simple, symbolic_output,
                 transcription_output
             ]
         )
 
-        # Add Examples
         gr.Examples(
             examples=[
-                ["I'm feeling anxious about my upcoming presentation.", None, 0, "sine", "Automatic", 10],
-                ["I feel grounded and peaceful today.", None, 0, "sine", "Automatic", 15],
-                ["I need to focus on deep work without distractions.", None, 0, "sine", "focused", 20],
-                ["I'm overwhelmed and need something steady.", None, 0, "sine", "Automatic", 10],
-                ["I'm excited and want a more energized soundscape.", None, 0, "pulse", "active", 10],
-                ["I want to relax after a long day.", None, 0, "sine", "relaxed", 30],
-                ["I'm feeling low and want something gentle.", None, 0, "sine", "Automatic", 15],
+                ["I need something steady before a difficult conversation.", None, 0, "sine", "Automatic", 12],
+                ["I want to feel grounded and open as the evening slows down.", None, 0, "sine", "Automatic", 18],
+                ["I need a clear horizon for deep work.", None, 0, "sine", "focused", 20],
+                ["Everything feels loud and I want a softer landing.", None, 0, "sine", "Automatic", 14],
+                ["I feel bright and want a livelier pulse without losing calm.", None, 0, "pulse", "active", 10],
+                ["Give me a long unwind after a heavy day.", None, 0, "sine", "relaxed", 30],
+                ["I want a gentle session for a low-energy morning.", None, 0, "sine", "Automatic", 16],
             ],
             inputs=[input_text, audio_input, override_freq, override_modulation, override_rhythm, duration],
-            outputs=[analysis_output, audio_output, waveform_plot, waveform_simple, symbolic_output, transcription_output],
+            outputs=[
+                session_name_output, emotional_tone_output, listening_path_output,
+                audio_output, waveform_plot, waveform_simple, symbolic_output,
+                transcription_output
+            ],
             fn=rhythma_experience,
             cache_examples=False
         )
@@ -226,10 +277,10 @@ def create_interface():
         gr.Markdown("---")
         gr.Markdown("""
         ## About Rhythma
-        Rhythma creates personalized soundscapes using frequency modulation based on your described emotional state or intention.
-        It leverages AI analysis (enhanced with Groq if available) and principles of rhythmic sound design.
-        **Note:** This is an experimental tool. The frequencies and interpretations are based on various theories and are not medical advice.
-        © 2025 Vers3Dynamics 
+        Rhythma is an artful wellness companion that turns a felt state into a reflective listening session.
+        It uses optional AI analysis, session profiling, and rhythmic sound design to shape a tone center, pattern, and guided path for the moment you are in.
+        **Note:** Rhythma is for reflective listening and personal wellbeing rituals. It is not medical advice or a clinical treatment.
+        © 2025 Vers3Dynamics
         """)
 
     return demo
@@ -238,6 +289,8 @@ def create_interface():
 if __name__ == "__main__":
     if symphai_core is None:
         LOGGER.error("Cannot launch Gradio app because RhythmaSymphAICore failed to initialize.")
+    elif gr is None:
+        LOGGER.error("Cannot launch Gradio app because gradio is not installed.")
     else:
         app_demo = create_interface()
         app_demo.launch()

tests/test_rhythma_ui_copy.py

@@ -0,0 +1,129 @@
+import importlib
+import sys
+import types
+from unittest import mock
+
+import pytest
+
+
+def import_app_with_gradio_stub():
+    sys.modules.pop("app", None)
+    sys.modules["gradio"] = types.ModuleType("gradio")
+    return importlib.import_module("app")
+
+
+def import_app_without_gradio():
+    original_import = __import__
+
+    def blocked_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "gradio":
+            raise ModuleNotFoundError("No module named 'gradio'")
+        return original_import(name, globals, locals, fromlist, level)
+
+    sys.modules.pop("app", None)
+    sys.modules.pop("gradio", None)
+    with mock.patch("builtins.__import__", side_effect=blocked_import):
+        return importlib.import_module("app")
+
+
+def test_normalize_rhythm_override_treats_automatic_as_none():
+    app = import_app_with_gradio_stub()
+
+    assert app.normalize_rhythm_override("Automatic") is None
+
+
+def test_build_session_copy_uses_human_labels():
+    app = import_app_with_gradio_stub()
+    analysis = {
+        "emotional_state": "anxious",
+        "session_profile": {
+            "title": "Grounding Tide",
+            "emotional_tone": "Settling and steady",
+            "guidance": "Let your breath fall behind the pulse until the session feels steady.",
+            "reflection": "This session favors stability over intensity.",
+        },
+    }
+
+    card = app.build_session_copy(analysis)
+
+    assert card["session_name"] == "Grounding Tide"
+    assert card["listening_path"].startswith("Settling and steady")
+    assert "stability over intensity" in card["session_reflection"]
+
+
+def test_import_without_gradio_uses_interface_guard():
+    app = import_app_without_gradio()
+
+    assert app.gr is None
+    with pytest.raises(ModuleNotFoundError, match="gradio is required"):
+        app.create_interface()
+
+
+def test_rhythma_experience_returns_session_led_copy(monkeypatch):
+    app = import_app_with_gradio_stub()
+    analysis = {
+        "emotional_state": "anxious",
+        "transcription": "",
+        "session_profile": {
+            "title": "Grounding Tide",
+            "emotional_tone": "Settling and steady",
+            "guidance": "Let your breath fall behind the pulse until the session feels steady.",
+            "reflection": "This session favors stability over intensity.",
+        },
+    }
+
+    monkeypatch.setattr(app, "analyze_input", lambda text, audio: analysis)
+    monkeypatch.setattr(
+        app,
+        "generate_modulated_experience",
+        lambda *args, **kwargs: ("legacy analysis", "session.wav", "plot", "image", "legacy symbolic"),
+    )
+
+    outputs = app.rhythma_experience(
+        "I feel anxious and need to settle down",
+        None,
+        override_freq=0,
+        override_modulation="sine",
+        override_rhythm="Automatic",
+        duration=5,
+    )
+
+    assert outputs[0] == "### Grounding Tide"
+    assert outputs[1] == "Settling and steady"
+    assert outputs[2].startswith("Settling and steady")
+    assert outputs[3] == "session.wav"
+    assert outputs[6] == "This session favors stability over intensity."
+    assert outputs[7] == ""
+
+
+def test_rhythma_experience_degrades_copy_consistently_on_generation_failure(monkeypatch):
+    app = import_app_with_gradio_stub()
+    analysis = {
+        "emotional_state": "anxious",
+        "transcription": "",
+        "session_profile": {
+            "title": "Grounding Tide",
+            "emotional_tone": "Settling and steady",
+            "guidance": "Let your breath fall behind the pulse until the session feels steady.",
+            "reflection": "This session favors stability over intensity.",
+        },
+    }
+
+    monkeypatch.setattr(app, "analyze_input", lambda text, audio: analysis)
+    monkeypatch.setattr(
+        app,
+        "generate_modulated_experience",
+        lambda *args, **kwargs: ("Generation unavailable", None, None, None, "legacy symbolic"),
+    )
+
+    outputs = app.rhythma_experience(
+        "I feel anxious and need to settle down",
+        None,
+        override_freq=0,
+        override_modulation="sine",
+        override_rhythm="Automatic",
+        duration=5,
+    )
+
+    assert outputs[2] == "Generation unavailable"
+    assert outputs[6] == "Generation unavailable"