AI Hub is a small BYOK (bring your own key) broker for Moodle. It lets the institution’s own plugins generate text through shared AI API keys, without each plugin reimplementing the HTTP transport, the SSRF guard, the provider ladder or a key store.

Use the sidebar to jump to any section on this page.

Source code: github.com/jeanlucio/moodle-local_aihub

✨ Features

• 🔑 BYOK key store: site keys (admin) and optional personal keys (per user, opt-in) for Gemini, Groq, DeepSeek and any OpenAI-compatible endpoint.
• 🪜 Personal → site resolution: the hub tries the user’s own key first, then the site key, exposing a single result to the caller.
• 🧩 One-call facade: \local_aihub\ai::generate_text() and is_available() — consumed by sibling plugins through a soft dependency (class_exists), with no hard dependency entry.
• 🚫 Does not wrap core_ai: each consumer keeps its own core_ai fallback, so a site that already has core_ai configured needs no extra setup — the hub stays optional.
• 👁️ Write-only personal keys: once saved, a personal key is never returned to the browser — the page only reports a configured / not configured status, closing the read vector via Log in as.
• 🧑‍💻 Self-service page: My AI keys (in the user’s preferences) to add/replace/remove personal keys and review one’s own recent usage.
• 📊 Administrator usage report: every request served by the site keys, across all users, with CSV / Excel download — gated by local/aihub:viewusage.
• 🛡️ SSRF guard: the configurable OpenAI-compatible endpoint is forced to HTTPS, with loopback / link-local / private ranges blocked and DNS A/AAAA anti-rebinding.
• 🧾 Usage log + retention task: one row per request (user, requesting component, what was generated, provider, model, key tier) and a scheduled task that purges logs past a configurable retention.
• 🔒 Privacy-complete: full Privacy provider for the usage log and personal preferences, with the three external destinations declared.

🧩 How consumers use it

A sibling plugin consumes the hub through a runtime guard and keeps its own core_ai fallback:

// Availability: hub keys first, then the consumer's own core_ai fallback.
public static function has_ai(): bool {
    if (class_exists(\local_aihub\ai::class) && \local_aihub\ai::is_available()) {
        return true;                       // BYOK via the hub
    }
    return self::has_core_ai();            // works without the hub
}

// Generation.
$result = \local_aihub\ai::generate_text(
    '',                    // system prompt (optional)
    $prompt,               // user prompt
    false,                 // JSON mode
    'your_frankenstyle',   // 4th arg: caller component, for the usage log
    'Short label'          // 5th arg: what is being generated, shown in the admin report
);
if ($result['success']) {
    // $result['data'] is RAW, untrusted text — validate and format_text() it.
}

The returned text is raw and untrusted: validate its structure and pass it through format_text() before displaying or persisting it.

🔗 Key resolution (BYOK ladder)

The hub resolves a key tier by tier and stops at the first tier that holds a key:

Within the chosen tier, providers are tried in the order Gemini → Groq → DeepSeek → OpenAI-compatible (first key found is used; if its call fails, the next provider in the same tier is tried). When no tier holds a key, generate_text() returns success = false — the hub never falls back to core_ai; that decision belongs to the consumer.

📦 Requirements

No bundled third-party libraries. The AI providers are external services, declared in the Privacy provider — not in thirdpartylibs.xml.

🛠️ Installation & Configuration

1. Download the .zip file or clone this repository.
2. Extract the folder into your Moodle local/ directory.
3. Rename the folder to aihub (if necessary). Final path: your-moodle/local/aihub/
4. Visit Site administration → Notifications to complete installation.

Configuring a provider key is optional — the plugin installs and works without one. See Usage below for setting site keys and enabling personal keys.

📖 Usage

1. Configure site keys (admin): Site administration → Plugins → Local plugins → AI Hub → Settings. Set any of the Gemini, Groq, DeepSeek or OpenAI-compatible keys, and (optionally) enable personal API keys.
2. Add a personal key (user): users who have the local/aihub:usepersonalkey capability get a My AI keys entry in their preferences, where they store their own key (write-only) and see their recent usage.
3. Review site-key usage (admin): the AI usage report (under the AI Hub category, capability local/aihub:viewusage) lists every request served by the site keys across all users, with CSV and Excel download.
4. Consume from a plugin (developer): call \local_aihub\ai::generate_text() behind a class_exists() guard, keeping your own core_ai fallback (see How consumers use it).

🧪 Automated Tests

The hub ships with a PHPUnit and Behat suite; every CI push runs against the matrix (Moodle 4.5 → 5.x, PostgreSQL & MariaDB).

PHPUnit — Unit & Integration Tests

vendor/bin/phpunit --testsuite local_aihub

Line coverage by class (PHPUnit + Xdebug):

Two classes are intentionally not fully unit-tested, both for the same reason — the untested lines are live network calls, not business logic:

• local\client: call_gemini(), call_groq(), call_deepseek(), call_openai_compatible() and http_post() make real HTTP calls to external providers, so they are never unit-tested against the live network. tests/fixtures/mock_client.php overrides them to test the key-resolution ladder in isolation; the transport methods themselves are verified by hand against the real APIs before each release instead. The DNS-rebinding branch of is_safe_url() used to fall in the same bucket (a real dns_get_record() call), but its resolution step was extracted into resolve_dns(), which tests/fixtures/dns_stub_client.php overrides — so that branch is now fully covered without any real DNS lookup.
• output\renderer: its only method delegates a single line to render_from_template(). Asserting the resulting HTML is a job for the Behat suite below (mykeys.feature), not PHPUnit.

Behat — Acceptance Tests

php admin/tool/behat/cli/init.php
vendor/bin/behat --tags=@local_aihub --profile=chrome

🔐 Security & Compliance

• Capability- and opt-in-gated personal keys (local/aihub:usepersonalkey and the site toggle).
• Write-only personal keys — never returned to the page after saving, even under Log in as.
• Site keys stored with admin_setting_configpasswordunmask; the SSRF guard protects the configurable endpoint.
• require_sesskey() on the key form; capability local/aihub:viewusage on the usage report.
• Full Privacy API coverage (export/delete of the usage log and personal preferences) with the external destinations declared.

🔎 Third-party Service Disclosure

The hub transmits prompt text to a third-party AI provider only when a key is configured and a generation is requested.

Is an API key required?

No. The plugin installs and runs without any key — it simply reports that no source is available, and consumers fall back to their own core_ai integration. No external request is made until a site or personal key is set.

Supported providers

• Google Gemini — https://ai.google.dev/ — model: gemini-flash-latest (rolling alias, always Google’s current Flash release; fixed, not configurable)
• Groq — https://console.groq.com/ — model: openai/gpt-oss-120b (fixed, not configurable; see Groq model choice below)
• DeepSeek — https://deepseek.com/ — model: deepseek-v4-flash (fixed, not configurable)
• OpenAI-compatible APIs — any provider that follows the OpenAI API format (OpenRouter, self-hosted models via LM Studio, an Ollama proxy, etc.) — model: configurable per key (site setting / personal key), defaults to gpt-4o-mini when left empty

These services operate under their own terms of service and privacy policies.

Groq model choice

The Groq slot calls a single fixed model, openai/gpt-oss-120b. Groq periodically deprecates specific model IDs (e.g. llama-3.3-70b-versatile, decommissioned 2026-08-16) and expects migration to a named replacement. Among the free-tier options Groq recommended for this migration, openai/gpt-oss-120b was chosen over qwen/qwen3.6-27b for stronger instruction-following and more reliable JSON-mode output across the varied prompts sent by different consumer plugins.

How to obtain an API key

API keys are created directly on the provider’s official website. Gemini, Groq and DeepSeek currently offer free usage tiers or trial credits (pricing policies may change). The hub does not provide API keys.

Where keys are configured

1. Personal key — set by each user in My AI keys (preferences), when personal keys are enabled and the user has the capability.
2. Site key — set by the admin in Site administration → Plugins → Local plugins → AI Hub.

Data Transmission

When a key resolves to a provider, the prompt text is transmitted to that provider’s API to generate the response:

• Google Gemini — generativelanguage.googleapis.com
• Groq — api.groq.com
• DeepSeek — api.deepseek.com
• OpenAI-compatible — the endpoint configured by the admin or user (default api.openai.com)

The hub stores a usage log (who requested, which component, a short label of what was generated, provider, model, key tier and time) but does not store prompts or AI responses. All external destinations are declared in the plugin’s Privacy provider.

Demo credentials

Not applicable — no credentials are required to install or use the hub. Every AI feature stays inert until a site or personal key is configured.

📄 License

This project is licensed under the GNU General Public License v3 (GPLv3).

Copyright: 2026 Jean Lúcio