Improvement: Make all parts of the prompt visible and configurable

[saladpanda]

Is your feature request related to a problem? Please describe.
While trying to optimize the prompt for best results i noticed that several hardcoded parts are added to the promt.
Examples:

• https://github.com/clusterzx/paperless-ai/blob/main/config/config.js#L62
• https://github.com/clusterzx/paperless-ai/blob/main/config/config.js#L77
• https://github.com/clusterzx/paperless-ai/blob/main/services/openaiService.js#L125
• https://github.com/clusterzx/paperless-ai/blob/main/services/openaiService.js#L138
• https://github.com/clusterzx/paperless-ai/blob/main/services/openaiService.js#L151
• https://github.com/clusterzx/paperless-ai/blob/main/services/openaiService.js#L261

It is not obvious to a user what exactly gets sent to the AI and therefore hard to adjust the prompt for the desired results.
E.g. I want to tell the AI to limit itself to only the preexisting tags. Knowing that they are prependet to the prompt here would have helped with this.

Further, these hardcoded elements are in english. I wanted to try whether a german prompt would give me better results, but the hardcoded parts will still remain english.

Describe the solution you'd like
I suggest making the full prompt configurable on the settings page.
Consider introducing variables for "preexisting tags" and "preexisting correspondents" similar to what paperless-gpt uses:
https://github.com/icereed/paperless-gpt?tab=readme-ov-file#custom-prompt-templates

For the part explaining the JSON output format to the AI you could use a separate box that only becomes editable when the user confirms they know what they are doing because this format is important for the implementation.

Describe alternatives you've considered

• I could edit the hardcoded prompt elements in the code and build my own docker container, but that wouldn't help others.

[clusterzx]

If you do this it will open the door to hell for issues here in the repo. So many users are already overwhelmed with the pre-existing options.

I wont imagine what will happen if you let the user full control over the JSON structure.

[saladpanda]

Agreed regarding the JSON structure :-D.

But I still think it would be benefitial to make the other hardcoded parts configurable.
And adding a notice to the settings page about what exactly gets added to the prompt would be helpful as well.

[micmart]

To mitigate to some extent, this feature could be hidden by default and only visible when the user enables "advanced features".

My use case is that I would like to edit the prompt for title generation to limit the title to e.g. 20 characters or 3 words max.

[Magelan88]

I was looking for exactly the same feature - while I also see your point, @clusterzx regarding complexity.
I was actually hoping i could give a description for all tags in papaerless and they would eb transfered over, but that does not seem to be supported by paperless. Now my idea would be to hard-code the tags and their meaning into the prompt. For that I would also be curious to have the entire output of the prompt sent to the LLM, so I can understand its structure. I really like the idea of the advanced mode.

[WildEchoWanderer]

i am coming from paperless-gpt and would love to have a similar prompting option. I got acceptable-to-good results with ollama (qwen3:8b) and paperless-gpt

i try to replicate the setup with paperless-ai but it does not take the already existing tags from paperless-ngx. How can i achieve it, to most likely take already existing tags & correspondents instead of making new ones?

[jcurtis260]

Love the work you have done, its amazing and made my life so much easier to use paperless. In regards to this discussion would it be an idea to have all the advanced options like this hidden under and tick box or tab with advanced settings? This allows the responsibility of the user to change the settings if they feel the need to. Also if you go down this route maybe a reset to factory settings just incase you mess it up.

[swdit]

Having a proper frontend for my naming automation would be my reas #1 to employ paperles-ai.
Therefore easy access to the prompts would be a must have to me.

I do have a tinkered Python Script doing the renaming at the moment.
It is a mess and far less pretty that Paperless-AI but the results are far better (at least consindering my wishes for OCR'ed german documents).

For example with paperless-ai a lot of documents just get namend "Rechnung" (invoice) and if the word is capitalized in the Document ist is "RECHNUNG" but not equalized to "Rechnung" besides that it is just a repitition of the Doc-Type.
It does not even differenciate terminology between inbound and outbound invoices.
In my world "invoice_phone_jan-2025" would be a helpfull name the current naming are far to generic.

I used gemma 2 9b for this task as it delivered by far the most robust results on naming german documents in my tests.

I have ran lots of tests on the same documents at tweaked settings and rated their naming.
Thats what I learned ranked by priority.

1. Most important is the prompt
2. Providing the original file name, as it often provides context ("scan001.pdf" vs. "invoice_phone_jan-2025" )
3. Giberish removal (running a script upfront removing OCR-caused trash text)

The biggest benefit is a summary from a multimodal LLM on a image of the documents first page.
However this is a different level of token und ressource usage and therefore not in my upper list.

[WildEchoWanderer]

This renamer python script sounds like i could use it. May you share it?

[0x000015]

In my opinion the way the RAG chat, or in general all AI related tasks should be able to be contextually aware of what exists in whatever tag/document type/correspondent as needed. A good example of this I feel would be Cline where it can inform the model to properly use 'tools' such as searching/editing/reading files with multi prompts.

I'm not sure how to explain this outside of just using multiple prompts to build up to a final/ideal document with references from other already tagged documents.

An issue I notice a lot due to the lack of this feature is where documents from the same company such as vehicle repair invoices will have slight variations of the document name despite containing the relatively same info.

issue example:

Invoice - [MY NAME] [TOTAL DUE]
Service Order - [CAR MODEL]
Invoice from [COMPANY NAME]

A way for the model to see what already exists for the company or similar documents would be ideal to fix this I believe.