Scolta AI Search for Drupal

AI-powered search for Drupal — semantic relevance scoring, AI summaries, and natural language query expansion on top of Drupal's Search API.

Built and maintained by Tag1 Consulting — technology leadership since 2007. Tag1 offers AI strategy, architecture, and implementation consulting for organizations evaluating or deploying AI-powered products.

Status

Scolta 1.0 — the API documented here is stable. Breaking changes follow semantic versioning: no removal or signature change without a major version bump and a deprecation cycle. File bugs at the issue tracker.

What Is Scolta?

Scolta is a scoring, ranking, and AI layer built on Pagefind. Pagefind is the search engine: it builds a static inverted index at publish time, runs a browser-side WASM search engine, produces word-position data, and generates highlighted excerpts. Scolta takes Pagefind's result set and re-ranks it with configurable boosts — title match weight, content match weight, recency decay curves, and phrase-proximity multipliers. No search server required. Queries resolve in the visitor's browser against the pre-built static index.

This Drupal module is one of three CMS adapters (alongside scolta-wp and scolta-laravel). It integrates with Drupal's Search API, provides Drush commands, an admin settings form, a search block, and API endpoints for AI query expansion and summarization.

The LLM tier — query expansion, result summarization, follow-up questions — is optional. When enabled, it sends the query text and selected result excerpts to a configured LLM provider. The base search tier shares nothing with any third party; it runs entirely in the visitor's browser.

Requirements

• Drupal 10.3+ or Drupal 11
• PHP 8.1+
• drupal/search_api ^1.0

Installation

composer require tag1/scolta-drupal
drush en scolta

Search API setup

Scolta uses Drupal's Search API as its indexing framework. After enabling the module:

1. Go to Administration > Configuration > Search and Metadata > Search API (/admin/config/search/search-api)
2. Add a new Server and select Scolta Pagefind as the backend
3. Add a new Index, select the content types you want to search, and assign it to the Scolta server
4. Build the search index:

drush scolta:build

5. Place the Scolta Search block on your site via Structure > Block Layout

Drush Commands

| Command | Description | |---|---| | drush scolta:export (se) | Export content as HTML files for Pagefind indexing | | drush scolta:build (sb) | Build the search index (export + index + deploy) | | drush scolta:build --force | Force rebuild even if content has not changed | | drush scolta:build --resume | Resume a previously interrupted build | | drush scolta:build --restart | Discard interrupted state and start fresh | | drush scolta:build --indexer=php | Use a specific indexer mode (php, binary, or auto) | | drush scolta:build --memory-budget=256M | Set memory budget (profile name or byte value) | | drush scolta:build --chunk-size=N | Process N pages per chunk (overrides config) | | drush scolta:finalize (sf) | Merge chunks into the final search index | | drush scolta:rebuild-index (sri) | Rebuild index from existing exported HTML files | | drush scolta:clear-cache (scc) | Clear expansion and summary caches | | drush scolta:check-setup (scs) | Verify dependencies and configuration | | drush scolta:status (sst) | Show current index, indexer, and AI provider status | | drush scolta:download-pagefind (sdp) | Download the Pagefind binary for the current platform |

Large Corpora and Shared Hosting

On sites with thousands of pages or on shared-hosting environments, builds can be interrupted by PHP timeouts, SSH disconnects, or memory limits.

Use drush scolta:build for initial and full index builds. Do not use drush search-api:index — Search API's batch pipeline can exhaust shared-host resource limits on large corpora.

Surviving SSH disconnects

Run the build inside a persistent terminal session so it survives disconnects:

# nohup — simplest, output goes to nohup.out
nohup drush scolta:build --indexer=php &

# screen
screen -S scolta
drush scolta:build --indexer=php
# Detach: Ctrl+A, D  — reconnect: screen -r scolta

# tmux
tmux new-session -s scolta
drush scolta:build --indexer=php
# Detach: Ctrl+B, D  — reconnect: tmux attach -t scolta

Resuming an interrupted build

If the build is interrupted (timeout, disconnect, memory limit), resume from where it stopped:

drush scolta:build --resume

Use --restart to discard the interrupted state and start the build fresh:

drush scolta:build --restart

Deferred finalization on very large corpora

On very large sites, drush scolta:build may defer the final merge step to stay within memory limits. Run finalization separately:

drush scolta:finalize

AI Provider Configuration

Scolta supports three AI provider paths. The right path depends on where you are in your deployment:

Selecting an AI provider is always manual

Scolta ships with no AI provider selected. The AI Provider field opens on - Select a provider -, and while nothing is selected AI features are off: search works exactly as it does now, no provider is assumed, and Anthropic in particular is not silently assumed. There is no default anywhere.

This is going-forward only. A site that already saved a provider keeps it and keeps working; nothing rewrites, clears or re-defaults an existing value, and there is no update hook that turns AI off on a working install. Only new installs start with nothing selected.

Amazee.ai (managed gateway, opt-in)

Amazee.ai is a managed AI gateway you can enable without holding an API key of your own, and it comes with a no-cost evaluation. Enabling it takes two deliberate steps and never happens on its own:

1. Select Amazee.ai (managed gateway) as the AI Provider at Administration > Configuration > Search and Metadata > Scolta AI Search > AI Configuration, and save.
2. Follow the Set up Amazee.ai link from that screen and choose one of two actions. Nothing is connected until you do:
   • Try the demo — one click. No email, no account, no card. AI is on immediately and runs until the demo's included credit is used up. The demo is one-time per site; it stays available whether you are on a fresh install or coming from another provider, and once it has been used the page points you at the account path instead.
   • Enter your Amazee credentials — sign in with the email address on your amazee.ai account. Amazee emails a verification code, you pick a region, and your account's credentials are stored for you. If you do not have an account yet, this creates one. You never generate or paste an API key: this mirrors amazee.ai's own ai_provider_amazeeio module, which manages the keys for you, so there is deliberately no bring-your-own-key form.

When a connection stops being accepted — a demo whose credit ran out, or revoked credentials — AI degrades cleanly, /health reports it, and the Amazee.ai settings page shows a prompt pointing straight at Enter your Amazee credentials. Completing that flow restores AI without disconnecting first. Nothing is provisioned automatically at any point in that recovery.

The settings page states which of the two actions established the current connection, because that is recorded when it happens rather than inferred afterwards. A connection made before Scolta recorded it says only "Connected to Amazee.ai".

Installing the module configures no AI provider and stores no credentials, and no page request, cron run or activation will establish a connection for you. Selecting any other provider afterwards removes the stored connection, so the gateway can never serve traffic for a site that has moved to its own key. Selecting Amazee.ai again and repeating the connect flow re-establishes it.

Model configuration on this path is separate. Amazee.ai serves models through a LiteLLM gateway under its own names (claude-4-5-sonnet), which no provider's own API accepts. Scolta therefore keeps them apart: the gateway's names are resolved automatically into amazee_model and amazee_expansion_model and are read only while Amazee.ai credentials are in use, while the AI Model and Expansion Model fields on the settings form hold provider-native IDs (claude-sonnet-4-5-20250929, gpt-4o) and are what a direct provider key uses. The two gateway settings have no form field, because there is nothing to choose — they are whatever the gateway offers. Switching away from Amazee.ai therefore leaves your own model choice intact.

Sites installed before this separation existed may have an Amazee.ai gateway name sitting in AI Model. drush updatedb moves it across and restores the shipped default, reporting what it moved; if you use a direct Anthropic or OpenAI key, check the AI Model field afterwards.

Drupal AI module (recommended for production)

For sites that want full control over their AI provider, Scolta integrates with the Drupal AI module — the same provider abstraction used by CKEditor AI, AI Automators, and other AI Initiative modules.

When "Drupal AI module" is selected in Scolta's settings, Scolta routes all AI requests through the Drupal AI module's configured default provider. This gives you:

• 48+ supported providers — Anthropic, OpenAI, Google Gemini, AWS