From 1c2c480b92fff7a543c96a933be64f80fed540ae Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Sun, 12 Jul 2026 20:29:19 +0530
Subject: [PATCH] feat(schemas): add LlmSetupStatusRead for
 server-authoritative onboarding

---
 surfsense_backend/app/schemas/__init__.py         |  4 +++-
 .../app/schemas/model_connections.py              | 15 ++++++++++++++-
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/surfsense_backend/app/schemas/__init__.py b/surfsense_backend/app/schemas/__init__.py
index 845136cfc..482c895a3 100644
--- a/surfsense_backend/app/schemas/__init__.py
+++ b/surfsense_backend/app/schemas/__init__.py
@@ -43,6 +43,7 @@ from .model_connections import (
     ConnectionCreate,
     ConnectionRead,
     ConnectionUpdate,
+    LlmSetupStatusRead,
     ModelCreate,
     ModelPreviewRead,
     ModelProviderRead,
@@ -185,13 +186,14 @@ __all__ = [
     "InviteInfoResponse",
     "InviteRead",
     "InviteUpdate",
+    # Auth schemas
+    "LlmSetupStatusRead",
     # Log schemas
     "LogBase",
     "LogCreate",
     "LogFilter",
     "LogRead",
     "LogUpdate",
-    # Auth schemas
     "LogoutAllResponse",
     "LogoutRequest",
     "LogoutResponse",
diff --git a/surfsense_backend/app/schemas/model_connections.py b/surfsense_backend/app/schemas/model_connections.py
index 7b7ac33ed..f190ad745 100644
--- a/surfsense_backend/app/schemas/model_connections.py
+++ b/surfsense_backend/app/schemas/model_connections.py
@@ -1,6 +1,6 @@
 import uuid
 from datetime import datetime
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -146,3 +146,16 @@ class ModelRolesUpdate(BaseModel):
     chat_model_id: int | None = None
     vision_model_id: int | None = None
     image_gen_model_id: int | None = None
+
+
+class LlmSetupStatusRead(BaseModel):
+    """Server-authoritative verdict for the per-workspace LLM onboarding gate.
+
+    ``status`` is the only thing the frontend gate acts on; ``source`` is
+    informational and ``can_configure`` selects the onboarding vs. blocked
+    screen for members who cannot manage models.
+    """
+
+    status: Literal["ready", "needs_setup"]
+    source: Literal["global_config", "models", "none"]
+    can_configure: bool