BookStack Query

This is an AI/LLM-based query extension for BookStack. It uses the BookStack visual and logical theme systems to extend the functionality of BookStack to provide a query interface in-app, and an integration with an external stack which performs vector storage and LLM querying.

Preview

Limitations & Considerations

• This is considered a non-official customization/hack, and is therefore not assured to be compatible with BookStack changes, nor is it considered or tested under the same levels as per the core official code-base.
• The responses provided by the LLM are not assured to be safe in any way.
• This does not yet enforce any kind of strict permission/view control.
  • It's possible that non-visible content will be shown in query results.
  • The system simply indexes all content in the BookStack system.
• There is no security/authentication applied to the query API or related services. It's assumed these will be placed behind the firewall, and not exposed to the internet.
• This only indexes titles and main content.
  • It does not yet consider tags, attachments, images etc...
• The query database is separate to the BookStack database, and can possibly become out of sync.
  • Update/remove requests are sent across to the query system, for the index to be updated, when changes are made in BookStack but there are no ongoing checks to ensure alignment.
• This can be accessed by all logged in users.
  • There is no role-based access control, and the BookStack endpoints are placed behind authentication since they can consume resources and expose content.
• This currently has only been built in English.
• This set-up can be resource intensive depending on content and host, so stability and compatibility may be variable.
  • By default, models are downloaded on demand on use, so an external internet connection is required from some of the containers.
• The docker image for the custom-built node API is not pre-built, so requires building via docker, although we may make this pre-built for quicker deployment in the future.

Requirements

• At minimum, about 2GB of RAM is advised for the vector database.
• In the default configuration with a local LLM, 8GB of RAM minimum is advised, along with a fairly strong CPU.
  • Alternatively, with some tweaking, you could use a different model with smaller/larger requirements.
  • Alternatively, with some tweaking, you could instead offload the local LLM handling to a GPU.
  • Alternatively, with some tweaking, you could instead use an external LLM service.
    • This has not yet been tested, and there may be compatibility issues.
• In the default configuration, you'll probably want at least 16GB of disk space for this set-up.

Known incompatibilities:

• The set-up has issues if ran in an LXC container unless it's has access to all cores on the parent host.

Setup

Note: This is subject to breaking changes as this is developed, and as it's used to test new integration options with BookStack.

1. Download the project files or git clone this project.

• Via git: git clone https://codeberg.org/bookstack/query.git bs-query
• Via wget: wget https://codeberg.org/bookstack/query/archive/main.tar.gz && tar -xzf main.tar.gz && mv query bs-query

2. Enter the directory containing all the downloaded files.

• cd bs-query

3. Build and pull the containers used in the docker-compose stack:

• docker compose build
  • This may take a little extra time, since it some embedding model data is downloaded as part of the build.
• docker compose pull

4. Bring up the stack:

• docker compose up -d
• This starts an API listening on port 3030 of the host.
• Ensure this API/port is only exposed to your BookStack instance. All data can be queried in an insecure manner via this service.
• The llm service may take a while to be ready on first run, or if the LLM model is changed, since it downloads the model from HugginFace at this time if not already found locally in the mounted ./docker_data/models folder.
  • This will typically use and consume multiple GigaBytes of network usage and disk space.
• You can watch the logs via docker compose logs -f

5. On your BookStack instance, set up a theme following the "Getting Started" part of our guidance here. You can use an existing configured theme if needed.
6. Copy the files within the theme/ directory of this project, into your BookStack theme folder.

• If you already have a theme functions.php defined, you can just copy the inner bsquery folder and include_once "bsquery/include.php"; to your existing functions.php folder.

7. Within your BookStack .env config file, add the following option:

• QUERY_API_ENDPOINT=http://localhost:3030
• Set the value of that option to be the URL at which the app service of the started compose stack can be found. By default this uses port 3030. You can leave the value as http://localhost:3030 if using configuration defaults, and if the compose stack is running on the same host that BookStack is running on.

8. Index your existing content using the command as shown in the commands section below.

Basic Usage

Before running queries, your content will need to be indexed. Content is sent to the query API for indexing upon creation/update/delete. You can also index all existing content using a command as detailed below.

You can access the query interface at the /query URL path of your BookStack instance. You can also start a query via the search by, by submitting a search ending with a question mark.

Commands

This provides a few commands which will be accessible like other official BookStack commands:

# Index all BookStack content
# Can take a while on large instances with a lot of content
php artisan bookstack-query:index-all

# Check how many entries there are in the query index
# Useful to test the connection, and to see if existing data is found
php artisan bookstack-query:index-stats

# Delete all content in the query index
php artisan bookstack-query:index-clear

Potential Tweaks

There are loads of elements and variables in something like this which can impact the quality and performance of results, so there may be things you want to tweak like:

• The LLM model used to provide text results.
  • Defaults to a variation of Google's Gemma 3 4b model: MaziyarPanahi/gemma-3-4b-it-GGUF:Q6_K
• The LLM service used.
  • By default this uses a local llama.cpp server.
  • If you have a GPU, you may want to ensure that you use an image with relevant GPU support.
• The embedding model used for chunk query handling.
  • By default this uses Chroma's default all-MiniLM-L6-v2 model.
• The way content is chunked before indexing for later querying.
  • Some options can be set via environment variables as seen in src/config.ts.
• The prompts/templates used when sent to the LLM.
  • Not yet extracted as options, but defined in src/llm.ts.

Not everything has been made easy to tweak, so right now you may need to hack around and customize code to refine the solution for your scenario.

So far, this has only been really tested using the defaults. Some elements, like the prompts and prompt formats, may not work for other models.

Project Structure

This is composed of the following parts:

• A BookStack theme, found in theme/.
  • This contains the BookStack customizations using the BookStack theme systems.
  • This provides in in-BookStack UI, required endpoints which are used by that UI, and commands for indexing.
  • This also sets up event handling to add or delete content from the query database when changes are made in BookStack.
• Chroma - A vector database. This is where content is stored in a way that can be used for querying parts of content.
• A NodeJS based API, found in src/.
  • This acts as an interface between BookStack, Chroma, and the LLM.
• An LLM text model.
  • Technically should be usable with any model via an OpenAI-compatible chat API interface.
  • By default, our docker-compose stack provides a local server via llama.cpp.
    • By default, a MaziyarPanahi/gemma-3-4b-it-GGUF:Q6_K model is download from HugginFace on start-up if not already downloaded.

AI Disclaimer

Many parts of the NodeJS API here have been built with heavy use of LLMs/AI tools (Gemini CLI), but all content has been reviewed by a Human with JavaScript/Typescript knowledge. The main purpose was to test these tools as an alternative to typing, to help with muscle issues, rather than to build quickly without concern.

Contributing

I'm open to small improvements, and bug fixes, but I don't want to over-expand the scope of this project so I wouldn't accept any larger changes or feature additions. Feel free to open issues for ideas or discussion, but they may be promptly closed since this project won't have maintained/managed open issues, to keep maintenance minimal.

This project is mainly intended to provide minimal LLM-based querying in BookStack, usable as a base starting point for more advanced scenario-specific implementations where needed, whilst also proving as a more extensive example of what can be achieved using the BookStack customization options.