karaoke-gen 0.96.0__py3-none-any.whl → 0.101.0__py3-none-any.whl

backend/main.py

@@ -7,10 +7,14 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from backend.config import settings
-from backend.api.routes import health, jobs, internal, file_upload, review, auth, audio_search, themes, users, admin
+from backend.api.routes import health, jobs, internal, file_upload, review, auth, audio_search, themes, users, admin, tenant
 from backend.services.tracing import setup_tracing, instrument_app, get_current_trace_id
 from backend.services.structured_logging import setup_structured_logging
+from backend.services.spacy_preloader import preload_spacy_model
+from backend.services.nltk_preloader import preload_all_nltk_resources
+from backend.services.langfuse_preloader import preload_langfuse_handler
 from backend.middleware.audit_logging import AuditLoggingMiddleware
+from backend.middleware.tenant import TenantMiddleware
 
 
 from backend.version import VERSION
@@ -67,7 +71,28 @@ async def lifespan(app: FastAPI):
     logger.info(f"Environment: {settings.environment}")
     logger.info(f"GCS Bucket: {settings.gcs_bucket_name}")
     logger.info(f"Tracing enabled: {tracing_enabled}")
-    
+
+    # Preload NLP models and resources to avoid cold start delays
+    # See docs/archive/2026-01-08-performance-investigation.md for background
+
+    # 1. SpaCy model (60+ second delay without preload)
+    try:
+        preload_spacy_model("en_core_web_sm")
+    except Exception as e:
+        logger.warning(f"SpaCy preload failed (will load lazily): {e}")
+
+    # 2. NLTK cmudict (50-100+ second delay without preload)
+    try:
+        preload_all_nltk_resources()
+    except Exception as e:
+        logger.warning(f"NLTK preload failed (will load lazily): {e}")
+
+    # 3. Langfuse callback handler (200+ second delay without preload)
+    try:
+        preload_langfuse_handler()
+    except Exception as e:
+        logger.warning(f"Langfuse preload failed (will initialize lazily): {e}")
+
     # Validate OAuth credentials (non-blocking)
     try:
         await validate_credentials_on_startup()
@@ -104,6 +129,9 @@ app.add_middleware(
 # Add audit logging middleware (captures all requests with request_id for correlation)
 app.add_middleware(AuditLoggingMiddleware)
 
+# Add tenant detection middleware (extracts tenant from subdomain/headers)
+app.add_middleware(TenantMiddleware)
+
 # Include routers
 app.include_router(health.router, prefix="/api")
 app.include_router(jobs.router, prefix="/api")
@@ -115,6 +143,7 @@ app.include_router(audio_search.router, prefix="/api")  # Audio search (artist+t
 app.include_router(themes.router, prefix="/api")  # Theme selection for styles
 app.include_router(users.router, prefix="/api")  # User auth, credits, and Stripe webhooks
 app.include_router(admin.router, prefix="/api")  # Admin dashboard and management
+app.include_router(tenant.router)  # Tenant/white-label configuration (no /api prefix, router has it)
 
 
 @app.get("/")

backend/middleware/__init__.py

@@ -1,5 +1,11 @@
 """Middleware package for FastAPI application."""
 
 from backend.middleware.audit_logging import AuditLoggingMiddleware
+from backend.middleware.tenant import TenantMiddleware, get_tenant_from_request, get_tenant_config_from_request
 
-__all__ = ["AuditLoggingMiddleware"]
+__all__ = [
+    "AuditLoggingMiddleware",
+    "TenantMiddleware",
+    "get_tenant_from_request",
+    "get_tenant_config_from_request",
+]

backend/middleware/tenant.py

@@ -0,0 +1,192 @@
+"""
+Tenant detection middleware for white-label B2B portals.
+
+This middleware extracts the tenant ID from incoming requests and attaches
+the tenant configuration to the request state for use by downstream handlers.
+
+Tenant detection priority:
+1. X-Tenant-ID header (explicitly set by frontend)
+2. `tenant` query parameter (for development/testing)
+3. Host header subdomain detection (production flow)
+
+The middleware is non-blocking - if no tenant is detected, the request
+proceeds as a default Nomad Karaoke request (tenant_id = None).
+"""
+
+import logging
+import os
+from typing import Optional
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from backend.services.tenant_service import get_tenant_service
+from backend.models.tenant import TenantConfig
+
+logger = logging.getLogger(__name__)
+
+# Only allow query param tenant override in non-production environments
+IS_PRODUCTION = os.environ.get("ENV", "").lower() == "production" or \
+                os.environ.get("ENVIRONMENT", "").lower() == "production"
+
+
+# Known non-tenant subdomains that should be treated as default Nomad Karaoke
+NON_TENANT_SUBDOMAINS = {"gen", "api", "www", "buy", "admin", "app", "beta"}
+
+
+class TenantMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that detects tenant from request and attaches config to state.
+
+    After this middleware runs, routes can access:
+    - request.state.tenant_id: str or None
+    - request.state.tenant_config: TenantConfig or None
+
+    Usage in route handlers:
+    ```python
+    @router.get("/something")
+    async def handler(request: Request):
+        tenant_id = getattr(request.state, "tenant_id", None)
+        tenant_config = getattr(request.state, "tenant_config", None)
+    ```
+    """
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        # Extract tenant ID from request
+        tenant_id = self._extract_tenant_id(request)
+
+        # Load tenant config if tenant detected
+        tenant_config: Optional[TenantConfig] = None
+        if tenant_id:
+            tenant_service = get_tenant_service()
+            tenant_config = tenant_service.get_tenant_config(tenant_id)
+
+            if tenant_config and not tenant_config.is_active:
+                # Tenant exists but is inactive - treat as default
+                logger.warning(f"Inactive tenant requested: {tenant_id}")
+                tenant_id = None
+                tenant_config = None
+
+        # Attach to request state
+        request.state.tenant_id = tenant_id
+        request.state.tenant_config = tenant_config
+
+        # Log tenant detection for debugging
+        if tenant_id:
+            logger.debug(f"Request tenant: {tenant_id} (path: {request.url.path})")
+
+        # Process request
+        response = await call_next(request)
+
+        # Add tenant ID to response headers for debugging
+        if tenant_id:
+            response.headers["X-Tenant-ID"] = tenant_id
+
+        return response
+
+    def _extract_tenant_id(self, request: Request) -> Optional[str]:
+        """
+        Extract tenant ID from request using priority-based detection.
+
+        Returns:
+            Tenant ID if detected, None for default Nomad Karaoke
+        """
+        # Priority 1: X-Tenant-ID header (explicitly set by frontend)
+        header_tenant = request.headers.get("X-Tenant-ID")
+        if header_tenant:
+            return header_tenant.lower().strip()
+
+        # Priority 2: Query parameter (for development/testing only)
+        # Disabled in production to prevent tenant spoofing
+        if not IS_PRODUCTION:
+            query_tenant = request.query_params.get("tenant")
+            if query_tenant:
+                return query_tenant.lower().strip()
+
+        # Priority 3: Host header subdomain detection
+        host = request.headers.get("Host", "")
+        return self._extract_tenant_from_host(host)
+
+    def _extract_tenant_from_host(self, host: str) -> Optional[str]:
+        """
+        Extract tenant ID from Host header subdomain.
+
+        Patterns handled:
+        - vocalstar.nomadkaraoke.com -> vocalstar
+        - vocalstar.gen.nomadkaraoke.com -> vocalstar
+        - localhost:3000 -> None (local dev)
+        - gen.nomadkaraoke.com -> None (main app)
+        - api.nomadkaraoke.com -> None (API)
+
+        Returns:
+            Tenant ID if subdomain matches tenant, None otherwise
+        """
+        if not host:
+            return None
+
+        # Normalize
+        host_lower = host.lower()
+
+        # Remove port if present
+        if ":" in host_lower:
+            host_lower = host_lower.split(":")[0]
+
+        # Check if this is a nomadkaraoke.com domain
+        if "nomadkaraoke.com" not in host_lower:
+            return None
+
+        # Split into parts
+        parts = host_lower.split(".")
+
+        # Need at least 3 parts: subdomain.nomadkaraoke.com
+        if len(parts) < 3:
+            return None
+
+        # First part is the potential tenant ID
+        potential_tenant = parts[0]
+
+        # Skip known non-tenant subdomains
+        if potential_tenant in NON_TENANT_SUBDOMAINS:
+            return None
+
+        # Verify tenant exists in GCS
+        tenant_service = get_tenant_service()
+        if tenant_service.tenant_exists(potential_tenant):
+            return potential_tenant
+
+        return None
+
+
+def get_tenant_from_request(request: Request) -> Optional[str]:
+    """
+    Helper function to get tenant ID from request state.
+
+    Usage in route handlers:
+    ```python
+    from backend.middleware.tenant import get_tenant_from_request
+
+    @router.get("/something")
+    async def handler(request: Request):
+        tenant_id = get_tenant_from_request(request)
+    ```
+    """
+    return getattr(request.state, "tenant_id", None)
+
+
+def get_tenant_config_from_request(request: Request) -> Optional[TenantConfig]:
+    """
+    Helper function to get tenant config from request state.
+
+    Usage in route handlers:
+    ```python
+    from backend.middleware.tenant import get_tenant_config_from_request
+
+    @router.get("/something")
+    async def handler(request: Request):
+        config = get_tenant_config_from_request(request)
+        if config and not config.features.audio_search:
+            raise HTTPException(403, "Audio search not available")
+    ```
+    """
+    return getattr(request.state, "tenant_config", None)

backend/models/job.py

@@ -207,6 +207,9 @@ class Job(BaseModel):
     webhook_url: Optional[str] = None            # Webhook for notifications
     user_email: Optional[str] = None             # Email for notifications
     non_interactive: bool = False                # Skip interactive steps (lyrics review, instrumental selection)
+
+    # Multi-tenant support (None = default Nomad Karaoke)
+    tenant_id: Optional[str] = None              # Tenant ID for white-label portal scoping
     
     # Theme configuration (pre-made themes from GCS)
     theme_id: Optional[str] = None               # Theme identifier (e.g., "nomad", "default")
@@ -276,7 +279,12 @@ class Job(BaseModel):
     review_token_expires_at: Optional[datetime] = None  # Token expiry time (optional, for extra security)
     instrumental_token: Optional[str] = None     # Job-scoped token for instrumental review UI access (generated when entering AWAITING_INSTRUMENTAL_SELECTION)
     instrumental_token_expires_at: Optional[datetime] = None  # Token expiry time
-    
+
+    # Made-for-you order tracking
+    made_for_you: bool = False                   # Flag indicating this is a made-for-you customer order
+    customer_email: Optional[str] = None         # Customer email for final delivery (job owned by admin during processing)
+    customer_notes: Optional[str] = None         # Notes provided by customer with their order
+
     # Processing state
     track_output_dir: Optional[str] = None       # Local output directory (temp)
     audio_hash: Optional[str] = None             # Hash for deduplication
@@ -474,7 +482,12 @@ class JobCreate(BaseModel):
     prep_only: bool = False                      # Stop after review, don't run finalisation
     finalise_only: bool = False                  # Skip prep, run only finalisation
     keep_brand_code: Optional[str] = None        # Preserve existing brand code instead of generating new one
-    
+
+    # Made-for-you order tracking
+    made_for_you: bool = False                   # Flag indicating this is a made-for-you customer order
+    customer_email: Optional[str] = None         # Customer email for final delivery (job owned by admin during processing)
+    customer_notes: Optional[str] = None         # Notes provided by customer with their order
+
     # Request metadata (set by API endpoint from request headers)
     request_metadata: Dict[str, Any] = Field(default_factory=dict)
     """
@@ -486,7 +499,10 @@ class JobCreate(BaseModel):
     - server_version: Current server version
     - custom_headers: All X-* headers
     """
-    
+
+    # Tenant scoping for white-label portals
+    tenant_id: Optional[str] = None              # Tenant ID for job scoping
+
     @validator('url')
     def validate_url(cls, v):
         """Validate URL is not empty."""

backend/models/tenant.py

@@ -0,0 +1,208 @@
+"""
+Tenant data models for white-label B2B portals.
+
+Tenants are B2B customers who get their own branded portal with custom
+configuration. Each tenant has:
+- Custom branding (logo, colors, site title)
+- Feature flags (enable/disable audio search, distribution, etc.)
+- Default settings (theme, distribution mode)
+- Auth configuration (allowed email domains, fixed tokens)
+
+Tenant configs are stored in GCS at tenants/{tenant_id}/config.json
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TenantBranding(BaseModel):
+    """Branding configuration for a tenant's portal."""
+
+    logo_url: Optional[str] = Field(
+        None, description="URL to tenant's logo image (PNG with transparency preferred)"
+    )
+    logo_height: int = Field(40, description="Logo height in pixels for header display")
+    primary_color: str = Field(
+        "#ff5bb8", description="Primary brand color (hex format)"
+    )
+    secondary_color: str = Field(
+        "#8b5cf6", description="Secondary brand color (hex format)"
+    )
+    accent_color: Optional[str] = Field(
+        None, description="Accent color for highlights (hex format)"
+    )
+    background_color: Optional[str] = Field(
+        None, description="Custom background color (defaults to dark theme)"
+    )
+    favicon_url: Optional[str] = Field(None, description="URL to custom favicon")
+    site_title: str = Field(
+        "Karaoke Generator", description="Browser tab title"
+    )
+    tagline: Optional[str] = Field(
+        None, description="Optional tagline shown below logo"
+    )
+
+
+class TenantFeatures(BaseModel):
+    """Feature flags controlling what's available in the tenant's portal."""
+
+    # Audio input methods
+    audio_search: bool = Field(
+        True, description="Enable audio search (flacfetch integration)"
+    )
+    file_upload: bool = Field(True, description="Enable direct file upload")
+    youtube_url: bool = Field(True, description="Enable YouTube URL input")
+
+    # Distribution options
+    youtube_upload: bool = Field(True, description="Enable YouTube upload option")
+    dropbox_upload: bool = Field(True, description="Enable Dropbox upload option")
+    gdrive_upload: bool = Field(True, description="Enable Google Drive upload option")
+
+    # Customization options
+    theme_selection: bool = Field(
+        True, description="Allow user to select theme (false = use default)"
+    )
+    color_overrides: bool = Field(
+        True, description="Allow user to customize colors"
+    )
+
+    # Output formats
+    enable_cdg: bool = Field(True, description="Generate CDG format output")
+    enable_4k: bool = Field(True, description="Generate 4K video output")
+
+    # Advanced features
+    admin_access: bool = Field(
+        False, description="Allow access to admin dashboard"
+    )
+
+
+class TenantDefaults(BaseModel):
+    """Default settings applied to all jobs for this tenant."""
+
+    theme_id: Optional[str] = Field(
+        None, description="Default theme ID (required if theme_selection=false)"
+    )
+    locked_theme: Optional[str] = Field(
+        None,
+        description="If set, users cannot change theme - always uses this theme ID"
+    )
+    distribution_mode: str = Field(
+        "all",
+        description="Distribution mode: 'all', 'download_only', or 'cloud_only'"
+    )
+    brand_prefix: Optional[str] = Field(
+        None, description="Prefix for output filenames (e.g., 'VSTAR')"
+    )
+    youtube_description_template: Optional[str] = Field(
+        None, description="Default YouTube description template"
+    )
+
+
+class TenantAuth(BaseModel):
+    """Authentication configuration for a tenant."""
+
+    allowed_email_domains: List[str] = Field(
+        default_factory=list,
+        description="Email domains allowed for magic link auth (e.g., ['vocal-star.com'])"
+    )
+    require_email_domain: bool = Field(
+        True,
+        description="If true, only allowed domains can sign up. If false, domains get auto-approved."
+    )
+    fixed_token_ids: List[str] = Field(
+        default_factory=list,
+        description="IDs of fixed API tokens for this tenant (tokens stored in auth_tokens)"
+    )
+    sender_email: Optional[str] = Field(
+        None,
+        description="Email sender address for this tenant (e.g., 'vocalstar@nomadkaraoke.com')"
+    )
+
+
+class TenantConfig(BaseModel):
+    """Complete configuration for a white-label tenant."""
+
+    id: str = Field(..., description="Unique tenant identifier (e.g., 'vocalstar')")
+    name: str = Field(..., description="Display name (e.g., 'Vocal Star')")
+    subdomain: str = Field(
+        ..., description="Full subdomain (e.g., 'vocalstar.nomadkaraoke.com')"
+    )
+    is_active: bool = Field(True, description="Whether tenant portal is active")
+
+    branding: TenantBranding = Field(default_factory=TenantBranding)
+    features: TenantFeatures = Field(default_factory=TenantFeatures)
+    defaults: TenantDefaults = Field(default_factory=TenantDefaults)
+    auth: TenantAuth = Field(default_factory=TenantAuth)
+
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    def get_sender_email(self) -> str:
+        """Get the email sender address for this tenant."""
+        if self.auth.sender_email:
+            return self.auth.sender_email
+        # Default pattern: {tenant_id}@nomadkaraoke.com
+        return f"{self.id}@nomadkaraoke.com"
+
+    def is_email_allowed(self, email: str) -> bool:
+        """Check if an email address is allowed for this tenant."""
+        if not self.auth.allowed_email_domains:
+            # No domain restrictions
+            return True
+
+        email_lower = email.lower()
+        for domain in self.auth.allowed_email_domains:
+            if email_lower.endswith(f"@{domain.lower()}"):
+                return True
+
+        return not self.auth.require_email_domain
+
+
+class TenantPublicConfig(BaseModel):
+    """
+    Public tenant configuration returned to frontend.
+
+    This excludes sensitive auth details like token IDs.
+    """
+
+    id: str
+    name: str
+    subdomain: str
+    is_active: bool
+    branding: TenantBranding
+    features: TenantFeatures
+    defaults: TenantDefaults
+    # Auth info limited to what frontend needs
+    allowed_email_domains: List[str] = Field(default_factory=list)
+
+    @classmethod
+    def from_config(cls, config: TenantConfig) -> "TenantPublicConfig":
+        """Create public config from full config."""
+        return cls(
+            id=config.id,
+            name=config.name,
+            subdomain=config.subdomain,
+            is_active=config.is_active,
+            branding=config.branding,
+            features=config.features,
+            defaults=TenantDefaults(
+                theme_id=config.defaults.theme_id,
+                locked_theme=config.defaults.locked_theme,
+                distribution_mode=config.defaults.distribution_mode,
+                # Don't expose brand_prefix or youtube_description_template
+            ),
+            allowed_email_domains=config.auth.allowed_email_domains,
+        )
+
+
+class TenantConfigResponse(BaseModel):
+    """Response from GET /api/tenant/config endpoint."""
+
+    tenant: Optional[TenantPublicConfig] = Field(
+        None, description="Tenant config if found, null for default Nomad Karaoke"
+    )
+    is_default: bool = Field(
+        True, description="True if using default Nomad Karaoke config"
+    )

backend/models/user.py

@@ -45,11 +45,17 @@ class User(BaseModel):
 
     Users are identified by email address. Authentication is via magic links
     (no passwords). Credits are consumed when creating karaoke jobs.
+
+    For multi-tenant white-label portals, users are scoped to a tenant.
+    Users with tenant_id=None are default Nomad Karaoke users.
     """
     email: str  # Primary identifier
     role: UserRole = UserRole.USER
     credits: int = 0
 
+    # Multi-tenant support (None = default Nomad Karaoke)
+    tenant_id: Optional[str] = None
+
     # Stripe integration
     stripe_customer_id: Optional[str] = None
 
@@ -87,6 +93,9 @@ class MagicLinkToken(BaseModel):
 
     Tokens are short-lived (15 minutes) and single-use.
     Stored in Firestore with automatic TTL.
+
+    For multi-tenant portals, the tenant_id determines which portal
+    the user will be redirected to after verification.
     """
     token: str  # Secure random token
     email: str
@@ -97,6 +106,9 @@ class MagicLinkToken(BaseModel):
     ip_address: Optional[str] = None
     user_agent: Optional[str] = None
 
+    # Multi-tenant support (None = default Nomad Karaoke)
+    tenant_id: Optional[str] = None
+
 
 class Session(BaseModel):
     """
@@ -104,6 +116,8 @@ class Session(BaseModel):
 
     Sessions are created after successful magic link verification.
     Sessions expire after 7 days of inactivity or 30 days absolute.
+
+    For multi-tenant portals, sessions are scoped to a tenant.
     """
     token: str  # Secure random session token
     user_email: str
@@ -114,6 +128,9 @@ class Session(BaseModel):
     user_agent: Optional[str] = None
     is_active: bool = True
 
+    # Multi-tenant support (None = default Nomad Karaoke)
+    tenant_id: Optional[str] = None
+
 
 # Pydantic models for API requests/responses
 
@@ -149,6 +166,7 @@ class UserPublic(BaseModel):
     display_name: Optional[str] = None
     total_jobs_created: int = 0
     total_jobs_completed: int = 0
+    tenant_id: Optional[str] = None
 
 
 class AddCreditsRequest(BaseModel):