LLM Index API (BETA)
 | APIs needed for the knowledge index in the LLM Application. |
| Type | JAR |
| Category | API |
| Developed by | Matéo Munoz, Ludovic Dubost, Michael Hamann, Paul Pantiru |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
This extension provides both Java and REST APIs for the Index for the LLM Application and implements the indexing of the stored content in Solr.
REST API
The REST API provides a convenient way to manage both collections and documents inside collections from external tools. This can be used in other applications to add, update and delete content that is indexed in the LLM application whenever content is added, changed or deleted the application.
Collections Resource
GET /wikis/{wikiName}/aiLLM/collections
Returns a list of all collection IDs that the current user can access as an array of strings.
Collection Resource
A collection object has the following properties, all properties are strings unless otherwise mentioned:
- id: id of the collection
- title: pretty name of the collection
- embedding_model: the embedding model as reference of the page that defines the model
- chunking_method: the chunking method, should be maxChars
- chunking_max_size: (int) the maximum size of a chunk
- chunking_overlap_offset: (int) the overlap of chunks
- document_spaces: (list of strings) the list of XWiki spaces indexed by this collection, currently not used
- allow_guests: (boolean) if guests can query this collection (as part of a chat completion)
- query_groups: (list of strings) the list of groups that are allowed to query this collection (as part of a chat completion). This is only used when guests aren't allowed to query the collection.
- rights_check_method: the method used for checking access rights of individual documents during queries. Supported values: public, external. See also the Authorization section of the Index for the LLM Application.
- rights_check_method_configuration: (object) options of the rights check method, values depend on the selected rights check method. The "external" rights check method supports the url parameter which is the URL that is used to check rights for all found documents.
GET /wikis/{wikiName}/aiLLM/collections/{collectionName}
Returns the collection of the given name.
PUT /wikis/{wikiName}/aiLLM/collections/{collectionName}
Creates or updates the collection of the given name. The body of the request is a collection, if not all properties are specified, only the specified properties are updated.
DELETE /wikis/{wikiName}/aiLLM/collections/{collectionName}
Deletes the collection of the given name
GET /wikis/{wikiName}/aiLLM/collections/{collectionName}/documents
Returns a list of document IDs that are contained in the collection of the given name. This resource supports the following query parameters:
- start: the index of the first document to retrieve (default: 0)
- number: the number of documents to retrieve (default: -1)
Document Resource
A document object has the following properties, all properties are strings unless otherwise mentioned:
- id: id of the document
- title: pretty name of the document
- language: the language of the document (currently not used)
- url: the URL of the document, used to display a link to the original resource when the document is used as context in a chat
- collection: the name of the collection the document is part of
- mimetype: the mime type of the document, currently not used, could be used in the future to use a chunking method that is specific to the mime type
- content: the content of the document that is indexed
GET /wikis/{wikiName}/aiLLM/collections/{collectionName}/documents/{documentID}
Returns the document of the given name in the collection of the given name.
PUT /wikis/{wikiName}/aiLLM/collections/{collectionName}/documents/{documentID}
Creates or updates the document of the given name in the collection of the given name. The body of the request is a document, if not all properties are specified, only the specified properties are updated.
DELETE /wikis/{wikiName}/aiLLM/collections/{collectionName}/documents/{documentID}
Deletes the document of the given name in the collection of the given name.
Custom Authorization Checks
The authorization system in the LLM application that checks in a query if a user can access a document (see also the documentation on authorization in the index) is designed to be fully extensible. To implement a custom authorization method, a component of type org.xwiki.contrib.llm.authorization.AuthorizationManagerBuilder needs to be implemented. If the authorization method needs any configuration, three additional parts need to be implemented:
- A class to store the configuration that is serializable and unserializable using Jackson. This class is mainly used to represent the configuration in the REST API for collections.
- An XClass to store the configuration in the wiki page of the collection
- A sheet to display the aforementioned XClass
The following shows an example component implemented in Groovy that can be used with the Script Component Extension:
import javax.inject.Named
import javax.inject.Singleton
import org.xwiki.component.annotation.Component
import org.xwiki.contrib.llm.authorization.AuthorizationManager
import org.xwiki.contrib.llm.authorization.AuthorizationManagerBuilder
import org.xwiki.contrib.llm.Collection
import org.xwiki.model.reference.EntityReference
import com.xpn.xwiki.objects.BaseObject
import org.xwiki.model.reference.LocalDocumentReference
/**
* A custom {@link AuthorizationManagerBuilder} that always returns true for all document ids.
*
* @version $Id$
* @since 0.3
*/
@Component
@Named("custom")
@Singleton
class CustomAuthorizationManagerBuilder implements AuthorizationManagerBuilder {
static class ConfigurationType {
String property
ConfigurationType(String property) {
this.property = property
}
}
@Override
AuthorizationManager build(BaseObject configurationObject) {
return { documentIds ->
documentIds.collectEntries { id -> [id, true] }
}
}
@Override
EntityReference getConfigurationClassReference() {
return new LocalDocumentReference('Custom Right Check', 'Class')
}
@Override
EntityReference getConfigurationSheetReference() {
return new LocalDocumentReference('Custom Right Check', 'Sheet')
}
@Override
Class getConfigurationType() {
return ConfigurationType.class
}
@Override
Object getConfiguration(BaseObject object) {
return new ConfigurationType(object.getStringValue("property"))
}
@Override
void setConfiguration(BaseObject object, Object configuration) {
object.setStringValue("property", configuration.property)
}
}
This code assume an XClass Custom Right Check.Class with a string property "property" and a sheet Custom Right Check.Sheet to display this property.
The sheet should contribute one or several dt and dd elements that are displayed in the configuration of the collection. A possible sheet would be the following.
#set ($object = $doc.getObject('Custom Right Check.Class', true))
#set ($editing = $xcontext.action == 'edit')
#set ($discard = $doc.use($object))
{{html clean="false"}}<dt #if (!$editing && $hasEdit)
class="editableProperty"
data-property="$escapetool.xml($services.model.serialize($object.getPropertyReference('property')))"
data-object-policy="updateOrCreate"
data-property-type="object"#end>
<label#if ($editing) for="Custom Right Check.Class_0_property"#end>
$escapetool.xml($doc.displayPrettyName('property', false, false))
</label>
</dt>
{{/html}}
{{html clean="false"}}<dd>{{/html}}
$doc.display('property')
{{html clean="false"}}</dd>{{/html}}
{{/velocity}}
It is important to use the updateOrCreate object policy as there is no separate code for adding the object. Further, this sheet will be applied also on documents that don't contain the configuration object yet, so it is important that the sheet creates it (first line of the code). This sheet is then dynamically loaded when the respective right check method is selected. When another value is selected, the sheet could be hidden again. The sheet thus shouldn't assume that when it is used it is also visible. In case any validation shall be performed, the sheet should verify that it is actually visible before performing any validation.
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.contrib.llm:application-ai-llm-index-api 0.6.2):
- org.xwiki.commons:xwiki-commons-script 16.2.0
- org.xwiki.platform:xwiki-platform-rest-api 16.2.0
- org.xwiki.platform:xwiki-platform-rest-server 16.2.0
- org.xwiki.platform:xwiki-platform-livedata-api 16.2.0
- org.xwiki.platform:xwiki-platform-search-solr-query 16.2.0
- org.xwiki.platform:xwiki-platform-security-authorization-api 16.2.0
- org.xwiki.platform:xwiki-platform-user-api 16.2.0
- org.xwiki.contrib.llm:application-ai-llm-models-api 0.6.2
- io.github.resilience4j:resilience4j-retry 2.2.0
