Developer Reference

Notes for developers extending the module or integrating with it.

Events the module listens to#

Any module that triggers the Blog events with a post_id parameter gets its posts indexed, provided the blog_post and blog_post_site tables exist.

Chatbot\Service\IndexSync holds this logic. Removals and metadata updates run in the request, whatever the Auto-index setting; queuing needs auto-indexing on and Turso reachable. Item and media saves are handled at priority -10, after other modules' listeners at the default priority: the Access module saves access levels and embargoes in its own api.create.post / api.update.post listeners, and IndexSync reads them back.

Jobs#

Dispatch them with Omeka\Job\Dispatcher like any other Omeka job.

Services#

All are registered in the service manager under their class names.

The Access module#

PublicResourcesFactory asks Omeka's module manager whether the module Access is active; only then does PublicResources read Access's access_status table, which holds each resource's effective level and embargo after inheritance (columns level, embargo_start, embargo_end; no row means free). An item is restricted when its row has a level other than free or an embargo in force; a media when its row or its item's row is. The check is added to the same one query (NOT EXISTS on access_status), so it costs no extra round trip per chunk.

Embargo dates are compared with UtcClock::now(): Access stores and compares them in UTC (Omeka's bootstrap sets PHP's zone to UTC). Access's access_embargo_bypass setting drops the embargo test. Changes Access writes straight to the database (item set levels, batch edits, its embargo and rebuild jobs) fire no events the module can hear; chat and search still hide newly restricted content at once.

Provider interfaces#

OpenAiProvider implements both interfaces. To add another backend, implement them, register a factory in config/module.config.php under service_manager.factories, and change ChatServiceFactory and IndexServiceFactory to fetch your provider instead of OpenAiProvider.

interface EmbeddingsProviderInterface
{
    /** @return float[] */
    public function embed(string $text, int $dimensions = 0): array;
    public function getName(): string;
}

interface LLMProviderInterface
{
    public function complete(array $messages, string $model, float $temperature = 0.2, int $maxTokens = 1024): string;
    public function getName(): string;
}

Turso schema#

Created automatically on first connection and dropped by Purge All Index Data:

CREATE TABLE chunks (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    resource_type TEXT    NOT NULL,
    resource_id   INTEGER NOT NULL,
    chunk_id      INTEGER NOT NULL,
    chunk_text    TEXT    NOT NULL,
    metadata      TEXT,            -- JSON: title, resource_type, site_ids, item_set_ids (items and media only);
                                   -- site_ids, item_set_ids and url follow an item's saves (updateMetadata())
    url           TEXT,
    created_at    TEXT    NOT NULL,
    embedding     F32_BLOB(3072)   -- size follows the Embedding dimensions setting
);
CREATE INDEX chunks_vec_idx ON chunks (libsql_vector_idx(embedding));

Searches use vector_top_k('chunks_vec_idx', vector32('[...]'), k) and order by vector_distance_cos. libSQL keeps the DiskANN graph in the chunks_vec_idx_shadow table and updates it on every insert and delete, so the module never rebuilds the index. On its first query of a request TursoService reads the schema from sqlite_master; getIndexProblem() reports an index that is missing its shadow table or a F32_BLOB size that differs from the Embedding dimensions setting, and indexing, chat and search stop before calling OpenAI until the index is purged.

MySQL tables#

• module_chatbot_log: id, level, event, message, context (JSON), created_at
• module_chatbot_rate_limit: ip_address, window_start, request_count

created_at, window_start and the Turso chunks' created_at are UTC, like Omeka's own timestamps. Chatbot\Service\UtcClock writes them and computes every cutoff from PHP's clock: MySQL's NOW() follows the connection's time zone, so the module does not use it. Admin pages convert the times to the installation's time zone with UtcClock::display().

Front-end scripts#

Both scripts are plain JavaScript with no dependencies, so a theme can mount them in custom markup.

• ChatbotWidget.init({ apiUrl, mode: 'widget' | 'inline', container, blockId, heading, siteId, siteSlug, itemSetIds }) from asset/js/chatbot.js. mode: 'widget' appends a floating button and panel to the body; mode: 'inline' renders the panel inside container. An inline chat passes the page block's blockId and sends only the question and the block id: the server looks up the block's system prompt, item sets and site and enforces its anonymous-use option (Chatbot\Service\ChatAccess). siteId, siteSlug and itemSetIds apply to the widget only. There is no systemPrompt option: the prompt is never sent from the browser.
• SemanticSearch.init({ apiUrl, container, perPage, placeholder, siteId, siteSlug }) from asset/js/semantic-search.js.

Get the endpoint URLs from the chatbot-api-chat and chatbot-api-search routes, for example $this->url('chatbot-api-chat') in a view.

Tests#

Unit tests use PHPUnit mocks and need no database or API keys. From the Omeka S root:

vendor/bin/phpunit -c modules/Chatbot/test/phpunit.xml