Reduce startup brittleness in the Rhythma experience

Split the monolithic backend into focused engine and analysis modules, keep the public rhythma import surface stable, trim obvious dependency and logging noise, and clean up the Gradio examples so the advanced-setting columns render intentionally. This keeps the app easier to change while avoiding a behavioral rewrite.

Constraint: The Hugging Face Space currently relies on app.py importing from rhythma
Constraint: Optional dependencies must not block module import when unavailable locally
Rejected: Full product-behavior redesign in the same change | too broad for a safe push
Rejected: Eager embedding initialization at startup | slows startup and increases failure surface
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep optional provider initialization lazy and preserve the public rhythma facade unless app.py is updated in the same change
Tested: python -m py_compile app.py rhythma.py rhythma_engine.py rhythma_analysis.py tests/test_rhythma_regression.py
Tested: python -c "from rhythma import RhythmaModulationEngine, RhythmaSymphAICore; core = RhythmaSymphAICore(use_groq=False, use_embeddings=False); result = core.analyze_input('feeling stressed about work'); wave = RhythmaModulationEngine(emotional_state='stressed').generate_modulated_wave(0.1); print(result['emotional_state'], result['rhythm_pattern'], len(wave))"
Not-tested: Full Gradio UI startup in this environment because gradio is not installed locally
Not-tested: End-to-end Hugging Face Space runtime after deployment

README.md

@@ -13,4 +13,23 @@ thumbnail: >-
 short_description: 🔊Reverse Active Denial System
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Local Development
+
+Install the dependencies, then run the Gradio app:
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+Set `GROQ_API_KEY` to enable Groq-backed text classification and audio transcription.
+
+## Project Structure
+
+- `app.py`: 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.py`: compatibility facade for the public classes
+- `tests/test_rhythma_regression.py`: regression tests for the core behavior

app.py

@@ -1,129 +1,106 @@
 import os
+import logging
 import gradio as gr
-import numpy as np
 import matplotlib
-matplotlib.use('Agg') # Set backend BEFORE importing pyplot
-import matplotlib.pyplot as plt
-from PIL import Image
-import soundfile as sf
+matplotlib.use('Agg')
 import tempfile
 import time
-from rhythma import RhythmaModulationEngine, RhythmaSymphAICore # Assuming rhythma.py is in the same directory
+from rhythma import RhythmaModulationEngine, RhythmaSymphAICore
+
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
 
 # --- Environment Variable Check ---
 GROQ_API_KEY = os.environ.get("GROQ_API_KEY")
 use_groq = bool(GROQ_API_KEY) # True only if key exists and is not empty
 
 if not use_groq:
-    print("*"*40)
-    print("⚠️ WARNING: GROQ_API_KEY not found or empty in environment variables.")
-    print("   Groq LLM analysis and audio transcription features will be disabled.")
-    print("   Falling back to local analysis methods.")
-    print("*"*40)
+    LOGGER.warning(
+        "GROQ_API_KEY not found. Advanced LLM analysis and transcription are disabled."
+    )
 else:
-    print("✅ GROQ_API_KEY found. Enabling Groq features.")
+    LOGGER.info("GROQ_API_KEY found. Enabling Groq features.")
 # --- End Environment Variable Check ---
 
 
 # --- Initialize Core Components ---
 try:
-    # Pass the determined use_groq flag to the core
     symphai_core = RhythmaSymphAICore(use_groq=use_groq)
 except Exception as e:
-     print(f"❌ FATAL ERROR: Could not initialize RhythmaSymphAICore: {e}")
-     # Handle fatal error appropriately - maybe exit or disable functionality
-     symphai_core = None # Indicate failure
+    LOGGER.exception("Could not initialize RhythmaSymphAICore: %s", e)
+    symphai_core = None
 # --- End Initialization ---
 
 
 # --- Core Functions ---
 def analyze_input(input_text=None, audio_input=None):
-    """Analyze user input using the SymphAI Core."""
     if symphai_core is None:
         return {"error": "Analysis Core failed to initialize."}
 
-    # Ensure audio_input is a filepath string or None
     audio_filepath = audio_input if isinstance(audio_input, str) else None
-
-    # Pass to SymphAI Core for analysis
-    # Add default empty string for input_text if None, as core expects string or None
     return symphai_core.analyze_input(input_text or "", audio_filepath)
 
 
 def generate_modulated_experience(analysis_result, base_freq=None, modulation_type="sine", rhythm_pattern=None, duration=5):
-    """Generate a complete modulated experience based on analysis and parameters."""
-    print(f"DEBUG: generate_modulated_experience received analysis: {analysis_result}")
-    print(f"DEBUG: Overrides - Freq: {base_freq}, Mod: {modulation_type}, Rhythm: {rhythm_pattern}, Dur: {duration}")
-
-    # --- Input Validation ---
     if not isinstance(analysis_result, dict):
-        error_msg = "Internal Error: Analysis result is not in the expected format."
-        print(f"❌ {error_msg}")
+        error_msg = "Internal error: analysis result is not in the expected format."
+        LOGGER.error(error_msg)
         return error_msg, None, None, None, None
 
-    if "error" in analysis_result and analysis_result["error"]:
+    if analysis_result.get("error"):
         error_msg = f"Analysis Error: {analysis_result['error']}"
-        print(f"❌ {error_msg}")
-        # Return the error message clearly for the analysis output
+        LOGGER.error(error_msg)
         return error_msg, None, None, None, None
 
-    # Ensure required keys exist, even if defaults were used in analysis
-    emotional_state = analysis_result.get("emotional_state", "neutral") # Default if missing
-    rhythm_pattern_from_analysis = analysis_result.get("rhythm_pattern", "calm") # Default if missing
-
-    # --- Determine Final Parameters ---
-    # Use manual override if provided and valid, otherwise use analysis result
-    final_rhythm_pattern = rhythm_pattern if rhythm_pattern else rhythm_pattern_from_analysis
-    # Use manual frequency override ONLY if it's > 0
-    final_base_freq = base_freq if base_freq and base_freq > 0 else None # Pass None to let engine use emotion/default
-
-    print(f"DEBUG: Engine Params - Emotion: {emotional_state}, Freq Override: {final_base_freq}, Rhythm: {final_rhythm_pattern}, Mod: {modulation_type}")
+    emotional_state = analysis_result.get("emotional_state", "neutral")
+    final_rhythm_pattern = rhythm_pattern or analysis_result.get("rhythm_pattern", "calm")
+    final_base_freq = base_freq if base_freq and base_freq > 0 else None
 
     try:
-        # --- Initialize the Rhythma Engine ---
         engine = RhythmaModulationEngine(
-            base_freq=final_base_freq,  # Engine handles None: uses emotional_state or default
+            base_freq=final_base_freq,
             modulation_type=modulation_type,
             rhythm_pattern=final_rhythm_pattern,
-            emotional_state=emotional_state if not final_base_freq else None # Pass emotion only if freq isn't overridden
+            emotional_state=emotional_state if not final_base_freq else None,
         )
 
-        # --- Generate Outputs ---
         timestamp = int(time.time())
         temp_dir = tempfile.gettempdir()
-        # Ensure temp_dir exists (useful in some restricted environments)
         os.makedirs(temp_dir, exist_ok=True)
         audio_file = os.path.join(temp_dir, f"rhythma_{timestamp}.wav")
 
-        # Generate and save audio
         saved_audio_path = engine.save_audio(duration, audio_file)
-        if not saved_audio_path: # Check if saving failed
-             raise RuntimeError("Failed to save generated audio file.")
+        if not saved_audio_path:
+            raise RuntimeError("Failed to save generated audio file.")
 
-        # Generate waveform visualization (Plot)
         fig = engine.visualize_waveform(duration)
-
-        # Get simple waveform image (PIL Image)
         waveform_image = engine.get_waveform_image()
-
-        # Get complete analysis text from the engine's perspective
         analysis_text = engine.get_complete_analysis()
-
-        # Get symbolic interpretation
         symbolic = engine.get_symbolic_interpretation()
 
-        print("✅ Modulation experience generated successfully.")
         return analysis_text, saved_audio_path, fig, waveform_image, symbolic
 
     except Exception as e:
         error_msg = f"Error during Rhythma generation: {e}"
-        print(f"❌ {error_msg}")
-        import traceback
-        traceback.print_exc()
-        # Return error message for analysis, and None for other outputs
+        LOGGER.exception(error_msg)
         return error_msg, None, None, None, None
 
 
+def coerce_frequency(value):
+    try:
+        numeric_value = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    return numeric_value if numeric_value > 0 else 0.0
+
+
+def normalize_rhythm_override(value):
+    if value in (None, "", "Automatic"):
+        return None
+    return value
+
+
 def rhythma_experience(
     input_text, audio_input,
     override_freq=None,
@@ -131,41 +108,20 @@ def rhythma_experience(
     override_rhythm=None,
     duration=5
 ):
-    """Complete Rhythma experience pipeline: Analysis -> Generation"""
-    print("\n--- Starting New Rhythma Experience ---")
-    # Clean up input text
     input_text = input_text.strip() if input_text else ""
-
-    # --- Step 1: Analyze input ---
-    # Ensure override_freq is float or None
-    try:
-         freq_override_value = float(override_freq) if override_freq is not None else 0.0
-    except (ValueError, TypeError):
-         freq_override_value = 0.0 # Default to 0 if invalid input
-
+    freq_override_value = coerce_frequency(override_freq)
     analysis = analyze_input(input_text, audio_input)
 
-    # --- Step 2: Generate modulated experience ---
-    # Pass analysis results and overrides to the generation function
     analysis_text, audio_file, fig, waveform_image, symbolic = generate_modulated_experience(
         analysis,
-        base_freq=freq_override_value, # Pass the validated float/int
+        base_freq=freq_override_value,
         modulation_type=override_modulation,
-        rhythm_pattern=override_rhythm if override_rhythm else None, # Pass None if dropdown default is selected
+        rhythm_pattern=normalize_rhythm_override(override_rhythm),
         duration=duration
     )
 
-    # --- Step 3: Prepare Outputs ---
-    # Get transcription from analysis result (will be empty string if no audio/transcription)
     transcription = analysis.get("transcription", "") if isinstance(analysis, dict) else ""
-    # If analysis itself failed, analysis_text will contain the error message from generate_modulated_experience
-    # If only transcription failed, it might be in the transcription field
-
-    # Handle potential None figure if generation failed
-    plot_output = fig if fig else None # Gradio handles None for Plot output
-
-    print("--- Rhythma Experience Complete ---")
-    # Return all outputs for Gradio interface
+    plot_output = fig if fig else None
     return analysis_text, audio_file, plot_output, waveform_image, symbolic, transcription
 
 # --- Create the Gradio Interface ---
@@ -206,13 +162,12 @@ def create_interface():
                         value="sine",
                         label="Override Modulation Type"
                     )
-                    # Get available patterns from the engine instance
                     available_patterns = list(RhythmaModulationEngine().rhythm_configs.keys())
                     override_rhythm = gr.Dropdown(
-                        choices=[None] + available_patterns, # Add None option for automatic
-                        value=None, # Default to automatic
+                        choices=["Automatic"] + available_patterns,
+                        value="Automatic",
                         label="Override Rhythm Pattern",
-                        info="Leave blank to use automatic pattern based on analysis."
+                        info="Leave on Automatic to use the pattern inferred from the analysis."
                     )
                     duration = gr.Slider(
                         minimum=3, maximum=60, value=10, step=1,
@@ -254,18 +209,18 @@ def create_interface():
         # Add Examples
         gr.Examples(
             examples=[
-                ["I'm feeling anxious about my upcoming presentation.", None, 0, "sine", None, 10],
-                ["I feel at peace and grounded today.", None, 0, "sine", None, 15],
-                ["I need to focus on my work but keep getting distracted.", None, 0, "sine", None, 20],
-                ["Feeling overwhelmed with responsibilities.", None, 0, "sine", None, 10],
-                ["Excited about my vacation next week!", None, 0, "sine", None, 10],
-                ["Just want to relax after a long day.", None, 0, "sine", "relaxed", 30], # Example with override
-                ["Feeling sad and low energy.", None, 0, "sine", None, 15],
+                ["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],
             ],
             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],
-            fn=rhythma_experience, # Ensure examples also run the main function
-            cache_examples=False # Maybe disable caching during development
+            fn=rhythma_experience,
+            cache_examples=False
         )
 
         gr.Markdown("---")
@@ -282,10 +237,7 @@ def create_interface():
 # --- Run the Gradio App ---
 if __name__ == "__main__":
     if symphai_core is None:
-         print("\n❌ Cannot launch Gradio app because RhythmaSymphAICore failed to initialize.\n")
+        LOGGER.error("Cannot launch Gradio app because RhythmaSymphAICore failed to initialize.")
     else:
-        print("\n🚀 Launching Rhythma Gradio Interface...")
         app_demo = create_interface()
-        # Set share=True if you need a public link (useful for testing deployment)
-        # Set debug=True for more verbose logs during development
-        app_demo.launch()#debug=True)
+        app_demo.launch()

requirements.txt

@@ -3,11 +3,7 @@ groq
 soundfile
 numpy
 sentence-transformers
-scikit-learn
-pandas
 matplotlib
 pillow
-librosa
-SpeechRecognition
 scipy
-torch
+torch

rhythma.py

@@ -1,663 +1,8 @@
-import numpy as np
-import matplotlib.pyplot as plt
-from scipy import signal
-# import pandas as pd # pandas wasn't used, commented out
-from PIL import Image
-import io
-from sklearn.metrics.pairwise import cosine_similarity
-import soundfile as sf
-import os
-import traceback # For better error logging
-
-# --- Optional Dependency Handling ---
-try:
-    from groq import Groq
-    GROQ_AVAILABLE = True
-except ImportError:
-    GROQ_AVAILABLE = False
-    print("⚠️ Groq package not installed. LLM analysis and transcription disabled.")
-
-try:
-    from sentence_transformers import SentenceTransformer
-    SENTENCE_TRANSFORMER_AVAILABLE = True
-except ImportError:
-    SENTENCE_TRANSFORMER_AVAILABLE = False
-    print("⚠️ SentenceTransformer not installed. Falling back to simple text matching for analysis.")
-# --- End Optional Dependency Handling ---
-
-class RhythmaModulationEngine:
-    """
-    Rhythma: The Living Modulation Engine
-    A dynamic rhythm-based audio modulation system that creates responsive
-    sound experiences based on rhythm patterns and emotional states.
-    """
-
-    def __init__(self, base_freq=None, modulation_type="sine", rhythm_pattern=None, emotional_state=None):
-        """
-        Initialize the RhythmaModulationEngine.
-        Args:
-            base_freq (float, optional): The base frequency in Hz. Overridden by emotional_state if provided.
-            modulation_type (str): Type of modulation (sine, pulse, chirp). Defaults to "sine".
-            rhythm_pattern (str, optional): Pattern type (calm, active, focused, relaxed). Defaults to "calm".
-            emotional_state (str, optional): Emotional state (anxious, stressed, calm, etc.). Maps to specific frequencies.
-        """
-        self.modulation_type = modulation_type
-        self.sample_rate = 44100  # Standard audio sample rate
-
-        # Define frequency mappings for emotional states (Example frequencies)
-        self.emotional_frequencies = {
-            "anxious": 396,
-            "stressed": 528,
-            "calm": 741,
-            "sad": 417,
-            "angry": 852,
-            "fearful": 639,
-            "confused": 285,
-            "happy": 432,
-            "neutral": 440, # Added neutral state
-            "focused": 639, # Example mapping for focus intention
-            "relaxed": 741, # Example mapping for relax intention
-            "active": 528,  # Example mapping for active intention
-        }
-
-        # Detailed information about emotional states/frequencies
-        self.emotional_info = {
-            "anxious": {"name": "Liberating Guilt and Fear", "advice": "The 396 Hz frequency may help release fear and guilt."},
-            "stressed": {"name": "Transformation and Miracles", "advice": "The 528 Hz frequency is associated with transformation."},
-            "calm": {"name": "Awakening Intuition", "advice": "The 741 Hz frequency is associated with awakening intuition."},
-            "sad": {"name": "Facilitating Change", "advice": "The 417 Hz frequency is linked to facilitating change."},
-            "angry": {"name": "Returning to Spiritual Order", "advice": "The 852 Hz frequency may aid in returning to inner strength."},
-            "fearful": {"name": "Connecting Relationships", "advice": "The 639 Hz frequency is associated with connecting relationships."},
-            "confused": {"name": "Quantum Cognition", "advice": "The 285 Hz frequency is believed to influence energy fields."},
-            "happy": {"name": "Harmonizing Vibrations", "advice": "The 432 Hz frequency is associated with natural harmony."},
-            "neutral": {"name": "Grounded Presence", "advice": "The 440 Hz frequency provides a stable reference point."},
-            "focused": {"name": "Clarity and Connection", "advice": "The 639 Hz frequency may support focus and understanding."},
-             "relaxed": {"name": "Intuitive Calm", "advice": "The 741 Hz frequency is linked to intuitive states and problem-solving."},
-             "active": {"name": "Dynamic Energy", "advice": "The 528 Hz frequency is associated with positive transformation."},
-        }
-
-        # Configure rhythm patterns
-        self.rhythm_configs = {
-            "calm": {"mod_depth": 0.15, "mod_freq": 0.5, "pulse_width": 0.7, "phase_shift": 0.1, "harmonics": [1.0, 0.5, 0.25, 0.125]},
-            "active": {"mod_depth": 0.4, "mod_freq": 2.5, "pulse_width": 0.3, "phase_shift": 0.3, "harmonics": [1.0, 0.7, 0.5, 0.3]},
-            "focused": {"mod_depth": 0.25, "mod_freq": 1.5, "pulse_width": 0.5, "phase_shift": 0.2, "harmonics": [1.0, 0.6, 0.3, 0.15]},
-            "relaxed": {"mod_depth": 0.2, "mod_freq": 0.3, "pulse_width": 0.8, "phase_shift": 0.05, "harmonics": [1.0, 0.4, 0.2, 0.1]}
-        }
-
-        # Symbolic mapping for rhythm patterns
-        self.symbolic_mapping = {
-            "calm": "Resonating in the Circle Archetype: completion, wholeness, presence",
-            "active": "Resonating in the Spiral Archetype: flow, transition, emergence",
-            "focused": "Resonating in the Triangle Archetype: clarity, direction, purpose",
-            "relaxed": "Resonating in the Wave Archetype: fluidity, acceptance, surrender"
-        }
-
-        # Determine emotional state and base frequency
-        valid_emotional_state = emotional_state if emotional_state and emotional_state in self.emotional_frequencies else None
-        self.emotional_state = valid_emotional_state
-
-        if self.emotional_state:
-            self.base_freq = self.emotional_frequencies[self.emotional_state]
-        elif base_freq and base_freq > 0: # Check if base_freq override is valid
-             self.base_freq = base_freq
-             # Try to find a state close to the frequency for info purposes
-             min_diff = float('inf')
-             closest_state = None
-             for state, freq in self.emotional_frequencies.items():
-                 diff = abs(freq - base_freq)
-                 if diff < min_diff:
-                     min_diff = diff
-                     closest_state = state
-             # Only assign if reasonably close (e.g., within 10 Hz)
-             if min_diff <= 10:
-                 self.emotional_state = closest_state # Use for info display only
-             else:
-                 self.emotional_state = None # No specific emotional state tied
-        else:
-            self.emotional_state = "neutral" # Default state if no emotion/freq provided
-            self.base_freq = self.emotional_frequencies[self.emotional_state]
-
-
-        # Set rhythm pattern
-        valid_rhythm_pattern = rhythm_pattern if rhythm_pattern and rhythm_pattern in self.rhythm_configs else None
-        self.rhythm_pattern = valid_rhythm_pattern or "calm"  # Default to calm if not provided or invalid
-
-        # Get current rhythm config
-        self.config = self.rhythm_configs.get(self.rhythm_pattern, self.rhythm_configs["calm"])
-
-    def _generate_base_wave(self, duration):
-        """Generate the base carrier wave"""
-        t = np.linspace(0, duration, int(self.sample_rate * duration), endpoint=False)
-        # Initial simple sine wave
-        base_wave = np.sin(2 * np.pi * self.base_freq * t)
-
-        # Apply harmonics for richer base sound *before* modulation
-        harmonics = self.config["harmonics"]
-        rich_wave = np.zeros_like(base_wave)
-        for i, harmonic_amp in enumerate(harmonics):
-            harmonic_freq = self.base_freq * (i + 1)
-            # Ensure harmonic frequency does not exceed Nyquist limit
-            if harmonic_freq < self.sample_rate / 2:
-                rich_wave += harmonic_amp * np.sin(2 * np.pi * harmonic_freq * t)
-
-        # Normalize the rich base wave before modulation
-        if np.max(np.abs(rich_wave)) > 0:
-           rich_wave = rich_wave / np.max(np.abs(rich_wave))
-        else:
-            rich_wave = base_wave # Fallback if harmonics resulted in zero
-
-        return t, rich_wave
-
-
-    def _apply_sine_modulation(self, t, carrier):
-        """Apply sine wave amplitude modulation"""
-        mod_freq = self.config["mod_freq"]
-        mod_depth = self.config["mod_depth"]
-        mod_env = 1.0 + mod_depth * np.sin(2 * np.pi * mod_freq * t + self.config["phase_shift"])
-        return carrier * mod_env
-
-    def _apply_pulse_modulation(self, t, carrier):
-        """Apply pulse wave amplitude modulation"""
-        mod_freq = self.config["mod_freq"]
-        mod_depth = self.config["mod_depth"]
-        pulse_width = self.config["pulse_width"]
-        pulse = 0.5 * (signal.square(2 * np.pi * mod_freq * t, duty=pulse_width) + 1) # 0 to 1
-        mod_env = 1.0 - mod_depth + mod_depth * pulse # Modulates between (1-depth) and 1
-        return carrier * mod_env
-
-    def _apply_chirp_modulation(self, t, carrier):
-        """Apply frequency chirp modulation (applied differently)"""
-        # Chirp modulation modifies frequency directly, not amplitude envelope
-        # This implementation is more complex and might replace the base wave generation
-        # For simplicity, let's keep amplitude modulation for 'chirp' but with a varying mod freq
-
-        # Simple approach: vary the *modulation frequency* over time (like a siren)
-        start_mod_freq = max(0.1, self.config["mod_freq"] / 2) # Avoid 0 Hz
-        end_mod_freq = self.config["mod_freq"] * 2
-        instantaneous_mod_freq = np.linspace(start_mod_freq, end_mod_freq, len(t))
-
-        mod_depth = self.config["mod_depth"]
-        # Integrate frequency to get phase: 2 * pi * integral(f(t) dt)
-        phase = 2 * np.pi * np.cumsum(instantaneous_mod_freq) / self.sample_rate
-        mod_env = 1.0 + mod_depth * np.sin(phase + self.config["phase_shift"])
-        return carrier * mod_env
-
-    def generate_modulated_wave(self, duration):
-        """
-        Generate modulated audio wave based on current settings.
-        Applies harmonics to the base wave first, then applies modulation.
-        """
-        t, base_carrier = self._generate_base_wave(duration) # Base carrier now includes harmonics
-
-        # Apply the selected amplitude modulation type
-        if self.modulation_type == "sine":
-            modulated = self._apply_sine_modulation(t, base_carrier)
-        elif self.modulation_type == "pulse":
-            modulated = self._apply_pulse_modulation(t, base_carrier)
-        elif self.modulation_type == "chirp":
-             # Using the amplitude modulation with varying frequency approach
-            modulated = self._apply_chirp_modulation(t, base_carrier)
-        else:
-            modulated = base_carrier  # Default to unmodulated rich carrier
-
-        # Final normalization to prevent clipping
-        max_amp = np.max(np.abs(modulated))
-        if max_amp > 0:
-            normalized = 0.9 * modulated / max_amp # Use 0.9 to leave headroom
-        else:
-            normalized = modulated # Avoid division by zero if signal is silent
-
-        return normalized
-
-    def save_audio(self, duration, file_path=None):
-        """Generate and save audio to a file"""
-        audio = self.generate_modulated_wave(duration)
-        file_path = file_path or f"rhythma_{self.base_freq}Hz_{self.rhythm_pattern}.wav"
-        try:
-            sf.write(file_path, audio, self.sample_rate)
-            print(f"Audio saved to: {file_path}")
-            return file_path
-        except Exception as e:
-            print(f"Error saving audio file: {e}")
-            traceback.print_exc()
-            return None # Return None if saving fails
-
-
-    def visualize_waveform(self, duration):
-        """Generate visualization of the modulated waveform"""
-        # Generate a shorter segment for visualization consistency
-        vis_duration = min(duration, 0.5) # Shorter duration for clearer plot
-        plot_samples = int(self.sample_rate * vis_duration)
-
-        t = np.linspace(0, vis_duration, plot_samples, endpoint=False)
-        modulated = self.generate_modulated_wave(vis_duration) # Generate specific duration
-
-        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 6), gridspec_kw={'height_ratios': [1, 1]})
-
-        # Plot time domain (zoom in on a small section for detail)
-        zoom_samples = min(plot_samples, 2000) # Show max ~45ms
-        ax1.plot(t[:zoom_samples], modulated[:zoom_samples])
-        title = f'Rhythma Waveform: {self.rhythm_pattern.capitalize()} ({self.modulation_type.capitalize()})'
-        if self.emotional_state:
-            title += f' - {self.emotional_state.capitalize()} ({self.base_freq} Hz)'
-        else:
-             title += f' - {self.base_freq} Hz'
-        ax1.set_title(title)
-        ax1.set_xlabel('Time (s)')
-        ax1.set_ylabel('Amplitude')
-        ax1.grid(True)
-
-        # Plot frequency domain (spectrogram)
-        try:
-             # Use the full generated segment for spectrogram if possible
-             full_wave = self.generate_modulated_wave(duration)
-             f, t_spec, Sxx = signal.spectrogram(full_wave, self.sample_rate, nperseg=1024)
-             # Limit frequency display range for clarity (e.g., up to 2kHz)
-             freq_limit_idx = np.where(f >= 2000)[0]
-             if len(freq_limit_idx) > 0:
-                 f = f[:freq_limit_idx[0]]
-                 Sxx = Sxx[:freq_limit_idx[0], :]
-             else: # Handle cases where max freq is below limit
-                  pass
-             # Use logarithmic scale for power if needed
-             pcm = ax2.pcolormesh(t_spec, f, 10 * np.log10(Sxx + 1e-9), shading='gouraud', cmap='viridis') # Log scale power
-             fig.colorbar(pcm, ax=ax2, label='Power (dB)') # Add colorbar
-             ax2.set_ylabel('Frequency (Hz)')
-             ax2.set_xlabel('Time (s)')
-             ax2.set_title('Spectrogram')
-
-        except Exception as e:
-            print(f"Error generating spectrogram: {e}")
-            ax2.set_title('Spectrogram (Error)')
-            ax2.text(0.5, 0.5, 'Could not generate spectrogram', horizontalalignment='center', verticalalignment='center', transform=ax2.transAxes)
-
-
-        plt.tight_layout(rect=[0, 0.05, 1, 1]) # Adjust layout to prevent overlap, leave space at bottom
-
-        # Add symbolic interpretation below plots
-        fig_text = self.get_symbolic_interpretation()
-        emotion_info = self.emotional_info.get(self.emotional_state, {})
-        if emotion_info:
-             fig_text += f"\n{self.base_freq} Hz - {emotion_info.get('name', '')}: {emotion_info.get('advice', '')}"
-        elif not self.emotional_state: # Case where only base_freq was set
-             fig_text += f"\nBase Frequency: {self.base_freq} Hz"
-
-
-        fig.text(0.5, 0.01, fig_text, ha='center', va='bottom', fontsize=9, style='italic', wrap=True)
-
-        return fig
-
-
-    def get_waveform_image(self):
-        """Generate a simple waveform image as a PIL Image"""
-        # Generate a short, clear representation of the *base* frequency wave
-        duration = 0.05  # Very short duration for visualization
-        t = np.linspace(0, duration, int(self.sample_rate * duration), False)
-        # Use the base frequency determined in __init__
-        tone = np.sin(2 * np.pi * self.base_freq * t)
-
-        plt.figure(figsize=(6, 2)) # Smaller figure for simple image
-        plt.plot(t, tone)
-        # plt.title(f"Base Tone: {self.base_freq} Hz") # Title might clutter small image
-        plt.xlabel("Time (s)")
-        plt.ylabel("Amplitude")
-        plt.ylim(-1.1, 1.1)
-        plt.grid(True)
-        plt.tight_layout()
-
-        buf = io.BytesIO()
-        plt.savefig(buf, format='png', bbox_inches='tight')
-        buf.seek(0)
-        plt.close() # Close the plot to free memory
-
-        return Image.open(buf)
-
-
-    def get_symbolic_interpretation(self):
-        """Return the symbolic interpretation of the current rhythm pattern"""
-        return self.symbolic_mapping.get(self.rhythm_pattern, "Pattern Interpretation: Default")
-
-    def get_emotional_advice(self):
-        """Get advice based on emotional state if available"""
-        if not self.emotional_state:
-            return "No specific emotional state identified."
-
-        emotion_info = self.emotional_info.get(self.emotional_state, {})
-        return emotion_info.get('advice', "General well-being advice applies.")
-
-
-    def get_complete_analysis(self):
-        """Get a complete analysis including emotional and rhythmic information"""
-        analysis = []
-
-        if self.emotional_state:
-            emotion_info = self.emotional_info.get(self.emotional_state, {})
-            analysis.append(f"Detected State/Intention: {self.emotional_state.capitalize()}")
-            analysis.append(f"Resonant Frequency: {self.base_freq} Hz - {emotion_info.get('name', 'Frequency Information')}")
-            analysis.append(f"Guidance: {emotion_info.get('advice', 'Focus on the sound.')}")
-        else:
-             # This case happens if only override_freq was used and it didn't map closely to a state
-            analysis.append(f"Using Manual Frequency: {self.base_freq} Hz")
-            analysis.append("Guidance: Tune into the custom frequency.")
-
-        analysis.append(f"Rhythm Pattern: {self.rhythm_pattern.capitalize()}")
-        analysis.append(f"Symbolic Interpretation: {self.get_symbolic_interpretation()}")
-        analysis.append(f"Modulation Type: {self.modulation_type.capitalize()}")
-
-        return "\n\n".join(analysis)
-
-
-class RhythmaSymphAICore:
-    """
-    SymphAI Core - Interprets input to determine emotional state and rhythm pattern.
-    Handles text and audio input, utilizing Groq LLM and Sentence Transformers if available.
-    """
-
-    def __init__(self, use_groq=True):
-        """Initialize the SymphAI Core"""
-        # Expanded emotional states / intentions
-        self.emotional_states = [
-            "anxious", "stressed", "calm", "sad",
-            "angry", "fearful", "confused", "happy",
-            "neutral", "focused", "relaxed", "active", # Added intentions
-        ]
-
-        # Default rhythm patterns
-        self.rhythm_patterns = list(RhythmaModulationEngine().rhythm_configs.keys()) # Get from engine
-
-        # Initialize Groq client if available and requested
-        self.groq_client = None
-        self.use_groq = use_groq and GROQ_AVAILABLE
-        if self.use_groq:
-            api_key = os.environ.get("GROQ_API_KEY")
-            if api_key:
-                try:
-                    self.groq_client = Groq(api_key=api_key)
-                    print("✅ Groq client initialized successfully.")
-                except Exception as e:
-                    print(f"⚠️ Failed to initialize Groq client: {str(e)}")
-                    self.use_groq = False # Disable Groq if init fails
-            else:
-                print("⚠️ GROQ_API_KEY environment variable not found. Groq features disabled.")
-                self.use_groq = False
-
-        # Initialize sentence transformer for semantic matching if available
-        self.embedding_model = None
-        self.emotional_embeddings = {}
-        self.rhythm_embeddings = {}
-        if SENTENCE_TRANSFORMER_AVAILABLE:
-            try:
-                # Using a common, effective model
-                self.embedding_model = SentenceTransformer('all-MiniLM-L6-v2')
-                # Pre-compute embeddings for faster lookup
-                self.emotional_embeddings = {
-                    state: self.embedding_model.encode([state])[0] # Get the 1D array
-                    for state in self.emotional_states
-                }
-                self.rhythm_embeddings = {
-                    pattern: self.embedding_model.encode([pattern])[0] # Get the 1D array
-                    for pattern in self.rhythm_patterns
-                }
-                print("✅ SentenceTransformer initialized successfully.")
-            except Exception as e:
-                print(f"⚠️ Failed to initialize SentenceTransformer: {str(e)}. Using basic text matching.")
-                self.embedding_model = None # Ensure it's None if init fails
-        else:
-             print("ℹ️ SentenceTransformer not installed. Using basic text matching.")
-
-
-    # Line 343:
-    def detect_emotion_with_groq(self, input_text):
-        """Use Groq LLM to detect emotion/intention in text"""
-        if not self.use_groq or not self.groq_client:
-            print("ℹ️ Groq not available or not initialized for emotion detection.")
-            return None # Indicate Groq wasn't used
-
-        # Refined prompt for better classification into our categories
-        available_states = ", ".join(self.emotional_states)
-        prompt = f"""Analyze the user's feeling described below.
-Identify the single MOST prominent emotional state or intention from the following list:
-{available_states}
-Focus on the core feeling expressed. Respond with ONLY the chosen state/intention from the list.
-User's feeling: "{input_text}"
-State/Intention:"""
-
-        try:
-            print(f"ℹ️ Querying Groq for emotion analysis...")
-            chat_completion = self.groq_client.chat.completions.create(
-                messages=[{"role": "user", "content": prompt}],
-                model="llama-3.3-70b-versatile", # Specify a capable model available on Groq
-                max_tokens=15, # Allow slightly more tokens for flexibility
-                temperature=0.2, # Lower temperature for more deterministic classification
-                stop=["\n"] # Stop generation after the first line
-            )
-
-            detected_emotion = chat_completion.choices[0].message.content.strip().lower()
-            print(f"✅ Groq detected: {detected_emotion}")
-
-            # Validate the detected emotion against our list
-            if detected_emotion in self.emotional_states:
-                return detected_emotion
-            else:
-                print(f"⚠️ Groq returned '{detected_emotion}', not in known states. Attempting fallback match.")
-                # Fallback: If LLM returns something unexpected, find the closest match in our list
-                return self.get_closest_emotional_state(detected_emotion) # Use fallback on unexpected LLM output
-
-        except Exception as e:
-            print(f"❌ Error using Groq for emotion detection: {str(e)}")
-            traceback.print_exc()
-            return None # Indicate error or inability to use Groq
-
-
-    def get_closest_emotional_state(self, input_text):
-        """Map input text to the closest emotional state using available methods."""
-        if not input_text:
-            return "neutral" # Default if no text
-
-        input_text_lower = input_text.lower()
-
-        # 1. Try simple keyword matching first (fastest)
-        for state in self.emotional_states:
-            if state in input_text_lower.split(): # Match whole words if possible
-                print(f"ℹ️ Matched keyword: {state}")
-                return state
-            # Simple substring check as backup
-            if state in input_text_lower:
-                 print(f"ℹ️ Matched substring: {state}")
-                 return state
-
-
-        # 2. If Sentence Transformer is available, use semantic similarity
-        if self.embedding_model and self.emotional_embeddings:
-            try:
-                print("ℹ️ Using Sentence Transformer for semantic emotion match.")
-                input_embedding = self.embedding_model.encode([input_text])[0] # Get 1D array
-                # Calculate cosine similarities
-                similarities = {
-                    state: cosine_similarity(input_embedding.reshape(1, -1), embedding.reshape(1, -1))[0][0]
-                    for state, embedding in self.emotional_embeddings.items()
-                }
-                # Find the state with the highest similarity
-                best_match = max(similarities, key=similarities.get)
-                print(f"✅ Semantic match: {best_match} (Similarity: {similarities[best_match]:.2f})")
-                return best_match
-            except Exception as e:
-                print(f"⚠️ Error during semantic matching: {e}. Falling back.")
-                traceback.print_exc()
-
-        # 3. Default fallback if no match found
-        print("ℹ️ No clear emotion match found, defaulting to 'neutral'.")
-        return "neutral"
-
-
-    def get_closest_rhythm_pattern(self, input_text=None, emotional_state=None):
-        """Map input text or emotional state to the closest rhythm pattern."""
-
-        # 1. Direct mapping from emotional state (prioritized if state is known)
-        if emotional_state:
-            # Refined mapping based on typical energy levels/needs
-            mapping = {
-                "anxious": "calm",    # Needs calming
-                "stressed": "relaxed",  # Needs relaxation
-                "calm": "calm",
-                "sad": "relaxed",     # Gentle support
-                "angry": "active",    # Needs release/energy shift
-                "fearful": "calm",    # Needs safety/grounding
-                "confused": "focused", # Needs clarity
-                "happy": "active",    # Can match higher energy
-                "neutral": "calm",
-                "focused": "focused", # Align with intention
-                "relaxed": "relaxed", # Align with intention
-                "active": "active",   # Align with intention
-            }
-            pattern = mapping.get(emotional_state, "calm") # Default to calm if state unknown
-            print(f"ℹ️ Rhythm pattern from state '{emotional_state}': {pattern}")
-            return pattern
-
-        # 2. If no emotional state, try matching input text semantically (if available)
-        if input_text and self.embedding_model and self.rhythm_embeddings:
-            try:
-                print("ℹ️ Using Sentence Transformer for semantic rhythm match.")
-                input_embedding = self.embedding_model.encode([input_text])[0]
-                similarities = {
-                    pattern: cosine_similarity(input_embedding.reshape(1, -1), embedding.reshape(1, -1))[0][0]
-                    for pattern, embedding in self.rhythm_embeddings.items()
-                }
-                best_match = max(similarities, key=similarities.get)
-                print(f"✅ Semantic rhythm match: {best_match} (Similarity: {similarities[best_match]:.2f})")
-                return best_match
-            except Exception as e:
-                print(f"⚠️ Error during semantic rhythm matching: {e}. Falling back.")
-                traceback.print_exc()
-
-        # 3. Default fallback
-        print("ℹ️ Defaulting rhythm pattern to 'calm'.")
-        return "calm"
-
-
-    def transcribe_audio(self, audio_path):
-        """Transcribe audio using Groq Whisper if available"""
-        if not self.use_groq or not self.groq_client:
-            print("ℹ️ Groq not available for transcription.")
-            return None, "Transcription disabled: Groq client not available or API key missing."
-
-        if not audio_path or not os.path.exists(audio_path):
-             return None, "Transcription failed: Audio file path is invalid or missing."
-
-        try:
-            print(f"ℹ️ Transcribing audio file: {audio_path}")
-            with open(audio_path, "rb") as audio_file:
-                # Use whisper-large-v3 for potentially better accuracy
-                transcription_response = self.groq_client.audio.transcriptions.create(
-                    file=(os.path.basename(audio_path), audio_file.read()),
-                    model="whisper-large-v3", # Using v3
-                    # response_format="verbose_json", # Get more details if needed
-                    response_format="json", # Simpler format
-                )
-
-            transcribed_text = transcription_response.text
-            print(f"✅ Groq transcription successful: '{transcribed_text}'")
-            return transcribed_text, None # Return text and no error
-
-        except Exception as e:
-            error_message = f"Error during Groq transcription: {str(e)}"
-            print(f"❌ {error_message}")
-            traceback.print_exc()
-            return None, error_message # Return None and the error message
-
-    # --- THIS IS THE FUNCTION STARTING AT LINE 410 ---
-    def analyze_input(self, input_text=None, audio_path=None):
-        """
-        Analyze input text and/or audio path to determine emotional state and rhythm pattern.
-        **Ensures a dictionary is always returned.**
-        """
-        # ---> Line 411: Ensure this block is indented <---
-        analysis_result = {
-            "emotional_state": "neutral", # Default values
-            "rhythm_pattern": "calm",    # Default values
-            "transcription": "",
-            "error": None
-        }
-        text_to_analyze = None
-        transcription_error = None
-
-        # ---> All lines below here inside the function must also be indented <---
-        print("-" * 20) # Separator for logs
-        print(f"ℹ️ SymphAI Core analyzing input: Text='{input_text}', Audio='{audio_path}'")
-
-        try:
-            # --- Step 1: Handle Audio Input (if provided and Groq available) ---
-            if audio_path and self.use_groq:
-                transcribed_text, transcription_error = self.transcribe_audio(audio_path)
-                if transcription_error:
-                    print(f"⚠️ Transcription failed: {transcription_error}")
-                    # Store error but potentially continue with text input if available
-                    analysis_result["error"] = transcription_error
-                    analysis_result["transcription"] = f"[Transcription Error: {transcription_error}]"
-                elif transcribed_text:
-                    analysis_result["transcription"] = transcribed_text
-                    text_to_analyze = transcribed_text # Prioritize transcribed text
-                    print(f"ℹ️ Using transcribed text for analysis: '{text_to_analyze}'")
-
-            # --- Step 2: Determine Text for Analysis ---
-            if not text_to_analyze and input_text:
-                text_to_analyze = input_text # Use input_text if no successful transcription
-                print(f"ℹ️ Using provided text for analysis: '{text_to_analyze}'")
-            elif not text_to_analyze:
-                 print("ℹ️ No text input or successful transcription available for analysis.")
-                 # Keep default neutral/calm state
-
-            # --- Step 3: Detect Emotional State (if text available) ---
-            detected_emotion = None
-            if text_to_analyze:
-                if self.use_groq:
-                    detected_emotion = self.detect_emotion_with_groq(text_to_analyze)
-                    if detected_emotion:
-                         analysis_result["emotional_state"] = detected_emotion
-                    else:
-                         # Groq failed or didn't run, try fallback
-                         print("ℹ️ Groq emotion detection failed or skipped, trying fallback.")
-                         analysis_result["emotional_state"] = self.get_closest_emotional_state(text_to_analyze)
-                else:
-                     # Groq not used, directly use fallback
-                     analysis_result["emotional_state"] = self.get_closest_emotional_state(text_to_analyze)
-            else:
-                 # No text to analyze, stick with default "neutral"
-                 analysis_result["emotional_state"] = "neutral"
-
-
-            # --- Step 4: Determine Rhythm Pattern ---
-            # Use the determined emotional state primarily, fallback to text if needed
-            current_emotion = analysis_result["emotional_state"]
-            analysis_result["rhythm_pattern"] = self.get_closest_rhythm_pattern(
-                input_text=text_to_analyze, # Pass text for potential semantic match if emotion is neutral/unclear
-                emotional_state=current_emotion
-            )
-
-            # Clean up error field if no actual error occurred during main analysis
-            if analysis_result["error"] is None and transcription_error:
-                 # If transcription failed but text analysis succeeded, maybe clear the error?
-                 # Decide if transcription error should persist if text analysis works.
-                 # Let's keep it for now to inform the user.
-                 pass
-            elif analysis_result["error"] is None:
-                 # analysis_result.pop("error", None) # Alternative way to remove if None
-                 del analysis_result["error"] # Remove error key if None
-
-
-        except Exception as e:
-            # --- Catch-all for unexpected errors during analysis ---
-            error_msg = f"Unexpected error during input analysis: {str(e)}"
-            print(f"❌ {error_msg}")
-            traceback.print_exc()
-            analysis_result = {
-                "emotional_state": "neutral", # Reset to defaults on error
-                "rhythm_pattern": "calm",
-                "transcription": analysis_result.get("transcription", ""), # Keep transcription if available
-                "error": error_msg
-            }
-
-        # ---> Ensure these lines are indented correctly at the function level <---
-        print(f"✅ SymphAI Core analysis complete. Result: {analysis_result}")
-        print("-" * 20) # Separator for logs
-        return analysis_result # GUARANTEED TO BE A DICTIONARY
+from rhythma_analysis import AnalysisResult, RhythmaSymphAICore
+from rhythma_engine import RhythmaModulationEngine
+
+__all__ = [
+    "AnalysisResult",
+    "RhythmaModulationEngine",
+    "RhythmaSymphAICore",
+]

rhythma_analysis.py

@@ -0,0 +1,259 @@
+import logging
+import os
+from dataclasses import asdict, dataclass
+
+import numpy as np
+
+from rhythma_engine import RhythmaModulationEngine
+
+try:
+    from groq import Groq
+
+    GROQ_AVAILABLE = True
+except ImportError:
+    Groq = None
+    GROQ_AVAILABLE = False
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class AnalysisResult:
+    emotional_state: str = "neutral"
+    rhythm_pattern: str = "calm"
+    transcription: str = ""
+    error: str | None = None
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def _cosine_similarity(left, right):
+    denominator = np.linalg.norm(left) * np.linalg.norm(right)
+    if denominator == 0:
+        return -1.0
+    return float(np.dot(left, right) / denominator)
+
+
+class RhythmaSymphAICore:
+    """
+    Interprets text and audio input to determine emotional state and rhythm pattern.
+    """
+
+    def __init__(self, use_groq=True, use_embeddings=True):
+        self.emotional_states = [
+            "anxious",
+            "stressed",
+            "calm",
+            "sad",
+            "angry",
+            "fearful",
+            "confused",
+            "happy",
+            "neutral",
+            "focused",
+            "relaxed",
+            "active",
+        ]
+        self.rhythm_patterns = list(RhythmaModulationEngine.RHYTHM_CONFIGS.keys())
+
+        self.groq_client = None
+        self.use_groq = use_groq and GROQ_AVAILABLE
+        self.use_embeddings = use_embeddings
+        self.embedding_model = None
+        self.emotional_embeddings = {}
+        self.rhythm_embeddings = {}
+        self._embedding_init_attempted = False
+
+        if self.use_groq:
+            self._initialize_groq_client()
+
+    def _initialize_groq_client(self):
+        api_key = os.environ.get("GROQ_API_KEY")
+        if not api_key:
+            LOGGER.warning("GROQ_API_KEY not found. Groq features disabled.")
+            self.use_groq = False
+            return
+
+        try:
+            self.groq_client = Groq(api_key=api_key)
+        except Exception:
+            LOGGER.exception("Failed to initialize Groq client.")
+            self.use_groq = False
+
+    def _ensure_embeddings_loaded(self):
+        if not self.use_embeddings or self._embedding_init_attempted:
+            return
+
+        self._embedding_init_attempted = True
+        try:
+            from sentence_transformers import SentenceTransformer
+
+            self.embedding_model = SentenceTransformer("all-MiniLM-L6-v2")
+            self.emotional_embeddings = {
+                state: self.embedding_model.encode([state])[0]
+                for state in self.emotional_states
+            }
+            self.rhythm_embeddings = {
+                pattern: self.embedding_model.encode([pattern])[0]
+                for pattern in self.rhythm_patterns
+            }
+        except ImportError:
+            LOGGER.info(
+                "SentenceTransformer not installed. Falling back to keyword matching."
+            )
+            self.use_embeddings = False
+        except Exception:
+            LOGGER.exception("Failed to initialize SentenceTransformer embeddings.")
+            self.use_embeddings = False
+            self.embedding_model = None
+            self.emotional_embeddings = {}
+            self.rhythm_embeddings = {}
+
+    def detect_emotion_with_groq(self, input_text):
+        if not self.use_groq or not self.groq_client:
+            return None
+
+        prompt = (
+            "Analyze the user's feeling described below.\n"
+            "Identify the single MOST prominent emotional state or intention from the following list:\n"
+            f"{', '.join(self.emotional_states)}\n"
+            "Focus on the core feeling expressed. Respond with ONLY the chosen state/intention from the list.\n"
+            f"User's feeling: \"{input_text}\"\n"
+            "State/Intention:"
+        )
+
+        try:
+            chat_completion = self.groq_client.chat.completions.create(
+                messages=[{"role": "user", "content": prompt}],
+                model="llama-3.3-70b-versatile",
+                max_tokens=15,
+                temperature=0.2,
+                stop=["\n"],
+            )
+            detected_emotion = chat_completion.choices[0].message.content.strip().lower()
+            if detected_emotion in self.emotional_states:
+                return detected_emotion
+            return self.get_closest_emotional_state(detected_emotion)
+        except Exception:
+            LOGGER.exception("Groq emotion detection failed.")
+            return None
+
+    def get_closest_emotional_state(self, input_text):
+        if not input_text:
+            return "neutral"
+
+        input_text_lower = input_text.lower()
+        words = set(input_text_lower.split())
+        for state in self.emotional_states:
+            if state in words or state in input_text_lower:
+                return state
+
+        self._ensure_embeddings_loaded()
+        if self.embedding_model and self.emotional_embeddings:
+            try:
+                input_embedding = self.embedding_model.encode([input_text])[0]
+                return max(
+                    self.emotional_embeddings,
+                    key=lambda state: _cosine_similarity(
+                        input_embedding, self.emotional_embeddings[state]
+                    ),
+                )
+            except Exception:
+                LOGGER.exception("Semantic emotion matching failed.")
+
+        return "neutral"
+
+    def get_closest_rhythm_pattern(self, input_text=None, emotional_state=None):
+        if emotional_state:
+            mapping = {
+                "anxious": "calm",
+                "stressed": "relaxed",
+                "calm": "calm",
+                "sad": "relaxed",
+                "angry": "active",
+                "fearful": "calm",
+                "confused": "focused",
+                "happy": "active",
+                "neutral": "calm",
+                "focused": "focused",
+                "relaxed": "relaxed",
+                "active": "active",
+            }
+            return mapping.get(emotional_state, "calm")
+
+        self._ensure_embeddings_loaded()
+        if input_text and self.embedding_model and self.rhythm_embeddings:
+            try:
+                input_embedding = self.embedding_model.encode([input_text])[0]
+                return max(
+                    self.rhythm_embeddings,
+                    key=lambda pattern: _cosine_similarity(
+                        input_embedding, self.rhythm_embeddings[pattern]
+                    ),
+                )
+            except Exception:
+                LOGGER.exception("Semantic rhythm matching failed.")
+
+        return "calm"
+
+    def transcribe_audio(self, audio_path):
+        if not self.use_groq or not self.groq_client:
+            return None, "Transcription disabled: Groq client not available or API key missing."
+
+        if not audio_path or not os.path.exists(audio_path):
+            return None, "Transcription failed: Audio file path is invalid or missing."
+
+        try:
+            with open(audio_path, "rb") as audio_file:
+                response = self.groq_client.audio.transcriptions.create(
+                    file=(os.path.basename(audio_path), audio_file.read()),
+                    model="whisper-large-v3",
+                    response_format="json",
+                )
+            return response.text, None
+        except Exception as exc:
+            LOGGER.exception("Groq transcription failed.")
+            return None, f"Error during Groq transcription: {exc}"
+
+    def analyze_input(self, input_text=None, audio_path=None):
+        result = AnalysisResult()
+        text_to_analyze = None
+
+        try:
+            if audio_path and self.use_groq:
+                transcribed_text, transcription_error = self.transcribe_audio(audio_path)
+                if transcription_error:
+                    result.error = transcription_error
+                    result.transcription = f"[Transcription Error: {transcription_error}]"
+                elif transcribed_text:
+                    result.transcription = transcribed_text
+                    text_to_analyze = transcribed_text
+
+            if not text_to_analyze and input_text:
+                text_to_analyze = input_text
+
+            if text_to_analyze:
+                detected_emotion = None
+                if self.use_groq:
+                    detected_emotion = self.detect_emotion_with_groq(text_to_analyze)
+
+                result.emotional_state = detected_emotion or self.get_closest_emotional_state(
+                    text_to_analyze
+                )
+            else:
+                result.emotional_state = "neutral"
+
+            result.rhythm_pattern = self.get_closest_rhythm_pattern(
+                input_text=text_to_analyze,
+                emotional_state=result.emotional_state,
+            )
+        except Exception as exc:
+            LOGGER.exception("Unexpected error during input analysis.")
+            result = AnalysisResult(
+                transcription=result.transcription,
+                error=f"Unexpected error during input analysis: {exc}",
+            )
+
+        return result.to_dict()

rhythma_engine.py

@@ -0,0 +1,377 @@
+import io
+import logging
+
+import matplotlib.pyplot as plt
+import numpy as np
+from PIL import Image
+from scipy import signal
+
+try:
+    import soundfile as sf
+
+    SOUNDFILE_AVAILABLE = True
+except ImportError:
+    sf = None
+    SOUNDFILE_AVAILABLE = False
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+class RhythmaModulationEngine:
+    """
+    Dynamic rhythm-based audio modulation engine.
+    """
+
+    SAMPLE_RATE = 44100
+    EMOTIONAL_FREQUENCIES = {
+        "anxious": 396,
+        "stressed": 528,
+        "calm": 741,
+        "sad": 417,
+        "angry": 852,
+        "fearful": 639,
+        "confused": 285,
+        "happy": 432,
+        "neutral": 440,
+        "focused": 639,
+        "relaxed": 741,
+        "active": 528,
+    }
+    EMOTIONAL_INFO = {
+        "anxious": {
+            "name": "Liberating Guilt and Fear",
+            "advice": "The 396 Hz frequency may help release fear and guilt.",
+        },
+        "stressed": {
+            "name": "Transformation and Miracles",
+            "advice": "The 528 Hz frequency is associated with transformation.",
+        },
+        "calm": {
+            "name": "Awakening Intuition",
+            "advice": "The 741 Hz frequency is associated with awakening intuition.",
+        },
+        "sad": {
+            "name": "Facilitating Change",
+            "advice": "The 417 Hz frequency is linked to facilitating change.",
+        },
+        "angry": {
+            "name": "Returning to Spiritual Order",
+            "advice": "The 852 Hz frequency may aid in returning to inner strength.",
+        },
+        "fearful": {
+            "name": "Connecting Relationships",
+            "advice": "The 639 Hz frequency is associated with connecting relationships.",
+        },
+        "confused": {
+            "name": "Quantum Cognition",
+            "advice": "The 285 Hz frequency is believed to influence energy fields.",
+        },
+        "happy": {
+            "name": "Harmonizing Vibrations",
+            "advice": "The 432 Hz frequency is associated with natural harmony.",
+        },
+        "neutral": {
+            "name": "Grounded Presence",
+            "advice": "The 440 Hz frequency provides a stable reference point.",
+        },
+        "focused": {
+            "name": "Clarity and Connection",
+            "advice": "The 639 Hz frequency may support focus and understanding.",
+        },
+        "relaxed": {
+            "name": "Intuitive Calm",
+            "advice": "The 741 Hz frequency is linked to intuitive states and problem-solving.",
+        },
+        "active": {
+            "name": "Dynamic Energy",
+            "advice": "The 528 Hz frequency is associated with positive transformation.",
+        },
+    }
+    RHYTHM_CONFIGS = {
+        "calm": {
+            "mod_depth": 0.15,
+            "mod_freq": 0.5,
+            "pulse_width": 0.7,
+            "phase_shift": 0.1,
+            "harmonics": [1.0, 0.5, 0.25, 0.125],
+        },
+        "active": {
+            "mod_depth": 0.4,
+            "mod_freq": 2.5,
+            "pulse_width": 0.3,
+            "phase_shift": 0.3,
+            "harmonics": [1.0, 0.7, 0.5, 0.3],
+        },
+        "focused": {
+            "mod_depth": 0.25,
+            "mod_freq": 1.5,
+            "pulse_width": 0.5,
+            "phase_shift": 0.2,
+            "harmonics": [1.0, 0.6, 0.3, 0.15],
+        },
+        "relaxed": {
+            "mod_depth": 0.2,
+            "mod_freq": 0.3,
+            "pulse_width": 0.8,
+            "phase_shift": 0.05,
+            "harmonics": [1.0, 0.4, 0.2, 0.1],
+        },
+    }
+    SYMBOLIC_MAPPING = {
+        "calm": "Resonating in the Circle Archetype: completion, wholeness, presence",
+        "active": "Resonating in the Spiral Archetype: flow, transition, emergence",
+        "focused": "Resonating in the Triangle Archetype: clarity, direction, purpose",
+        "relaxed": "Resonating in the Wave Archetype: fluidity, acceptance, surrender",
+    }
+
+    def __init__(
+        self,
+        base_freq=None,
+        modulation_type="sine",
+        rhythm_pattern=None,
+        emotional_state=None,
+    ):
+        self.modulation_type = modulation_type
+        self.sample_rate = self.SAMPLE_RATE
+        self.emotional_frequencies = self.EMOTIONAL_FREQUENCIES
+        self.emotional_info = self.EMOTIONAL_INFO
+        self.rhythm_configs = self.RHYTHM_CONFIGS
+        self.symbolic_mapping = self.SYMBOLIC_MAPPING
+
+        valid_emotional_state = (
+            emotional_state
+            if emotional_state and emotional_state in self.emotional_frequencies
+            else None
+        )
+        self.emotional_state = valid_emotional_state
+
+        if self.emotional_state:
+            self.base_freq = self.emotional_frequencies[self.emotional_state]
+        elif base_freq and base_freq > 0:
+            self.base_freq = base_freq
+            self.emotional_state = self._find_closest_state(base_freq)
+        else:
+            self.emotional_state = "neutral"
+            self.base_freq = self.emotional_frequencies[self.emotional_state]
+
+        valid_rhythm_pattern = (
+            rhythm_pattern if rhythm_pattern and rhythm_pattern in self.rhythm_configs else None
+        )
+        self.rhythm_pattern = valid_rhythm_pattern or "calm"
+        self.config = self.rhythm_configs[self.rhythm_pattern]
+
+    def _find_closest_state(self, base_freq):
+        min_diff = float("inf")
+        closest_state = None
+        for state, freq in self.emotional_frequencies.items():
+            diff = abs(freq - base_freq)
+            if diff < min_diff:
+                min_diff = diff
+                closest_state = state
+        return closest_state if min_diff <= 10 else None
+
+    def _generate_base_wave(self, duration):
+        t = np.linspace(0, duration, int(self.sample_rate * duration), endpoint=False)
+        base_wave = np.sin(2 * np.pi * self.base_freq * t)
+
+        rich_wave = np.zeros_like(base_wave)
+        for index, harmonic_amp in enumerate(self.config["harmonics"], start=1):
+            harmonic_freq = self.base_freq * index
+            if harmonic_freq < self.sample_rate / 2:
+                rich_wave += harmonic_amp * np.sin(2 * np.pi * harmonic_freq * t)
+
+        if np.max(np.abs(rich_wave)) > 0:
+            rich_wave = rich_wave / np.max(np.abs(rich_wave))
+        else:
+            rich_wave = base_wave
+
+        return t, rich_wave
+
+    def _apply_sine_modulation(self, t, carrier):
+        mod_env = 1.0 + self.config["mod_depth"] * np.sin(
+            2 * np.pi * self.config["mod_freq"] * t + self.config["phase_shift"]
+        )
+        return carrier * mod_env
+
+    def _apply_pulse_modulation(self, t, carrier):
+        pulse = 0.5 * (
+            signal.square(
+                2 * np.pi * self.config["mod_freq"] * t,
+                duty=self.config["pulse_width"],
+            )
+            + 1
+        )
+        mod_env = 1.0 - self.config["mod_depth"] + self.config["mod_depth"] * pulse
+        return carrier * mod_env
+
+    def _apply_chirp_modulation(self, t, carrier):
+        start_mod_freq = max(0.1, self.config["mod_freq"] / 2)
+        end_mod_freq = self.config["mod_freq"] * 2
+        instantaneous_mod_freq = np.linspace(start_mod_freq, end_mod_freq, len(t))
+        phase = 2 * np.pi * np.cumsum(instantaneous_mod_freq) / self.sample_rate
+        mod_env = 1.0 + self.config["mod_depth"] * np.sin(
+            phase + self.config["phase_shift"]
+        )
+        return carrier * mod_env
+
+    def generate_modulated_wave(self, duration):
+        t, base_carrier = self._generate_base_wave(duration)
+
+        if self.modulation_type == "sine":
+            modulated = self._apply_sine_modulation(t, base_carrier)
+        elif self.modulation_type == "pulse":
+            modulated = self._apply_pulse_modulation(t, base_carrier)
+        elif self.modulation_type == "chirp":
+            modulated = self._apply_chirp_modulation(t, base_carrier)
+        else:
+            modulated = base_carrier
+
+        max_amp = np.max(np.abs(modulated))
+        if max_amp <= 0:
+            return modulated
+        return 0.9 * modulated / max_amp
+
+    def save_audio(self, duration, file_path=None):
+        if not SOUNDFILE_AVAILABLE:
+            LOGGER.error("soundfile is not installed; audio export is unavailable.")
+            return None
+
+        audio = self.generate_modulated_wave(duration)
+        output_path = file_path or f"rhythma_{self.base_freq}Hz_{self.rhythm_pattern}.wav"
+        try:
+            sf.write(output_path, audio, self.sample_rate)
+            LOGGER.info("Audio saved to %s", output_path)
+            return output_path
+        except Exception:
+            LOGGER.exception("Failed to save audio to %s", output_path)
+            return None
+
+    def visualize_waveform(self, duration):
+        vis_duration = min(duration, 0.5)
+        plot_samples = int(self.sample_rate * vis_duration)
+        t = np.linspace(0, vis_duration, plot_samples, endpoint=False)
+        modulated = self.generate_modulated_wave(vis_duration)
+
+        fig, (ax1, ax2) = plt.subplots(
+            2, 1, figsize=(10, 6), gridspec_kw={"height_ratios": [1, 1]}
+        )
+
+        zoom_samples = min(plot_samples, 2000)
+        ax1.plot(t[:zoom_samples], modulated[:zoom_samples])
+        title = (
+            f"Rhythma Waveform: {self.rhythm_pattern.capitalize()} "
+            f"({self.modulation_type.capitalize()})"
+        )
+        if self.emotional_state:
+            title += f" - {self.emotional_state.capitalize()} ({self.base_freq} Hz)"
+        else:
+            title += f" - {self.base_freq} Hz"
+        ax1.set_title(title)
+        ax1.set_xlabel("Time (s)")
+        ax1.set_ylabel("Amplitude")
+        ax1.grid(True)
+
+        try:
+            full_wave = self.generate_modulated_wave(duration)
+            freqs, times, spectrogram = signal.spectrogram(
+                full_wave, self.sample_rate, nperseg=1024
+            )
+            freq_limit_idx = np.where(freqs >= 2000)[0]
+            if len(freq_limit_idx) > 0:
+                cutoff = freq_limit_idx[0]
+                freqs = freqs[:cutoff]
+                spectrogram = spectrogram[:cutoff, :]
+
+            pcm = ax2.pcolormesh(
+                times,
+                freqs,
+                10 * np.log10(spectrogram + 1e-9),
+                shading="gouraud",
+                cmap="viridis",
+            )
+            fig.colorbar(pcm, ax=ax2, label="Power (dB)")
+            ax2.set_ylabel("Frequency (Hz)")
+            ax2.set_xlabel("Time (s)")
+            ax2.set_title("Spectrogram")
+        except Exception:
+            LOGGER.exception("Failed to generate spectrogram.")
+            ax2.set_title("Spectrogram (Error)")
+            ax2.text(
+                0.5,
+                0.5,
+                "Could not generate spectrogram",
+                horizontalalignment="center",
+                verticalalignment="center",
+                transform=ax2.transAxes,
+            )
+
+        plt.tight_layout(rect=[0, 0.05, 1, 1])
+
+        fig_text = self.get_symbolic_interpretation()
+        emotion_info = self.emotional_info.get(self.emotional_state, {})
+        if emotion_info:
+            fig_text += (
+                f"\n{self.base_freq} Hz - {emotion_info.get('name', '')}: "
+                f"{emotion_info.get('advice', '')}"
+            )
+        elif not self.emotional_state:
+            fig_text += f"\nBase Frequency: {self.base_freq} Hz"
+
+        fig.text(0.5, 0.01, fig_text, ha="center", va="bottom", fontsize=9, style="italic", wrap=True)
+        return fig
+
+    def get_waveform_image(self):
+        duration = 0.05
+        t = np.linspace(0, duration, int(self.sample_rate * duration), False)
+        tone = np.sin(2 * np.pi * self.base_freq * t)
+
+        plt.figure(figsize=(6, 2))
+        plt.plot(t, tone)
+        plt.xlabel("Time (s)")
+        plt.ylabel("Amplitude")
+        plt.ylim(-1.1, 1.1)
+        plt.grid(True)
+        plt.tight_layout()
+
+        buffer = io.BytesIO()
+        plt.savefig(buffer, format="png", bbox_inches="tight")
+        buffer.seek(0)
+        plt.close()
+        return Image.open(buffer)
+
+    def get_symbolic_interpretation(self):
+        return self.symbolic_mapping.get(
+            self.rhythm_pattern, "Pattern Interpretation: Default"
+        )
+
+    def get_emotional_advice(self):
+        if not self.emotional_state:
+            return "No specific emotional state identified."
+        return self.emotional_info.get(self.emotional_state, {}).get(
+            "advice", "General well-being advice applies."
+        )
+
+    def get_complete_analysis(self):
+        analysis = []
+
+        if self.emotional_state:
+            emotion_info = self.emotional_info.get(self.emotional_state, {})
+            analysis.append(f"Detected State/Intention: {self.emotional_state.capitalize()}")
+            analysis.append(
+                f"Resonant Frequency: {self.base_freq} Hz - "
+                f"{emotion_info.get('name', 'Frequency Information')}"
+            )
+            analysis.append(
+                f"Guidance: {emotion_info.get('advice', 'Focus on the sound.')}"
+            )
+        else:
+            analysis.append(f"Using Manual Frequency: {self.base_freq} Hz")
+            analysis.append("Guidance: Tune into the custom frequency.")
+
+        analysis.append(f"Rhythm Pattern: {self.rhythm_pattern.capitalize()}")
+        analysis.append(
+            f"Symbolic Interpretation: {self.get_symbolic_interpretation()}"
+        )
+        analysis.append(f"Modulation Type: {self.modulation_type.capitalize()}")
+        return "\n\n".join(analysis)

tests/test_rhythma_regression.py

@@ -0,0 +1,34 @@
+import numpy as np
+from rhythma import RhythmaModulationEngine, RhythmaSymphAICore
+
+
+def test_analyze_input_maps_stressed_text_to_relaxed_pattern():
+    core = RhythmaSymphAICore(use_groq=False, use_embeddings=False)
+
+    result = core.analyze_input("feeling stressed about work")
+
+    assert result["emotional_state"] == "stressed"
+    assert result["rhythm_pattern"] == "relaxed"
+    assert result["transcription"] == ""
+    assert result["error"] is None
+
+
+def test_analyze_input_defaults_to_neutral_when_no_text_is_provided():
+    core = RhythmaSymphAICore(use_groq=False, use_embeddings=False)
+
+    result = core.analyze_input("")
+
+    assert result["emotional_state"] == "neutral"
+    assert result["rhythm_pattern"] == "calm"
+    assert result["transcription"] == ""
+    assert result["error"] is None
+
+
+def test_generate_modulated_wave_has_expected_length_and_headroom():
+    engine = RhythmaModulationEngine(emotional_state="stressed")
+
+    wave = engine.generate_modulated_wave(0.1)
+
+    assert len(wave) == 4410
+    assert np.max(np.abs(wave)) <= 0.9 + 1e-9
+    assert engine.get_symbolic_interpretation().startswith("Resonating in the Circle")