Improvements to Stirling Engine to prepare for SaaS release (#6603)

# Description of Changes
- Use pool for postgres connections
- Add ability to require user ID to be set on API calls to the engine
- Add process-wide concurrency cap on AI access (in addition to existing
user caps)
- Allow number of workers (threads) to be specified for stirling engine
- Update env var names to reflect that the DB is not just for RAG

engine/src/stirling/config/__init__.py

@@ -1,10 +1,10 @@
 """Configuration models and loaders for the Stirling AI service."""
 
-from .settings import ENGINE_ROOT, AppSettings, RagBackend, load_settings
+from .settings import ENGINE_ROOT, AppSettings, DocumentsBackend, load_settings
 
 __all__ = [
     "ENGINE_ROOT",
     "AppSettings",
-    "RagBackend",
+    "DocumentsBackend",
     "load_settings",
 ]

engine/src/stirling/config/settings.py

@@ -15,7 +15,7 @@ ENV_FILE = ENGINE_ROOT / ".env"
 ENV_LOCAL_FILE = ENGINE_ROOT / ".env.local"
 
 
-class RagBackend(StrEnum):
+class DocumentsBackend(StrEnum):
     SQLITE = "sqlite"
     PGVECTOR = "pgvector"
 
@@ -27,12 +27,22 @@ class AppSettings(BaseSettings):
     fast_model_name: str = Field(validation_alias="STIRLING_FAST_MODEL")
     smart_model_max_tokens: int = Field(validation_alias="STIRLING_SMART_MODEL_MAX_TOKENS")
     fast_model_max_tokens: int = Field(validation_alias="STIRLING_FAST_MODEL_MAX_TOKENS")
+    # Process-wide ceiling on concurrent model API calls, shared by both model
+    # tiers. Per-request fan-outs (chunked reasoner, contradiction detection)
+    # carry their own per-request caps, but those multiply under concurrent
+    # traffic; this is the global backstop.
+    model_max_concurrency: int = Field(validation_alias="STIRLING_MODEL_MAX_CONCURRENCY")
 
-    # RAG settings — always on; the backend picks between embedded sqlite-vec and external pgvector.
-    rag_backend: RagBackend = Field(validation_alias="STIRLING_RAG_BACKEND")
+    # Document store: the one database holding vector chunks, ordered page
+    # text, and ACL rows - embedded sqlite-vec or external pgvector.
+    documents_backend: DocumentsBackend = Field(validation_alias="STIRLING_DOCUMENTS_BACKEND")
+    documents_sqlite_path: Path = Field(validation_alias="STIRLING_DOCUMENTS_SQLITE_PATH")
+    documents_pgvector_dsn: str = Field(validation_alias="STIRLING_DOCUMENTS_PGVECTOR_DSN")
+    documents_pgvector_pool_min_size: int = Field(validation_alias="STIRLING_DOCUMENTS_PGVECTOR_POOL_MIN_SIZE")
+    documents_pgvector_pool_max_size: int = Field(validation_alias="STIRLING_DOCUMENTS_PGVECTOR_POOL_MAX_SIZE")
+
+    # RAG settings - always on.
     rag_embedding_model: str = Field(validation_alias="STIRLING_RAG_EMBEDDING_MODEL")
-    rag_store_path: Path = Field(validation_alias="STIRLING_RAG_STORE_PATH")
-    rag_pgvector_dsn: str = Field(validation_alias="STIRLING_RAG_PGVECTOR_DSN")
     rag_chunk_size: int = Field(validation_alias="STIRLING_RAG_CHUNK_SIZE")
     rag_chunk_overlap: int = Field(validation_alias="STIRLING_RAG_CHUNK_OVERLAP")
     rag_default_top_k: int = Field(validation_alias="STIRLING_RAG_TOP_K")
@@ -88,6 +98,12 @@ class AppSettings(BaseSettings):
     max_pages: int = Field(validation_alias="STIRLING_MAX_PAGES")
     max_characters: int = Field(validation_alias="STIRLING_MAX_CHARACTERS")
 
+    # When true, API routes reject requests that lack an X-User-Id header at
+    # the boundary. Self-hosted deployments with security disabled have no
+    # user identity and leave this off; multi-tenant deployments turn it on so
+    # user-scoped work is never processed without a tenant attached.
+    require_user_id: bool = Field(validation_alias="STIRLING_REQUIRE_USER_ID")
+
     log_level: str = Field(default="INFO", validation_alias="STIRLING_LOG_LEVEL")
     log_file: str = Field(default="", validation_alias="STIRLING_LOG_FILE")
     # When true, raises httpx + httpcore logger levels so every outgoing