Add startup import guardrails for HF Space env robustness

app/backend/app/config/settings.py

@@ -1,9 +1,45 @@
 """Application settings loaded from environment variables."""
 
-from pydantic import AliasChoices, Field
+from __future__ import annotations
+
+import re
+
+from pydantic import AliasChoices, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
+_TRUTHY_TOKENS = {"1", "true", "yes", "on", "enable", "enabled"}
+_FALSY_TOKENS = {"0", "false", "no", "off", "disable", "disabled"}
+
+
+def _parse_bool_with_fallback(value: object, default: bool) -> bool:
+    """Parse permissive boolean-like values and fall back to default when ambiguous."""
+
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if not isinstance(value, str):
+        return default
+
+    normalized = value.strip().lower()
+    if normalized in _TRUTHY_TOKENS:
+        return True
+    if normalized in _FALSY_TOKENS:
+        return False
+
+    tokens = re.findall(r"[a-z0-9]+", normalized)
+    has_truthy = any(token in _TRUTHY_TOKENS for token in tokens)
+    has_falsy = any(token in _FALSY_TOKENS for token in tokens)
+
+    if has_truthy and not has_falsy:
+        return True
+    if has_falsy and not has_truthy:
+        return False
+
+    return default
+
+
 class Settings(BaseSettings):
     """Runtime settings for the backend application."""
 
@@ -12,13 +48,15 @@ class Settings(BaseSettings):
     debug: bool = False
     request_timeout_seconds: float = Field(default=8.0, gt=0)
     cors_allow_origins: list[str] = Field(default_factory=lambda: ["http://localhost:5173"])
+    serve_frontend: bool = True
+    frontend_dist_dir: str = "app/frontend/dist"
 
-    # Connector settings
-    gallica_use_fixtures: bool = False
+    # Connector settings (fixture-first for MVP demo stability)
+    gallica_use_fixtures: bool = True
     gallica_sru_base_url: str = "https://gallica.bnf.fr/SRU"
-    bodleian_use_fixtures: bool = False
+    bodleian_use_fixtures: bool = True
     bodleian_api_base_url: str = "https://api.bodleian.ox.ac.uk/iiif"
-    europeana_use_fixtures: bool = False
+    europeana_use_fixtures: bool = True
     europeana_api_base_url: str = "https://api.europeana.eu/record/v2/search.json"
     europeana_api_key: str = Field(
         default="",
@@ -31,6 +69,23 @@ class Settings(BaseSettings):
     capability_probe_timeout_seconds: float = Field(default=3.0, gt=0)
     capability_probe_cache_ttl_seconds: int = Field(default=300, ge=0)
 
+    @field_validator(
+        "debug",
+        "serve_frontend",
+        "gallica_use_fixtures",
+        "bodleian_use_fixtures",
+        "europeana_use_fixtures",
+        "enable_capability_probing",
+        "capability_probe_use_fixtures",
+        mode="before",
+    )
+    @classmethod
+    def normalize_bool_env_values(cls, value: object, info):
+        """Normalize permissive boolean-like environment values for robust deployments."""
+
+        default = bool(cls.model_fields[info.field_name].default)
+        return _parse_bool_with_fallback(value=value, default=default)
+
     model_config = SettingsConfigDict(env_prefix="CLAFOUTIS_", extra="ignore")
 
 

app/backend/app/main.py

@@ -1,8 +1,11 @@
 """FastAPI application entrypoint for backend lot 1."""
 
+from pathlib import Path
+
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
 
 from app.api.router import api_router
 from app.config.settings import settings
@@ -38,6 +41,33 @@ def create_app() -> FastAPI:
         payload = ErrorResponse(error="application_error", details=str(exc)).model_dump()
         return JSONResponse(status_code=500, content=payload)
 
+    if settings.serve_frontend:
+        frontend_dist = Path(settings.frontend_dist_dir)
+        index_file = frontend_dist / "index.html"
+
+        if index_file.exists():
+            assets_dir = frontend_dist / "assets"
+            if assets_dir.exists():
+                application.mount(
+                    "/assets",
+                    StaticFiles(directory=str(assets_dir)),
+                    name="frontend-assets",
+                )
+
+            @application.get("/", include_in_schema=False)
+            async def serve_frontend_index() -> FileResponse:
+                return FileResponse(index_file)
+
+            @application.get("/{full_path:path}", include_in_schema=False)
+            async def serve_frontend_spa(full_path: str):
+                if full_path.startswith("api/"):
+                    return JSONResponse(status_code=404, content={"detail": "Not Found"})
+
+                candidate = frontend_dist / full_path
+                if candidate.is_file():
+                    return FileResponse(candidate)
+                return FileResponse(index_file)
+
     return application
 
 

app/tests/unit/backend/test_frontend_serving.py

@@ -0,0 +1,30 @@
+"""Frontend static serving behavior tests."""
+
+from fastapi.testclient import TestClient
+
+from app.config.settings import settings
+from app.main import create_app
+
+
+def test_root_serves_frontend_index_when_configured(tmp_path) -> None:
+    """Root path should serve SPA index when frontend serving is enabled."""
+
+    original_serve_frontend = settings.serve_frontend
+    original_frontend_dist_dir = settings.frontend_dist_dir
+
+    try:
+        dist_dir = tmp_path / "dist"
+        dist_dir.mkdir()
+        (dist_dir / "index.html").write_text("<html><body>Clafoutis UI</body></html>", encoding="utf-8")
+
+        settings.serve_frontend = True
+        settings.frontend_dist_dir = str(dist_dir)
+
+        client = TestClient(create_app())
+        response = client.get("/")
+
+        assert response.status_code == 200
+        assert "Clafoutis UI" in response.text
+    finally:
+        settings.serve_frontend = original_serve_frontend
+        settings.frontend_dist_dir = original_frontend_dist_dir

app/tests/unit/backend/test_settings.py

@@ -25,3 +25,50 @@ def test_europeana_api_key_accepts_hf_token_fallback(monkeypatch) -> None:
     loaded = Settings()
 
     assert loaded.europeana_api_key == "hf-secret-token"
+
+
+def test_bodleian_use_fixtures_accepts_descriptive_value(monkeypatch) -> None:
+    """Boolean settings should stay robust with descriptive env values from platform UIs."""
+
+    monkeypatch.setenv(
+        "CLAFOUTIS_BODLEIAN_USE_FIXTURES",
+        "Use fixture data for Bodleian connector to keep the demo stable",
+    )
+
+    loaded = Settings()
+
+    assert loaded.bodleian_use_fixtures is True
+
+
+def test_serve_frontend_accepts_descriptive_value(monkeypatch) -> None:
+    """Frontend serving flag should tolerate descriptive values from Space UI."""
+
+    monkeypatch.setenv("CLAFOUTIS_SERVE_FRONTEND", "Serve the built frontend from the backend")
+
+    loaded = Settings()
+
+    assert loaded.serve_frontend is True
+
+
+def test_fixture_flags_default_to_true_for_mvp(monkeypatch) -> None:
+    """Fixture flags should default to true to match MVP fixture-first deployment."""
+
+    monkeypatch.delenv("CLAFOUTIS_GALLICA_USE_FIXTURES", raising=False)
+    monkeypatch.delenv("CLAFOUTIS_BODLEIAN_USE_FIXTURES", raising=False)
+    monkeypatch.delenv("CLAFOUTIS_EUROPEANA_USE_FIXTURES", raising=False)
+
+    loaded = Settings()
+
+    assert loaded.gallica_use_fixtures is True
+    assert loaded.bodleian_use_fixtures is True
+    assert loaded.europeana_use_fixtures is True
+
+
+def test_serve_frontend_accepts_disable_token(monkeypatch) -> None:
+    """Explicit disable token should disable frontend serving."""
+
+    monkeypatch.setenv("CLAFOUTIS_SERVE_FRONTEND", "disabled")
+
+    loaded = Settings()
+
+    assert loaded.serve_frontend is False

app/tests/unit/backend/test_startup_import.py

@@ -0,0 +1,27 @@
+"""Startup import smoke tests for deployment robustness."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+
+def test_importing_main_with_descriptive_env_values_does_not_crash() -> None:
+    """Importing app.main should not fail even with descriptive HF Space env values."""
+
+    env = os.environ.copy()
+    env["CLAFOUTIS_SERVE_FRONTEND"] = "Serve the built frontend from the backend"
+    env["CLAFOUTIS_BODLEIAN_USE_FIXTURES"] = "Use fixture data for Bodleian connector to keep the demo stable"
+
+    completed = subprocess.run(
+        [sys.executable, "-c", "from app.main import app; print(app.title)"],
+        cwd="app/backend",
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert completed.returncode == 0, completed.stderr
+    assert "Clafoutis Backend" in completed.stdout