feat: scaffold FastAPI backend with ports-and-adapters layout

backend/app/config.py

@@ -0,0 +1,53 @@
+"""Typed application settings — the only reader of environment variables."""
+
+from enum import StrEnum
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AppMode(StrEnum):
+    """Runtime mode: live Spotify + Anthropic, or fixture-replay demo."""
+
+    LIVE = "live"
+    DEMO = "demo"
+
+
+class Settings(BaseSettings):
+    """All pipeline tunables in one place so the eval harness can sweep them."""
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    app_mode: AppMode = AppMode.DEMO
+    host_port: int = 8000
+
+    # credentials (empty in demo mode; incomplete live config fails fast)
+    spotify_client_id: str = ""
+    spotify_client_secret: str = ""
+    spotify_redirect_uri: str = "http://127.0.0.1:8000/callback"
+    anthropic_api_key: str = ""
+    # hosted instance only: installs a session at startup (never set locally)
+    spotify_refresh_token: str = ""
+
+    # LLM
+    llm_model: str = "claude-sonnet-5"
+    llm_effort_intent: str = "low"
+    llm_effort_rerank: str = "medium"
+    llm_max_tokens: int = 4096
+
+    # pipeline shape
+    candidate_count: int = 30
+    recommendation_count: int = 15
+    rerank_buffer: int = 5
+
+    # grounding
+    grounding_fanout_width: int = 8
+    grounding_floor: int = 10
+    title_similarity_threshold: float = 0.82
+    request_deadline_seconds: float = 20.0
+
+    # caches
+    resolution_cache_ttl_seconds: int = 3600
+    taste_profile_ttl_seconds: int = 1800
+
+
+settings = Settings()