From 624b30eafd943037ff53a42875cc6a1af2980931 Mon Sep 17 00:00:00 2001
From: Dave Page <dpage@pgadmin.org>
Date: Mon, 16 Mar 2026 16:48:38 +0000
Subject: [PATCH] Clarify where the LLM API key files should be. #9758

---
 docs/en_US/ai_tools.rst     |  4 ++--
 docs/en_US/preferences.rst  | 10 ++++++++--
 web/pgadmin/llm/__init__.py |  4 ++++
 3 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/en_US/ai_tools.rst b/docs/en_US/ai_tools.rst
index 1a81a0a9fa3..fdd6f438388 100644
--- a/docs/en_US/ai_tools.rst
+++ b/docs/en_US/ai_tools.rst
@@ -51,7 +51,7 @@ Select your preferred LLM provider from the dropdown:
   Use Claude models from Anthropic, or any Anthropic-compatible API provider.
 
   * **API URL**: Custom API endpoint URL (leave empty for default: https://api.anthropic.com/v1).
-  * **API Key File**: Path to a file containing your Anthropic API key (obtain from https://console.anthropic.com/). Optional when using a custom URL with a provider that does not require authentication.
+  * **API Key File**: Path to a file containing your Anthropic API key (obtain from https://console.anthropic.com/). This path refers to the filesystem where the pgAdmin server is running (e.g., inside the container if using Docker). The ``~`` prefix is expanded to the home directory of the user running the pgAdmin server process. Optional when using a custom URL with a provider that does not require authentication.
   * **Model**: Select from available Claude models (e.g., claude-sonnet-4-20250514).
 
 **OpenAI**
@@ -59,7 +59,7 @@ Select your preferred LLM provider from the dropdown:
   LiteLLM, LM Studio, EXO, or other local inference servers).
 
   * **API URL**: Custom API endpoint URL (leave empty for default: https://api.openai.com/v1). Include the ``/v1`` path prefix if required by your provider.
-  * **API Key File**: Path to a file containing your OpenAI API key (obtain from https://platform.openai.com/). Optional when using a custom URL with a provider that does not require authentication.
+  * **API Key File**: Path to a file containing your OpenAI API key (obtain from https://platform.openai.com/). This path refers to the filesystem where the pgAdmin server is running (e.g., inside the container if using Docker). The ``~`` prefix is expanded to the home directory of the user running the pgAdmin server process. Optional when using a custom URL with a provider that does not require authentication.
   * **Model**: Select from available GPT models (e.g., gpt-4).
 
 **Ollama**
diff --git a/docs/en_US/preferences.rst b/docs/en_US/preferences.rst
index caaaca4a268..0fcf6413bd5 100644
--- a/docs/en_US/preferences.rst
+++ b/docs/en_US/preferences.rst
@@ -52,7 +52,10 @@ Use the fields on the *AI* panel to configure your LLM provider:
   to use an Anthropic-compatible API provider.
 
 * Use the *API Key File* field to specify the path to a file containing your
-  Anthropic API key. The API key may be optional when using a custom API URL
+  Anthropic API key. This path refers to the filesystem where the pgAdmin
+  server is running (e.g., inside the container if using Docker). The ``~``
+  prefix is expanded to the home directory of the user running the pgAdmin
+  server process. The API key may be optional when using a custom API URL
   with a provider that does not require authentication.
 
 * Use the *Model* field to select from the available Claude models. Click the
@@ -68,7 +71,10 @@ Use the fields on the *AI* panel to configure your LLM provider:
   (e.g., ``http://localhost:1234/v1``).
 
 * Use the *API Key File* field to specify the path to a file containing your
-  OpenAI API key. The API key may be optional when using a custom API URL
+  OpenAI API key. This path refers to the filesystem where the pgAdmin
+  server is running (e.g., inside the container if using Docker). The ``~``
+  prefix is expanded to the home directory of the user running the pgAdmin
+  server process. The API key may be optional when using a custom API URL
   with a provider that does not require authentication.
 
 * Use the *Model* field to select from the available GPT models. Click the
diff --git a/web/pgadmin/llm/__init__.py b/web/pgadmin/llm/__init__.py
index bd61ed090b7..e7dedefaad9 100644
--- a/web/pgadmin/llm/__init__.py
+++ b/web/pgadmin/llm/__init__.py
@@ -123,6 +123,8 @@ def register_preferences(self):
             category_label=gettext('Anthropic'),
             help_str=gettext(
                 'Path to a file containing your Anthropic API key. '
+                'This path must be on the server hosting pgAdmin, '
+                'e.g. inside the container when using Docker. '
                 'The file should contain only the API key. The API key '
                 'may be optional when using a custom API URL with a '
                 'provider that does not require authentication.'
@@ -185,6 +187,8 @@ def register_preferences(self):
             category_label=gettext('OpenAI'),
             help_str=gettext(
                 'Path to a file containing your OpenAI API key. '
+                'This path must be on the server hosting pgAdmin, '
+                'e.g. inside the container when using Docker. '
                 'The file should contain only the API key. The API key '
                 'may be optional when using a custom API URL with a '
                 'provider that does not require authentication.'