feat: remix engine routes dream analysis servisleri ve dataset organization utilities eklendi

app/main.py

@@ -16,6 +16,8 @@ from .routes.data_processing import router as data_processing_router
 from .routes.analyze import router as analyze_router
 from .routes.commend import router as commend_router
 from .routes.reservations import router as reservations_router
+from .routes.dreams import router as dreams_router
+from .routes.remix import router as remix_router
 from .services.logging_config import setup_logging, get_logger
 
 
@@ -89,6 +91,7 @@ app.add_middleware(
     allow_credentials="*" not in _origins,
     allow_methods=["GET", "POST", "OPTIONS"],
     allow_headers=["Content-Type", "Accept"],
+    expose_headers=["X-Remix-Analysis"],
 )
 
 app.include_router(health_router)
@@ -97,5 +100,7 @@ app.include_router(data_processing_router)
 app.include_router(analyze_router)
 app.include_router(commend_router)
 app.include_router(reservations_router)
+app.include_router(dreams_router)
+app.include_router(remix_router)
 
 logger.info("CrownCode backend API initialized")

app/routes/commend/gemini_service.py

@@ -115,7 +115,12 @@ Comment:"""
         logger.error(f"Generate error: {e}")
         err = str(e).lower()
 
-        if "api key" in err:
+        # Match "api key" / "api_key" / "apikey" — the local ValueError from
+        # _get_client() reads "..._API_KEY required" (underscore), which the
+        # space-only check below never matched, so a missing key fell
+        # through to the generic "Generation failed" message instead of
+        # "Invalid API key".
+        if "api key" in err or "api_key" in err or "apikey" in err:
             return None, "Invalid API key"
         elif "quota" in err or "limit" in err or "resource" in err:
             return None, "API quota exceeded"

app/routes/dreams.py

@@ -0,0 +1,67 @@
+"""
+Routes for Crown Dreams — real AI-powered dream analysis.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+
+from app.schemas import DreamAnalysisRequest, DreamAnalysisResponse
+from app.services.dream_analyzer import analyze_dream
+from app.services.logging_config import get_logger
+
+router = APIRouter(prefix="/api/dreams", tags=["Dreams"])
+logger = get_logger(__name__)
+
+# Same bounded in-memory rate limiter pattern used by data_processing.py
+# and commend/router.py — one call to an LLM per request is expensive
+# enough to need this even for a read-only analysis endpoint.
+_rate_store: dict[str, list[float]] = defaultdict(list)
+_RATE_WINDOW = 60
+_RATE_MAX = 8
+_MAX_TRACKED_IPS = 10_000
+
+
+async def _rate_limit(request: Request) -> None:
+    client_ip = request.client.host if request.client else "unknown"
+    now = time.time()
+    cutoff = now - _RATE_WINDOW
+
+    if len(_rate_store) > _MAX_TRACKED_IPS:
+        stale = [ip for ip, ts in _rate_store.items() if not ts or all(t <= cutoff for t in ts)]
+        for ip in stale:
+            del _rate_store[ip]
+
+    hits = [t for t in _rate_store[client_ip] if t > cutoff]
+    if len(hits) >= _RATE_MAX:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail={"code": "rate_limit_exceeded", "message": "Too many analysis requests. Please wait."},
+        )
+    hits.append(now)
+    _rate_store[client_ip] = hits
+
+
+@router.post("/analyze", response_model=DreamAnalysisResponse, dependencies=[Depends(_rate_limit)])
+async def analyze_dream_endpoint(payload: DreamAnalysisRequest) -> DreamAnalysisResponse:
+    """
+    Analyze a user-submitted dream description with Gemini: detected
+    emotions, themes, recurring symbols, and a grounded interpretation.
+    """
+    logger.info(f"Dream analysis request ({len(payload.dream_text)} chars, lang={payload.language})")
+
+    result, error = analyze_dream(payload.dream_text, payload.language)
+
+    if error is not None:
+        if "too short" in error.lower():
+            raise HTTPException(status_code=400, detail={"code": "dream_too_short", "message": error})
+        if "api key" in error.lower():
+            raise HTTPException(status_code=503, detail={"code": "service_not_configured", "message": "Dream analysis is not configured."})
+        if "quota" in error.lower():
+            raise HTTPException(status_code=503, detail={"code": "service_unavailable", "message": error})
+        raise HTTPException(status_code=502, detail={"code": "analysis_failed", "message": error})
+
+    return DreamAnalysisResponse(**result)

app/routes/remix.py

@@ -0,0 +1,120 @@
+"""
+Routes for the Creator Studio AI Remix engine.
+"""
+
+import json
+import logging
+import time
+from collections import defaultdict
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile, status
+from fastapi.responses import StreamingResponse
+from pydantic import ValidationError
+
+from app.schemas import RemixOptions
+from app.services.remix_engine import build_remix
+
+router = APIRouter(prefix="/api/remix", tags=["Creator Studio"])
+logger = logging.getLogger(__name__)
+
+# Same sliding-window rate limiter pattern as data_processing.py — remixing
+# is CPU-heavy (two beat-tracking passes plus a phase-vocoder stretch), so it
+# gets its own store rather than sharing the general processing budget.
+_remix_rate_store: dict[str, list[float]] = defaultdict(list)
+_REMIX_RATE_WINDOW = 60
+_REMIX_RATE_MAX = 6
+_REMIX_MAX_IPS = 10_000
+
+
+async def _remix_rate_limit(request: Request) -> None:
+    client_ip = request.client.host if request.client else "unknown"
+    now = time.time()
+    cutoff = now - _REMIX_RATE_WINDOW
+
+    if len(_remix_rate_store) > _REMIX_MAX_IPS:
+        stale = [ip for ip, ts in _remix_rate_store.items() if not ts or all(t <= cutoff for t in ts)]
+        for ip in stale:
+            del _remix_rate_store[ip]
+
+    hits = [t for t in _remix_rate_store[client_ip] if t > cutoff]
+    if len(hits) >= _REMIX_RATE_MAX:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail={"code": "rate_limit_exceeded", "message": "Too many remix requests. Please wait."},
+        )
+    hits.append(now)
+    _remix_rate_store[client_ip] = hits
+
+
+async def _read_capped(file: UploadFile, max_bytes: int) -> bytes:
+    chunks = []
+    total_read = 0
+    chunk_size = 1024 * 1024
+    while True:
+        chunk = await file.read(chunk_size)
+        if not chunk:
+            break
+        total_read += len(chunk)
+        if total_read > max_bytes:
+            raise HTTPException(
+                status_code=413,
+                detail={"code": "file_too_large", "message": f"File too large. Maximum size is {max_bytes // (1024*1024)} MB."},
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+@router.post("/blend", dependencies=[Depends(_remix_rate_limit)])
+async def remix_blend_endpoint(
+    track_a: UploadFile = File(...),
+    track_b: UploadFile = File(...),
+    options: str = Form(default="{}"),
+):
+    """
+    Blend two uploaded tracks into one: detects real BPM/key for each,
+    optionally time-stretches/pitch-shifts track B to match track A, and
+    crossfades them together. Returns the mixed WAV plus the detected
+    analysis in the X-Remix-Analysis response header (JSON) so the caller
+    gets both the audio and the real numbers behind it in one round trip.
+    """
+    MAX_PAYLOAD_BYTES = 30 * 1024 * 1024  # 30 MB per track
+    logger.info(f"Received remix blend request: {track_a.filename} + {track_b.filename}")
+
+    raw_options = options.strip() if options else "{}"
+    if not raw_options:
+        raw_options = "{}"
+    try:
+        parsed_options = RemixOptions.model_validate_json(raw_options)
+    except (ValidationError, json.JSONDecodeError) as e:
+        raise HTTPException(status_code=422, detail={"code": "invalid_options", "message": f"Invalid options format: {e}"})
+
+    for f, label in ((track_a, "track_a"), (track_b, "track_b")):
+        if not f.content_type or not f.content_type.startswith("audio/"):
+            raise HTTPException(
+                status_code=400,
+                detail={"code": "invalid_file_type", "message": f"Invalid file type for {label}. Must be audio."},
+            )
+
+    try:
+        content_a = await _read_capped(track_a, MAX_PAYLOAD_BYTES)
+        content_b = await _read_capped(track_b, MAX_PAYLOAD_BYTES)
+
+        result = build_remix(content_a, content_b, parsed_options)
+
+        analysis_json = json.dumps(result.analysis)
+        return StreamingResponse(
+            result.audio,
+            media_type="audio/wav",
+            headers={
+                "Content-Disposition": "attachment; filename=crowncode-remix.wav",
+                "X-Remix-Analysis": analysis_json,
+            },
+        )
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail={"code": "validation_error", "message": str(e)})
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error in remix blend: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during remix"})

app/schemas.py

@@ -89,3 +89,62 @@ class DatasetEntryMetadata(BaseModel):
     key: str
     loudness_db: float = Field(alias="loudnessDb")
     tags: List[str]
+
+
+class DreamAnalysisRequest(BaseModel):
+    dream_text: str = Field(..., alias="dreamText", min_length=1, max_length=4000)
+    language: str = Field(default="English", description="Output language for the interpretation")
+
+    model_config = {"populate_by_name": True}
+
+
+class DreamAnalysisResponse(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    emotions: List[str]
+    themes: List[str]
+    symbols: List[str]
+    interpretation: str
+    lucidity_indicator: bool = Field(alias="lucidityIndicator")
+
+
+RemixCrossfadeCurve = Literal["equal_power", "linear"]
+
+
+class RemixOptions(BaseModel):
+    """Options for the Creator Studio AI Remix engine — auto tempo/key
+    matching plus a crossfade blend between two uploaded tracks."""
+
+    model_config = {"populate_by_name": True}
+
+    match_tempo: bool = Field(
+        default=True, alias="matchTempo",
+        description="Time-stretch the second track to the first track's detected BPM"
+    )
+    match_key: bool = Field(
+        default=False, alias="matchKey",
+        description="Pitch-shift the second track to the first track's detected key"
+    )
+    crossfade_seconds: float = Field(
+        default=4.0, alias="crossfadeSeconds", ge=0.5, le=30.0,
+        description="Length of the crossfade transition between the two tracks"
+    )
+    crossfade_curve: RemixCrossfadeCurve = Field(
+        default="equal_power", alias="crossfadeCurve",
+        description="Crossfade power curve — equal_power avoids a volume dip at the midpoint"
+    )
+
+
+class RemixAnalysis(BaseModel):
+    """Reports what the remix engine actually detected/did to each track,
+    so the UI can show real numbers instead of a black box."""
+
+    model_config = {"populate_by_name": True}
+
+    track_a_bpm: float = Field(alias="trackABpm")
+    track_b_bpm: float = Field(alias="trackBBpm")
+    track_a_key: str = Field(alias="trackAKey")
+    track_b_key: str = Field(alias="trackBKey")
+    applied_stretch_rate: float = Field(alias="appliedStretchRate")
+    applied_pitch_shift_semitones: float = Field(alias="appliedPitchShiftSemitones")
+    output_duration_sec: float = Field(alias="outputDurationSec")

app/services/dataset_organizer.py

@@ -18,7 +18,7 @@ import numpy as np
 
 logger = logging.getLogger(__name__)
 
-_PITCH_CLASSES = [
+PITCH_CLASSES = [
     "C", "C#", "D", "D#", "E", "F",
     "F#", "G", "G#", "A", "A#", "B",
 ]
@@ -33,7 +33,7 @@ _MINOR_PROFILE = np.array(
 )
 
 
-def _detect_key(chroma_mean: np.ndarray) -> str:
+def detect_key(chroma_mean: np.ndarray) -> str:
     """Correlate the mean chroma vector against all 24 rotated key profiles."""
     best_score = -np.inf
     best_key = "C major"
@@ -44,10 +44,10 @@ def _detect_key(chroma_mean: np.ndarray) -> str:
         minor_score = float(np.corrcoef(chroma_mean, minor_rot)[0, 1])
         if major_score > best_score:
             best_score = major_score
-            best_key = f"{_PITCH_CLASSES[shift]} major"
+            best_key = f"{PITCH_CLASSES[shift]} major"
         if minor_score > best_score:
             best_score = minor_score
-            best_key = f"{_PITCH_CLASSES[shift]} minor"
+            best_key = f"{PITCH_CLASSES[shift]} minor"
     return best_key
 
 
@@ -141,7 +141,7 @@ def analyze_for_organization(file_bytes: bytes) -> DatasetEntryMetadata:
     tempo_bpm = round(float(np.atleast_1d(tempo)[0]), 1)
 
     chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
-    key = _detect_key(np.mean(chroma, axis=1))
+    key = detect_key(np.mean(chroma, axis=1))
 
     loudness_db = _loudness_lufs_approx(y)
     rms_mean = float(np.mean(librosa.feature.rms(y=y)[0]))

app/services/dream_analyzer.py

@@ -0,0 +1,139 @@
+"""
+Dream Analysis Service — real Gemini-powered analysis of a user-submitted
+dream description: detected emotions, recurring symbols, likely themes,
+and a genuine interpretive summary.
+
+Mirrors the established Gemini client pattern from
+app/routes/commend/gemini_service.py (same lazy client, same env var
+naming convention, same error classification) rather than inventing a
+second way to talk to the same API.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from google import genai
+
+from .logging_config import get_logger
+
+logger = get_logger(__name__)
+
+_client = None
+
+_MAX_DREAM_CHARS = 4000
+_MIN_DREAM_CHARS = 10
+
+
+def _get_client():
+    global _client
+    if _client is not None:
+        return _client
+
+    api_key = os.getenv("DREAMS_GEMINI_API_KEY") or os.getenv("COMMEND_GEMINI_API_KEY")
+    if not api_key:
+        raise ValueError("DREAMS_GEMINI_API_KEY (or COMMEND_GEMINI_API_KEY) required")
+
+    try:
+        _client = genai.Client(api_key=api_key)
+        logger.info("Gemini initialized for dream analysis")
+        return _client
+    except Exception as e:
+        logger.error(f"Gemini init failed: {e}")
+        raise ValueError(f"Gemini failed: {e}")
+
+
+_ALLOWED_EMOTIONS = {
+    "joy", "fear", "anxiety", "sadness", "anger", "confusion",
+    "peace", "excitement", "nostalgia", "wonder", "shame", "love",
+}
+
+
+def _extract_json(text: str) -> Optional[Dict[str, Any]]:
+    """Gemini sometimes wraps JSON in a ```json fence despite instructions
+    not to — strip that before parsing rather than fail the whole request."""
+    cleaned = text.strip()
+    fence_match = re.match(r"^```(?:json)?\s*(.*?)\s*```$", cleaned, re.DOTALL)
+    if fence_match:
+        cleaned = fence_match.group(1)
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        return None
+
+
+def analyze_dream(
+    dream_text: str,
+    language: str = "English",
+) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """
+    Analyze a dream description and return structured findings:
+    {
+      "emotions": ["fear", "wonder"],
+      "themes": ["falling", "being chased"],
+      "symbols": ["water", "flying"],
+      "interpretation": "...",
+      "lucidityIndicator": bool
+    }
+    Returns (result, None) on success or (None, error_message) on failure.
+    """
+    text = dream_text.strip()
+    if len(text) < _MIN_DREAM_CHARS:
+        return None, "Dream description is too short to analyze."
+    if len(text) > _MAX_DREAM_CHARS:
+        text = text[:_MAX_DREAM_CHARS]
+
+    try:
+        client = _get_client()
+
+        prompt = f"""You are a dream analyst. Analyze this dream description and respond with ONLY a raw JSON object (no markdown fence, no commentary) with this exact shape:
+{{"emotions": string[] (2-4 items from: joy, fear, anxiety, sadness, anger, confusion, peace, excitement, nostalgia, wonder, shame, love), "themes": string[] (1-3 short phrases describing narrative themes, e.g. "being chased", "falling", "losing teeth"), "symbols": string[] (1-4 concrete recurring symbols/objects mentioned or implied, e.g. "water", "flying", "a locked door"), "interpretation": string (2-3 sentences, a grounded psychological reading, not mystical fortune-telling, in {language}), "lucidityIndicator": boolean (true only if the dreamer describes realizing they were dreaming)}}
+
+Dream description:
+{text}
+
+JSON:"""
+
+        response = client.models.generate_content(
+            model="gemini-2.5-flash-lite",
+            contents=prompt,
+        )
+
+        raw = response.text.strip() if response.text else ""
+        parsed = _extract_json(raw)
+        if parsed is None:
+            logger.error(f"Dream analysis returned non-JSON: {raw[:200]}")
+            return None, "Analysis produced an unexpected response format."
+
+        emotions = [e for e in parsed.get("emotions", []) if e in _ALLOWED_EMOTIONS][:4]
+        themes = [str(t)[:60] for t in parsed.get("themes", [])][:3]
+        symbols = [str(s)[:40] for s in parsed.get("symbols", [])][:4]
+        interpretation = str(parsed.get("interpretation", ""))[:800]
+        lucidity_indicator = bool(parsed.get("lucidityIndicator", False))
+
+        if not emotions or not interpretation:
+            return None, "Analysis was incomplete. Please try again."
+
+        return {
+            "emotions": emotions,
+            "themes": themes,
+            "symbols": symbols,
+            "interpretation": interpretation,
+            "lucidityIndicator": lucidity_indicator,
+        }, None
+
+    except Exception as e:
+        logger.error(f"Dream analysis error: {e}")
+        err = str(e).lower()
+        # Match "api key", "api_key", and "apikey" — the local ValueError
+        # from _get_client() reads "..._api_key required" (underscore), and
+        # Gemini's own errors tend to read "API key not valid" (space), so
+        # a plain substring check on either form alone misses the other.
+        if "api key" in err or "api_key" in err or "apikey" in err:
+            return None, "Invalid API key"
+        if "quota" in err or "limit" in err or "resource" in err:
+            return None, "API quota exceeded"
+        return None, f"Analysis failed: {str(e)}"

app/services/remix_engine.py

@@ -0,0 +1,136 @@
+"""
+Creator Studio AI Remix engine — real DSP, not a mock.
+
+Takes two uploaded tracks, detects each one's tempo (via librosa beat
+tracking) and musical key (via the same Krumhansl-Schmuckler chroma
+correlation used by dataset_organizer.py), time-stretches/pitch-shifts the
+second track to match the first, and blends them with a crossfade so the
+end of track A overlaps into the start of track B.
+
+This is deliberately a "remix as a smooth two-track blend" rather than a
+full beat-synced stem remix (that needs source separation, which this
+codebase doesn't ship) — but every number it reports (BPM, key, applied
+stretch rate) comes from real analysis of the real uploaded audio.
+"""
+
+import io
+import logging
+
+import librosa
+import numpy as np
+import soundfile as sf
+
+from app.schemas import RemixOptions
+from app.services.dataset_organizer import PITCH_CLASSES, detect_key
+
+logger = logging.getLogger(__name__)
+
+_MAX_STRETCH_RATE = 1.6
+_MIN_STRETCH_RATE = 0.625  # 1 / _MAX_STRETCH_RATE, kept symmetric in log-space
+
+
+class RemixResult:
+    """Plain result container, mirroring DatasetEntryMetadata's pattern —
+    keeps this module free of a pydantic dependency."""
+
+    def __init__(self, audio: io.BytesIO, analysis: dict) -> None:
+        self.audio = audio
+        self.analysis = analysis
+
+
+def _analyze_track(y: np.ndarray, sr: int) -> tuple[float, str]:
+    tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
+    bpm = round(float(np.atleast_1d(tempo)[0]), 1)
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+    key = detect_key(np.mean(chroma, axis=1))
+    return bpm, key
+
+
+def _key_root_index(key: str) -> int:
+    root = key.split(" ")[0]
+    return PITCH_CLASSES.index(root) if root in PITCH_CLASSES else 0
+
+
+def _semitone_distance(from_key: str, to_key: str) -> float:
+    """Shortest signed semitone distance between two detected keys' roots,
+    e.g. "C major" -> "A major" is -3 (down 3), not +9 (up 9)."""
+    diff = (_key_root_index(to_key) - _key_root_index(from_key)) % 12
+    if diff > 6:
+        diff -= 12
+    return float(diff)
+
+
+def build_remix(
+    track_a_bytes: bytes,
+    track_b_bytes: bytes,
+    options: RemixOptions,
+) -> RemixResult:
+    try:
+        y_a, sr = librosa.load(io.BytesIO(track_a_bytes), sr=22050, mono=True)
+        y_b, _ = librosa.load(io.BytesIO(track_b_bytes), sr=sr, mono=True)
+    except Exception as e:
+        logger.error(f"Failed to load audio for remix: {e}", exc_info=True)
+        raise ValueError(f"Could not read audio file: {e}")
+
+    if y_a.size == 0 or float(np.max(np.abs(y_a))) < 1e-6:
+        raise ValueError("Track A is empty or silent")
+    if y_b.size == 0 or float(np.max(np.abs(y_b))) < 1e-6:
+        raise ValueError("Track B is empty or silent")
+
+    bpm_a, key_a = _analyze_track(y_a, sr)
+    bpm_b, key_b = _analyze_track(y_b, sr)
+
+    applied_rate = 1.0
+    if options.match_tempo and bpm_a >= 1 and bpm_b >= 1:
+        raw_rate = bpm_b / bpm_a
+        # Clamp to a musically sane range — librosa's phase vocoder degrades
+        # badly outside roughly 0.6x-1.6x, and a tempo detector octave error
+        # (BPM doubled/halved) would otherwise send this to an extreme.
+        applied_rate = float(np.clip(raw_rate, _MIN_STRETCH_RATE, _MAX_STRETCH_RATE))
+        y_b = librosa.effects.time_stretch(y_b, rate=applied_rate)
+        logger.info(f"Remix: stretched track B by {applied_rate:.3f}x ({bpm_b}->{bpm_a} bpm)")
+
+    applied_semitones = 0.0
+    if options.match_key:
+        applied_semitones = _semitone_distance(key_b, key_a)
+        if abs(applied_semitones) > 0.01:
+            y_b = librosa.effects.pitch_shift(y_b, sr=sr, n_steps=applied_semitones)
+            logger.info(f"Remix: pitch-shifted track B by {applied_semitones:+.1f} semitones ({key_b}->{key_a})")
+
+    crossfade_samples = int(options.crossfade_seconds * sr)
+    crossfade_samples = min(crossfade_samples, len(y_a), len(y_b))
+
+    if crossfade_samples <= 0:
+        # No usable overlap — just concatenate.
+        mixed = np.concatenate([y_a, y_b])
+    else:
+        t = np.linspace(0.0, 1.0, crossfade_samples, dtype=np.float64)
+        if options.crossfade_curve == "equal_power":
+            fade_out = np.cos(t * np.pi / 2)
+            fade_in = np.sin(t * np.pi / 2)
+        else:
+            fade_out = 1.0 - t
+            fade_in = t
+
+        head = y_a[:-crossfade_samples]
+        tail_a = y_a[-crossfade_samples:]
+        overlap = tail_a * fade_out.astype(np.float32) + y_b[:crossfade_samples] * fade_in.astype(np.float32)
+        rest_b = y_b[crossfade_samples:]
+        mixed = np.concatenate([head, overlap, rest_b])
+
+    mixed = librosa.util.normalize(mixed)
+
+    out_buffer = io.BytesIO()
+    sf.write(out_buffer, mixed, sr, format="WAV")
+    out_buffer.seek(0)
+
+    analysis = {
+        "track_a_bpm": bpm_a,
+        "track_b_bpm": bpm_b,
+        "track_a_key": key_a,
+        "track_b_key": key_b,
+        "applied_stretch_rate": round(applied_rate, 3),
+        "applied_pitch_shift_semitones": applied_semitones,
+        "output_duration_sec": round(float(len(mixed) / sr), 2),
+    }
+    return RemixResult(audio=out_buffer, analysis=analysis)

tests/test_dreams.py

@@ -0,0 +1,117 @@
+"""Tests for /api/dreams/analyze endpoint."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.routes.dreams import _rate_store
+
+
+@pytest.fixture(autouse=True)
+def _reset_rate_limiter():
+    _rate_store.clear()
+    yield
+    _rate_store.clear()
+
+
+def _mock_gemini_response(**overrides: object) -> MagicMock:
+    defaults = {
+        "emotions": ["fear", "wonder"],
+        "themes": ["being chased"],
+        "symbols": ["water"],
+        "interpretation": "This reflects anxiety about a real-life situation.",
+        "lucidityIndicator": False,
+    }
+    defaults.update(overrides)
+    response = MagicMock()
+    response.text = json.dumps(defaults)
+    return response
+
+
+def test_analyze_valid_dream_returns_structured_result(client: TestClient) -> None:
+    mock_client = MagicMock()
+    mock_client.models.generate_content.return_value = _mock_gemini_response()
+    with patch("app.services.dream_analyzer._get_client", return_value=mock_client):
+        response = client.post(
+            "/api/dreams/analyze",
+            json={"dreamText": "I was being chased through a dark forest and found a river.", "language": "English"},
+        )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["emotions"] == ["fear", "wonder"]
+    assert body["themes"] == ["being chased"]
+    assert body["lucidityIndicator"] is False
+
+
+def test_analyze_rejects_too_short_dream(client: TestClient) -> None:
+    response = client.post("/api/dreams/analyze", json={"dreamText": "hi"})
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "dream_too_short"
+
+
+def test_analyze_rejects_empty_dream_text(client: TestClient) -> None:
+    response = client.post("/api/dreams/analyze", json={"dreamText": ""})
+    assert response.status_code == 422
+
+
+def test_analyze_rejects_missing_dream_text(client: TestClient) -> None:
+    response = client.post("/api/dreams/analyze", json={})
+    assert response.status_code == 422
+
+
+def test_analyze_handles_missing_api_key(client: TestClient) -> None:
+    with patch("app.services.dream_analyzer._get_client", side_effect=ValueError("DREAMS_GEMINI_API_KEY required")):
+        response = client.post(
+            "/api/dreams/analyze",
+            json={"dreamText": "A perfectly normal dream about flying over mountains."},
+        )
+    assert response.status_code == 503
+    assert response.json()["detail"]["code"] == "service_not_configured"
+
+
+def test_analyze_handles_malformed_gemini_output(client: TestClient) -> None:
+    mock_client = MagicMock()
+    bad_response = MagicMock()
+    bad_response.text = "I refuse to analyze this."
+    mock_client.models.generate_content.return_value = bad_response
+    with patch("app.services.dream_analyzer._get_client", return_value=mock_client):
+        response = client.post(
+            "/api/dreams/analyze",
+            json={"dreamText": "A perfectly normal dream about flying over mountains."},
+        )
+    assert response.status_code == 502
+    assert response.json()["detail"]["code"] == "analysis_failed"
+
+
+def test_analyze_filters_invalid_emotions_from_gemini(client: TestClient) -> None:
+    """Gemini could hallucinate an emotion outside the allowed set — the
+    service must filter it rather than pass it straight through."""
+    mock_client = MagicMock()
+    mock_client.models.generate_content.return_value = _mock_gemini_response(
+        emotions=["fear", "not_a_real_emotion", "joy"]
+    )
+    with patch("app.services.dream_analyzer._get_client", return_value=mock_client):
+        response = client.post(
+            "/api/dreams/analyze",
+            json={"dreamText": "A perfectly normal dream about flying over mountains."},
+        )
+    assert response.status_code == 200
+    assert "not_a_real_emotion" not in response.json()["emotions"]
+
+
+def test_analyze_enforces_rate_limit(client: TestClient) -> None:
+    mock_client = MagicMock()
+    mock_client.models.generate_content.return_value = _mock_gemini_response()
+    with patch("app.services.dream_analyzer._get_client", return_value=mock_client):
+        last_status = 200
+        for _ in range(10):
+            r = client.post(
+                "/api/dreams/analyze",
+                json={"dreamText": "A perfectly normal dream about flying over mountains."},
+            )
+            last_status = r.status_code
+    assert last_status == 429

tests/test_remix.py

@@ -0,0 +1,195 @@
+"""
+Tests for the Creator Studio AI Remix engine (/api/remix/blend).
+
+Uses real synthesized audio — a pure tone for basic plumbing/error-path
+tests, and a click track (periodic impulses) for tempo-detection tests,
+since librosa.beat.beat_track needs actual rhythmic structure to lock onto.
+"""
+
+import io
+import json
+
+import numpy as np
+import pytest
+import soundfile as sf
+from fastapi.testclient import TestClient
+
+from app.routes.remix import _remix_rate_store
+
+
+@pytest.fixture(autouse=True)
+def _reset_remix_rate_limiter():
+    """The rate limiter's store is module-level and shared across every
+    test in this file (6 requests/60s per IP, and TestClient always uses
+    the same fake client IP) — without resetting it, tests that pass in
+    isolation start failing with 429 once enough tests run before them in
+    the same process."""
+    _remix_rate_store.clear()
+    yield
+    _remix_rate_store.clear()
+
+
+def _tone_wav(freq: float = 440.0, duration: float = 3.0, sr: int = 22050) -> io.BytesIO:
+    t = np.linspace(0, duration, int(sr * duration))
+    y = (0.3 * np.sin(2 * np.pi * freq * t)).astype(np.float32)
+    buf = io.BytesIO()
+    sf.write(buf, y, sr, format="WAV")
+    buf.seek(0)
+    return buf
+
+
+def _click_track_wav(bpm: float, duration: float = 6.0, sr: int = 22050) -> io.BytesIO:
+    """A percussive click every beat at the given BPM — enough rhythmic
+    structure for librosa's onset-based beat tracker to detect real tempo."""
+    n_samples = int(sr * duration)
+    y = np.zeros(n_samples, dtype=np.float32)
+    beat_interval_sec = 60.0 / bpm
+    click_len = int(sr * 0.02)
+    decay = np.exp(-np.linspace(0, 12, click_len)).astype(np.float32)
+    t = 0.0
+    while t < duration:
+        start = int(t * sr)
+        end = min(start + click_len, n_samples)
+        y[start:end] += decay[: end - start]
+        t += beat_interval_sec
+    buf = io.BytesIO()
+    sf.write(buf, y, sr, format="WAV")
+    buf.seek(0)
+    return buf
+
+
+def _valid_options(**overrides) -> str:
+    base = {"matchTempo": True, "matchKey": False, "crossfadeSeconds": 2.0, "crossfadeCurve": "equal_power"}
+    base.update(overrides)
+    return json.dumps(base)
+
+
+def test_remix_blend_rejects_non_audio_track_a(client: TestClient) -> None:
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": _valid_options()},
+        files={
+            "track_a": ("a.txt", io.BytesIO(b"not audio"), "text/plain"),
+            "track_b": ("b.wav", _tone_wav(440), "audio/wav"),
+        },
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "invalid_file_type"
+
+
+def test_remix_blend_rejects_non_audio_track_b(client: TestClient) -> None:
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": _valid_options()},
+        files={
+            "track_a": ("a.wav", _tone_wav(440), "audio/wav"),
+            "track_b": ("b.bin", io.BytesIO(b"not audio"), "application/octet-stream"),
+        },
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "invalid_file_type"
+
+
+def test_remix_blend_rejects_invalid_options_json(client: TestClient) -> None:
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": "{not json"},
+        files={
+            "track_a": ("a.wav", _tone_wav(440), "audio/wav"),
+            "track_b": ("b.wav", _tone_wav(220), "audio/wav"),
+        },
+    )
+    assert response.status_code == 422
+
+
+def test_remix_blend_rejects_silent_track(client: TestClient) -> None:
+    silent = io.BytesIO()
+    sf.write(silent, np.zeros(22050, dtype=np.float32), 22050, format="WAV")
+    silent.seek(0)
+
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": _valid_options()},
+        files={
+            "track_a": ("a.wav", silent, "audio/wav"),
+            "track_b": ("b.wav", _tone_wav(440), "audio/wav"),
+        },
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "validation_error"
+
+
+def test_remix_blend_returns_wav_with_analysis_header(client: TestClient) -> None:
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": _valid_options(matchTempo=False)},
+        files={
+            "track_a": ("a.wav", _tone_wav(440, duration=2.0), "audio/wav"),
+            "track_b": ("b.wav", _tone_wav(330, duration=2.0), "audio/wav"),
+        },
+    )
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "audio/wav"
+    assert "X-Remix-Analysis" in response.headers
+
+    analysis = json.loads(response.headers["X-Remix-Analysis"])
+    assert "trackABpm" in analysis or "track_a_bpm" in analysis  # camelCase alias in JSON
+    assert response.content[:4] == b"RIFF"
+
+
+def test_remix_blend_output_is_real_blended_audio_not_passthrough(client: TestClient) -> None:
+    """The output WAV must actually contain a crossfaded blend — verify via
+    duration: two 2s tracks with a 1s crossfade should yield ~3s of audio,
+    not 2s (passthrough) or 4s (naive concatenation)."""
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": _valid_options(matchTempo=False, crossfadeSeconds=1.0)},
+        files={
+            "track_a": ("a.wav", _tone_wav(440, duration=2.0), "audio/wav"),
+            "track_b": ("b.wav", _tone_wav(330, duration=2.0), "audio/wav"),
+        },
+    )
+    assert response.status_code == 200
+    y, sr = sf.read(io.BytesIO(response.content))
+    duration = len(y) / sr
+    assert 2.8 < duration < 3.2
+
+
+def test_remix_blend_matches_tempo_with_click_tracks(client: TestClient) -> None:
+    """Two click tracks at different real BPMs: with matchTempo on, the
+    engine must detect both tempos and report a non-trivial stretch rate."""
+    response = client.post(
+        "/api/remix/blend",
+        data={"options": _valid_options(matchTempo=True, crossfadeSeconds=1.0)},
+        files={
+            "track_a": ("a.wav", _click_track_wav(120.0), "audio/wav"),
+            "track_b": ("b.wav", _click_track_wav(140.0), "audio/wav"),
+        },
+    )
+    assert response.status_code == 200
+    analysis_raw = response.headers["X-Remix-Analysis"]
+    analysis = json.loads(analysis_raw)
+
+    bpm_a = analysis.get("track_a_bpm", analysis.get("trackABpm"))
+    bpm_b = analysis.get("track_b_bpm", analysis.get("trackBBpm"))
+    stretch = analysis.get("applied_stretch_rate", analysis.get("appliedStretchRate"))
+
+    assert bpm_a > 1  # real beat detected, not the "beatless" 0 fallback
+    assert bpm_b > 1
+    assert stretch != 1.0  # tempos differed, so a real stretch must have been applied
+
+
+def test_remix_blend_rate_limit(client: TestClient) -> None:
+    last_status = None
+    for _ in range(7):
+        response = client.post(
+            "/api/remix/blend",
+            data={"options": _valid_options(matchTempo=False)},
+            files={
+                "track_a": ("a.wav", _tone_wav(440, duration=0.5), "audio/wav"),
+                "track_b": ("b.wav", _tone_wav(330, duration=0.5), "audio/wav"),
+            },
+        )
+        last_status = response.status_code
+
+    assert last_status == 429