Grand refactoring of the AI features

CHANGELOG.md

@@ -11,6 +11,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv
 
 ### Added
 
+- We added support for selecting answer engines and summarization algorithms, allowing users to change the underlying AI behavior. [#15688](https://github.com/JabRef/jabref/pull/15688)
 - The citation key generator also normalizes super and subscript characters. [#15743](https://github.com/JabRef/jabref/pull/15743)
 - We added automatic source groups to SLR results and fixed group merging to preserve all source groups. [#12542](https://github.com/JabRef/jabref/issues/12542)
 - We enabled usage of relative or absolute file paths depending on your file directory settings. [#3590](https://github.com/JabRef/jabref/issues/3590)

build.gradle.kts

@@ -51,6 +51,18 @@ requirementTracing {
             "jabsrv/src/test/java"
         )
     )
+
+	filteredArtifactTypes =
+        listOf(
+            "impl",
+            "utest",
+            "model",
+            "guard",
+            "pp",
+            "feat",
+            "req"
+		)
+
     // TODO: Short Tag Importer: https://github.com/itsallcode/openfasttrace-gradle#configuring-the-short-tag-importer
 }
 

docs/code-howtos/ai.md

@@ -4,29 +4,101 @@ parent: Code Howtos
 
 # AI
 
-The AI feature of JabRef is built on [LangChain4j](https://github.com/langchain4j/langchain4j) and [Deep Java Library](https://djl.ai/).
+The JabRef has next AI features:
+
+- Chatting with entries,
+- Chatting with groups,
+- Summarization of entries,
+- Parsing of plain citations using LLMs
+- Extracting "References" section from PDFs with the help of LLMs.
+
+The features are built on [LangChain4j](https://github.com/langchain4j/langchain4j) and [Deep Java Library](https://djl.ai/).
 
 ## Architectural Decisions
 
-See [ADR-0037](../decisions/0037-rag-architecture-implementation.md) for the decision regarding the RAG infrastructure.
+See [ADR-0037](./../decisions/0037-rag-architecture-implementation.md) for the decision regarding the RAG infrastructure.
+
+The [ADR-0032](./../decisions/0032-store-chats-in-local-user-folder.md) and [ADR-0033](./../decisions/0033-store-chats-in-mvstore.md) are important ones, because they explain the decisions regarding the storage of AI artifacts (summaries, chat histories, embeddings, etc.).
+
+## Requirements
+
+See [the requirements page of AI features](./../requirements/ai.md).
+
+## Features
+
+### Feature "Chat with PDF(s)"
 
-## Feature "Chat with PDF(s)"
+The interface with all of the features (chat history, regeneration, follow up questions, etc.) is implemented in the class [org.jabref.gui.ai.chat.AiChatView]. From there, one will find preferences and other required infrastructure.
 
-This is implemented mainly in the class [org.jabref.logic.ai.chatting.AiChatLogic].
-From there, one will find preferences and other required infrastructure.
+The RAG entry point is located in [org.jabref.logic.ai.chatting.tasks.GenerateRagResponseTask].
 
-## Feature "Summarize PDF(s)"
+### Feature "Summarize PDF(s)"
 
-This is implemented in the class [org.jabref.logic.ai.summarization.GenerateSummaryTask].
+This is implemented in the class [org.jabref.logic.ai.summarization.tasks.GenerateSummaryTask].
 
-## Feature "BibTeX from Reference Text"
+### Feature "BibTeX from Reference Text"
 
 The general interface is [org.jabref.logic.importer.plaincitation.PlainCitationParser].
 The class implementing it using AI is [org.jabref.logic.importer.plaincitation.LlmPlainCitationParser].
 
-## Feature "Reference Extractor"
+### Feature "Reference Extractor"
 
 Extracts the list of references (Section ["References"](../glossary/references.md)) from the last page of the PDF to a List of BibEntry.
 
 The general interface is [org.jabref.logic.importer.fileformat.pdf.BibliographyFromPdfImporter].
 The class implementing it using AI is [org.jabref.logic.importer.plaincitation.LlmPlainCitationParser].
+
+## Code organization
+
+As every JabRef feature, AI is divided into 3 layers: GUI, logic, and model. Inside the `logic` package the AI code is split by feature (each feature has its own package).
+
+The GUI code strongly follows [MVVM pattern](./javafx.md). Though, the GUI code is a bit complicated as:
+
+1. Most of the core GUI components (chat and summary components) are designed as a state machine. Typical states include: loading, presenting the result, error, etc.
+2. These core GUI components are also made that way so it would be possible to rebind them to another `BibEntry`. For the details, take a look at the section [How to add a new AI feature](## How to add a new AI feature).
+
+## Internal model (v2)
+
+There are 3 core models in the AI features:
+
+1. Chat history.
+2. Summaries.
+3. Embeddings.
+4. Fully ingested documents.
+
+The code strictly follows the repository pattern, where an interface is created to access the internal storage for the purpose of abstraction. At the moment of writing, all of these models are implemented by using the [`MVStore`](https://www.h2database.com/html/mvstore.html). For the details of this decisions take a look at the [ADR 0033](./../decisions/0033-store-chats-in-mvstore.md). A helper class was made `MVStoreBase` so that it would be possible to use an in-memory `MVStore` in case there are some errors while opening on-disk storage.
+
+A note needs to be made for embeddings: the embeddings storage is also implementing the internal LangChain4j interface for embeddings so that it could be used in LangChain4j algorithms. Additionally, there is a "fully ingested" repository, which simply contains a "list" of files that were fully ingested. This helps with checking if a file needs to be ingested or not, as there is no 1 to 1 correspondense with embeddings to file (which is many to one).
+
+Because JabRef is not build around one global database, but rather it is a `.bib` file editor, a problem of identifying a `BibEntry` arose and it was solved in a somewhat complicated way:
+
+- In order to uniquely identify a library, an "AI library ID" was introduced (as a metadata field), which is just a UUID. An alternative would be to use the library path, but if the library moves, the path changes, but AI library ID is not.
+- In order to uniquely identify an entry, the citation key is used, but only if it is non-empty and unique.
+- In some cases (that arise potentially often), the conditions above are not met (for example, a library is not saved - it does not have a path, or an entry does not have a citation key), however user is actively working on an entry. In this case the AI features have an *in-memory cache layer*. So whenever a chat or a summary is created for an entry, it is firstly interacted with the in-memory storage layer. The cache is flushed to the on-disk storage at the close of the JabRef.
+- In order to uniquely identify a file, we use the file hash. An alternative would be to use the file path, but the file could be moved, or defined by a relative path. This is also useful when several libraries cite the same paper, and instead of ingesting
+
+## [OLD] Internal model (v1)
+
+The model v1 differs from v2 by:
+
+1. Fields of the chat messages and summaries were differently organized in the `MVStore`.
+2. A `LinkedFile#getLink()` was used to identify a file.
+
+To migrate from v1 to v2, the classes `ChatHistoryMigrationV1` and `SummariesMigrationV2` were made.
+
+## How to add a new AI feature
+
+This section describes the standard pattern used for AI features. If should follow a similar plan:
+
+1. Define the model of the artifact of your feature (for example, for summarization it is an AI summary, for chatting they are chat messages and chat history).
+2. Define a repository interface (e.g. `SummaryRepository`, `ChatHistoryRepository`) and implement an `MVStore` implementation using the [org.jabref.logic.ai.util.MVStoreBase].
+3. Define a logic class in the `logic` package: either a task (e.g. `GenerateSummaryTask` or a utility class for performing an AI feature. It is recommended to make it "without side-effects" (it does not change or write anything in the system). Firstly, this will help in testing the class, and, secondly, the storage is typically hanlded in *in-memory cache* layer, that will be discussed next.
+4. Make an in-memory cache storage layer for your feature that has a RAM map between a `BibEntry` (or a group, or some other object that your artifact is linked to) and your model. Sometimes this can be omitted (for example, embeddings do not have the in-memory cache and always use a repository), but generally it is made in order to always have access to the AI feature even if some precondition is not satisfied (for example, storing chat history and summmaries requires that there is a database path and a non-empty unique citation key, but in-memory layer allows to work with them as is). At the close of JabRef (or a library) the in-memory cache layer will check the preconditions and only then write the data to the repository.
+5. Make a `TaskAggregator` class. This is needed in order to be able to switch a component between entries and to deduplicate the tasks. So whenever you want to generate the artifact of your feature, you need to always communicate to the `TaskAggregator` class which will either create a new task or give you an already running one. The `TaskAggregator` also connects the results to the in-memory cache.
+
+The next points are targeted to the GUI of the feature:
+
+1. Design a component using the MVVM pattern. You need to write the interface in the FXML, then write a controller `Ai<Feature>View` and a view-model `Ai<Feature>ViewModel`.
+2. A typical AI component will be a state machine: first and foremost, check if the AI features are enabled in JabRef (which equals to accepting a privacy policy of AI features). If not, then you must ensure that you component does nothing. To show the privacy policy banner, there is a dedicated component [org.jabref.gui.ai.AiPrivacyNoticeView]. The next states typically envolve checking some preconditions (for example, you can not summarize an entry, if it does not have linked files), and the final is the working state. You might find the [org.jabref.gui.util.BindingsHelper#bindEnum] useful.
+3. The entry editor tabs are designed to be switchable (rebound to some other `BibEntry`), so you can have an `entryProperty` and whenver it is changed, the state machine of the component is rerun.
+4. When you read an artifact for an entry (or a group, or other entity that is linked to your AI feature), the look-up should be made in 3 steps: look into the repository, look in to the in-memory cache, and only then contact the `TaskAggregator` to start a new generation task.

docs/decisions/0033-store-chats-in-mvstore.md

@@ -4,6 +4,8 @@ parent: Decision Records
 ---
 
 # Store Chats in MVStore
+<!-- dsn->req~ai.summarization.general.storage~1 -->
+<!-- dsn->req~ai.chat.entries.history-storage~1 -->
 
 ## Context and Problem Statement
 
@@ -51,3 +53,7 @@ Chosen option: "MVStore", because it is simple and memory-efficient.
 * Good, because we have the full control
 * Bad, because involves writing our own language and parser
 * Bad, because we need to implement optimizations found in databases on our own (storing some data in RAM, other on disk)
+
+## More information
+
+For the same logic, the summaries are stored in MVStore.

docs/decisions/0036-use-textarea-for-chat-content.md → docs/decisions/0036-use-markdown-for-chat-content.md

@@ -3,7 +3,7 @@ nav_order: 0036
 parent: Decision Records
 ---
 
-# Use `TextArea` for Chat Message Content
+# Use Markdown rendering for Chat Message Content
 
 ## Context and Problem Statement
 
@@ -25,10 +25,8 @@ This decision record concerns the UI component that is used for rendering the co
 
 ## Decision Outcome
 
-Chosen option: "Use `TextArea`".
-All other options require more time to implement.
-Some of the options do not support text selection and copying,
-which for now we value more than Markdown rendering.
+Chosen option: (modified) "Use a Markdown parser and convert AST nodes to JavaFX TextFlow elements".
+In JabRef there is a component `SelectableTextFlow` which allows to create a formatted text and to select it. This makes possible to use a Markdown parser that converts the content into JavaFX nodes and adds the feature selecting the text.
 
 ## Pros and Cons of the Options
 

docs/decisions/0058-use-djl-for-embeddings.md

@@ -0,0 +1,65 @@
+---
+nav_order: 0058
+parent: Decision Records
+---
+# Use Deep Java Library for embeddings in AI features
+
+<!-- dsn->feat~ai.answer-engines.embeddings-search~1 -->
+
+## Context and Problem Statement
+
+JabRef needs to use embedding models to perform Retrieval-Augmented Generation (RAG) by generating embeddings for chunks of papers.
+
+The Java AI ecosystem is not as diverse as the Python AI ecosystem, so the choice must be careful to ensure stability and ease of use for end users.
+
+Which library to choose?
+
+## Decision Drivers
+
+* The library should not require additional setup from the user side
+* It should be cross-platform
+* It should support a wide variety of model architectures
+* It should have an easy-to-use API
+* The request that the library makes should be known and controlled
+* We should know how and where the library downloads and stores models
+
+## Considered Options
+
+* LangChain4j
+* ONNX Runtime
+* Deep Java Library (DJL)
+* DeepLearning4j
+
+## Decision Outcome
+
+Chosen option: "Deep Java Library (DJL)", because it satisfies all our requirements for an all-in-one solution that handles model management and inference.
+
+However, users have reported problems with the PyTorch engine integration and unstable behavior. Moreover, its API is a bit complex.
+
+### Consequences
+
+* Good, because it has an API to show available models
+* Good, because it handles model downloading automatically
+* Neutral, because the API is complex
+* Bad, because users have reported problems with the PyTorch engine integration and unstable behavior
+
+## Pros and Cons of the Options
+
+### LangChain4j
+
+* Good, because it offers a high-level abstraction for LLM workflows
+* Neutral, because it actually wraps other libraries like DJL or ONNX Runtime for the embeddings
+* Bad, because it is a general LLM framework
+
+### ONNX Runtime
+
+* Good, because it is fast and efficient
+* Bad, because it is a low-level inference engine and does not provide model management or downloading features out of the box
+* Bad, because it supplies all binaries for different platforms at once and also supply debugging symbols, which makes it larger than necessary (see [this issue in LangChain4j repository](https://github.com/langchain4j/langchain4j/issues/1492) and [this issue in ONNX repository](https://github.com/langchain4j/langchain4j/issues/1492))
+
+### Deep Java Library (DJL)
+
+* Good, because it supports multiple engines including PyTorch and ONNX
+* Good, because it has a built-in model zoo for downloading models
+* Neutral, because its API is a bit complex
+* Bad, because of reported stability issues with certain engines

docs/decisions/0059-use-cuid2-for-ai-library-id.md

@@ -0,0 +1,89 @@
+---
+nav_order: 0059
+parent: Decision Records
+---
+# Use CUID2 for `aiLibraryId`
+
+## Context and Problem Statement
+
+JabRef stores an `aiLibraryId` in the library's metadata to associate AI artifacts (chat history, summaries, embeddings) with a specific `.bib` library across launches.
+The id is serialized into the `.bib` file as `@Comment{jabref-meta: aiLibraryId:<id>;}` and is therefore visible to anyone who opens the file in a text editor.
+Carrying the id inside the file content (rather than keying off the file path) is what lets AI artifacts stay correlated with the library even when the user renames or moves the `.bib` file.
+
+Because `.bib` files are routinely shared between researchers (e.g., via Git, email, cloud drives, supplementary material of papers), the id ends up in human-facing contexts.
+A v4 UUID such as `550e8400-e29b-41d4-a716-446655440000` looks alarming or "machine-y" to a researcher who is just inspecting their references file.
+
+What identifier scheme should we use for `aiLibraryId`?
+
+## Decision Drivers
+
+* The id must be globally unique with negligible collision probability (multiple researchers can independently create libraries; ids must not clash when libraries are merged).
+* The id must be stable across JabRef launches and cross-platform.
+* The id should look reasonably unobtrusive when a researcher reads the `.bib` file in a text editor — BibTeX files are shared, and the id should not say "WTF".
+* The id should be generated locally without contacting a server (consistent with [ADR-0034](0034-use-citation-key-for-grouping-chat-messages.md): no server is available).
+* Prefer a modern, actively maintained scheme.
+
+## Considered Options
+
+* `UUID.randomUUID()` (RFC 4122 v4 UUID).
+* [CUID2](https://github.com/paralleldrive/cuid2).
+* Short hash of the file path / first entry.
+
+## Decision Outcome
+
+Chosen option: **CUID2**, because it offers the same collision-resistance guarantees as a v4 UUID while producing a shorter, lowercase, alphanumeric string that is far less jarring inside a shared `.bib` file.
+The Java port `io.github.thibaultmeyer:cuid` is on the dependency graph, and its v2.x line implements the CUID2 specification.
+
+`AiService.ensureAiLibraryIdPresent` generates the id via the CUID2 generator.
+The id remains an opaque `String` from the rest of the code's perspective, so no API changes propagate beyond that call site.
+
+### Consequences
+
+* Good, because the id is shorter (~24 chars instead of 36) and lowercase alphanumeric, which reads better in a shared `.bib` file.
+* Good, because CUID2 is explicitly designed to be collision-resistant for horizontally-distributed generation, which matches our case (every JabRef install generates ids independently).
+* Good, because CUID2 is, by design, hard to guess — slightly better than v4 UUIDs against fingerprinting if an id ever leaks into a URL or log.
+* Bad, because we carry a small dependency surface compared to the JDK-builtin `UUID`.
+* Bad, because CUID2 is less universally recognized than UUID — a developer encountering one for the first time may need a moment to identify the format.
+
+### Confirmation
+
+The serialization round-trip tests (`BibDatabaseWriterTest.writeAiLibraryId`, `MetaDataParser`) treat the value as an opaque string and pass with a CUID2 value.
+A code review of `AiService.ensureAiLibraryIdPresent` confirms the CUID2 generator is the only source of new ids.
+
+## Pros and Cons of the Options
+
+### `UUID.randomUUID()`
+
+Example: `550e8400-e29b-41d4-a716-446655440000`.
+
+* Good, because it is built into the JDK — no extra dependency.
+* Good, because it is universally recognized.
+* Neutral, because collision probability is negligible (122 random bits).
+* Bad, because the canonical form (`8-4-4-4-12` hex with hyphens) is long and visually noisy in a `.bib` file shared with researchers.
+* Bad, because it conveys a "this is a generated machine token" feeling that is at odds with the otherwise human-readable nature of `.bib` files.
+
+### CUID2
+
+Example: `tz4a98xxat96iws9zmbrgj3a`.
+
+Java port used: [thibaultmeyer/cuid-java](https://github.com/thibaultmeyer/cuid-java).
+
+* Good, because the textual form is shorter and lowercase alphanumeric, blending in with other identifiers researchers already see (citation keys, DOIs).
+* Good, because the spec is explicit about collision resistance under distributed generation.
+* Good, because it is a modern, actively maintained scheme (the original CUID has been deprecated in favor of CUID2).
+* Good, because already used in indexing and OpenOffice integration.
+* Bad, because it is one more dependency to track.
+* Bad, because it is slightly less familiar to developers than UUID.
+
+### Short hash of the file path / first entry
+
+Example: `a3f1c9d2` (CRC32 / truncated SHA-1 of the absolute path).
+
+* Good, because it is deterministic — moving a `.bib` file would not orphan its AI artifacts.
+* Bad, because it is not unique: two libraries can share a citation key, and file paths change.
+* Bad, because if a user copies a library, both copies would point at the same AI artifacts — exactly what `aiLibraryId` is meant to prevent.
+* Bad, because the id would change if the underlying input changes, breaking the stability requirement.
+
+## More Information
+
+Implementation site: `AiService.ensureAiLibraryIdPresent` in `jablib/src/main/java/org/jabref/logic/ai/AiService.java`.