Docs

docs/configuration.md

@@ -1700,3 +1700,48 @@ password. All of these options come from their similarly-named [Django settings]
 #### [`PAPERLESS_EMAIL_USE_SSL=<bool>`](#PAPERLESS_EMAIL_USE_SSL) {#PAPERLESS_EMAIL_USE_SSL}
 
 : Defaults to false.
+
+## AI {#ai}
+
+#### [`PAPERLESS_ENABLE_AI=<bool>`](#PAPERLESS_ENABLE_AI) {#PAPERLESS_ENABLE_AI}
+
+: Enables the AI features in Paperless. This includes the AI-based
+suggestions. This setting is required to be set to true in order to use the AI features.
+
+    Defaults to false.
+
+#### [`PAPERLESS_AI_BACKEND=<str>`](#PAPERLESS_AI_BACKEND) {#PAPERLESS_AI_BACKEND}
+
+: The AI backend to use. This can be either "openai" or "ollama". If set to "ollama", the AI
+features will be run locally on your machine. If set to "openai", the AI features will be run
+using the OpenAI API. This setting is required to be set to use the AI features.
+
+    Defaults to None.
+
+    !!! note
+
+        The OpenAI API is a paid service. You will need to set up an OpenAI account and
+        will be charged for usage incurred by Paperless-ngx features and your document data
+        will (of course) be shared with OpenAI. Paperless-ngx does not endorse the use of the
+        OpenAI API in any way.
+
+        Refer to the OpenAI terms of service, and use at your own risk.
+
+#### [`PAPERLESS_LLM_MODEL=<str>`](#PAPERLESS_LLM_MODEL) {#PAPERLESS_LLM_MODEL}
+
+: The model to use for the AI backend, i.e. "gpt-3.5-turbo", "gpt-4" or any of the models supported by the
+current backend. This setting is required to be set to use the AI features.
+
+    Defaults to None.
+
+#### [`PAPERLESS_LLM_API_KEY=<str>`](#PAPERLESS_LLM_API_KEY) {#PAPERLESS_LLM_API_KEY}
+
+: The API key to use for the AI backend. This is required for the OpenAI backend only.
+
+    Defaults to None.
+
+#### [`PAPERLESS_LLM_URL=<str>`](#PAPERLESS_LLM_URL) {#PAPERLESS_LLM_URL}
+
+: The URL to use for the AI backend. This is required for the Ollama backend only.
+
+    Defaults to None.

docs/index.md

@@ -25,11 +25,12 @@ physical documents into a searchable online archive so you can keep, well, _less
 ## Features
 
 -   **Organize and index** your scanned documents with tags, correspondents, types, and more.
--   _Your_ data is stored locally on _your_ server and is never transmitted or shared in any way.
+-   _Your_ data is stored locally on _your_ server and is never transmitted or shared in any way, unless you explicitly choose to do so.
 -   Performs **OCR** on your documents, adding searchable and selectable text, even to documents scanned with only images.
 -   Utilizes the open-source Tesseract engine to recognize more than 100 languages.
 -   Documents are saved as PDF/A format which is designed for long term storage, alongside the unaltered originals.
 -   Uses machine-learning to automatically add tags, correspondents and document types to your documents.
+-   **New**: Paperless-ngx can now leverage AI (Large Language Models or LLMs) for document suggestions. This is an optional feature that can be enabled (and is disabled by default).
 -   Supports PDF documents, images, plain text files, Office documents (Word, Excel, Powerpoint, and LibreOffice equivalents)[^1] and more.
 -   Paperless stores your documents plain on disk. Filenames and folders are managed by paperless and their format can be configured freely with different configurations assigned to different documents.
 -   **Beautiful, modern web application** that features:

docs/usage.md

@@ -260,6 +260,14 @@ Once setup, navigating to the email settings page in Paperless-ngx will allow yo
 You can also submit a document using the REST API, see [POSTing documents](api.md#file-uploads)
 for details.
 
+## Document Suggestions
+
+Paperless-ngx can suggest tags, correspondents, document types and storage paths for documents based on the content of the document. This is done using a machine learning model that is trained on the documents in your database. The suggestions are shown in the document detail page and can be accepted or rejected by the user.
+
+### AI-Enhanced Suggestions
+
+If enabled, Paperless-ngx can use an AI LLM model to suggest document titles, dates, tags, correspondents and document types for documents. This feature will always be "opt-in" and does not disable the existing suggestion system. Currently, both remote (via the OpenAI API) and local (via Ollama) models are supported, see [configuration](configuration.md#ai) for details.
+
 ## Sharing documents from Paperless-ngx
 
 Paperless-ngx supports sharing documents with other users by assigning them [permissions](#object-permissions)

src-ui/src/app/components/admin/config/config.component.html

@@ -35,6 +35,7 @@
                                                     @case (ConfigOptionType.String) { <pngx-input-text [formControlName]="option.key" [error]="errors[option.key]"></pngx-input-text> }
                                                     @case (ConfigOptionType.JSON) { <pngx-input-text [formControlName]="option.key" [error]="errors[option.key]"></pngx-input-text> }
                                                     @case (ConfigOptionType.File) { <pngx-input-file [formControlName]="option.key" (upload)="uploadFile($event, option.key)" [error]="errors[option.key]"></pngx-input-file> }
+                                                    @case (ConfigOptionType.Password) { <pngx-input-password [formControlName]="option.key" [error]="errors[option.key]"></pngx-input-password> }
                                                 }
                                             </div>
                                         </div>

src-ui/src/app/components/admin/config/config.component.ts

@@ -29,6 +29,7 @@ import { SettingsService } from 'src/app/services/settings.service'
 import { ToastService } from 'src/app/services/toast.service'
 import { FileComponent } from '../../common/input/file/file.component'
 import { NumberComponent } from '../../common/input/number/number.component'
+import { PasswordComponent } from '../../common/input/password/password.component'
 import { SelectComponent } from '../../common/input/select/select.component'
 import { SwitchComponent } from '../../common/input/switch/switch.component'
 import { TextComponent } from '../../common/input/text/text.component'
@@ -46,6 +47,7 @@ import { LoadingComponentWithPermissions } from '../../loading-component/loading
     TextComponent,
     NumberComponent,
     FileComponent,
+    PasswordComponent,
     AsyncPipe,
     NgbNavModule,
     FormsModule,

src-ui/src/app/components/common/input/password/password.component.html

@@ -1,5 +1,11 @@
-<div class="mb-3">
-  <label class="form-label" [for]="inputId">{{title}}</label>
+<div class="mb-3" [class.pb-3]="error">
+  <div class="row">
+    <div class="d-flex align-items-center position-relative hidden-button-container" [class.col-md-3]="horizontal">
+      @if (title) {
+        <label class="form-label" [class.mb-md-0]="horizontal" [for]="inputId">{{title}}</label>
+      }
+    </div>
+  <div class="position-relative" [class.col-md-9]="horizontal">
     <div class="input-group" [class.is-invalid]="error">
       <input #inputField [type]="showReveal && textVisible ? 'text' : 'password'" class="form-control" [class.is-invalid]="error" [id]="inputId" [(ngModel)]="value" (focus)="onFocus()" (focusout)="onFocusOut()" (change)="onChange(value)" [disabled]="disabled" [autocomplete]="autocomplete">
       @if (showReveal) {
@@ -15,3 +21,4 @@
       <small class="form-text text-muted" [innerHTML]="hint | safeHtml"></small>
     }
   </div>
+</div>

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.html

@@ -1,5 +1,5 @@
 <div class="btn-group">
-  <button type="button" class="btn btn-sm btn-outline-primary" (click)="clickSuggest()" [disabled]="loading">
+  <button type="button" class="btn btn-sm btn-outline-primary" (click)="clickSuggest()" [disabled]="loading || (suggestions && !aiEnabled)">
     @if (loading) {
       <div class="spinner-border spinner-border-sm" role="status"></div>
     } @else {
@@ -10,14 +10,20 @@
       <span class="badge bg-primary ms-2">{{ totalSuggestions }}</span>
     }
   </button>
-  <div class="btn-group" ngbDropdown #dropdown="ngbDropdown" [popperOptions]="popperOptions">
 
+  @if (aiEnabled) {
+    <div class="btn-group" ngbDropdown #dropdown="ngbDropdown" [popperOptions]="popperOptions">
       <button type="button" class="btn btn-sm btn-outline-primary" ngbDropdownToggle [disabled]="loading || !suggestions" aria-expanded="false" aria-controls="suggestionsDropdown" aria-label="Suggestions dropdown">
         <span class="visually-hidden" i18n>Show suggestions</span>
       </button>
 
       <div ngbDropdownMenu aria-labelledby="suggestionsDropdown" class="shadow suggestions-dropdown">
-        <div class="list-group list-group-flush small">
+        <div class="list-group list-group-flush small pb-0">
+          @if (!suggestions?.suggested_tags && !suggestions?.suggested_document_types && !suggestions?.suggested_correspondents) {
+            <div class="list-group-item text-muted fst-italic">
+              <small class="text-muted small fst-italic" i18n>No novel suggestions</small>
+            </div>
+          }
           @if (suggestions?.suggested_tags.length > 0) {
             <small class="list-group-item text-uppercase text-muted small">Tags</small>
             @for (tag of suggestions.suggested_tags; track tag) {
@@ -39,4 +45,5 @@
         </div>
       </div>
     </div>
+  }
 </div>

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.spec.ts

@@ -38,6 +38,8 @@ describe('SuggestionsDropdownComponent', () => {
   })
 
   it('should toggle dropdown when clickSuggest is called and suggestions are not null', () => {
+    component.aiEnabled = true
+    fixture.detectChanges()
     component.suggestions = {
       suggested_correspondents: [],
       suggested_tags: [],

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.ts

@@ -24,6 +24,9 @@ export class SuggestionsDropdownComponent {
   @Input()
   suggestions: DocumentSuggestions = null
 
+  @Input()
+  aiEnabled: boolean = false
+
   @Input()
   loading: boolean = false
 
@@ -47,7 +50,7 @@ export class SuggestionsDropdownComponent {
     if (!this.suggestions) {
       this.getSuggestions.emit(this)
     } else {
-      this.dropdown.toggle()
+      this.dropdown?.toggle()
     }
   }
 

src-ui/src/app/components/document-detail/document-detail.component.html

@@ -115,6 +115,7 @@
               [disabled]="!userCanEdit || suggestionsLoading"
               [loading]="suggestionsLoading"
               [suggestions]="suggestions"
+              [aiEnabled]="aiEnabled"
               (getSuggestions)="getSuggestions()"
               (addTag)="createTag($event)"
               (addDocumentType)="createDocumentType($event)"

src-ui/src/app/components/document-detail/document-detail.component.ts

@@ -299,6 +299,10 @@ export class DocumentDetailComponent
     return this.settings.get(SETTINGS_KEYS.USE_NATIVE_PDF_VIEWER)
   }
 
+  get aiEnabled(): boolean {
+    return this.settings.get(SETTINGS_KEYS.AI_ENABLED)
+  }
+
   get archiveContentRenderType(): ContentRenderType {
     return this.document?.archived_file_name
       ? this.getRenderType('application/pdf')

src-ui/src/app/data/paperless-config.ts

@@ -44,11 +44,18 @@ export enum ConfigOptionType {
   Boolean = 'boolean',
   JSON = 'json',
   File = 'file',
+  Password = 'password',
 }
 
 export const ConfigCategory = {
   General: $localize`General Settings`,
   OCR: $localize`OCR Settings`,
+  AI: $localize`AI Settings`,
+}
+
+export const LLMBackendConfig = {
+  OPENAI: 'openai',
+  OLLAMA: 'ollama',
 }
 
 export interface ConfigOption {
@@ -180,6 +187,42 @@ export const PaperlessConfigOptions: ConfigOption[] = [
     config_key: 'PAPERLESS_APP_TITLE',
     category: ConfigCategory.General,
   },
+  {
+    key: 'ai_enabled',
+    title: $localize`AI Enabled`,
+    type: ConfigOptionType.Boolean,
+    config_key: 'PAPERLESS_AI_ENABLED',
+    category: ConfigCategory.AI,
+  },
+  {
+    key: 'llm_backend',
+    title: $localize`LLM Backend`,
+    type: ConfigOptionType.Select,
+    choices: mapToItems(LLMBackendConfig),
+    config_key: 'PAPERLESS_LLM_BACKEND',
+    category: ConfigCategory.AI,
+  },
+  {
+    key: 'llm_model',
+    title: $localize`LLM Model`,
+    type: ConfigOptionType.String,
+    config_key: 'PAPERLESS_LLM_MODEL',
+    category: ConfigCategory.AI,
+  },
+  {
+    key: 'llm_api_key',
+    title: $localize`LLM API Key`,
+    type: ConfigOptionType.Password,
+    config_key: 'PAPERLESS_LLM_API_KEY',
+    category: ConfigCategory.AI,
+  },
+  {
+    key: 'llm_url',
+    title: $localize`LLM URL`,
+    type: ConfigOptionType.String,
+    config_key: 'PAPERLESS_LLM_URL',
+    category: ConfigCategory.AI,
+  },
 ]
 
 export interface PaperlessConfig extends ObjectWithId {
@@ -198,4 +241,9 @@ export interface PaperlessConfig extends ObjectWithId {
   user_args: object
   app_logo: string
   app_title: string
+  ai_enabled: boolean
+  llm_backend: string
+  llm_model: string
+  llm_api_key: string
+  llm_url: string
 }

src-ui/src/app/data/ui-settings.ts

@@ -73,6 +73,7 @@ export const SETTINGS_KEYS = {
   GMAIL_OAUTH_URL: 'gmail_oauth_url',
   OUTLOOK_OAUTH_URL: 'outlook_oauth_url',
   EMAIL_ENABLED: 'email_enabled',
+  AI_ENABLED: 'ai_enabled',
 }
 
 export const SETTINGS: UiSetting[] = [
@@ -276,4 +277,9 @@ export const SETTINGS: UiSetting[] = [
     type: 'string',
     default: 'page-width', // ZoomSetting from 'document-detail.component'
   },
+  {
+    key: SETTINGS_KEYS.AI_ENABLED,
+    type: 'boolean',
+    default: false,
+  },
 ]

src/documents/tests/test_api_app_config.py

@@ -31,10 +31,9 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
         response = self.client.get(self.ENDPOINT, format="json")
 
         self.assertEqual(response.status_code, status.HTTP_200_OK)
-
-        self.assertEqual(
-            json.dumps(response.data[0]),
-            json.dumps(
+        self.maxDiff = None
+        self.assertDictEqual(
+            response.data[0],
             {
                 "id": 1,
                 "user_args": None,
@@ -52,8 +51,12 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
                 "color_conversion_strategy": None,
                 "app_title": None,
                 "app_logo": None,
+                "ai_enabled": False,
+                "llm_backend": None,
+                "llm_model": None,
+                "llm_api_key": None,
+                "llm_url": None,
             },
-            ),
         )
 
     def test_api_get_ui_settings_with_config(self):

src/documents/tests/test_api_uisettings.py

@@ -47,6 +47,7 @@ class TestApiUiSettings(DirectoriesMixin, APITestCase):
                     "backend_setting": "default",
                 },
                 "email_enabled": False,
+                "ai_enabled": False,
             },
         )
 

src/documents/views.py

@@ -177,6 +177,7 @@ from paperless.ai.matching import match_document_types_by_name
 from paperless.ai.matching import match_storage_paths_by_name
 from paperless.ai.matching import match_tags_by_name
 from paperless.celery import app as celery_app
+from paperless.config import AIConfig
 from paperless.config import GeneralConfig
 from paperless.db import GnuPG
 from paperless.serialisers import GroupSerializer
@@ -738,10 +739,12 @@ class DocumentViewSet(
         ):
             return HttpResponseForbidden("Insufficient permissions")
 
-        if settings.AI_ENABLED:
+        ai_config = AIConfig()
+
+        if ai_config.ai_enabled:
             cached_llm_suggestions = get_llm_suggestion_cache(
                 doc.pk,
-                backend=settings.LLM_BACKEND,
+                backend=ai_config.llm_backend,
             )
 
             if cached_llm_suggestions:
@@ -792,7 +795,7 @@ class DocumentViewSet(
                 "dates": llm_suggestions.get("dates", []),
             }
 
-            set_llm_suggestions_cache(doc.pk, resp_data, backend=settings.LLM_BACKEND)
+            set_llm_suggestions_cache(doc.pk, resp_data, backend=ai_config.llm_backend)
         else:
             document_suggestions = get_suggestion_cache(doc.pk)
 
@@ -2221,6 +2224,10 @@ class UiSettingsView(GenericAPIView):
 
         ui_settings["email_enabled"] = settings.EMAIL_ENABLED
 
+        ai_config = AIConfig()
+
+        ui_settings["ai_enabled"] = ai_config.ai_enabled
+
         user_resp = {
             "id": user.id,
             "username": user.username,

src/paperless/ai/ai_classifier.py

@@ -2,7 +2,7 @@ import json
 import logging
 
 from documents.models import Document
-from paperless.ai.client import run_llm_query
+from paperless.ai.client import AIClient
 
 logger = logging.getLogger("paperless.ai.ai_classifier")
 
@@ -49,7 +49,8 @@ def get_ai_document_classification(document: Document) -> dict:
     """
 
     try:
-        result = run_llm_query(prompt)
+        client = AIClient()
+        result = client.run_llm_query(prompt)
         suggestions = parse_ai_classification_response(result)
         return suggestions or {}
     except Exception:

src/paperless/ai/client.py

@@ -1,34 +1,45 @@
 import logging
 
 import httpx
-from django.conf import settings
+
+from paperless.config import AIConfig
 
 logger = logging.getLogger("paperless.ai.client")
 
 
-def run_llm_query(prompt: str) -> str:
+class AIClient:
+    """
+    A client for interacting with an LLM backend.
+    """
+
+    def __init__(self):
+        self.settings = AIConfig()
+
+    def run_llm_query(self, prompt: str) -> str:
         logger.debug(
             "Running LLM query against %s with model %s",
-        settings.LLM_BACKEND,
-        settings.LLM_MODEL,
+            self.settings.llm_backend,
+            self.settings.llm_model,
         )
-    match settings.LLM_BACKEND:
+        match self.settings.llm_backend:
             case "openai":
-            result = _run_openai_query(prompt)
+                result = self._run_openai_query(prompt)
             case "ollama":
-            result = _run_ollama_query(prompt)
+                result = self._run_ollama_query(prompt)
             case _:
-            raise ValueError(f"Unsupported LLM backend: {settings.LLM_BACKEND}")
+                raise ValueError(
+                    f"Unsupported LLM backend: {self.settings.llm_backend}",
+                )
         logger.debug("LLM query result: %s", result)
         return result
 
-
-def _run_ollama_query(prompt: str) -> str:
+    def _run_ollama_query(self, prompt: str) -> str:
+        url = self.settings.llm_url or "http://localhost:11434"
         with httpx.Client(timeout=30.0) as client:
             response = client.post(
-            f"{settings.OLLAMA_URL}/api/chat",
+                f"{url}/api/chat",
                 json={
-                "model": settings.LLM_MODEL,
+                    "model": self.settings.llm_model,
                     "messages": [{"role": "user", "content": prompt}],
                     "stream": False,
                 },
@@ -36,20 +47,21 @@ def _run_ollama_query(prompt: str) -> str:
             response.raise_for_status()
             return response.json()["message"]["content"]
 
-
-def _run_openai_query(prompt: str) -> str:
-    if not settings.LLM_API_KEY:
+    def _run_openai_query(self, prompt: str) -> str:
+        if not self.settings.llm_api_key:
             raise RuntimeError("PAPERLESS_LLM_API_KEY is not set")
 
+        url = self.settings.llm_url or "https://api.openai.com"
+
         with httpx.Client(timeout=30.0) as client:
             response = client.post(
-            f"{settings.OPENAI_URL}/v1/chat/completions",
+                f"{url}/v1/chat/completions",
                 headers={
-                "Authorization": f"Bearer {settings.LLM_API_KEY}",
+                    "Authorization": f"Bearer {self.settings.llm_api_key}",
                     "Content-Type": "application/json",
                 },
                 json={
-                "model": settings.LLM_MODEL,
+                    "model": self.settings.llm_model,
                     "messages": [{"role": "user", "content": prompt}],
                     "temperature": 0.3,
                 },

src/paperless/config.py

@@ -114,3 +114,25 @@ class GeneralConfig(BaseConfig):
 
         self.app_title = app_config.app_title or None
         self.app_logo = app_config.app_logo.url if app_config.app_logo else None
+
+
+@dataclasses.dataclass
+class AIConfig(BaseConfig):
+    """
+    AI related settings that require global scope
+    """
+
+    ai_enabled: bool = dataclasses.field(init=False)
+    llm_backend: str = dataclasses.field(init=False)
+    llm_model: str = dataclasses.field(init=False)
+    llm_api_key: str = dataclasses.field(init=False)
+    llm_url: str = dataclasses.field(init=False)
+
+    def __post_init__(self) -> None:
+        app_config = self._get_config_instance()
+
+        self.ai_enabled = app_config.ai_enabled or settings.AI_ENABLED
+        self.llm_backend = app_config.llm_backend or settings.LLM_BACKEND
+        self.llm_model = app_config.llm_model or settings.LLM_MODEL
+        self.llm_api_key = app_config.llm_api_key or settings.LLM_API_KEY
+        self.llm_url = app_config.llm_url or settings.LLM_URL

src/paperless/migrations/0004_applicationconfiguration_ai_enabled_and_more.py

@@ -0,0 +1,63 @@
+# Generated by Django 5.1.7 on 2025-04-24 02:09
+
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("paperless", "0003_alter_applicationconfiguration_max_image_pixels"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="applicationconfiguration",
+            name="ai_enabled",
+            field=models.BooleanField(
+                default=False,
+                null=True,
+                verbose_name="Enables AI features",
+            ),
+        ),
+        migrations.AddField(
+            model_name="applicationconfiguration",
+            name="llm_api_key",
+            field=models.CharField(
+                blank=True,
+                max_length=128,
+                null=True,
+                verbose_name="Sets the LLM API key",
+            ),
+        ),
+        migrations.AddField(
+            model_name="applicationconfiguration",
+            name="llm_backend",
+            field=models.CharField(
+                blank=True,
+                choices=[("openai", "OpenAI"), ("ollama", "Ollama")],
+                max_length=32,
+                null=True,
+                verbose_name="Sets the LLM backend",
+            ),
+        ),
+        migrations.AddField(
+            model_name="applicationconfiguration",
+            name="llm_model",
+            field=models.CharField(
+                blank=True,
+                max_length=32,
+                null=True,
+                verbose_name="Sets the LLM model",
+            ),
+        ),
+        migrations.AddField(
+            model_name="applicationconfiguration",
+            name="llm_url",
+            field=models.CharField(
+                blank=True,
+                max_length=128,
+                null=True,
+                verbose_name="Sets the LLM URL, optional",
+            ),
+        ),
+    ]

src/paperless/models.py

@@ -74,6 +74,15 @@ class ColorConvertChoices(models.TextChoices):
     CMYK = ("CMYK", _("CMYK"))
 
 
+class LLMBackend(models.TextChoices):
+    """
+    Matches to --llm-backend
+    """
+
+    OPENAI = ("openai", _("OpenAI"))
+    OLLAMA = ("ollama", _("Ollama"))
+
+
 class ApplicationConfiguration(AbstractSingletonModel):
     """
     Settings which are common across more than 1 parser
@@ -184,6 +193,45 @@ class ApplicationConfiguration(AbstractSingletonModel):
         upload_to="logo/",
     )
 
+    """
+    AI related settings
+    """
+
+    ai_enabled = models.BooleanField(
+        verbose_name=_("Enables AI features"),
+        null=True,
+        default=False,
+    )
+
+    llm_backend = models.CharField(
+        verbose_name=_("Sets the LLM backend"),
+        null=True,
+        blank=True,
+        max_length=32,
+        choices=LLMBackend.choices,
+    )
+
+    llm_model = models.CharField(
+        verbose_name=_("Sets the LLM model"),
+        null=True,
+        blank=True,
+        max_length=32,
+    )
+
+    llm_api_key = models.CharField(
+        verbose_name=_("Sets the LLM API key"),
+        null=True,
+        blank=True,
+        max_length=128,
+    )
+
+    llm_url = models.CharField(
+        verbose_name=_("Sets the LLM URL, optional"),
+        null=True,
+        blank=True,
+        max_length=128,
+    )
+
     class Meta:
         verbose_name = _("paperless application settings")
 

src/paperless/serialisers.py

@@ -185,6 +185,10 @@ class ProfileSerializer(serializers.ModelSerializer):
 
 class ApplicationConfigurationSerializer(serializers.ModelSerializer):
     user_args = serializers.JSONField(binary=True, allow_null=True)
+    llm_api_key = ObfuscatedPasswordField(
+        required=False,
+        allow_null=True,
+    )
 
     def run_validation(self, data):
         # Empty strings treated as None to avoid unexpected behavior

src/paperless/settings.py

@@ -1275,5 +1275,4 @@ AI_ENABLED = __get_boolean("PAPERLESS_AI_ENABLED", "NO")
 LLM_BACKEND = os.getenv("PAPERLESS_LLM_BACKEND", "openai")  # or "ollama"
 LLM_MODEL = os.getenv("PAPERLESS_LLM_MODEL")
 LLM_API_KEY = os.getenv("PAPERLESS_LLM_API_KEY")
-OPENAI_URL = os.getenv("PAPERLESS_OPENAI_URL", "https://api.openai.com")
-OLLAMA_URL = os.getenv("PAPERLESS_OLLAMA_URL", "http://localhost:11434")
+LLM_URL = os.getenv("PAPERLESS_LLM_URL")

src/paperless/tests/test_ai_classifier.py

@@ -13,7 +13,8 @@ def mock_document():
     return Document(filename="test.pdf", content="This is a test document content.")
 
 
-@patch("paperless.ai.ai_classifier.run_llm_query")
+@pytest.mark.django_db
+@patch("paperless.ai.client.AIClient.run_llm_query")
 def test_get_ai_document_classification_success(mock_run_llm_query, mock_document):
     mock_response = json.dumps(
         {
@@ -37,7 +38,8 @@ def test_get_ai_document_classification_success(mock_run_llm_query, mock_documen
     assert result["dates"] == ["2023-01-01"]
 
 
-@patch("paperless.ai.ai_classifier.run_llm_query")
+@pytest.mark.django_db
+@patch("paperless.ai.client.AIClient.run_llm_query")
 def test_get_ai_document_classification_failure(mock_run_llm_query, mock_document):
     mock_run_llm_query.side_effect = Exception("LLM query failed")
 

src/paperless/tests/test_ai_client.py

@@ -4,9 +4,7 @@ from unittest.mock import patch
 import pytest
 from django.conf import settings
 
-from paperless.ai.client import _run_ollama_query
-from paperless.ai.client import _run_openai_query
-from paperless.ai.client import run_llm_query
+from paperless.ai.client import AIClient
 
 
 @pytest.fixture
@@ -14,52 +12,59 @@ def mock_settings():
     settings.LLM_BACKEND = "openai"
     settings.LLM_MODEL = "gpt-3.5-turbo"
     settings.LLM_API_KEY = "test-api-key"
-    settings.OPENAI_URL = "https://api.openai.com"
-    settings.OLLAMA_URL = "https://ollama.example.com"
     yield settings
 
 
-@patch("paperless.ai.client._run_openai_query")
-@patch("paperless.ai.client._run_ollama_query")
+@pytest.mark.django_db
+@patch("paperless.ai.client.AIClient._run_openai_query")
+@patch("paperless.ai.client.AIClient._run_ollama_query")
 def test_run_llm_query_openai(mock_ollama_query, mock_openai_query, mock_settings):
+    mock_settings.LLM_BACKEND = "openai"
     mock_openai_query.return_value = "OpenAI response"
-    result = run_llm_query("Test prompt")
+    client = AIClient()
+    result = client.run_llm_query("Test prompt")
     assert result == "OpenAI response"
     mock_openai_query.assert_called_once_with("Test prompt")
     mock_ollama_query.assert_not_called()
 
 
-@patch("paperless.ai.client._run_openai_query")
-@patch("paperless.ai.client._run_ollama_query")
+@pytest.mark.django_db
+@patch("paperless.ai.client.AIClient._run_openai_query")
+@patch("paperless.ai.client.AIClient._run_ollama_query")
 def test_run_llm_query_ollama(mock_ollama_query, mock_openai_query, mock_settings):
     mock_settings.LLM_BACKEND = "ollama"
     mock_ollama_query.return_value = "Ollama response"
-    result = run_llm_query("Test prompt")
+    client = AIClient()
+    result = client.run_llm_query("Test prompt")
     assert result == "Ollama response"
     mock_ollama_query.assert_called_once_with("Test prompt")
     mock_openai_query.assert_not_called()
 
 
+@pytest.mark.django_db
 def test_run_llm_query_unsupported_backend(mock_settings):
     mock_settings.LLM_BACKEND = "unsupported"
+    client = AIClient()
     with pytest.raises(ValueError, match="Unsupported LLM backend: unsupported"):
-        run_llm_query("Test prompt")
+        client.run_llm_query("Test prompt")
 
 
+@pytest.mark.django_db
 def test_run_openai_query(httpx_mock, mock_settings):
+    mock_settings.LLM_BACKEND = "openai"
     httpx_mock.add_response(
-        url=f"{mock_settings.OPENAI_URL}/v1/chat/completions",
+        url="https://api.openai.com/v1/chat/completions",
         json={
             "choices": [{"message": {"content": "OpenAI response"}}],
         },
     )
 
-    result = _run_openai_query("Test prompt")
+    client = AIClient()
+    result = client.run_llm_query("Test prompt")
     assert result == "OpenAI response"
 
     request = httpx_mock.get_request()
     assert request.method == "POST"
-    assert request.url == f"{mock_settings.OPENAI_URL}/v1/chat/completions"
     assert request.headers["Authorization"] == f"Bearer {mock_settings.LLM_API_KEY}"
     assert request.headers["Content-Type"] == "application/json"
     assert json.loads(request.content) == {
@@ -69,18 +74,20 @@ def test_run_openai_query(httpx_mock, mock_settings):
     }
 
 
+@pytest.mark.django_db
 def test_run_ollama_query(httpx_mock, mock_settings):
+    mock_settings.LLM_BACKEND = "ollama"
     httpx_mock.add_response(
-        url=f"{mock_settings.OLLAMA_URL}/api/chat",
+        url="http://localhost:11434/api/chat",
         json={"message": {"content": "Ollama response"}},
     )
 
-    result = _run_ollama_query("Test prompt")
+    client = AIClient()
+    result = client.run_llm_query("Test prompt")
     assert result == "Ollama response"
 
     request = httpx_mock.get_request()
     assert request.method == "POST"
-    assert request.url == f"{mock_settings.OLLAMA_URL}/api/chat"
     assert json.loads(request.content) == {
         "model": mock_settings.LLM_MODEL,
         "messages": [{"role": "user", "content": "Test prompt"}],