Getting Started

Installation

Requirements

  • Omeka S 4.0 or later
  • PHP 8.1 or later with the curl and openssl extensions. They are used for the Turso and OpenAI HTTP calls and for encrypting the API key.
  • A Turso database. The module talks to it over HTTPS, so no client library or PHP extension is needed on the server.
  • An OpenAI API key. The module calls the embeddings API (text-embedding-3-large or text-embedding-3-small) and the chat completions API.
  • Working Omeka S background jobs. Indexing runs as jobs through Omeka's default PhpCli dispatch strategy.
  • Optional: the Blog module, if you want blog posts indexed.

Creating the Turso database

  1. Sign in at turso.tech and create a database, or use the Turso CLI:

    turso db create omeka-chatbot
turso db show omeka-chatbot --url
turso db tokens create omeka-chatbot

  2. Note the database URL (libsql://...turso.io) and the token. The module accepts either a libsql:// or an https:// URL.

The module creates its own chunks table and DISKANN vector index the first time it connects. Use a database dedicated to the chatbot: the Purge All Index Data action drops that table.

Installing

  1. Copy the Chatbot folder into modules/.

  2. Add an encryption key to config/local.config.php. It is used to encrypt the OpenAI API key stored in the database.

    'chatbot' => [
    'encryption_key' => 'a-long-random-string',
    // Optional: keep the key out of the database entirely. When set, it
    // is always used and any key saved in module settings is ignored.
    // 'openai_api_key' => 'sk-...',
],

    If no encryption_key is set, the module falls back to a fixed built-in key, so a stored API key could be decrypted by anyone with the module code and a database dump. Always set one.

  3. Log in as a global administrator, open Admin > Modules and click Install next to Chatbot. This creates two MySQL tables, module_chatbot_log and module_chatbot_rate_limit.

  4. A Chatbot entry appears in the admin sidebar. Open it and click Settings (/admin/chatbot/settings).

  5. On the Connection tab enter the Turso database URL and Turso auth token. Paste your OpenAI API key unless you put it in local.config.php. Click Save Settings.

  6. After the page reloads, a green message such as "0 chunks indexed" confirms the Turso connection. A red Turso Not Available message means the URL or token is wrong; the message says why.

  7. Open the Diagnostics tab and click Re-index Now to build the index. See Indexing Content.

  8. Put the chatbot on your site: check Enable global chat widget on all public pages on the Behaviour tab, or add a Chatbot block to a site page. See Chat Widget and Block.

Upgrading

Copy the new version over modules/Chatbot, then open Admin > Modules and click Upgrade if prompted. Upgrading from a version before 1.2.0 drops the old module_chatbot_index_map MySQL table; vectors now live only in Turso.

If you change the Embedding model or Embedding dimensions after indexing, purge and rebuild the index. See Troubleshooting.

Uninstalling

Uninstalling drops the module's two MySQL tables, module_chatbot_log and module_chatbot_rate_limit. It does not remove the module's settings from Omeka's setting table, and it does not touch the chunks table in your Turso database. Delete the Turso database yourself if you no longer need it.

Log in for Support