Wanda - AI Chat Assistant for MediaWiki

Wanda is a MediaWiki extension that provides an AI-powered chatbot interface for your wiki. It can answer questions about your wiki content using various LLM providers and includes both a dedicated special page and a floating chat widget.

Features

  • Multiple LLM Providers: Support for Ollama (self-hosted), OpenAI, Anthropic Claude, Azure OpenAI, and Google Gemini
  • Vector-Based Semantic Search: Uses high-dimensional embeddings for intelligent content retrieval with configurable similarity thresholds
  • Dual Search Strategy: Automatic fallback from vector search to text-based search for reliability
  • Floating Chat Widget: Always-accessible chat button on all pages
  • Special Page: Dedicated chat interface at Special:Wanda
  • Responsive Design: Works on desktop and mobile devices
  • Cargo Table Queries: Query structured data from Cargo tables using LLM-generated queries
  • Secure Configuration: API key management and timeout controls

Installation

  1. Clone or download this extension to your MediaWiki extensions/ directory
  2. Add the following to your LocalSettings.php:
wfLoadExtension( 'Wanda' );
  1. Configure your preferred LLM provider (see Configuration section)
  2. Run MediaWiki update script:
php maintenance/update.php

Configuration

Add these configuration variables to your LocalSettings.php:

// Choose your LLM provider
$wgWandaLLMProvider = 'ollama'; // Options: 'ollama', 'openai', 'anthropic', 'azure', 'gemini'

// Provider-specific settings
$wgWandaLLMApiKey = 'your-api-key-here'; // Not needed for Ollama

$wgWandaLLMModel = 'gemma:2b'; // Model name to use for the LLM provider

$wgWandaLLMApiEndpoint = 'http://localhost:11434/api/'; // API endpoint URL for the LLM provider

// Elasticsearch configuration
$wgWandaLLMElasticsearchUrl = 'http://elasticsearch:9200';

// Embedding model configuration (for semantic search)
$wgWandaLLMEmbeddingModel = 'text-embedding-004'; // Model for generating embeddings

// Vector search configuration
$wgWandaVectorSearchMinScore = 1.7; // Minimum similarity score threshold (1.0-2.0, default: 1.7)

// UI and interface settings
$wgWandaShowPopup = true; // Show/hide the floating chat widget on all pages

$wgWandaEnableAttachments = true; // Show/hide the "Attach images" icon

// Custom prompt settings
$wgWandaCustomPrompt = ''; // Custom prompt template to override default behavior

$wgWandaCustomPromptTitle = ''; // Wiki page title containing custom prompt template

// LLM behavior settings
$wgWandaLLMMaxTokens = 1000; // Maximum tokens in LLM responses

$wgWandaLLMTemperature = '0.7'; // Creativity/randomness setting (0.0-1.0)

$wgWandaLLMTimeout = 30; // Request timeout in seconds for LLM calls

// Indexing settings
$wgWandaAutoReindex = true; // Automatically reindex content after update.php

$wgWandaSkipESQuery = false; //Skip Elastic Search

// Cargo structured data integration
$wgWandaEnableCargoQueries = false; // Enable querying Cargo tables for structured data
$wgWandaCargoExcludedTables = []; // Array of Cargo table names to exclude from queries

API Actions

Wandachat

The Wanda extension provides a MediaWiki API module called wandachat for programmatic access to the AI chat functionality. This API allows you to send questions and receive AI-generated responses based on your wiki's content.

Required Parameters:

  1. action (string) - Must be set to wandachat
  2. message (string) - The user's question or query

Optional Parameters:

  1. format (string) - Response format, recommended: json
  2. usepublicknowledge (boolean) - Allow fallback to public knowledge when wiki context is insufficient (default: false)

Optional LLM Override Parameters:

These parameters allow you to override the default configuration settings for individual API calls:

  1. provider (string) - Override LLM provider (ollama, openai, anthropic, azure, gemini)
  2. model (string) - Override the model name for the request
  3. apikey (string) - Override API key for the request
  4. apiendpoint (string) - Override API endpoint URL
  5. maxtokens (integer) - Override maximum tokens in the response
  6. temperature (float) - Override creativity/randomness setting (0.0-1.0)
  7. timeout (integer) - Override request timeout in seconds
  8. customprompt (string) - Override the default prompt template
  9. customprompttitle (string) - Override using content from a wiki page as prompt template

Provider Examples

Ollama (Self-hosted)

$wgWandaLLMProvider = 'ollama';
$wgWandaLLMApiEndpoint = 'http://localhost:11434/api/';
$wgWandaLLMModel = 'gemma:2b';

OpenAI

$wgWandaLLMProvider = 'openai';
$wgWandaLLMApiKey = 'sk-your-openai-api-key';
$wgWandaLLMModel = 'gpt-3.5-turbo';

Anthropic Claude

$wgWandaLLMProvider = 'anthropic';
$wgWandaLLMApiKey = 'sk-ant-your-anthropic-key';
$wgWandaLLMModel = 'claude-3-haiku-20240307';

Google Gemini (Generative Language API)

$wgWandaLLMProvider = 'gemini';
$wgWandaLLMApiKey = 'your-gemini-api-key'; // Obtain from Google AI Studio
$wgWandaLLMModel = 'gemini-1.5-flash'; // Or gemini-1.5-pro, etc.
// Optional: override endpoint (default used if omitted)
$wgWandaLLMApiEndpoint = 'https://generativelanguage.googleapis.com/v1';

For detailed configuration options, see LLM-CONFIG.md.

Usage

Floating Chat Widget

The floating chat widget appears on all pages (except Special:Wanda) as a blue chat button in the bottom-right corner. Click it to open the chat interface.

Add the following configuration in LocalSettings.php to show/hide the floating chat widget.

$wgWandaShowPopup = true;

Special Page

Visit Special:Wanda on your wiki to access the full-featured chat interface.

Indexing Content

To enable the chatbot to answer questions about your wiki content, you need to index your pages in Elasticsearch. Use the maintenance script:

php extensions/Wanda/maintenance/ReindexAllPages.php

Custom Prompt Configuration

You can configure a custom prompt in two ways:

  1. Use a custom prompt directly
$wgWandaCustomPrompt = "Custom_Prompt_to_be_used";
  1. Use a custom prompt from a wiki page
$wgWandaCustomPromptTitle = "Title_of_the_page";

Note: If both $wgWandaCustomPrompt and $wgWandaCustomPromptTitle are set, $wgWandaCustomPrompt will take precedence.

Automatic Reindex After Updates

This extension now schedules a full reindex automatically after you run php maintenance/update.php by registering the maintenance script as a post-update task. On large wikis this may be time-consuming. If you prefer to disable auto reindexing, remove the LoadExtensionSchemaUpdates hook entry from extension.json or replace the full reindex with a lighter custom script.

To keep indexing continuously fresh without large batch jobs, the extension also updates the index on page saves and file uploads via hooks.

You can also control this behavior via a configuration flag. Add to LocalSettings.php:

// Disable automatic full reindex after update.php
$wgWandaAutoReindex = false;

When set to false, the hook will skip scheduling the maintenance script; you can still run it manually:

php extensions/Wanda/maintenance/ReindexAllPages.php

Cargo Integration

Wanda can query structured data stored in Cargo tables alongside its Elasticsearch-based search. When enabled, Wanda uses the LLM to generate structured queries against Cargo tables based on the user's natural language question.

Setup

  1. Install and configure the Cargo extension
  2. Enable Cargo queries in LocalSettings.php:
$wgWandaEnableCargoQueries = true;

// Optionally exclude specific tables
$wgWandaCargoExcludedTables = ['InternalTable', 'TempData'];

How It Works

  1. Wanda auto-discovers all Cargo tables and their schemas
  2. When a user asks a question, the LLM receives the table schemas and generates a structured Cargo query (or determines no query is relevant)
  3. The query is validated and executed against the Cargo database
  4. Results are combined with Elasticsearch results and fed to the LLM for the final answer

Source Citations

Cargo results include source links:

  • Row-level: Links to PageName?action=pagevalues showing the page's stored Cargo data
  • Table-level: Links to Special:CargoTables/TableName showing the full table

Requirements

  • The Cargo extension must be installed and loaded
  • At least one Cargo table must be declared and populated
  • If Cargo is not installed, the feature is silently skipped

Requirements

  • MediaWiki 1.36.0 or later
  • PHP 7.4 or later
  • Elasticsearch (with dense_vector support for semantic search)
  • One of the supported LLM providers:
    • Ollama (self-hosted)
    • OpenAI API access
    • Anthropic Claude API access
    • Azure OpenAI service
    • Google Gemini (Generative Language API)
  • Cargo extension (optional, for structured data queries)

Architecture

  1. Content Indexing: Wiki pages (and extracted PDF text) are chunked and stored in Elasticsearch with semantic embeddings
  2. Query Processing: User queries are converted to embeddings using the configured embedding model
  3. Vector Search: Elasticsearch performs cosine similarity search with configurable threshold
    • Similarity Score Range: 1.0 (no similarity) to 2.0 (perfect match)
    • Default Threshold: 1.7 (cosine similarity ≥ 0.7)
    • Configuration: Adjustable via $wgWandaVectorSearchMinScore
  4. Fallback Strategy: If vector search fails or returns no results, falls back to text-based BM25 search
  5. Cargo Queries: If enabled, the LLM generates structured queries against Cargo tables in parallel; results are merged with Elasticsearch context
  6. Response Generation: The LLM generates answers based on the combined context from Elasticsearch and Cargo
  7. Incremental Updates: Page save and file upload hooks automatically regenerate embeddings and update the index

Security Considerations

  • API keys are stored securely in MediaWiki configuration
  • Content is processed by your chosen LLM provider
  • For sensitive wikis, consider using self-hosted Ollama
  • Configure appropriate timeouts and rate limits

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This extension is licensed under the MIT License.