Handle KG upstream errors gracefully and add /health endpoint

- Map KG 500 responses to HTTP 503 with a "retry later" message via a
  global exception handler, so clients can distinguish upstream failures
  from bugs in this service
- Map fairgraph AuthenticationError to HTTP 401 in the same handler,
  fixing a bug where expired-token requests returned 500
- Add allow_interactive=False to both KGClient constructors so the
  client never makes an eager user_info() call that could raise
  AuthenticationError before the first real request
- Add GET /health endpoint that probes the KG with a minimal query and
  retries up to 3 times before returning 503, so the monitor can
  distinguish a consistently-down KG from transient flakiness

Author: apdavison

validation_service_api/validation_service/auth.py

@@ -53,12 +53,13 @@ def get_kg_client_for_service_account():
             client_id=settings.KG_SERVICE_ACCOUNT_CLIENT_ID,
             client_secret=settings.KG_SERVICE_ACCOUNT_SECRET,
             host=settings.KG_CORE_API_HOST,
+            allow_interactive=False,
         )
     return kg_client_for_service_account
 
 
 def get_kg_client_for_user_account(token):
-    return KGClient(token=token.credentials, host=settings.KG_CORE_API_HOST)
+    return KGClient(token=token.credentials, host=settings.KG_CORE_API_HOST, allow_interactive=False)
 
 
 async def get_collab_info(collab_id, token):

validation_service_api/validation_service/main.py

@@ -1,13 +1,20 @@
+import asyncio
+import functools
+import logging
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
 from starlette.middleware.sessions import SessionMiddleware
 from starlette.middleware.cors import CORSMiddleware
+from fairgraph.errors import AuthenticationError
 
 from .resources import models, tests, vocab, results, auth, comments
 from . import settings
 from .auth import get_kg_client_for_service_account
 
+logger = logging.getLogger("validation_service_api")
+
 
 description = """
 The EBRAINS Model Validation Service is a web service to support
@@ -42,6 +49,65 @@ async def lifespan(app: FastAPI):
 
 app = FastAPI(title="EBRAINS Model Validation Service", description=description, version="3beta", lifespan=lifespan)
 
+
+@app.exception_handler(Exception)
+async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    if isinstance(exc, AuthenticationError):
+        logger.warning("Unauthenticated KG request (likely expired token): %s", exc)
+        return JSONResponse(
+            status_code=401,
+            content={"detail": "Authentication failed. Your token may have expired."},
+        )
+    if "code=500" in str(exc):
+        logger.warning("KG upstream 500: %s", exc)
+        return JSONResponse(
+            status_code=503,
+            content={"detail": "The upstream data service is temporarily unavailable. Please try again in a few minutes."},
+        )
+    logger.exception("Unhandled exception", exc_info=exc)
+    return JSONResponse(status_code=500, content={"detail": "Internal server error"})
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    service_status = getattr(settings, "SERVICE_STATUS", "ok")
+    if service_status != "ok":
+        return JSONResponse(
+            status_code=503,
+            content={"status": "unavailable", "reason": service_status},
+        )
+
+    kg_client = get_kg_client_for_service_account()
+    query = kg_client.retrieve_query("VF_ScientificModelSummary")
+    if query is None:
+        return JSONResponse(status_code=503, content={"status": "unavailable"})
+
+    probe = functools.partial(
+        kg_client.query,
+        query,
+        {"space": "model"},
+        size=1,
+        from_index=0,
+        release_status="released",
+        use_stored_query=True,
+    )
+
+    last_exc = None
+    for attempt in range(3):
+        if attempt > 0:
+            await asyncio.sleep(2)
+        try:
+            loop = asyncio.get_running_loop()
+            await asyncio.wait_for(loop.run_in_executor(None, probe), timeout=5.0)
+            return {"status": "ok"}
+        except Exception as exc:
+            last_exc = exc
+            logger.warning("Health check attempt %d/3 failed: %s", attempt + 1, exc)
+
+    logger.error("Health check: KG unavailable after 3 attempts. Last error: %s", last_exc)
+    return JSONResponse(status_code=503, content={"status": "unavailable"})
+
+
 app.add_middleware(
     SessionMiddleware,
     secret_key=settings.SESSIONS_SECRET_KEY