From c8bc4afc9381a4d49455da5eefaf49d84c02ed3d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 5 Mar 2026 22:03:30 +0000
Subject: [PATCH] =?UTF-8?q?fix:=20address=20code=20review=20=E2=80=94=20us?=
 =?UTF-8?q?e=20modern=20type=20hints=20and=20Callable=20annotation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
---
 app/api/files.py                  |  4 ++--
 app/utils/suggestion_providers.py |  3 ++-
 docs/API.md                       | 32 +++++++++++++++++++++++++++++++
 docs/SettingsManagement.md        |  3 ++-
 4 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/app/api/files.py b/app/api/files.py
index 29a649e1..b8ce40f8 100644
--- a/app/api/files.py
+++ b/app/api/files.py
@@ -1450,7 +1450,7 @@ def claim_file(request: Request, file_id: int, db: DbSession):
 
 @router.post("/files/bulk-claim")
 @require_login
-def bulk_claim_files(request: Request, file_ids: List[int], db: DbSession):
+def bulk_claim_files(request: Request, file_ids: list[int], db: DbSession):
     """
     Claim multiple unowned documents for the current user.
 
@@ -1496,7 +1496,7 @@ def bulk_claim_files(request: Request, file_ids: List[int], db: DbSession):
 
 @router.post("/files/assign-owner")
 @require_login
-def assign_owner(request: Request, db: DbSession, owner_id: str = Query(...), file_ids: List[int] | None = None):
+def assign_owner(request: Request, db: DbSession, owner_id: str = Query(...), file_ids: list[int] | None = None):
     """
     Admin-only: assign an owner to documents.
 
diff --git a/app/utils/suggestion_providers.py b/app/utils/suggestion_providers.py
index 68c6fb70..7ea43b74 100644
--- a/app/utils/suggestion_providers.py
+++ b/app/utils/suggestion_providers.py
@@ -16,6 +16,7 @@ the bundled static list.
 
 import logging
 import subprocess  # noqa: S404 — only used with fixed args, no user input
+from typing import Callable
 
 logger = logging.getLogger(__name__)
 
@@ -407,7 +408,7 @@ def get_embedding_models() -> list[str]:
 # Registry — maps setting keys to their provider functions
 # ---------------------------------------------------------------------------
 
-SUGGESTION_PROVIDERS: dict[str, callable] = {
+SUGGESTION_PROVIDERS: dict[str, Callable[[], list[str]]] = {
     "aws_region": get_aws_regions,
     "azure_region": get_azure_regions,
     "tesseract_language": get_tesseract_languages,
diff --git a/docs/API.md b/docs/API.md
index 04a4c45b..2afd5ac2 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -726,6 +726,38 @@ curl "http://<your-instance>/api/users/search?q=risti&limit=5"
 }
 ```
 
+---
+
+### Settings Suggestions (Autocomplete)
+
+**GET** `/api/settings/{key}/suggestions`
+
+Return dynamic autocomplete suggestions for a setting. Providers attempt to
+resolve values from cloud SDKs or installed tools and fall back to curated
+static lists when unavailable.
+
+**Supported keys**: `aws_region`, `azure_region`, `tesseract_language`,
+`easyocr_languages`, `embedding_model`
+
+**Query Parameters**:
+- `q` (optional): Substring to filter suggestions (case-insensitive)
+- `limit` (optional): Maximum results to return (default: 10, max: 50)
+
+```bash
+curl "http://<your-instance>/api/settings/aws_region/suggestions?q=east&limit=5"
+```
+
+**Response**:
+```json
+{
+  "key": "aws_region",
+  "suggestions": ["ap-east-1", "ap-northeast-1", "ap-southeast-1", "us-east-1", "us-east-2"]
+}
+```
+
+**Error Responses**:
+- `404`: No suggestion provider registered for the given key
+
 ### File Preview
 
 **GET** `/api/files/{file_id}/preview`
diff --git a/docs/SettingsManagement.md b/docs/SettingsManagement.md
index 705e9690..b64c1ef4 100644
--- a/docs/SettingsManagement.md
+++ b/docs/SettingsManagement.md
@@ -48,7 +48,8 @@ Settings are organized into logical categories for easy navigation:
 - **Dropdown**: Predefined option lists (e.g., PDF/A format, S3 storage class, S3 ACL)
 - **Multi-select**: Comma-separated selections from a list (e.g., OCR providers)
 - **Model Picker**: Free-text with suggested model names (e.g., AI model selection)
-- **User Autocomplete**: Typeahead search for existing user identifiers (e.g., default owner assignment)
+- **User Autocomplete**: Typeahead search for existing user identifiers (e.g., default owner assignment), fetches from `GET /api/users/search`
+- **Autocomplete**: Typeahead search with dynamic suggestions fetched from `GET /api/settings/{key}/suggestions`. Used for AWS/Azure regions, OCR language codes, and embedding models. Providers attempt dynamic resolution (e.g., boto3 for AWS regions, `tesseract --list-langs` for Tesseract) and fall back to curated static lists if the SDK or tool is unavailable.
 - **List**: Comma-separated values (notification URLs, CORS origins)
 
 ### Sensitive Data