diff --git a/.eslintrc.js b/.eslintrc.js
new file mode 100644
index 0000000..3584c62
--- /dev/null
+++ b/.eslintrc.js
@@ -0,0 +1,7 @@
+module.exports = {
+  rules: {
+    // This plugin's Vue SFCs use the `<script setup>`-first ordering
+    // (script before template), so the default tag-order check does not apply.
+    'vue/component-tags-order': 'off',
+  },
+};
diff --git a/.github/workflows/buildvue.yml b/.github/workflows/buildvue.yml
new file mode 100644
index 0000000..000863e
--- /dev/null
+++ b/.github/workflows/buildvue.yml
@@ -0,0 +1,105 @@
+name: Vue build check
+
+on: pull_request
+
+permissions:
+  actions: read
+  checks: read
+  contents: read
+  deployments: none
+  issues: read
+  packages: none
+  pull-requests: read
+  repository-projects: none
+  security-events: none
+  statuses: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PLUGIN_NAME: AIProviders
+
+jobs:
+  buildvue:
+    name: Vue build check
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          lfs: false
+          persist-credentials: false
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
+        with:
+          php-version: '8.1'
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '16'
+
+      - name: Check out github-action-tests repository
+        uses: actions/checkout@v7
+        with:
+          repository: matomo-org/github-action-tests
+          ref: main
+          path: github-action-tests
+
+      - name: Check out Matomo for plugin builds
+        run: ${{ github.workspace }}/github-action-tests/scripts/bash/checkout_matomo.sh
+        env:
+          PLUGIN_NAME: ${{ env.PLUGIN_NAME }}
+          WORKSPACE: ${{ github.workspace }}
+          ACTION_PATH: ${{ github.workspace }}/github-action-tests
+          MATOMO_TEST_TARGET: maximum_supported_matomo
+
+      - name: Install Composer dependencies
+        run: composer install --ignore-platform-reqs --no-progress
+        working-directory: matomo
+
+      - name: Install npm dependencies
+        run: npm install --no-audit --no-fund
+        working-directory: matomo
+
+      - name: Write minimal Matomo config
+        run: |
+          cat <<'EOF' > config/config.ini.php
+          [General]
+          always_load_commands_from_plugin=CoreVue
+
+          [Development]
+          enabled = 1
+          EOF
+        working-directory: matomo
+
+      - name: Build Vue artifacts
+        run: php ./console vue:build ${{ env.PLUGIN_NAME }}
+        working-directory: matomo
+
+      - name: Verify dist matches committed artifacts
+        run: |
+          # Replace the plugin checkout's dist with the freshly built one.
+          # rsync --delete picks up any tracked file the build no longer
+          # produces.
+          rsync -a --delete matomo/plugins/${{ env.PLUGIN_NAME }}/vue/dist/ vue/dist/
+
+          # git respects .gitignore — generated artifacts the plugin
+          # intentionally ignores (e.g. *.map, *.common.js,
+          # *.development.*) won't be staged here, so they don't cause
+          # false-positive drift.
+          git add -A vue/dist/
+
+          if ! git diff --cached --quiet -- vue/dist/; then
+            echo "::error::Vue dist files are out of date."
+            echo ""
+            echo "Drift summary:"
+            git diff --cached --stat -- vue/dist/
+            echo ""
+            echo "Please run './console vue:build ${{ env.PLUGIN_NAME }}' locally and commit the resulting changes under vue/dist/."
+            exit 1
+          fi
+          echo "Vue dist is up to date."
diff --git a/.github/workflows/matomo-tests.yml b/.github/workflows/matomo-tests.yml
new file mode 100644
index 0000000..50d520f
--- /dev/null
+++ b/.github/workflows/matomo-tests.yml
@@ -0,0 +1,53 @@
+# Action for running tests
+# This file has been automatically created.
+# To recreate it you can run this command
+# ./console generate:test-action --plugin="AIProviders" --php-versions="7.2,8.4"
+
+name: Plugin AIProviders Tests
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+  push:
+    branches:
+      - '**.x-dev'
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  checks: none
+  contents: read
+  deployments: none
+  issues: read
+  packages: none
+  pull-requests: read
+  repository-projects: none
+  security-events: none
+  statuses: none
+
+concurrency:
+  group: php-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  PluginTests:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [ '7.2', '8.4' ]
+        target: ['minimum_required_matomo', 'maximum_supported_matomo']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          lfs: true
+          persist-credentials: false
+      - name: Run tests
+        uses: matomo-org/github-action-tests@main
+        with:
+          plugin-name: 'AIProviders'
+          php-version: ${{ matrix.php }}
+          test-type: 'PluginTests'
+          matomo-test-branch: ${{ matrix.target }}
+          artifacts-pass: ${{ secrets.ARTIFACTS_PASS }}
+          upload-artifacts: ${{ matrix.php == '7.2' && matrix.target == 'maximum_supported_matomo' }}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..9283149
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,9 @@
+.DS_Store
+.idea/
+/node_modules
+tests/System/processed/*xml
+/vue/dist/demo.html
+/vue/dist/*.common.js
+/vue/dist/*.map
+/vue/dist/*.development.*
+.codex
diff --git a/AIConversationRequest.php b/AIConversationRequest.php
new file mode 100644
index 0000000..3a271fb
--- /dev/null
+++ b/AIConversationRequest.php
@@ -0,0 +1,273 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+/**
+ * Immutable description of a single conversational round-trip: the full
+ * message history in the canonical shape (see {@link CanonicalMessage}),
+ * plus an optional tool catalogue the model may call.
+ *
+ * This is the multi-turn, tool-capable counterpart of {@link AIRequest}.
+ * Use {@link AIRequest} with {@link AIProviderService::complete()} for
+ * simple prompt-in/text-out features; use this class with
+ * {@link AIProviderService::converse()} when the caller maintains a
+ * conversation and dispatches tool calls itself:
+ *
+ *     $response = $service->converse(
+ *         (new AIConversationRequest($messages, 'AskMatomo'))
+ *             ->withSystemPrompt($systemPrompt)
+ *             ->withTools($toolCatalog)
+ *             ->withMaxTokens(2048)
+ *     );
+ *
+ * The provider returns one assistant turn per call; running tools and
+ * appending their results to the history for the next call is the caller's
+ * responsibility.
+ *
+ * The same hard rule as for {@link AIRequest} applies: values passed to
+ * {@link withProviderId()} and {@link withModel()} must originate from
+ * plugin code constants or server-side configuration — never, directly or
+ * indirectly, from request input.
+ *
+ * @phpstan-import-type CanonicalMessageArray from CanonicalMessage
+ * @phpstan-type ToolCatalogEntryArray array{
+ *     name: string,
+ *     title?: string|null,
+ *     description: string,
+ *     inputSchema: array<string, mixed>,
+ *     outputSchema?: array<string, mixed>|null,
+ *     readOnly?: bool|null,
+ *     destructive?: bool|null,
+ *     idempotent?: bool|null,
+ *     openWorld?: bool|null
+ * }
+ */
+class AIConversationRequest
+{
+    public const DEFAULT_MAX_TOKENS = 2048;
+    public const DEFAULT_TIMEOUT_SECONDS = 60;
+
+    /**
+     * Conversation history in canonical shape, oldest first.
+     *
+     * @var list<CanonicalMessageArray>
+     */
+    private $messages;
+
+    /**
+     * Name of the plugin issuing the request, used for accountability and
+     * future usage accounting (for example `'AskMatomo'`).
+     *
+     * @var string
+     */
+    private $callerPluginName;
+
+    /**
+     * @var string|null
+     */
+    private $systemPrompt = null;
+
+    /**
+     * Tool catalogue offered to the model, in the MCP-aligned shape produced
+     * by the McpServer plugin's tool catalog. The annotation hints
+     * (readOnly/destructive/idempotent/openWorld) are advisory metadata for
+     * the caller's approval flow; providers only forward name, description,
+     * and inputSchema.
+     *
+     * @var list<ToolCatalogEntryArray>
+     */
+    private $tools = [];
+
+    /**
+     * @var string|null
+     */
+    private $providerId = null;
+
+    /**
+     * @var string|null
+     */
+    private $model = null;
+
+    /**
+     * Optional identifier of the feature issuing the request, used for
+     * future usage accounting.
+     *
+     * @var string|null
+     */
+    private $featureKey = null;
+
+    /**
+     * @var int
+     */
+    private $maxTokens = self::DEFAULT_MAX_TOKENS;
+
+    /**
+     * @var float
+     */
+    private $temperature = AIRequest::DEFAULT_TEMPERATURE;
+
+    /**
+     * Provider HTTP timeout. Conversational round-trips replay the whole
+     * history and may produce tool calls, so the default is more generous
+     * than for simple completions.
+     *
+     * @var int
+     */
+    private $timeoutSeconds = self::DEFAULT_TIMEOUT_SECONDS;
+
+    /**
+     * @param list<CanonicalMessageArray> $messages
+     */
+    public function __construct(array $messages, string $callerPluginName)
+    {
+        $this->messages = $messages;
+        $this->callerPluginName = $callerPluginName;
+    }
+
+    public function withSystemPrompt(?string $systemPrompt): self
+    {
+        $request = clone $this;
+        $request->systemPrompt = $systemPrompt;
+
+        return $request;
+    }
+
+    /**
+     * Offers a tool catalogue to the model. See the `$tools` property for the
+     * expected shape.
+     *
+     * @param list<ToolCatalogEntryArray> $tools
+     */
+    public function withTools(array $tools): self
+    {
+        $request = clone $this;
+        $request->tools = $tools;
+
+        return $request;
+    }
+
+    /**
+     * Requests a specific provider. Honoured on unmanaged instances and for
+     * allowlisted caller plugins on managed instances; otherwise the forced
+     * default provider wins. The value must be a plugin constant or
+     * server-side config value, never request input — see the class docblock.
+     */
+    public function withProviderId(?string $providerId): self
+    {
+        $request = clone $this;
+        $request->providerId = $providerId;
+
+        return $request;
+    }
+
+    /**
+     * Requests a specific model. Stripped on managed instances unless the
+     * caller plugin is allowlisted, because the model decides cost there.
+     * The value must be a plugin constant or server-side config value, never
+     * request input — see the class docblock.
+     */
+    public function withModel(?string $model): self
+    {
+        $request = clone $this;
+        $request->model = $model;
+
+        return $request;
+    }
+
+    public function withFeatureKey(?string $featureKey): self
+    {
+        $request = clone $this;
+        $request->featureKey = $featureKey;
+
+        return $request;
+    }
+
+    public function withMaxTokens(int $maxTokens): self
+    {
+        $request = clone $this;
+        $request->maxTokens = $maxTokens;
+
+        return $request;
+    }
+
+    public function withTemperature(float $temperature): self
+    {
+        $request = clone $this;
+        $request->temperature = $temperature;
+
+        return $request;
+    }
+
+    public function withTimeoutSeconds(int $timeoutSeconds): self
+    {
+        $request = clone $this;
+        $request->timeoutSeconds = max(1, $timeoutSeconds);
+
+        return $request;
+    }
+
+    /**
+     * @return list<CanonicalMessageArray>
+     */
+    public function getMessages(): array
+    {
+        return $this->messages;
+    }
+
+    public function getCallerPluginName(): string
+    {
+        return $this->callerPluginName;
+    }
+
+    public function getSystemPrompt(): ?string
+    {
+        return $this->systemPrompt;
+    }
+
+    /**
+     * @return list<ToolCatalogEntryArray>
+     */
+    public function getTools(): array
+    {
+        return $this->tools;
+    }
+
+    public function getProviderId(): ?string
+    {
+        return $this->providerId;
+    }
+
+    public function getModel(): ?string
+    {
+        return $this->model;
+    }
+
+    public function getFeatureKey(): ?string
+    {
+        return $this->featureKey;
+    }
+
+    public function getMaxTokens(): int
+    {
+        return $this->maxTokens;
+    }
+
+    public function getTemperature(): float
+    {
+        return $this->temperature;
+    }
+
+    public function getTimeoutSeconds(): int
+    {
+        return $this->timeoutSeconds;
+    }
+}
diff --git a/AIConversationResponse.php b/AIConversationResponse.php
new file mode 100644
index 0000000..f184d2b
--- /dev/null
+++ b/AIConversationResponse.php
@@ -0,0 +1,171 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+/**
+ * One assistant turn returned by {@link AIProviderService::converse()}: the
+ * assistant's content blocks in the canonical shape (see
+ * {@link CanonicalMessage}), the reason the model stopped, and usage
+ * metadata.
+ *
+ * When `stopReason` is {@link STOP_TOOL_USE} the content contains one or
+ * more `tool_use` blocks; the caller runs the tools and issues a follow-up
+ * request whose history includes this turn and the tool results.
+ *
+ * @phpstan-import-type CanonicalContentBlockArray from CanonicalMessage
+ */
+class AIConversationResponse
+{
+    /**
+     * Canonical stop reasons. Providers map their own vocabulary onto these
+     * where a mapping exists and pass their raw value through otherwise, so
+     * callers should treat unknown values like {@link STOP_END_TURN}.
+     */
+    public const STOP_END_TURN = 'end_turn';
+    public const STOP_TOOL_USE = 'tool_use';
+    public const STOP_MAX_TOKENS = 'max_tokens';
+    public const STOP_SEQUENCE = 'stop_sequence';
+    public const STOP_GUARDRAIL_INTERVENED = 'guardrail_intervened';
+
+    /**
+     * @var string
+     */
+    private $providerId;
+
+    /**
+     * @var string
+     */
+    private $providerName;
+
+    /**
+     * @var string
+     */
+    private $model;
+
+    /**
+     * Canonical assistant content blocks ('text' and/or 'tool_use').
+     *
+     * @var list<CanonicalContentBlockArray>
+     */
+    private $content;
+
+    /**
+     * @var string
+     */
+    private $stopReason;
+
+    /**
+     * Number of input (prompt) tokens reported by the provider, or null when
+     * the provider does not report token usage.
+     *
+     * @var int|null
+     */
+    private $inputTokens;
+
+    /**
+     * Number of output (completion) tokens reported by the provider, or null
+     * when the provider does not report token usage.
+     *
+     * @var int|null
+     */
+    private $outputTokens;
+
+    /**
+     * Total provider request time in milliseconds, including retries.
+     *
+     * @var int|null
+     */
+    private $executionTimeMs;
+
+    /**
+     * @param list<CanonicalContentBlockArray> $content
+     */
+    public function __construct(
+        string $providerId,
+        string $providerName,
+        string $model,
+        array $content,
+        string $stopReason,
+        ?int $inputTokens = null,
+        ?int $outputTokens = null,
+        ?int $executionTimeMs = null
+    ) {
+        $this->providerId = $providerId;
+        $this->providerName = $providerName;
+        $this->model = $model;
+        $this->content = $content;
+        $this->stopReason = $stopReason;
+        $this->inputTokens = $inputTokens;
+        $this->outputTokens = $outputTokens;
+        $this->executionTimeMs = $executionTimeMs;
+    }
+
+    public function getProviderId(): string
+    {
+        return $this->providerId;
+    }
+
+    public function getProviderName(): string
+    {
+        return $this->providerName;
+    }
+
+    public function getModel(): string
+    {
+        return $this->model;
+    }
+
+    /**
+     * @return list<CanonicalContentBlockArray>
+     */
+    public function getContent(): array
+    {
+        return $this->content;
+    }
+
+    public function getStopReason(): string
+    {
+        return $this->stopReason;
+    }
+
+    /**
+     * Concatenated text of all canonical text blocks. Convenience for
+     * logging and for turns that carry no tool calls; tool-aware callers
+     * should read {@link getContent()} instead.
+     */
+    public function getText(): string
+    {
+        $parts = [];
+        foreach ($this->content as $block) {
+            if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                $parts[] = $block['text'];
+            }
+        }
+
+        return implode("\n", $parts);
+    }
+
+    public function getInputTokens(): ?int
+    {
+        return $this->inputTokens;
+    }
+
+    public function getOutputTokens(): ?int
+    {
+        return $this->outputTokens;
+    }
+
+    public function getExecutionTimeMs(): ?int
+    {
+        return $this->executionTimeMs;
+    }
+}
diff --git a/AIProviderResponse.php b/AIProviderResponse.php
new file mode 100644
index 0000000..7bed0d7
--- /dev/null
+++ b/AIProviderResponse.php
@@ -0,0 +1,186 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+class AIProviderResponse
+{
+    /**
+     * @var string
+     */
+    private $providerId;
+
+    /**
+     * @var string
+     */
+    private $providerName;
+
+    /**
+     * @var string
+     */
+    private $model;
+
+    /**
+     * @var string
+     */
+    private $text;
+
+    /**
+     * Number of input (prompt) tokens reported by the provider, or null when
+     * the provider does not report token usage.
+     *
+     * @var int|null
+     */
+    private $inputTokens;
+
+    /**
+     * Number of output (completion) tokens reported by the provider, or null
+     * when the provider does not report token usage.
+     *
+     * @var int|null
+     */
+    private $outputTokens;
+
+    /**
+     * Provider reasoning level that was actually applied.
+     *
+     * @var string
+     */
+    private $reasoningLevel;
+
+    /**
+     * Whether provider-side web search was actually applied.
+     *
+     * @var bool
+     */
+    private $webSearchEnabled;
+
+    /**
+     * Total provider request time in milliseconds, including retries.
+     *
+     * @var int|null
+     */
+    private $executionTimeMs;
+
+    /**
+     * Provider stop reason, when available.
+     *
+     * @var string|null
+     */
+    private $stopReason;
+
+    public function __construct(
+        string $providerId,
+        string $providerName,
+        string $model,
+        string $text,
+        ?int $inputTokens = null,
+        ?int $outputTokens = null,
+        string $reasoningLevel = AIRequest::REASONING_NONE,
+        bool $webSearchEnabled = false,
+        ?int $executionTimeMs = null,
+        ?string $stopReason = null
+    ) {
+        $this->providerId = $providerId;
+        $this->providerName = $providerName;
+        $this->model = $model;
+        $this->text = $text;
+        $this->inputTokens = $inputTokens;
+        $this->outputTokens = $outputTokens;
+        $this->reasoningLevel = $reasoningLevel;
+        $this->webSearchEnabled = $webSearchEnabled;
+        $this->executionTimeMs = $executionTimeMs;
+        $this->stopReason = $stopReason;
+    }
+
+    public function getText(): string
+    {
+        return $this->text;
+    }
+
+    public function getModel(): string
+    {
+        return $this->model;
+    }
+
+    public function getInputTokens(): ?int
+    {
+        return $this->inputTokens;
+    }
+
+    public function getOutputTokens(): ?int
+    {
+        return $this->outputTokens;
+    }
+
+    public function getReasoningLevel(): string
+    {
+        return $this->reasoningLevel;
+    }
+
+    public function isWebSearchEnabled(): bool
+    {
+        return $this->webSearchEnabled;
+    }
+
+    public function getExecutionTimeMs(): ?int
+    {
+        return $this->executionTimeMs;
+    }
+
+    public function getStopReason(): ?string
+    {
+        return $this->stopReason;
+    }
+
+    /**
+     * Returns the response text decoded as a JSON array/object, or null when the
+     * text is not valid JSON. Intended for requests made with
+     * {@link AIRequest::withJsonResponse()}.
+     *
+     * @return array<mixed>|null
+     */
+    public function getJsonData(): ?array
+    {
+        $decoded = json_decode($this->stripJsonCodeFence($this->text), true);
+
+        return is_array($decoded) ? $decoded : null;
+    }
+
+    private function stripJsonCodeFence(string $text): string
+    {
+        $text = trim($text);
+        if (preg_match('/^```(?:json)?\s*(.*?)\s*```$/is', $text, $matches) === 1) {
+            return trim($matches[1]);
+        }
+
+        return $text;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'providerId' => $this->providerId,
+            'providerName' => $this->providerName,
+            'model' => $this->model,
+            'text' => $this->text,
+            'inputTokens' => $this->inputTokens,
+            'outputTokens' => $this->outputTokens,
+            'reasoningLevel' => $this->reasoningLevel,
+            'webSearchEnabled' => $this->webSearchEnabled,
+            'executionTimeMs' => $this->executionTimeMs,
+            'stopReason' => $this->stopReason,
+        ];
+    }
+}
diff --git a/AIProviderService.php b/AIProviderService.php
new file mode 100644
index 0000000..6640fc0
--- /dev/null
+++ b/AIProviderService.php
@@ -0,0 +1,365 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+use InvalidArgumentException;
+use Piwik\Plugins\AIProviders\Exception\AIProviderClientException;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+use Piwik\Plugins\AIProviders\Provider\AIProvider;
+
+/**
+ * Entry point for Matomo plugins that want to run AI features.
+ *
+ * Obtain the service from the dependency injection container and pass an
+ * {@link AIRequest}:
+ *
+ *     $service  = \Piwik\Container\StaticContainer::get(AIProviderService::class);
+ *     $response = $service->complete(new AIRequest($prompt, 'Goals'));
+ *     $text     = $response->getText();
+ */
+class AIProviderService
+{
+    /** Conversational features can run: provider configured and capable. */
+    public const CONVERSATION_READY = 'ready';
+
+    /** No conversation-capable provider is configured (missing credentials or no provider). */
+    public const CONVERSATION_NOT_CONFIGURED = 'not_configured';
+
+    /** A provider is selected but does not implement conversations. */
+    public const CONVERSATION_PROVIDER_UNSUPPORTED = 'provider_unsupported';
+
+    /**
+     * @var Configuration
+     */
+    private $configuration;
+
+    public function __construct(Configuration $configuration)
+    {
+        $this->configuration = $configuration;
+    }
+
+    /**
+     * Completes the given request.
+     *
+     * The provider is resolved in this order: the provider forced by a managed
+     * environment, then the provider requested by
+     * the caller, then the configured default provider. A managed environment
+     * wins even when the caller requests another provider, except for callers
+     * on the `providerSelectionAllowlist` of the managed config, whose
+     * requested provider and model are honoured (see below).
+     *
+     * Allowlisted callers (for example a plugin that must query several AI
+     * engines because comparing the engines is the feature itself) get no
+     * silent fallback: an unknown requested provider throws, and an
+     * unconfigured one fails in the provider. Falling back to the forced
+     * provider would silently produce answers from the wrong engine, which is
+     * worse than a clear error.
+     *
+     * The requested model is forwarded for allowlisted callers and on
+     * unmanaged instances, and stripped otherwise.
+     */
+    public function complete(AIRequest $request): AIProviderResponse
+    {
+        // use the capability level set in the admin ui, unless overwritten through the request
+        if ($request->getCapabilityLevel() === null) {
+            $request = $request->withCapabilityLevel($this->configuration->getDefaultCapabilityLevel());
+        }
+
+        $providers = AIProviders::getAvailableProviders();
+        $resolution = $this->resolveProviderId($request->getProviderId(), $request->getCallerPluginName(), $providers);
+
+        if ($resolution['stripRequestedModel']) {
+            $request = $request->withProviderId($resolution['providerId'])->withModel(null);
+        }
+
+        $provider = $this->requireProvider($providers, $resolution['providerId']);
+        $configuration = $this->configuration->getProviderConfiguration($provider->getId());
+
+        $response = $this->runWithProvider($provider, $configuration, $request);
+
+        /**
+         * TODO: publish an observability event here so billing or monitoring can
+         * hook into AI usage without this plugin depending on them. Emit basic
+         * data, for example:
+         *
+         *     Piwik::postEvent('AIProviders.usage', [[
+         *         'caller'    => $request->getCallerPluginName(),
+         *         'feature'   => $request->getFeatureKey(),
+         *         'idSite'    => $request->getIdSite(),
+         *         'login'     => Piwik::getCurrentUserLogin(),
+         *         'provider'  => $provider->getId(),
+         *         'model'     => $response->getModel(),
+         *         'tokensIn'  => $response->getInputTokens(),
+         *         'tokensOut' => $response->getOutputTokens(),
+         *     ]]);
+         *
+         * Not implemented yet.
+         */
+        return $response;
+    }
+
+    /**
+     * Runs one conversational round-trip (multi-turn messages plus optional
+     * tool calls) and returns the assistant's turn.
+     *
+     * The provider is resolved exactly like in {@link complete()}: forced
+     * provider, then the caller's requested provider when allowlisted, then
+     * the configured default. A provider that does not support conversations
+     * fails with a clear error instead of silently degrading; callers should
+     * gate conversational features on {@link canConverse()}.
+     *
+     * Unlike {@link complete()}, an empty text response is valid here: a turn
+     * may consist solely of tool_use blocks.
+     */
+    public function converse(AIConversationRequest $request): AIConversationResponse
+    {
+        $providers = AIProviders::getAvailableProviders();
+        $resolution = $this->resolveProviderId($request->getProviderId(), $request->getCallerPluginName(), $providers);
+
+        if ($resolution['stripRequestedModel']) {
+            $request = $request->withProviderId($resolution['providerId'])->withModel(null);
+        }
+
+        $provider = $this->requireProvider($providers, $resolution['providerId']);
+
+        if (!$provider->supportsConversations()) {
+            throw new AIProviderClientException(sprintf(
+                '%s does not support multi-turn conversations.',
+                $provider->getName()
+            ));
+        }
+
+        $configuration = $this->configuration->getProviderConfiguration($provider->getId());
+
+        // TODO: publish the same `AIProviders.usage` observability event as
+        // planned for complete() once it is implemented there.
+        return $provider->converse($request, $configuration);
+    }
+
+    /**
+     * Returns whether conversational features can run right now: the default
+     * provider (honouring a managed environment's forced provider) exists, is
+     * configured, and supports conversations. Plugins offering chat-style
+     * features should hide or disable themselves when this returns false; use
+     * {@link getConversationAvailability()} when the reason matters for the UI.
+     */
+    public function canConverse(): bool
+    {
+        return $this->getConversationAvailability()['status'] === self::CONVERSATION_READY;
+    }
+
+    /**
+     * Reports whether conversational features can run, and why not when they
+     * cannot, so callers can show an actionable message instead of a generic
+     * "not configured" notice.
+     *
+     * `status` is one of:
+     * - {@link CONVERSATION_READY}: the default provider exists, supports
+     *   conversations, and is configured.
+     * - {@link CONVERSATION_PROVIDER_UNSUPPORTED}: a provider is selected but
+     *   does not implement conversations (for example a completion-only
+     *   provider). The fix is to switch providers, so this wins over a missing
+     *   configuration.
+     * - {@link CONVERSATION_NOT_CONFIGURED}: the conversation-capable provider
+     *   has no credentials yet, or no provider could be resolved.
+     *
+     * `providerId`/`providerName` identify the resolved provider when one
+     * exists, so the message can name it.
+     *
+     * @return array{status: string, providerId: ?string, providerName: ?string}
+     */
+    public function getConversationAvailability(): array
+    {
+        try {
+            $provider = $this->getDefaultProvider();
+        } catch (InvalidArgumentException $e) {
+            return ['status' => self::CONVERSATION_NOT_CONFIGURED, 'providerId' => null, 'providerName' => null];
+        }
+
+        $base = ['providerId' => $provider->getId(), 'providerName' => $provider->getName()];
+
+        if (!$provider->supportsConversations()) {
+            return ['status' => self::CONVERSATION_PROVIDER_UNSUPPORTED] + $base;
+        }
+
+        if (!$provider->isConfigured($this->configuration->getProviderConfiguration($provider->getId()))) {
+            return ['status' => self::CONVERSATION_NOT_CONFIGURED] + $base;
+        }
+
+        return ['status' => self::CONVERSATION_READY] + $base;
+    }
+
+    /**
+     * Resolves which provider a request runs through: the provider forced by
+     * a managed environment, then the caller's requested provider (always on
+     * unmanaged instances; on managed instances only for callers on the
+     * `providerSelectionAllowlist` — the caller name is self-declared, see
+     * {@link Configuration::isPluginAllowedToSelectProvider()} for why this
+     * is a policy gate, not a sandbox), then the configured default.
+     *
+     * `stripRequestedModel` is true when the forced provider overrode the
+     * request, in which case the caller must also drop the requested model
+     * because the model decides cost on managed instances.
+     *
+     * @return array{providerId: string, stripRequestedModel: bool}
+     */
+    private function resolveProviderId(
+        ?string $requestedProviderId,
+        string $callerPluginName,
+        AIProvidersList $providers
+    ): array {
+        $forcedProviderId = $this->configuration->getForcedProviderId();
+        $hasRequestedProvider = $requestedProviderId !== null && $requestedProviderId !== '';
+
+        if (
+            $forcedProviderId !== null
+            && $hasRequestedProvider
+            && $this->configuration->isPluginAllowedToSelectProvider($callerPluginName)
+        ) {
+            // TODO: consider validating the requested model against a
+            // per-provider `allowedModels` list from the managed config as a
+            // cost backstop, once the planned `AIProviders.usage` event shows
+            // whether actual token usage needs it.
+            return ['providerId' => $requestedProviderId, 'stripRequestedModel' => false];
+        }
+
+        if ($forcedProviderId !== null) {
+            return ['providerId' => $forcedProviderId, 'stripRequestedModel' => true];
+        }
+
+        if ($hasRequestedProvider) {
+            return ['providerId' => $requestedProviderId, 'stripRequestedModel' => false];
+        }
+
+        return [
+            'providerId' => $this->configuration->getDefaultProviderId($providers),
+            'stripRequestedModel' => false,
+        ];
+    }
+
+    private function requireProvider(AIProvidersList $providers, string $providerId): AIProvider
+    {
+        $provider = $providers->getProvider($providerId);
+
+        if ($provider === null) {
+            throw new InvalidArgumentException(sprintf('Unknown AI provider "%s".', $providerId));
+        }
+
+        return $provider;
+    }
+
+    /**
+     * Validates a specific provider and configuration, with no provider
+     * resolution. Restricted to the admin "test connection" flow, which needs
+     * to test an unsaved provider/configuration before it is stored. Delegates
+     * to the provider's lightweight connection probe and throws on failure.
+     *
+     * Callers must enforce their own access control (the admin API gates this
+     * behind super-user access). Because it bypasses resolution — including the
+     * provider forced by a managed environment — it must not be used as a general
+     * completion entry point; use {@link complete()} for that.
+     *
+     * @param array<string, string> $configuration
+     */
+    public function testProviderConnection(AIProvider $provider, array $configuration): void
+    {
+        $provider->verifyConnection($configuration);
+    }
+
+    /**
+     * Executes the request against the given provider and guards against an empty
+     * completion. Used by {@link complete()}.
+     *
+     * @param array<string, string> $configuration
+     */
+    private function runWithProvider(AIProvider $provider, array $configuration, AIRequest $request): AIProviderResponse
+    {
+        $response = $provider->complete($request, $configuration);
+
+        if (trim($response->getText()) === '') {
+            throw new \RuntimeException(sprintf('%s returned an empty response.', $provider->getName()));
+        }
+
+        return $response;
+    }
+
+    /**
+     * Returns the provider that completions run through by default, honouring a
+     * provider forced by a managed environment.
+     */
+    public function getDefaultProvider(): AIProvider
+    {
+        $providers = AIProviders::getAvailableProviders();
+        $forcedProviderId = $this->configuration->getForcedProviderId();
+        $providerId = $forcedProviderId ?? $this->configuration->getDefaultProviderId($providers);
+
+        return $this->requireProvider($providers, $providerId);
+    }
+
+    /**
+     * Returns the configured default model capability level.
+     */
+    public function getDefaultCapabilityLevel(): string
+    {
+        return $this->configuration->getDefaultCapabilityLevel();
+    }
+
+    /**
+     * Returns whether the plugin runs in a managed environment, that is, the
+     * default provider is forced (and locked) from configuration so settings
+     * cannot be changed from the administration UI.
+     */
+    public function isManaged(): bool
+    {
+        return $this->configuration->isManaged();
+    }
+
+    /**
+     * Returns provider status metadata for trusted PHP callers.
+     *
+     * Restricted providers (registered as non-selectable by a managed
+     * environment) are excluded so they stay invisible outside the
+     * allowlisted completion flow.
+     *
+     * @return array<int, array{
+     *     id: string,
+     *     name: string,
+     *     description: string,
+     *     defaultModel: string,
+     *     isDefault: bool,
+     *     isConfigured: bool,
+     *     supportsCustomEndpoint: bool,
+     *     endpointUrl: string
+     * }>
+     */
+    public function getAvailableProviderStatuses(): array
+    {
+        $providers = AIProviders::getAvailableProviders();
+        $defaultProviderId = $this->configuration->getForcedProviderId()
+            ?? $this->configuration->getDefaultProviderId($providers);
+
+        return array_map(function (AIProvider $provider) use ($defaultProviderId): array {
+            $configuration = $this->configuration->getProviderConfiguration($provider->getId());
+
+            return [
+                'id' => $provider->getId(),
+                'name' => $provider->getName(),
+                'description' => $provider->getDescription(),
+                'defaultModel' => $provider->getDefaultModel(),
+                'isDefault' => $provider->getId() === $defaultProviderId,
+                'isConfigured' => $provider->isConfigured($configuration),
+                'supportsCustomEndpoint' => $provider->supportsCustomEndpoint(),
+                'endpointUrl' => $configuration['endpointUrl'],
+            ];
+        }, $providers->getSelectableProviders());
+    }
+}
diff --git a/AIProviders.php b/AIProviders.php
new file mode 100644
index 0000000..182e20a
--- /dev/null
+++ b/AIProviders.php
@@ -0,0 +1,132 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+use Piwik\Piwik;
+use Piwik\Plugin;
+
+class AIProviders extends Plugin
+{
+    public function registerEvents(): array
+    {
+        return [
+            'AIProviders.addAIProviders'             => 'addAIProviders',
+            'Translate.getClientSideTranslationKeys' => 'getClientSideTranslationKeys',
+        ];
+    }
+
+    /**
+     * Registers the built-in AI providers.
+     *
+     * Provider IDs are unique and cannot be overwritten: the first registration
+     * for an ID wins (see {@link AIProvidersList::addProvider()}). This protects
+     * the built-in providers, and a provider that is centrally forced in a
+     * managed environment, from being shadowed by another plugin.
+     */
+    public function addAIProviders(AIProvidersList $providers): void
+    {
+        $providers->addProvider(new Provider\Claude());
+        $providers->addProvider(new Provider\Gemini());
+        $providers->addProvider(new Provider\OpenAI());
+        $providers->addProvider(new Provider\CustomProvider());
+    }
+
+    /**
+     * Returns all AI providers registered by active plugins.
+     */
+    public static function getAvailableProviders(): AIProvidersList
+    {
+        $providers = new AIProvidersList();
+
+        /**
+         * Triggered to let plugins register AI providers.
+         *
+         * Plugins can add providers by calling `$providers->addProvider()` with
+         * a `Piwik\Plugins\AIProviders\Provider\AIProvider` instance.
+         *
+         * **Example**
+         *
+         *     public function registerEvents()
+         *     {
+         *         return ['AIProviders.addAIProviders' => 'addAIProviders'];
+         *     }
+         *
+         *     public function addAIProviders(AIProvidersList $providers): void
+         *     {
+         *         $providers->addProvider(new MyProvider());
+         *     }
+         *
+         * @param AIProvidersList $providers Provider registry to mutate.
+         */
+        Piwik::postEvent('AIProviders.addAIProviders', [$providers]);
+
+        /**
+         * Triggered after providers have been registered, so plugins can remove
+         * or adjust providers before they are shown or used.
+         *
+         * A managed environment that wants providers hidden from users but
+         * still available to allowlisted plugins should demote them with
+         * `$providers->setSelectable($id, false)` instead of removing them
+         * (see {@link AIProvidersList}).
+         *
+         * @param AIProvidersList $providers Provider registry to mutate.
+         */
+        Piwik::postEvent('AIProviders.filterAIProviders', [$providers]);
+
+        return $providers;
+    }
+
+    public function getClientSideTranslationKeys(array &$translations): void
+    {
+        $translations[] = 'AIProviders_ApiKey';
+        $translations[] = 'AIProviders_ApiKeyAlreadyConfiguredPlaceholder';
+        $translations[] = 'AIProviders_ApiKeyPlaceholder';
+        $translations[] = 'AIProviders_BedrockDescription';
+        $translations[] = 'AIProviders_ClaudeDescription';
+        $translations[] = 'AIProviders_ClickTestConnectionToShowAvailableModels';
+        $translations[] = 'AIProviders_ConfigurationIntro';
+        $translations[] = 'AIProviders_CustomProviderDescription';
+        $translations[] = 'AIProviders_DefaultBadge';
+        $translations[] = 'AIProviders_DefaultCapabilityLevel';
+        $translations[] = 'AIProviders_DefaultCapabilityLevelHelp';
+        $translations[] = 'AIProviders_DefaultProvider';
+        $translations[] = 'AIProviders_DefaultProviderHelp';
+        $translations[] = 'AIProviders_DefaultsTitle';
+        $translations[] = 'AIProviders_Disconnect';
+        $translations[] = 'AIProviders_DisconnectSuccess';
+        $translations[] = 'AIProviders_Disconnecting';
+        $translations[] = 'AIProviders_EndpointUrl';
+        $translations[] = 'AIProviders_EndpointUrlPlaceholder';
+        $translations[] = 'AIProviders_GeminiDescription';
+        $translations[] = 'AIProviders_InstantCapability';
+        $translations[] = 'AIProviders_InstantCapabilityDescription';
+        $translations[] = 'AIProviders_ManagedConfigurationHelp';
+        $translations[] = 'AIProviders_MenuTitle';
+        $translations[] = 'AIProviders_Model';
+        $translations[] = 'AIProviders_NoDefaultProviderWarning';
+        $translations[] = 'AIProviders_OpenAIDescription';
+        $translations[] = 'AIProviders_RefreshModels';
+        $translations[] = 'AIProviders_RequestFailed';
+        $translations[] = 'AIProviders_SettingsSaveSuccess';
+        $translations[] = 'AIProviders_StatusConnected';
+        $translations[] = 'AIProviders_StatusNotConnected';
+        $translations[] = 'AIProviders_TestConnection';
+        $translations[] = 'AIProviders_TestConnectionSuccess';
+        $translations[] = 'AIProviders_TestingConnection';
+        $translations[] = 'AIProviders_ThinkingCapability';
+        $translations[] = 'AIProviders_ThinkingCapabilityDescription';
+        $translations[] = 'AIProviders_UnexpectedError';
+        $translations[] = 'AIProviders_UnsavedChanges';
+        $translations[] = 'General_Cancel';
+        $translations[] = 'General_LoadingData';
+    }
+}
diff --git a/AIProvidersList.php b/AIProvidersList.php
new file mode 100644
index 0000000..f1450ce
--- /dev/null
+++ b/AIProvidersList.php
@@ -0,0 +1,146 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+use Piwik\Container\StaticContainer;
+use Piwik\Plugins\AIProviders\Provider\AIProvider;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Registry of the AI providers registered by active plugins.
+ *
+ * Providers come in two flavours:
+ *
+ * - **Selectable** providers (the default) are offered to super users in the
+ *   administration UI and are eligible to become the instance-wide default
+ *   provider.
+ * - **Restricted** (non-selectable) providers stay registered and can serve
+ *   completions, but are hidden from every admin surface and can never become
+ *   the default. A managed environment uses this to keep the
+ *   basic providers available for plugins that are allowed to target a
+ *   specific provider (see {@link AIProviderService::complete()}) while only
+ *   offering the managed provider to users.
+ */
+class AIProvidersList
+{
+    /**
+     * @var array<string, AIProvider>
+     */
+    private $providers = [];
+
+    /**
+     * Selectable flag per provider ID, see the class docblock.
+     *
+     * @var array<string, bool>
+     */
+    private $selectable = [];
+
+    /**
+     * Registers a provider, unless its ID is already taken.
+     *
+     * Provider IDs are unique and cannot be overwritten: the first registration
+     * for a given ID wins and later registrations are ignored. This protects the
+     * built-in providers (and a provider that is centrally forced in a managed
+     * multi-tenant environment) from being shadowed by another plugin. The
+     * selectable flag of the first registration is kept for the same reason.
+     *
+     * @return bool True when the provider was added, false when an entry for the
+     *              same ID already existed and this registration was ignored
+     *              (also logged as a warning so the collision is visible).
+     */
+    public function addProvider(AIProvider $provider, bool $selectable = true): bool
+    {
+        $providerId = $provider->getId();
+
+        if (isset($this->providers[$providerId])) {
+            StaticContainer::get(LoggerInterface::class)->warning(
+                'AI provider "{id}" is already registered as {existing}; ignoring duplicate registration of {ignored}.',
+                [
+                    'id' => $providerId,
+                    'existing' => get_class($this->providers[$providerId]),
+                    'ignored' => get_class($provider),
+                ]
+            );
+
+            return false;
+        }
+
+        $this->providers[$providerId] = $provider;
+        $this->selectable[$providerId] = $selectable;
+
+        return true;
+    }
+
+    public function removeProvider(string $providerId): void
+    {
+        unset($this->providers[$providerId], $this->selectable[$providerId]);
+    }
+
+    /**
+     * Marks a registered provider as selectable or restricted. Intended for
+     * `AIProviders.filterAIProviders` subscribers; unknown IDs are ignored.
+     */
+    public function setSelectable(string $providerId, bool $selectable): void
+    {
+        if (isset($this->providers[$providerId])) {
+            $this->selectable[$providerId] = $selectable;
+        }
+    }
+
+    /**
+     * Returns whether the provider may be offered in the administration UI and
+     * used as the default provider. Unknown providers are not selectable.
+     */
+    public function isSelectable(string $providerId): bool
+    {
+        return $this->selectable[$providerId] ?? false;
+    }
+
+    public function hasProvider(string $providerId): bool
+    {
+        return isset($this->providers[$providerId]);
+    }
+
+    public function getProvider(string $providerId): ?AIProvider
+    {
+        return $this->providers[$providerId] ?? null;
+    }
+
+    /**
+     * Returns all registered providers, including restricted ones. Completion
+     * requests resolve against this list; admin surfaces must use
+     * {@link getSelectableProviders()} instead so restricted providers stay
+     * hidden.
+     *
+     * @return list<AIProvider>
+     */
+    public function getProviders(): array
+    {
+        return array_values($this->providers);
+    }
+
+    /**
+     * Returns the providers that may be shown in the administration UI and
+     * chosen as the default provider.
+     *
+     * @return list<AIProvider>
+     */
+    public function getSelectableProviders(): array
+    {
+        return array_values(array_filter(
+            $this->providers,
+            function (AIProvider $provider): bool {
+                return $this->isSelectable($provider->getId());
+            }
+        ));
+    }
+}
diff --git a/AIRequest.php b/AIRequest.php
new file mode 100644
index 0000000..0091ed2
--- /dev/null
+++ b/AIRequest.php
@@ -0,0 +1,344 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+/**
+ * Immutable description of a single AI completion request.
+ *
+ * Trusted Matomo plugins build an {@link AIRequest} and pass it to
+ * {@link AIProviderService::complete()} to run an AI feature through the
+ * configured provider. Optional values are set with the fluent `with*()`
+ * methods, each of which returns a new instance:
+ *
+ *     $response = $service->complete(
+ *         (new AIRequest('Summarise this report.', 'Goals'))
+ *             ->withSystemPrompt('You are a concise web analytics assistant.')
+ *             ->withCapabilityLevel(Configuration::CAPABILITY_THINKING)
+ *             ->withIdSite($idSite)
+ *     );
+ *
+ * The selected `providerId` is treated as a hint: on a managed environment
+ * it is overridden by the forced default provider,
+ * unless the caller plugin is on the centrally managed
+ * `[AIProviders] providerSelectionAllowlist`, in which case the requested
+ * provider and model are honoured. See {@link AIProviderService::complete()}.
+ *
+ * **Hard rule:** the values passed to {@link withProviderId()} and
+ * {@link withModel()} must originate from plugin code constants or
+ * server-side configuration — never, directly or indirectly, from request
+ * input (`Request::fromRequest()`, `Common::getRequestVar()`, superglobals).
+ * Forwarding request input would let any API/HTTP client pick the provider
+ * and model the server calls, which on managed hosting means circumventing
+ * the centrally managed provider and its cost controls. If users may choose
+ * between engines in a UI, the request parameter must be a key into a
+ * server-side map defined by the plugin, never the provider/model string
+ * itself.
+ */
+class AIRequest
+{
+    public const DEFAULT_MAX_TOKENS = 1024;
+    public const DEFAULT_TEMPERATURE = 0.2;
+
+    public const REASONING_NONE = 'none';
+
+    public const FORMAT_TEXT = 'text';
+    public const FORMAT_JSON = 'json';
+
+    /**
+     * @var string
+     */
+    private $userPrompt;
+
+    /**
+     * Name of the plugin issuing the request, used for accountability and
+     * future usage accounting (for example `'Goals'`).
+     *
+     * @var string
+     */
+    private $callerPluginName;
+
+    /**
+     * @var string|null
+     */
+    private $systemPrompt = null;
+
+    /**
+     * @var string|null
+     */
+    private $providerId = null;
+
+    /**
+     * @var string|null
+     */
+    private $model = null;
+
+    /**
+     * Requested model capability level (see Configuration::CAPABILITY_*).
+     * Advisory for now: providers do not yet map this to a specific model.
+     *
+     * @var string|null
+     */
+    private $capabilityLevel = null;
+
+    /**
+     * Optional identifier of the feature issuing the request (for example
+     * `'goal-recommendation'`), used for future usage accounting.
+     *
+     * @var string|null
+     */
+    private $featureKey = null;
+
+    /**
+     * @var int|null
+     */
+    private $idSite = null;
+
+    /**
+     * @var int
+     */
+    private $maxTokens = self::DEFAULT_MAX_TOKENS;
+
+    /**
+     * @var float
+     */
+    private $temperature = self::DEFAULT_TEMPERATURE;
+
+    /**
+     * Desired response format: FORMAT_TEXT (default) or FORMAT_JSON. In JSON mode
+     * the provider is asked to return a single JSON object — natively where the
+     * provider supports it, otherwise via an explicit instruction.
+     *
+     * @var string
+     */
+    private $responseFormat = self::FORMAT_TEXT;
+
+    /**
+     * Requested reasoning level. Currently advisory only; providers do not send
+     * provider-specific reasoning controls until those request formats are
+     * confirmed.
+     *
+     * @var string
+     */
+    private $reasoningLevel = self::REASONING_NONE;
+
+    /**
+     * Whether the caller wants provider web search. Currently advisory only;
+     * providers do not enable provider-specific web search tools yet.
+     *
+     * @var bool
+     */
+    private $webSearchEnabled = false;
+
+    /**
+     * Future provider-specific thinking budget. Not applied to requests yet.
+     *
+     * @var int|null
+     */
+    private $thinkingBudget = null;
+
+    public function __construct(string $userPrompt, string $callerPluginName)
+    {
+        $this->userPrompt = $userPrompt;
+        $this->callerPluginName = $callerPluginName;
+    }
+
+    public function withSystemPrompt(?string $systemPrompt): self
+    {
+        $request = clone $this;
+        $request->systemPrompt = $systemPrompt;
+
+        return $request;
+    }
+
+    /**
+     * Requests a specific provider. Honoured on unmanaged instances and for
+     * allowlisted caller plugins on managed instances; otherwise the forced
+     * default provider wins (see the class docblock).
+     *
+     * The value must be a plugin constant or server-side config value, never
+     * request input — see the hard rule in the class docblock.
+     */
+    public function withProviderId(?string $providerId): self
+    {
+        $request = clone $this;
+        $request->providerId = $providerId;
+
+        return $request;
+    }
+
+    /**
+     * Requests a specific model. Stripped on managed instances unless the
+     * caller plugin is allowlisted, because the model decides cost there.
+     *
+     * The value must be a plugin constant or server-side config value, never
+     * request input — see the hard rule in the class docblock.
+     */
+    public function withModel(?string $model): self
+    {
+        $request = clone $this;
+        $request->model = $model;
+
+        return $request;
+    }
+
+    public function withCapabilityLevel(?string $capabilityLevel): self
+    {
+        $request = clone $this;
+        $request->capabilityLevel = $capabilityLevel;
+
+        return $request;
+    }
+
+    public function withFeatureKey(?string $featureKey): self
+    {
+        $request = clone $this;
+        $request->featureKey = $featureKey;
+
+        return $request;
+    }
+
+    public function withIdSite(?int $idSite): self
+    {
+        $request = clone $this;
+        $request->idSite = $idSite;
+
+        return $request;
+    }
+
+    public function withMaxTokens(int $maxTokens): self
+    {
+        $request = clone $this;
+        $request->maxTokens = $maxTokens;
+
+        return $request;
+    }
+
+    public function withTemperature(float $temperature): self
+    {
+        $request = clone $this;
+        $request->temperature = $temperature;
+
+        return $request;
+    }
+
+    public function withReasoningLevel(?string $reasoningLevel): self
+    {
+        $request = clone $this;
+        $reasoningLevel = trim((string) $reasoningLevel);
+        $request->reasoningLevel = $reasoningLevel !== '' ? $reasoningLevel : self::REASONING_NONE;
+
+        return $request;
+    }
+
+    public function withWebSearchEnabled(bool $webSearchEnabled): self
+    {
+        $request = clone $this;
+        $request->webSearchEnabled = $webSearchEnabled;
+
+        return $request;
+    }
+
+    public function withThinkingBudget(?int $thinkingBudget): self
+    {
+        $request = clone $this;
+        $request->thinkingBudget = $thinkingBudget;
+
+        return $request;
+    }
+
+    /**
+     * Requests a JSON response. The provider is asked to return a single valid
+     * JSON object; read it with {@link AIProviderResponse::getJsonData()}.
+     */
+    public function withJsonResponse(): self
+    {
+        $request = clone $this;
+        $request->responseFormat = self::FORMAT_JSON;
+
+        return $request;
+    }
+
+    public function getUserPrompt(): string
+    {
+        return $this->userPrompt;
+    }
+
+    public function getCallerPluginName(): string
+    {
+        return $this->callerPluginName;
+    }
+
+    public function getSystemPrompt(): ?string
+    {
+        return $this->systemPrompt;
+    }
+
+    public function getProviderId(): ?string
+    {
+        return $this->providerId;
+    }
+
+    public function getModel(): ?string
+    {
+        return $this->model;
+    }
+
+    public function getCapabilityLevel(): ?string
+    {
+        return $this->capabilityLevel;
+    }
+
+    public function getFeatureKey(): ?string
+    {
+        return $this->featureKey;
+    }
+
+    public function getIdSite(): ?int
+    {
+        return $this->idSite;
+    }
+
+    public function getMaxTokens(): int
+    {
+        return $this->maxTokens;
+    }
+
+    public function getTemperature(): float
+    {
+        return $this->temperature;
+    }
+
+    public function getResponseFormat(): string
+    {
+        return $this->responseFormat;
+    }
+
+    public function getReasoningLevel(): string
+    {
+        return $this->reasoningLevel;
+    }
+
+    public function isWebSearchEnabled(): bool
+    {
+        return $this->webSearchEnabled;
+    }
+
+    public function getThinkingBudget(): ?int
+    {
+        return $this->thinkingBudget;
+    }
+
+    public function isJsonResponse(): bool
+    {
+        return $this->responseFormat === self::FORMAT_JSON;
+    }
+}
diff --git a/API.php b/API.php
new file mode 100644
index 0000000..bf40e8a
--- /dev/null
+++ b/API.php
@@ -0,0 +1,191 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+use Exception;
+use Piwik\Piwik;
+use Piwik\Plugin\API as PluginAPI;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+use Piwik\Plugins\AIProviders\Provider\AIProvider;
+
+/**
+ * Exposes AI provider configuration methods for the Matomo administration UI.
+ *
+ * @method static \Piwik\Plugins\AIProviders\API getInstance()
+ */
+class API extends PluginAPI
+{
+    /**
+     * @var bool
+     */
+    protected $autoSanitizeInputParams = false;
+
+    /**
+     * @var Configuration
+     */
+    private $configuration;
+
+    /**
+     * @var AIProviderService
+     */
+    private $aiProviderService;
+
+    public function __construct(Configuration $configuration, AIProviderService $aiProviderService)
+    {
+        $this->configuration = $configuration;
+        $this->aiProviderService = $aiProviderService;
+    }
+
+    /**
+     * Returns AI provider settings for the administration UI.
+     *
+     * @return array<string, mixed> Provider metadata and masked configuration values.
+     * @throws Exception
+     */
+    public function getSettings(): array
+    {
+        Piwik::checkUserHasSuperUserAccess();
+
+        $providers = AIProviders::getAvailableProviders();
+
+        return $this->configuration->getSettings($providers);
+    }
+
+    /**
+     * Saves AI provider settings from the administration UI.
+     *
+     * API keys should be submitted as POST data and are never returned by this
+     * API. In a managed environment the provider is
+     * forced from configuration, so the submitted default provider, credentials,
+     * and capability level are all ignored.
+     *
+     * All parameters are optional so the form can be saved before any provider
+     * is connected: an empty default provider clears the stored default (or
+     * falls back to the first usable provider), and an empty capability level
+     * keeps the stored one. This lets a super user save credentials or the
+     * default capability level on their own without first connecting a provider.
+     *
+     * @param string $defaultProviderId Provider ID to use by default. Empty to
+     *                                  clear the default / let it fall back.
+     * @param string $defaultCapabilityLevel Default model capability level.
+     *                                       Empty to keep the stored value.
+     * @param string $providerConfigurations JSON object keyed by provider ID
+     *                                      with connection settings.
+     * @return array<string, mixed> Updated provider metadata and masked configuration values.
+     * @throws Exception
+     */
+    public function saveSettings(
+        string $defaultProviderId = '',
+        string $defaultCapabilityLevel = '',
+        #[\SensitiveParameter]
+        string $providerConfigurations = '{}'
+    ): array {
+        Piwik::checkUserHasSuperUserAccess();
+
+        $providers = AIProviders::getAvailableProviders();
+        $configuration = $this->configuration;
+        $configuration->saveSettings(
+            $providers,
+            $defaultProviderId,
+            $defaultCapabilityLevel,
+            $providerConfigurations
+        );
+
+        return $configuration->getSettings($providers);
+    }
+
+    /**
+     * Tests one provider using the submitted connection settings.
+     *
+     * @param string $providerId Provider ID to test.
+     * @param string $providerConfiguration JSON object with unsaved apiKey
+     *                                      and endpointUrl values.
+     * @return array{providerId: string, providerName: string, models: list<string>}
+     *         Tested provider's metadata and the models it can serve (empty for
+     *         providers that do not expose a model listing).
+     * @throws Exception when the connection cannot be established.
+     */
+    public function testConnection(
+        string $providerId,
+        #[\SensitiveParameter]
+        string $providerConfiguration = '{}'
+    ): array {
+        Piwik::checkUserHasSuperUserAccess();
+
+        $providers = AIProviders::getAvailableProviders();
+        $provider = $this->getSelectableProvider($providers, $providerId);
+        $configuration = $this->configuration->getProviderConfigurationForUse(
+            $provider,
+            $this->decodeProviderConfiguration($providerConfiguration)
+        );
+
+        $this->aiProviderService->testProviderConnection($provider, $configuration);
+
+        return [
+            'providerId' => $provider->getId(),
+            'providerName' => $provider->getName(),
+            'models' => $provider->listModels($configuration),
+        ];
+    }
+
+    /**
+     * Removes a stored provider connection.
+     *
+     * @param string $providerId Provider ID to disconnect.
+     * @return array<string, mixed> Updated provider metadata and masked configuration values.
+     * @throws Exception
+     */
+    public function disconnectProvider(string $providerId): array
+    {
+        Piwik::checkUserHasSuperUserAccess();
+
+        $providers = AIProviders::getAvailableProviders();
+        $this->getSelectableProvider($providers, $providerId);
+
+        $this->configuration->removeProviderConfiguration($providerId);
+
+        return $this->configuration->getSettings($providers);
+    }
+
+    /**
+     * Resolves a provider for the administration endpoints. Restricted
+     * providers (registered as non-selectable by a managed environment) are
+     * reported as unknown on purpose, so admin surfaces neither reveal nor
+     * operate on them.
+     */
+    private function getSelectableProvider(AIProvidersList $providers, string $providerId): AIProvider
+    {
+        $provider = $providers->getProvider($providerId);
+
+        if ($provider === null || !$providers->isSelectable($providerId)) {
+            throw new \InvalidArgumentException(sprintf('Unknown AI provider "%s".', $providerId));
+        }
+
+        return $provider;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function decodeProviderConfiguration(
+        #[\SensitiveParameter]
+        string $providerConfigurationJson
+    ): array {
+        $decoded = json_decode($providerConfigurationJson, true);
+
+        if (!is_array($decoded)) {
+            throw new \InvalidArgumentException('Provider configuration must be a JSON object.');
+        }
+
+        return $decoded;
+    }
+}
diff --git a/CanonicalMessage.php b/CanonicalMessage.php
new file mode 100644
index 0000000..1877913
--- /dev/null
+++ b/CanonicalMessage.php
@@ -0,0 +1,122 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+/**
+ * Reference documentation for the canonical, provider-agnostic conversation
+ * message shape used by {@link AIConversationRequest} and {@link AIConversationResponse}.
+ *
+ * Callers persist, build, and read this shape and every provider translates
+ * it to and from its own format inside its `converse()` implementation,
+ * so swapping the configured provider never changes the calling plugin implementation.
+ *
+ * A message is an envelope of role + content blocks:
+ *
+ *     {
+ *         role: 'user' | 'assistant' | 'tool',
+ *         content: list<ContentBlock>
+ *     }
+ *
+ * Roles:
+ * - 'user'      Human-authored text.
+ * - 'assistant' Model output (text and/or tool_use blocks).
+ * - 'tool'      Tool execution results fed back to the model.
+ *
+ * Content block shapes:
+ *
+ *   Text block (user or assistant):
+ *     { type: 'text', text: string }
+ *
+ *   Tool use block (assistant only):
+ *     { type: 'tool_use', id: string, name: string, input: array<string, mixed> }
+ *
+ *     `id` is the provider's correlation id: callers must never invent or
+ *     rewrite it. `input` is a JSON object; providers must keep an empty
+ *     object as `{}` (stdClass) on the wire to satisfy providers that reject
+ *     `[]` for object slots.
+ *
+ *   Tool result block (tool role only):
+ *     {
+ *         type: 'tool_result',
+ *         tool_use_id: string,
+ *         content: list<ToolContentBlock>,
+ *         structuredContent?: array<string, mixed>|null,
+ *         is_error: bool
+ *     }
+ *
+ *     Where `content` is the MCP content block list emitted by the tool
+ *     (each `{type: 'text' | 'image' | …, …}`) and `structuredContent`
+ *     carries the tool's optional structured output word for word. Providers with
+ *     a native JSON return path (for example Bedrock's `{json}` block) will
+ *     prefer `structuredContent` when present.
+ *
+ * ## Importable PHPStan types
+ *
+ * The request/response and provider boundaries import these aliases (with
+ * `@phpstan-import-type ... from CanonicalMessage`) instead of restating the
+ * shape inline, so the contract has a single home that the type checker pins:
+ *
+ * @phpstan-type CanonicalContentBlockArray array<string, mixed>
+ * @phpstan-type CanonicalMessageArray array{role: string, content: list<CanonicalContentBlockArray>}
+ *
+ * `CanonicalContentBlockArray` is intentionally an open map rather than a union of
+ * the text/tool_use/tool_result shapes above: providers build and read blocks
+ * dynamically, so the per-type shapes are documented here as the contract but
+ * not enforced as a closed type.
+ *
+ * The class is never instantiated; it hosts this contract, the PHPStan
+ * aliases the boundaries import, and small static helpers for reading the
+ * canonical shape that producers and providers would otherwise reimplement.
+ */
+final class CanonicalMessage
+{
+    private function __construct()
+    {
+    }
+
+    /**
+     * Extracts the valid `tool_use` blocks from a canonical content list, in
+     * order, as `{id, name, input}`. Non-tool_use blocks and malformed
+     * tool_use blocks (missing id/name or a non-object input) are skipped, and
+     * input keys are normalised to strings so the result always carries a plain
+     * arguments object.
+     *
+     * @param list<CanonicalContentBlockArray> $content canonical content blocks
+     * @return list<array{id: string, name: string, input: array<string, mixed>}>
+     */
+    public static function toolUseBlocks(array $content): array
+    {
+        $blocks = [];
+        foreach ($content as $block) {
+            if (($block['type'] ?? null) !== 'tool_use') {
+                continue;
+            }
+            $id = $block['id'] ?? null;
+            $name = $block['name'] ?? null;
+            $input = $block['input'] ?? [];
+            if (!is_string($id) || !is_string($name) || !is_array($input)) {
+                continue;
+            }
+
+            $normalizedInput = [];
+            foreach ($input as $key => $value) {
+                if (is_string($key)) {
+                    $normalizedInput[$key] = $value;
+                }
+            }
+
+            $blocks[] = ['id' => $id, 'name' => $name, 'input' => $normalizedInput];
+        }
+
+        return $blocks;
+    }
+}
diff --git a/Controller.php b/Controller.php
new file mode 100644
index 0000000..fc06d0f
--- /dev/null
+++ b/Controller.php
@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+use Exception;
+use Piwik\Piwik;
+use Piwik\Plugin\ControllerAdmin;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+
+class Controller extends ControllerAdmin
+{
+    /**
+     * @var Configuration
+     */
+    private $configuration;
+
+    public function __construct(Configuration $configuration)
+    {
+        parent::__construct();
+
+        $this->configuration = $configuration;
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function index(): string
+    {
+        Piwik::checkUserHasSuperUserAccess();
+
+        /**
+         * In a managed environment the provider is
+         * forced from configuration and there is nothing to configure, so the
+         * settings page is intentionally unavailable (the menu entry is hidden
+         * too). This guards against direct URL access.
+         */
+        if ($this->configuration->isManaged()) {
+            throw new Exception('AI provider settings are managed and cannot be changed on this instance.');
+        }
+
+        return $this->renderTemplate('index');
+    }
+}
diff --git a/Exception/AIProviderClientException.php b/Exception/AIProviderClientException.php
new file mode 100644
index 0000000..2f31904
--- /dev/null
+++ b/Exception/AIProviderClientException.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Exception;
+
+/**
+ * Permanent failure caused by the request or the configuration: missing or
+ * rejected credentials, an unknown or incapable provider, a malformed
+ * request, or a provider 4xx response. Retrying the same request will fail
+ * again; the caller should surface the error instead.
+ */
+class AIProviderClientException extends AIProviderException
+{
+}
diff --git a/Exception/AIProviderException.php b/Exception/AIProviderException.php
new file mode 100644
index 0000000..d2a2816
--- /dev/null
+++ b/Exception/AIProviderException.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Exception;
+
+use RuntimeException;
+
+/**
+ * Base exception for AI provider failures.
+ *
+ * Extends RuntimeException so existing callers that catch RuntimeException
+ * keep working. Use the subclasses to decide whether a failure is worth
+ * retrying: {@link AIProviderClientException} is permanent (configuration,
+ * authentication, invalid request), {@link AIProviderServerException} is
+ * transient (provider-side errors, throttling). Failures that fit neither
+ * bucket — transport errors, malformed provider responses — throw this base
+ * class directly.
+ */
+class AIProviderException extends RuntimeException
+{
+}
diff --git a/Exception/AIProviderServerException.php b/Exception/AIProviderServerException.php
new file mode 100644
index 0000000..413fc23
--- /dev/null
+++ b/Exception/AIProviderServerException.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Exception;
+
+/**
+ * Transient provider-side failure: a 5xx response, throttling, or exhausted
+ * capacity. Thrown after the provider's automatic retries are used up, so an
+ * immediate retry is unlikely to help, but a later retry of the same request
+ * may succeed.
+ */
+class AIProviderServerException extends AIProviderException
+{
+}
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
diff --git a/Menu.php b/Menu.php
new file mode 100644
index 0000000..916494a
--- /dev/null
+++ b/Menu.php
@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders;
+
+use Piwik\Menu\MenuAdmin;
+use Piwik\Piwik;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+
+class Menu extends \Piwik\Plugin\Menu
+{
+    /**
+     * @var Configuration
+     */
+    private $configuration;
+
+    public function __construct(Configuration $configuration)
+    {
+        parent::__construct();
+
+        $this->configuration = $configuration;
+    }
+
+    public function configureAdminMenu(MenuAdmin $menu): void
+    {
+        if (!Piwik::hasUserSuperUserAccess()) {
+            return;
+        }
+
+        /**
+         * In a managed environment the provider is
+         * forced from configuration and there is nothing to configure, so the
+         * settings page is hidden entirely.
+         */
+        if ($this->configuration->isManaged()) {
+            return;
+        }
+
+        $menu->addSystemItem('AIProviders_MenuTitle', $this->urlForAction('index'), 36);
+    }
+}
diff --git a/Model/Configuration.php b/Model/Configuration.php
new file mode 100644
index 0000000..bc2d95d
--- /dev/null
+++ b/Model/Configuration.php
@@ -0,0 +1,698 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Model;
+
+use InvalidArgumentException;
+use Piwik\Config;
+use Piwik\Settings\FieldConfig;
+use Piwik\Settings\Plugin\SystemSetting;
+use Piwik\Plugins\AIProviders\AIProvidersList;
+use Piwik\Plugins\AIProviders\Provider\AIProvider;
+
+/**
+ * Stores and resolves the AI provider configuration.
+ *
+ * Provider connection settings come from two sources, merged per field with
+ * the config file winning:
+ *
+ * 1. The database, written from the administration UI ("provider credentials"
+ *    system setting).
+ * 2. The `[AIProviders]` section of `config.ini.php`, or environment
+ *    variables, keyed per provider:
+ *
+ *        [AIProviders]
+ *        openaiApiKey = "..."       ; or env MATOMO_AIPROVIDERS_OPENAI_API_KEY
+ *        openaiEndpointUrl = "..."  ; or env MATOMO_AIPROVIDERS_OPENAI_ENDPOINT_URL
+ *
+ *    The config key is `<providerId>` verbatim plus the field suffix; the
+ *    environment variable upper-cases the ID and replaces `-` with `_`
+ *    (for example `MATOMO_AIPROVIDERS_CUSTOM_PROVIDER_API_KEY`).
+ *
+ * The config-file source is how a managed environment supplies
+ * credentials for providers its own plugins are allowed to target (see
+ * `providerSelectionAllowlist` below) without the credentials ever being
+ * stored in the database or shown in the UI. On a self-hosted instance both
+ * sources belong to the instance owner; config-file credentials simply cannot
+ * be edited or removed from the UI.
+ */
+class Configuration
+{
+    public const SETTING_DEFAULT_PROVIDER = 'defaultProvider';
+    public const SETTING_DEFAULT_CAPABILITY_LEVEL = 'defaultCapabilityLevel';
+    public const SETTING_PROVIDER_CREDENTIALS = 'providerCredentials';
+
+    /**
+     * Key in the `[AIProviders]` config section listing the plugins that may
+     * target a specific provider per request even when a managed environment
+     * forces the default provider. See {@link isPluginAllowedToSelectProvider()}.
+     */
+    public const CONFIG_PROVIDER_SELECTION_ALLOWLIST = 'providerSelectionAllowlist';
+
+    public const CAPABILITY_INSTANT = 'instant';
+    public const CAPABILITY_THINKING = 'thinking';
+
+    private const PLUGIN_NAME = 'AIProviders';
+    private const DEFAULT_PROVIDER_ID = 'openai';
+
+    /**
+     * Stored default provider ID. Persisted in the plugin settings storage, but
+     * not shown on the generic plugin settings page (the settings are not
+     * registered in a settings container). The value can be overridden and
+     * locked from `config.ini.php`, which is how managed environments force
+     * a provider:
+     *
+     *     [AIProviders]
+     *     defaultProvider = "openai"
+     *
+     * @var SystemSetting
+     */
+    private $defaultProvider;
+
+    /**
+     * @var SystemSetting
+     */
+    private $defaultCapabilityLevel;
+
+    /**
+     * Per-provider connection settings keyed by provider ID, for example
+     * `['openai' => ['apiKey' => '...', 'endpointUrl' => '']]`.
+     *
+     * @var SystemSetting
+     */
+    private $providerCredentials;
+
+    public function __construct()
+    {
+        $this->defaultProvider = new SystemSetting(
+            self::SETTING_DEFAULT_PROVIDER,
+            '',
+            FieldConfig::TYPE_STRING,
+            self::PLUGIN_NAME
+        );
+        $this->defaultCapabilityLevel = new SystemSetting(
+            self::SETTING_DEFAULT_CAPABILITY_LEVEL,
+            self::CAPABILITY_INSTANT,
+            FieldConfig::TYPE_STRING,
+            self::PLUGIN_NAME
+        );
+        $this->providerCredentials = new SystemSetting(
+            self::SETTING_PROVIDER_CREDENTIALS,
+            [],
+            FieldConfig::TYPE_ARRAY,
+            self::PLUGIN_NAME
+        );
+    }
+
+    /**
+     * Returns masked AI provider settings for the administration UI.
+     *
+     * Only selectable providers are included, so providers a managed
+     * environment registered as restricted (usable by allowlisted plugins
+     * only) are never revealed to admin surfaces.
+     *
+     * @return array{
+     *     defaultProviderId: string,
+     *     defaultCapabilityLevel: string,
+     *     canEditProviderConfiguration: bool,
+     *     canEditCapabilityLevel: bool,
+     *     capabilityLevels: array<string, array{label: string, description: string}>,
+     *     providers: array<int, array<string, mixed>>
+     * } Provider metadata and masked configuration values.
+     */
+    public function getSettings(AIProvidersList $providers): array
+    {
+        return [
+            'defaultProviderId' => $this->getDefaultProviderId($providers),
+            'defaultCapabilityLevel' => $this->getDefaultCapabilityLevel(),
+            'canEditProviderConfiguration' => $this->canEditProviderConfiguration(),
+            'canEditCapabilityLevel' => $this->canEditCapabilityLevel(),
+            'capabilityLevels' => $this->getCapabilityLevels(),
+            'providers' => array_map(function (AIProvider $provider): array {
+                $providerConfiguration = $this->getProviderConfiguration($provider->getId());
+
+                return array_merge($provider->toArray(), [
+                    'configuration' => [
+                        'hasApiKey' => !empty($providerConfiguration['apiKey']),
+                        'endpointUrl' => $providerConfiguration['endpointUrl'],
+                        'model' => $providerConfiguration['model'],
+                        'isUsable' => $provider->isConfigured($providerConfiguration),
+                    ],
+                ]);
+            }, $providers->getSelectableProviders()),
+        ];
+    }
+
+    /**
+     * Saves the default provider, capability level, and provider connection settings.
+     *
+     * Both are optional so the form can be saved before any provider is
+     * connected: an empty default provider clears it (or falls back to the
+     * first usable one), and an empty capability level keeps the stored value.
+     *
+     * In a managed environment the provider and its credentials
+     * are forced from configuration, so nothing is persisted here.
+     */
+    public function saveSettings(
+        AIProvidersList $providers,
+        string $defaultProviderId,
+        string $defaultCapabilityLevel,
+        #[\SensitiveParameter]
+        string $providerConfigurationsJson
+    ): void {
+        if ($this->canEditProviderConfiguration()) {
+            $submittedProviderConfigurations = $this->decodeProviderConfigurations($providerConfigurationsJson);
+            $this->saveProviderConfigurations($providers, $submittedProviderConfigurations);
+            $this->saveDefaultProviderId($providers, $defaultProviderId);
+        }
+
+        if ($this->canEditCapabilityLevel() && trim($defaultCapabilityLevel) !== '') {
+            $this->saveDefaultCapabilityLevel($defaultCapabilityLevel);
+        }
+    }
+
+    /**
+     * Returns the effective server-side provider configuration including the
+     * API key: per field, a value from the config file or environment wins
+     * over the database value (see the class docblock for the sources).
+     *
+     * The config file always winning keeps the rule identical on managed and
+     * self-hosted instances. It is still safe in a managed environment because
+     * the UI that writes database credentials is locked there from the start,
+     * so no database value can exist to begin with.
+     *
+     * The returned array contains secrets. It is internal to the AIProviders
+     * plugin and its providers and must never be returned from API methods,
+     * logged, or exposed to other plugins; other plugins run completions via
+     * {@link \Piwik\Plugins\AIProviders\AIProviderService::complete()} and
+     * never see credentials.
+     *
+     * @internal
+     * @return array{apiKey: string, endpointUrl: string, model: string}
+     */
+    public function getProviderConfiguration(string $providerId): array
+    {
+        $storedConfiguration = $this->getProviderConfigurations()[$providerId] ?? [
+            'apiKey' => '',
+            'endpointUrl' => '',
+            'model' => '',
+        ];
+        $configFileConfiguration = $this->getConfigFileProviderConfiguration($providerId);
+
+        return [
+            'apiKey' => $configFileConfiguration['apiKey'] !== ''
+                ? $configFileConfiguration['apiKey']
+                : $storedConfiguration['apiKey'],
+            'endpointUrl' => $configFileConfiguration['endpointUrl'] !== ''
+                ? $configFileConfiguration['endpointUrl']
+                : $storedConfiguration['endpointUrl'],
+            'model' => $configFileConfiguration['model'] !== ''
+                ? $configFileConfiguration['model']
+                : $storedConfiguration['model'],
+        ];
+    }
+
+    /**
+     * Returns a validated server-side provider configuration, optionally using
+     * unsaved values from the admin UI for connection testing.
+     *
+     * @param array<string, mixed> $submittedProviderConfiguration
+     * @return array<string, string>
+     */
+    public function getProviderConfigurationForUse(
+        AIProvider $provider,
+        #[\SensitiveParameter]
+        array $submittedProviderConfiguration = []
+    ): array {
+        $providerId = $provider->getId();
+        // Base the merge on the effective configuration so a connection test
+        // exercises what complete() would actually use, including config-file
+        // credentials.
+        $existingConfiguration = $this->getProviderConfiguration($providerId);
+        $submittedProviderConfiguration = array_merge(
+            $existingConfiguration,
+            $submittedProviderConfiguration
+        );
+
+        return [
+            'apiKey' => $this->getSubmittedApiKey(
+                $submittedProviderConfiguration,
+                [$providerId => $existingConfiguration],
+                $providerId
+            ),
+            'endpointUrl' => $this->getSubmittedEndpointUrl($submittedProviderConfiguration, $provider),
+            'model' => $this->getSubmittedModel($submittedProviderConfiguration, $provider),
+        ];
+    }
+
+    /**
+     * Removes the database-stored connection settings for a provider.
+     *
+     * Credentials supplied via the config file or environment (see the class
+     * docblock) are not touched: they are not stored in the database and can
+     * only be removed where they were defined.
+     */
+    public function removeProviderConfiguration(string $providerId): void
+    {
+        $providerConfigurations = $this->getProviderConfigurations();
+        unset($providerConfigurations[$providerId]);
+
+        $this->providerCredentials->setValue($providerConfigurations);
+        $this->providerCredentials->save();
+    }
+
+    /**
+     * @return array<string, array{label: string, description: string}>
+     */
+    public function getCapabilityLevels(): array
+    {
+        return [
+            self::CAPABILITY_INSTANT => [
+                'label' => 'AIProviders_InstantCapability',
+                'description' => 'AIProviders_InstantCapabilityDescription',
+            ],
+            self::CAPABILITY_THINKING => [
+                'label' => 'AIProviders_ThinkingCapability',
+                'description' => 'AIProviders_ThinkingCapabilityDescription',
+            ],
+        ];
+    }
+
+    /**
+     * Returns whether provider connections can be edited in the UI.
+     *
+     * Provider configuration is locked whenever the default provider is forced
+     * from configuration (a managed environment).
+     */
+    public function canEditProviderConfiguration(): bool
+    {
+        return !$this->isManaged();
+    }
+
+    public function canEditCapabilityLevel(): bool
+    {
+        return !$this->isManaged();
+    }
+
+    /**
+     * Returns the forced provider ID when running in a managed environment, or
+     * null when the default provider may be chosen freely.
+     *
+     * Trusted callers use this to honour the centrally managed provider even
+     * when they request a specific one.
+     */
+    public function getForcedProviderId(): ?string
+    {
+        if (!$this->isManaged()) {
+            return null;
+        }
+
+        $providerId = $this->defaultProvider->getValue();
+
+        return is_string($providerId) && $providerId !== '' ? $providerId : null;
+    }
+
+    /**
+     * Returns the configured default provider ID, falling back to the first
+     * configured provider. Only selectable providers are considered, so a
+     * restricted provider can never become the default.
+     */
+    public function getDefaultProviderId(AIProvidersList $providers): string
+    {
+        $providerId = $this->defaultProvider->getValue();
+
+        /**
+         * When forced from configuration, use the
+         * configured provider as-is so misconfiguration surfaces a clear error
+         * from the provider rather than silently falling back.
+         */
+        if ($this->isManaged() && is_string($providerId) && $providerId !== '' && $providers->hasProvider($providerId)) {
+            return $providerId;
+        }
+
+        if (
+            is_string($providerId)
+            && $providers->isSelectable($providerId)
+            && $this->isProviderUsable($providers->getProvider($providerId))
+        ) {
+            return $providerId;
+        }
+
+        if (
+            $providers->isSelectable(self::DEFAULT_PROVIDER_ID)
+            && $this->isProviderUsable($providers->getProvider(self::DEFAULT_PROVIDER_ID))
+        ) {
+            return self::DEFAULT_PROVIDER_ID;
+        }
+
+        return $this->getFirstConfiguredProviderId($providers);
+    }
+
+    private function saveDefaultProviderId(AIProvidersList $providers, string $providerId): void
+    {
+        $providerId = trim($providerId);
+
+        if ($providerId === '') {
+            $providerId = $this->getFirstConfiguredProviderId($providers);
+
+            if ($providerId === '') {
+                $this->defaultProvider->setValue('');
+                $this->defaultProvider->save();
+                return;
+            }
+        }
+
+        // Restricted providers are reported as unknown on purpose: admin
+        // surfaces must not reveal that they exist.
+        if (!$providers->hasProvider($providerId) || !$providers->isSelectable($providerId)) {
+            throw new InvalidArgumentException(sprintf('Unknown AI provider "%s".', $providerId));
+        }
+
+        if (!$this->isProviderUsable($providers->getProvider($providerId))) {
+            throw new InvalidArgumentException(sprintf('AI provider "%s" is not configured.', $providerId));
+        }
+
+        $this->defaultProvider->setValue($providerId);
+        $this->defaultProvider->save();
+    }
+
+    /**
+     * Returns the configured default model capability level.
+     */
+    public function getDefaultCapabilityLevel(): string
+    {
+        $capabilityLevel = $this->defaultCapabilityLevel->getValue();
+
+        if (!is_string($capabilityLevel) || !array_key_exists($capabilityLevel, $this->getCapabilityLevels())) {
+            return self::CAPABILITY_INSTANT;
+        }
+
+        return $capabilityLevel;
+    }
+
+    private function saveDefaultCapabilityLevel(string $capabilityLevel): void
+    {
+        $capabilityLevel = trim($capabilityLevel);
+
+        if (!array_key_exists($capabilityLevel, $this->getCapabilityLevels())) {
+            throw new InvalidArgumentException(sprintf('Unknown AI model capability level "%s".', $capabilityLevel));
+        }
+
+        $this->defaultCapabilityLevel->setValue($capabilityLevel);
+        $this->defaultCapabilityLevel->save();
+    }
+
+    /**
+     * Returns whether the plugin runs in a managed environment, that is, the
+     * default provider is forced (and locked) from configuration.
+     */
+    public function isManaged(): bool
+    {
+        return !$this->defaultProvider->isWritableByCurrentUser();
+    }
+
+    /**
+     * @return array<string, array<string, string>>
+     */
+    private function getProviderConfigurations(): array
+    {
+        $rawValue = $this->providerCredentials->getValue();
+
+        if (!is_array($rawValue)) {
+            return [];
+        }
+
+        $providerConfigurations = [];
+        foreach ($rawValue as $providerId => $providerConfiguration) {
+            if (!is_string($providerId) || !is_array($providerConfiguration)) {
+                continue;
+            }
+
+            $providerConfigurations[$providerId] = [
+                'apiKey' => isset($providerConfiguration['apiKey']) && is_string($providerConfiguration['apiKey'])
+                    ? $providerConfiguration['apiKey']
+                    : '',
+                'endpointUrl' => isset($providerConfiguration['endpointUrl']) && is_string($providerConfiguration['endpointUrl'])
+                    ? $providerConfiguration['endpointUrl']
+                    : '',
+                'model' => isset($providerConfiguration['model']) && is_string($providerConfiguration['model'])
+                    ? $providerConfiguration['model']
+                    : '',
+            ];
+        }
+
+        return $providerConfigurations;
+    }
+
+    /**
+     * @return array<string, array<string, string>>
+     */
+    private function decodeProviderConfigurations(
+        #[\SensitiveParameter]
+        string $providerConfigurationsJson
+    ): array {
+        $decoded = json_decode($providerConfigurationsJson, true);
+
+        if (!is_array($decoded)) {
+            throw new InvalidArgumentException('Provider configurations must be a JSON object.');
+        }
+
+        return $decoded;
+    }
+
+    /**
+     * Persists the submitted provider connection settings to the database.
+     *
+     * Only selectable providers are accepted, so restricted providers cannot
+     * be configured through the administration flow. The API key fallback
+     * reads the stored (database) value on purpose: config-file credentials
+     * must never be copied into the database.
+     *
+     * @param array<string, mixed> $submittedProviderConfigurations
+     */
+    private function saveProviderConfigurations(
+        AIProvidersList $providers,
+        #[\SensitiveParameter]
+        array $submittedProviderConfigurations
+    ): void {
+        $existingProviderConfigurations = $this->getProviderConfigurations();
+        $providerConfigurations = [];
+
+        foreach ($providers->getSelectableProviders() as $provider) {
+            $providerId = $provider->getId();
+            $submittedProviderConfiguration = $submittedProviderConfigurations[$providerId] ?? [];
+
+            if (!is_array($submittedProviderConfiguration)) {
+                throw new InvalidArgumentException(sprintf('Invalid configuration for AI provider "%s".', $providerId));
+            }
+
+            $apiKey = $this->getSubmittedApiKey($submittedProviderConfiguration, $existingProviderConfigurations, $providerId);
+            $endpointUrl = $this->getSubmittedEndpointUrl($submittedProviderConfiguration, $provider);
+            $model = $this->getSubmittedModel($submittedProviderConfiguration, $provider);
+
+            if ($apiKey === '' && $endpointUrl === '') {
+                continue;
+            }
+
+            $providerConfigurations[$providerId] = [
+                'apiKey' => $apiKey,
+                'endpointUrl' => $endpointUrl,
+                'model' => $model,
+            ];
+        }
+
+        $this->providerCredentials->setValue($providerConfigurations);
+        $this->providerCredentials->save();
+    }
+
+    /**
+     * @param array<string, mixed> $submittedProviderConfiguration
+     * @param array<string, array<string, string>> $existingProviderConfigurations
+     */
+    private function getSubmittedApiKey(
+        #[\SensitiveParameter]
+        array $submittedProviderConfiguration,
+        #[\SensitiveParameter]
+        array $existingProviderConfigurations,
+        string $providerId
+    ): string {
+        if (
+            isset($submittedProviderConfiguration['apiKey'])
+            && is_string($submittedProviderConfiguration['apiKey'])
+            && trim($submittedProviderConfiguration['apiKey']) !== ''
+        ) {
+            return trim($submittedProviderConfiguration['apiKey']);
+        }
+
+        return $existingProviderConfigurations[$providerId]['apiKey'] ?? '';
+    }
+
+    /**
+     * @param array<string, mixed> $submittedProviderConfiguration
+     */
+    private function getSubmittedEndpointUrl(array $submittedProviderConfiguration, AIProvider $provider): string
+    {
+        if (!$provider->supportsCustomEndpoint()) {
+            return '';
+        }
+
+        $endpointUrl = isset($submittedProviderConfiguration['endpointUrl'])
+            && is_string($submittedProviderConfiguration['endpointUrl'])
+            ? trim($submittedProviderConfiguration['endpointUrl'])
+            : '';
+
+        if ($endpointUrl === '') {
+            return '';
+        }
+
+        $parsedUrl = parse_url($endpointUrl);
+        $scheme = is_array($parsedUrl) ? ($parsedUrl['scheme'] ?? '') : '';
+
+        if (
+            !filter_var($endpointUrl, FILTER_VALIDATE_URL)
+            || !in_array($scheme, ['http', 'https'], true)
+        ) {
+            throw new InvalidArgumentException(sprintf(
+                'Invalid endpoint URL for AI provider "%s".',
+                $provider->getId()
+            ));
+        }
+
+        return $endpointUrl;
+    }
+
+    /**
+     * The model only applies to providers with a custom endpoint (the admin
+     * picks it from the server's discovered models); it is empty for fixed
+     * hosted providers, which use their own default model.
+     *
+     * @param array<string, mixed> $submittedProviderConfiguration
+     */
+    private function getSubmittedModel(array $submittedProviderConfiguration, AIProvider $provider): string
+    {
+        if (!$provider->supportsCustomEndpoint()) {
+            return '';
+        }
+
+        return isset($submittedProviderConfiguration['model'])
+            && is_string($submittedProviderConfiguration['model'])
+            ? trim($submittedProviderConfiguration['model'])
+            : '';
+    }
+
+    private function getFirstConfiguredProviderId(AIProvidersList $providers): string
+    {
+        foreach ($providers->getSelectableProviders() as $provider) {
+            if ($this->isProviderUsable($provider)) {
+                return $provider->getId();
+            }
+        }
+
+        return '';
+    }
+
+    /**
+     * Returns whether the provider can run completions with its effective
+     * configuration (database merged with config file/environment).
+     */
+    private function isProviderUsable(?AIProvider $provider): bool
+    {
+        if ($provider === null) {
+            return false;
+        }
+
+        return $provider->isConfigured($this->getProviderConfiguration($provider->getId()));
+    }
+
+    /**
+     * Returns whether the given plugin may target a specific provider (and
+     * model) per request even though a managed environment forces the default
+     * provider. Controlled by the `[AIProviders] providerSelectionAllowlist[]`
+     * config entries, which a managed environment keeps in its locked,
+     * centrally managed config.
+     *
+     * This is a policy gate for centrally deployed plugins, not a sandbox:
+     * the caller plugin name on an {@link \Piwik\Plugins\AIProviders\AIRequest}
+     * is self-declared, and PHP code on the same instance can ultimately not
+     * be restrained from anything. The guarantee that matters is that on a
+     * managed instance neither this allowlist nor the values an allowlisted
+     * plugin passes can be influenced by users (see the hard rule on
+     * {@link \Piwik\Plugins\AIProviders\AIRequest::withProviderId()}).
+     */
+    public function isPluginAllowedToSelectProvider(string $pluginName): bool
+    {
+        if ($pluginName === '') {
+            return false;
+        }
+
+        return in_array($pluginName, $this->getProviderSelectionAllowlist(), true);
+    }
+
+    /**
+     * @return string[]
+     */
+    private function getProviderSelectionAllowlist(): array
+    {
+        $config = Config::getInstance()->AIProviders;
+        $allowlist = is_array($config) ? ($config[self::CONFIG_PROVIDER_SELECTION_ALLOWLIST] ?? []) : [];
+
+        // A single `providerSelectionAllowlist = "X"` entry (without `[]`)
+        // parses as a string; accept it as a one-element list.
+        if (is_string($allowlist)) {
+            $allowlist = [$allowlist];
+        }
+
+        if (!is_array($allowlist)) {
+            return [];
+        }
+
+        return array_values(array_filter($allowlist, 'is_string'));
+    }
+
+    /**
+     * Returns the provider connection settings supplied via the config file or
+     * environment variables (see the class docblock for the exact keys).
+     *
+     * @return array{apiKey: string, endpointUrl: string, model: string}
+     */
+    private function getConfigFileProviderConfiguration(string $providerId): array
+    {
+        return [
+            'apiKey' => $this->getConfigFileValue($providerId, 'ApiKey', 'API_KEY'),
+            'endpointUrl' => $this->getConfigFileValue($providerId, 'EndpointUrl', 'ENDPOINT_URL'),
+            'model' => $this->getConfigFileValue($providerId, 'Model', 'MODEL'),
+        ];
+    }
+
+    /**
+     * Reads one provider connection field from the `[AIProviders]` config
+     * section (key `<providerId><configSuffix>`), falling back to the
+     * environment variable `MATOMO_AIPROVIDERS_<PROVIDER_ID>_<ENV_SUFFIX>`.
+     */
+    private function getConfigFileValue(string $providerId, string $configSuffix, string $envSuffix): string
+    {
+        $config = Config::getInstance()->AIProviders;
+        $configKey = $providerId . $configSuffix;
+
+        if (is_array($config) && isset($config[$configKey]) && is_string($config[$configKey]) && trim($config[$configKey]) !== '') {
+            return trim($config[$configKey]);
+        }
+
+        $envKey = 'MATOMO_AIPROVIDERS_' . strtoupper(str_replace('-', '_', $providerId)) . '_' . $envSuffix;
+        $envValue = getenv($envKey);
+
+        if (is_string($envValue) && trim($envValue) !== '') {
+            return trim($envValue);
+        }
+
+        return '';
+    }
+}
diff --git a/Provider/AIProvider.php b/Provider/AIProvider.php
new file mode 100644
index 0000000..f60ac79
--- /dev/null
+++ b/Provider/AIProvider.php
@@ -0,0 +1,1221 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Provider;
+
+use Exception;
+use Piwik\Container\StaticContainer;
+use Piwik\Development;
+use Piwik\Http;
+use Piwik\Log\LoggerInterface;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\CanonicalMessage;
+use Piwik\Plugins\AIProviders\Exception\AIProviderClientException;
+use Piwik\Plugins\AIProviders\Exception\AIProviderException;
+use Piwik\Plugins\AIProviders\Exception\AIProviderServerException;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+
+/**
+ * @phpstan-import-type CanonicalMessageArray from CanonicalMessage
+ * @phpstan-import-type CanonicalContentBlockArray from CanonicalMessage
+ * @phpstan-import-type ToolCatalogEntryArray from AIConversationRequest
+ */
+abstract class AIProvider
+{
+    private const TRANSIENT_ERROR_RETRY_DELAYS = [1, 2];
+
+    private const JSON_RESPONSE_INSTRUCTION = 'Respond with a single valid JSON object and nothing else. Do not wrap it in Markdown code fences.';
+
+    /**
+     * Token budget given to provider-specific "thinking" when the thinking
+     * capability is requested without an explicit per-request budget. Kept well
+     * above Anthropic's 1024-token minimum so it is valid for every provider.
+     */
+    protected const DEFAULT_THINKING_BUDGET = 2048;
+
+    /**
+     * @var string
+     */
+    private $id;
+
+    /**
+     * @var string
+     */
+    private $name;
+
+    /**
+     * @var string
+     */
+    private $description;
+
+    /**
+     * @var bool
+     */
+    private $supportsCustomEndpoint;
+
+    /**
+     * @var int|null
+     */
+    private $lastRequestExecutionTimeMs = null;
+
+    public function __construct(
+        string $id,
+        string $name,
+        string $description,
+        bool $supportsCustomEndpoint = false
+    ) {
+        $this->id = $id;
+        $this->name = $name;
+        $this->description = $description;
+        $this->supportsCustomEndpoint = $supportsCustomEndpoint;
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    public function supportsCustomEndpoint(): bool
+    {
+        return $this->supportsCustomEndpoint;
+    }
+
+    public function getDefaultEndpointUrl(): string
+    {
+        return '';
+    }
+
+    public function getDefaultModel(): string
+    {
+        return '';
+    }
+
+    protected function isTrustedRequestHost(string $host): bool
+    {
+        return false;
+    }
+
+    /**
+     * Completes the given request using the provider.
+     *
+     * Implementations should honor the request's system prompt, model,
+     * max tokens, and temperature, and populate token usage on the response
+     * when the provider reports it.
+     *
+     * @param array<string, string> $configuration
+     */
+    abstract public function complete(AIRequest $request, array $configuration): AIProviderResponse;
+
+    /**
+     * Returns whether the provider implements {@link converse()}: multi-turn
+     * conversations with tool calling. Callers should check
+     * {@link \Piwik\Plugins\AIProviders\AIProviderService::canConverse()}
+     * before offering conversational features.
+     */
+    public function supportsConversations(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Runs one conversational round-trip and returns the assistant's turn in
+     * the canonical shape (see {@link \Piwik\Plugins\AIProviders\CanonicalMessage}).
+     *
+     * Implementations must translate the canonical messages and the tool
+     * catalogue to their wire format, honour the request's system prompt,
+     * model, max tokens, temperature, and timeout, and map their stop-reason
+     * vocabulary to the AIConversationResponse::STOP_* constants where a
+     * mapping exists. Providers that override this method must also override
+     * {@link supportsConversations()} to return true.
+     *
+     * @param array<string, string> $configuration
+     */
+    public function converse(AIConversationRequest $request, array $configuration): AIConversationResponse
+    {
+        throw new AIProviderClientException(
+            sprintf('%s does not support multi-turn conversations.', $this->getName())
+        );
+    }
+
+    /**
+     * Validates the given connection settings, throwing on failure.
+     *
+     * Used by the admin "test connection" flow before a configuration is
+     * stored. The default implementation proves the full round-trip with a
+     * tiny completion; providers that expose a cheaper auth/health endpoint
+     * (e.g. a models listing) should override this to avoid spending
+     * generation tokens. Returns normally when the connection works.
+     *
+     * @param array<string, string> $configuration
+     * @throws AIProviderException when the connection cannot be established
+     */
+    public function verifyConnection(array $configuration): void
+    {
+        $request = (new AIRequest('Reply with the single word: OK', 'AIProviders'))
+            ->withFeatureKey('test-connection')
+            ->withMaxTokens(16);
+
+        $response = $this->complete($request, $configuration);
+
+        if (trim($response->getText()) === '') {
+            throw new AIProviderServerException(sprintf('%s returned an empty response.', $this->getName()));
+        }
+    }
+
+    /**
+     * Returns the list of model identifiers the provider can serve with the
+     * given configuration, used to populate the model picker in the admin UI.
+     * The default implementation returns no models; providers that can discover
+     * them (e.g. an OpenAI-compatible `/models` listing) should override this.
+     *
+     * @param array<string, string> $configuration
+     * @return list<string>
+     */
+    public function listModels(array $configuration): array
+    {
+        return [];
+    }
+
+    /**
+     * Returns whether the provider has everything it needs to run completions.
+     *
+     * Providers that talk to a fixed hosted API require an API key. Providers
+     * that support a custom endpoint instead require the endpoint URL; their
+     * API key is optional, because local LLM servers (Ollama, LM Studio,
+     * llama.cpp, vLLM, …) commonly run with authentication disabled. Providers
+     * whose credentials are supplied by the environment (rather than stored
+     * configuration) should override this method.
+     *
+     * @param array<string, string> $configuration
+     */
+    public function isConfigured(array $configuration): bool
+    {
+        if ($this->supportsCustomEndpoint()) {
+            return trim($configuration['endpointUrl'] ?? '') !== '';
+        }
+
+        return trim($configuration['apiKey'] ?? '') !== '';
+    }
+
+    /**
+     * Returns the model to use for the request, falling back to the provider default.
+     */
+    protected function resolveModel(AIRequest $request): string
+    {
+        $model = $request->getModel();
+
+        // The capability level (instant/thinking) is not a different model: each
+        // provider's default model handles both, toggled by provider-specific
+        // thinking parameters (see wantsThinking()). An explicit per-request
+        // model still wins.
+        return $model !== null && $model !== '' ? $model : $this->getDefaultModel();
+    }
+
+    /**
+     * Returns the model to use for the conversation request, falling back to
+     * the provider default.
+     */
+    protected function resolveConversationModel(AIConversationRequest $request): string
+    {
+        $model = $request->getModel();
+
+        return $model !== null && $model !== '' ? $model : $this->getDefaultModel();
+    }
+
+    /**
+     * Returns the system prompt for the request, augmented with a JSON-output
+     * instruction when JSON mode is requested. Providers should use this rather
+     * than reading the request's system prompt directly, so JSON mode works even
+     * for providers without a native JSON option (and so the word "JSON" is
+     * present, which some providers require to enable their JSON mode).
+     */
+    protected function getSystemPrompt(AIRequest $request): ?string
+    {
+        $systemPrompt = $request->getSystemPrompt();
+
+        if (!$request->isJsonResponse()) {
+            return $systemPrompt;
+        }
+
+        if ($systemPrompt === null || trim($systemPrompt) === '') {
+            return self::JSON_RESPONSE_INSTRUCTION;
+        }
+
+        return rtrim($systemPrompt) . "\n\n" . self::JSON_RESPONSE_INSTRUCTION;
+    }
+
+    /**
+     * @param int|null $inputTokens  Prompt tokens reported by the provider, if any.
+     * @param int|null $outputTokens Completion tokens reported by the provider, if any.
+     */
+    protected function buildResponse(
+        AIRequest $request,
+        string $model,
+        string $text,
+        ?int $inputTokens = null,
+        ?int $outputTokens = null,
+        ?string $stopReason = null
+    ): AIProviderResponse {
+        return new AIProviderResponse(
+            $this->getId(),
+            $this->getName(),
+            $model,
+            trim($text),
+            $inputTokens,
+            $outputTokens,
+            $this->getReasoningLevelUsed($request),
+            $this->isWebSearchUsed($request),
+            $this->lastRequestExecutionTimeMs,
+            $stopReason
+        );
+    }
+
+    /**
+     * @param list<CanonicalContentBlockArray> $content canonical assistant content blocks
+     * @param int|null $inputTokens  Prompt tokens reported by the provider, if any.
+     * @param int|null $outputTokens Completion tokens reported by the provider, if any.
+     */
+    protected function buildConversationResponse(
+        string $model,
+        array $content,
+        string $stopReason,
+        ?int $inputTokens = null,
+        ?int $outputTokens = null
+    ): AIConversationResponse {
+        return new AIConversationResponse(
+            $this->getId(),
+            $this->getName(),
+            $model,
+            $content,
+            $stopReason,
+            $inputTokens,
+            $outputTokens,
+            $this->lastRequestExecutionTimeMs
+        );
+    }
+
+    protected function getReasoningLevelUsed(AIRequest $request): string
+    {
+        // Reported back on the response so callers can see whether the request
+        // actually ran with thinking. Providers that enable thinking per the
+        // resolved capability level all map onto this single flag.
+        return $this->wantsThinking($request) ? Configuration::CAPABILITY_THINKING : AIRequest::REASONING_NONE;
+    }
+
+    protected function isWebSearchUsed(AIRequest $request): bool
+    {
+        // TODO: Implement provider-specific web search/tool configuration for
+        // OpenAI, Gemini, Claude, and managed providers separately.
+        return false;
+    }
+
+    /**
+     * Completes a request against an OpenAI-compatible Chat Completions endpoint.
+     *
+     * Shared by providers that speak the OpenAI `/chat/completions` wire format
+     * (system + user messages, `max_tokens`/`temperature`, and a `usage` object
+     * with `prompt_tokens`/`completion_tokens`).
+     *
+     * @param array<string, string> $headers Additional request headers, such as authentication.
+     */
+    protected function completeChatCompletion(AIRequest $request, string $endpointUrl, array $headers): AIProviderResponse
+    {
+        $messages = [];
+
+        $systemPrompt = $this->getSystemPrompt($request);
+        if ($systemPrompt !== null && $systemPrompt !== '') {
+            $messages[] = ['role' => 'system', 'content' => $systemPrompt];
+        }
+
+        $messages[] = ['role' => 'user', 'content' => $request->getUserPrompt()];
+
+        $model = $this->resolveModel($request);
+
+        $payload = [
+            'model' => $model,
+            'messages' => $messages,
+        ];
+        $payload[$this->chatCompletionTokenLimitField()] = $request->getMaxTokens();
+        if ($this->chatCompletionSupportsTemperature()) {
+            $payload['temperature'] = $request->getTemperature();
+        }
+
+        $payload = array_merge($payload, $this->getExtraChatCompletionPayload($request));
+
+        if ($request->isJsonResponse()) {
+            $payload['response_format'] = ['type' => 'json_object'];
+        }
+
+        $response = $this->sendJsonRequest($endpointUrl, $headers, $payload);
+
+        $text = $response['choices'][0]['message']['content'] ?? '';
+        $finishReason = is_string($response['choices'][0]['finish_reason'] ?? null)
+            ? $response['choices'][0]['finish_reason']
+            : null;
+
+        return $this->buildResponse(
+            $request,
+            $model,
+            is_string($text) ? $text : '',
+            isset($response['usage']['prompt_tokens']) ? (int) $response['usage']['prompt_tokens'] : null,
+            isset($response['usage']['completion_tokens']) ? (int) $response['usage']['completion_tokens'] : null,
+            $finishReason
+        );
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function getExtraChatCompletionPayload(AIRequest $request): array
+    {
+        return [];
+    }
+
+    /**
+     * The Chat Completions field that bounds output length. Defaults to the
+     * classic `max_tokens`; OpenAI's reasoning models require
+     * `max_completion_tokens` instead.
+     */
+    protected function chatCompletionTokenLimitField(): string
+    {
+        return 'max_tokens';
+    }
+
+    /**
+     * Whether the provider accepts a custom `temperature`. Reasoning models
+     * (e.g. OpenAI's gpt-5 family) only allow the default temperature, so they
+     * override this to false and the field is omitted.
+     */
+    protected function chatCompletionSupportsTemperature(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Whether this request should run with the provider's "thinking" mode on.
+     *
+     * The capability level set on the request — or the configured default,
+     * applied by {@link \Piwik\Plugins\AIProviders\AIProviderService::complete()}
+     * — decides this, but an explicit per-request thinking budget always wins:
+     * a budget of 0 forces instant, a positive budget forces thinking. This is
+     * how a caller overrides the configured default for a single request (see
+     * {@link AIRequest::withThinkingBudget()}).
+     */
+    protected function wantsThinking(AIRequest $request): bool
+    {
+        $budget = $request->getThinkingBudget();
+        if ($budget !== null) {
+            return $budget > 0;
+        }
+
+        return $request->getCapabilityLevel() === Configuration::CAPABILITY_THINKING;
+    }
+
+    /**
+     * The thinking token budget to send when thinking is on: the caller's
+     * explicit positive budget, otherwise {@link self::DEFAULT_THINKING_BUDGET}.
+     */
+    protected function thinkingBudget(AIRequest $request): int
+    {
+        $budget = $request->getThinkingBudget();
+
+        return $budget !== null && $budget > 0 ? $budget : self::DEFAULT_THINKING_BUDGET;
+    }
+
+    /**
+     * Runs one conversational round-trip against an OpenAI-compatible Chat
+     * Completions endpoint.
+     *
+     * Shared by providers that speak the OpenAI `/chat/completions` wire format
+     * for multi-turn, tool-calling conversations. The canonical message shape
+     * is translated to OpenAI `messages` (system/user/assistant/tool roles,
+     * assistant `tool_calls` with JSON-string arguments, and one `tool` message
+     * per tool result), the tool catalogue to `tools`, and the response's
+     * `choices[0]` back to canonical content blocks with stop reasons mapped
+     * onto the AIConversationResponse::STOP_* constants.
+     *
+     * @see https://platform.openai.com/docs/api-reference/chat/create
+     * @param array<string, string> $headers Additional request headers, such as authentication.
+     */
+    protected function converseChatCompletion(AIConversationRequest $request, string $endpointUrl, array $headers): AIConversationResponse
+    {
+        $model = $this->resolveConversationModel($request);
+
+        $payload = [
+            'model' => $model,
+            'messages' => $this->canonicalMessagesToOpenAI($request->getMessages(), $request->getSystemPrompt()),
+        ];
+        $payload[$this->chatCompletionTokenLimitField()] = $request->getMaxTokens();
+        if ($this->chatCompletionSupportsTemperature()) {
+            $payload['temperature'] = $request->getTemperature();
+        }
+
+        $tools = $this->toolCatalogToOpenAI($request->getTools());
+        if ($tools !== null) {
+            $payload['tools'] = $tools;
+        }
+
+        $response = $this->sendJsonRequest($endpointUrl, $headers, $payload, $request->getTimeoutSeconds());
+
+        $message = is_array($response['choices'][0]['message'] ?? null) ? $response['choices'][0]['message'] : [];
+        $finishReason = is_string($response['choices'][0]['finish_reason'] ?? null)
+            ? $response['choices'][0]['finish_reason']
+            : '';
+
+        return $this->buildConversationResponse(
+            $model,
+            $this->openAIMessageToCanonical($message),
+            $this->mapOpenAIFinishReason($finishReason),
+            isset($response['usage']['prompt_tokens']) ? (int) $response['usage']['prompt_tokens'] : null,
+            isset($response['usage']['completion_tokens']) ? (int) $response['usage']['completion_tokens'] : null
+        );
+    }
+
+    /**
+     * @param list<CanonicalMessageArray> $messages canonical messages
+     * @return list<array<string, mixed>>
+     */
+    private function canonicalMessagesToOpenAI(array $messages, ?string $systemPrompt): array
+    {
+        $openAIMessages = [];
+
+        if ($systemPrompt !== null && $systemPrompt !== '') {
+            $openAIMessages[] = ['role' => 'system', 'content' => $systemPrompt];
+        }
+
+        foreach ($messages as $message) {
+            if ($message['role'] === 'assistant') {
+                $openAIMessages[] = $this->canonicalAssistantToOpenAI($message['content']);
+                continue;
+            }
+
+            if ($message['role'] === 'tool') {
+                // OpenAI expects one message per tool result, so a single
+                // canonical 'tool' message fans out into N 'tool' messages.
+                foreach ($this->canonicalToolResultsToOpenAI($message['content']) as $toolMessage) {
+                    $openAIMessages[] = $toolMessage;
+                }
+                continue;
+            }
+
+            // Canonical 'user' messages carry only text blocks.
+            $openAIMessages[] = ['role' => 'user', 'content' => $this->textBlocksToString($message['content'])];
+        }
+
+        return $openAIMessages;
+    }
+
+    /**
+     * @param list<CanonicalContentBlockArray> $content canonical assistant content blocks
+     * @return array<string, mixed>
+     */
+    private function canonicalAssistantToOpenAI(array $content): array
+    {
+        $toolCalls = [];
+        foreach (CanonicalMessage::toolUseBlocks($content) as $block) {
+            // tool_call.arguments must be a JSON string holding an object even
+            // when empty; json_encode collapses `[]` to `[]`, so coerce empty
+            // inputs to stdClass so the arguments string is `{}`.
+            $arguments = json_encode($block['input'] === [] ? new \stdClass() : $block['input']);
+            $toolCalls[] = [
+                'id' => $block['id'],
+                'type' => 'function',
+                'function' => [
+                    'name' => $block['name'],
+                    'arguments' => $arguments === false ? '{}' : $arguments,
+                ],
+            ];
+        }
+
+        // OpenAI requires the content key to be present even when tool_calls
+        // carry the turn; an empty string keeps it valid.
+        $message = ['role' => 'assistant', 'content' => $this->textBlocksToString($content)];
+
+        if ($toolCalls !== []) {
+            $message['tool_calls'] = $toolCalls;
+        }
+
+        return $message;
+    }
+
+    /**
+     * @param list<CanonicalContentBlockArray> $content canonical tool_result blocks
+     * @return list<array<string, mixed>>
+     */
+    private function canonicalToolResultsToOpenAI(array $content): array
+    {
+        $messages = [];
+        foreach ($content as $block) {
+            if (($block['type'] ?? null) !== 'tool_result') {
+                continue;
+            }
+            $toolUseId = $block['tool_use_id'] ?? null;
+            if (!is_string($toolUseId)) {
+                continue;
+            }
+            $structured = is_array($block['structuredContent'] ?? null) ? $block['structuredContent'] : null;
+            $mcpContent = is_array($block['content'] ?? null) ? $block['content'] : [];
+
+            $messages[] = [
+                'role' => 'tool',
+                'tool_call_id' => $toolUseId,
+                'content' => $this->toolResultContentToOpenAI($structured, $mcpContent),
+            ];
+        }
+
+        return $messages;
+    }
+
+    /**
+     * OpenAI tool messages carry a single string content. The tool's
+     * structured output, when present, is serialised; otherwise MCP text
+     * blocks are concatenated, with non-text blocks JSON-stringified so their
+     * data still reaches the model.
+     *
+     * @param array<string, mixed>|null $structured
+     * @param list<array<string, mixed>> $mcpContent
+     */
+    private function toolResultContentToOpenAI(?array $structured, array $mcpContent): string
+    {
+        if ($structured !== null) {
+            $serialised = json_encode($structured);
+
+            return $serialised === false ? '' : $serialised;
+        }
+
+        $parts = [];
+        foreach ($mcpContent as $block) {
+            if (!is_array($block)) {
+                continue;
+            }
+            if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                $parts[] = $block['text'];
+                continue;
+            }
+            $serialised = json_encode($block);
+            if ($serialised !== false) {
+                $parts[] = $serialised;
+            }
+        }
+
+        return implode("\n", $parts);
+    }
+
+    /**
+     * Concatenates the text blocks of a canonical content list, ignoring any
+     * non-text blocks. Returns '' when there are none.
+     *
+     * @param list<CanonicalContentBlockArray> $content
+     */
+    private function textBlocksToString(array $content): string
+    {
+        $parts = [];
+        foreach ($content as $block) {
+            if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                $parts[] = $block['text'];
+            }
+        }
+
+        return implode("\n", $parts);
+    }
+
+    /**
+     * @param list<ToolCatalogEntryArray> $tools
+     * @return list<array{type: string, function: array<string, mixed>}>|null
+     */
+    private function toolCatalogToOpenAI(array $tools): ?array
+    {
+        if ($tools === []) {
+            return null;
+        }
+
+        $openAITools = [];
+        foreach ($tools as $tool) {
+            $openAITools[] = [
+                'type' => 'function',
+                'function' => [
+                    'name' => $tool['name'],
+                    'description' => $tool['description'],
+                    'parameters' => $this->toToolParametersObjectSchema($tool['inputSchema']),
+                ],
+            ];
+        }
+
+        return $openAITools;
+    }
+
+    /**
+     * Makes a tool's parameter schema acceptable to OpenAI and Gemini.
+     *
+     * Both reject certain keywords at the top level of the schema
+     * (`oneOf`/`anyOf`/`allOf`/`not`/`enum`/`const`), so this method strips them and
+     * forces a plain top-level `type: object`.
+     *
+     * These are only validation hints, and the tool server re-validates arguments
+     * on the actual call, so nothing is really loosened. Nested property schemas
+     * are left untouched, and `additionalProperties` are kept on purpose
+     * (OpenAI's strict mode requires it).
+     *
+     * Claude and Bedrock accept the original schema and skip this entirely.
+     * Gemini is stricter and adds a deeper recursive strip on top, in
+     * {@see Gemini::geminiParameterSchema()}.
+     *
+     * @param array<string, mixed> $schema
+     * @return array<string, mixed>
+     */
+    protected function toToolParametersObjectSchema(array $schema): array
+    {
+        unset(
+            $schema['oneOf'],
+            $schema['anyOf'],
+            $schema['allOf'],
+            $schema['not'],
+            $schema['enum'],
+            $schema['const']
+        );
+
+        if (($schema['type'] ?? null) !== 'object') {
+            $schema['type'] = 'object';
+        }
+
+        return $schema;
+    }
+
+    /**
+     * @param array<string, mixed> $message OpenAI assistant message
+     * @return list<CanonicalContentBlockArray> canonical assistant content blocks
+     */
+    private function openAIMessageToCanonical(array $message): array
+    {
+        $canonical = [];
+
+        $text = $message['content'] ?? null;
+        if (is_string($text) && $text !== '') {
+            $canonical[] = ['type' => 'text', 'text' => $text];
+        }
+
+        $toolCalls = is_array($message['tool_calls'] ?? null) ? $message['tool_calls'] : [];
+        foreach ($toolCalls as $toolCall) {
+            if (!is_array($toolCall)) {
+                continue;
+            }
+            $id = $toolCall['id'] ?? null;
+            $name = $toolCall['function']['name'] ?? null;
+            if (!is_string($id) || !is_string($name)) {
+                continue;
+            }
+
+            $arguments = $toolCall['function']['arguments'] ?? null;
+            $decoded = is_string($arguments) && $arguments !== '' ? json_decode($arguments, true) : [];
+            $input = [];
+            if (is_array($decoded)) {
+                foreach ($decoded as $key => $value) {
+                    if (is_string($key)) {
+                        $input[$key] = $value;
+                    }
+                }
+            }
+
+            $canonical[] = [
+                'type' => 'tool_use',
+                'id' => $id,
+                'name' => $name,
+                'input' => $input,
+            ];
+        }
+
+        return $canonical;
+    }
+
+    /**
+     * Maps an OpenAI `finish_reason` onto the canonical stop reasons, passing
+     * unknown values through unchanged.
+     */
+    private function mapOpenAIFinishReason(string $finishReason): string
+    {
+        switch ($finishReason) {
+            case 'tool_calls':
+                return AIConversationResponse::STOP_TOOL_USE;
+            case 'stop':
+                return AIConversationResponse::STOP_END_TURN;
+            case 'length':
+                return AIConversationResponse::STOP_MAX_TOKENS;
+            case 'content_filter':
+                return AIConversationResponse::STOP_GUARDRAIL_INTERVENED;
+            default:
+                return $finishReason;
+        }
+    }
+
+    /**
+     * @return array{
+     *     id: string,
+     *     name: string,
+     *     description: string,
+     *     supportsCustomEndpoint: bool,
+     *     defaultModel: string
+     * }
+     */
+    public function toArray(): array
+    {
+        return [
+            'id' => $this->getId(),
+            'name' => $this->getName(),
+            'description' => $this->getDescription(),
+            'supportsCustomEndpoint' => $this->supportsCustomEndpoint(),
+            'defaultModel' => $this->getDefaultModel(),
+        ];
+    }
+
+    /**
+     * @param array<string, string> $configuration
+     */
+    protected function getApiKey(array $configuration): string
+    {
+        $apiKey = trim($configuration['apiKey'] ?? '');
+
+        if ($apiKey === '') {
+            throw new AIProviderClientException(sprintf('No API key is configured for %s.', $this->getName()));
+        }
+
+        return $apiKey;
+    }
+
+    /**
+     * Builds the bearer Authorization header for OpenAI-compatible providers,
+     * omitting it entirely when no API key is configured. This lets custom
+     * endpoints point at local LLM servers that run without authentication
+     * while still sending the key when one is provided.
+     *
+     * @param array<string, string> $configuration
+     * @return array<string, string>
+     */
+    protected function getBearerAuthorizationHeaders(array $configuration): array
+    {
+        $apiKey = trim($configuration['apiKey'] ?? '');
+
+        return $apiKey === '' ? [] : ['Authorization' => 'Bearer ' . $apiKey];
+    }
+
+    /**
+     * @param array<string, string> $configuration
+     */
+    protected function getEndpointUrl(array $configuration): string
+    {
+        $endpointUrl = $this->supportsCustomEndpoint()
+            ? trim($configuration['endpointUrl'] ?? '')
+            : '';
+
+        if ($endpointUrl === '') {
+            $endpointUrl = $this->getDefaultEndpointUrl();
+        }
+
+        if ($endpointUrl === '') {
+            throw new AIProviderClientException(sprintf('No endpoint URL is configured for %s.', $this->getName()));
+        }
+
+        $parsedUrl = parse_url($endpointUrl);
+        $scheme = is_array($parsedUrl) ? ($parsedUrl['scheme'] ?? '') : '';
+
+        if (
+            !filter_var($endpointUrl, FILTER_VALIDATE_URL)
+            || !in_array($scheme, ['http', 'https'], true)
+        ) {
+            throw new AIProviderClientException(sprintf('The endpoint URL for %s is invalid.', $this->getName()));
+        }
+
+        return $endpointUrl;
+    }
+
+    /**
+     * Derives the OpenAI-compatible models-listing endpoint from a chat
+     * completions endpoint, e.g. `.../v1/chat/completions` or a bare `.../v1`
+     * base both become `.../v1/models` — the standard `GET {base}/models`
+     * probe used by the "test connection" flow.
+     */
+    protected function openAiCompatibleModelsEndpoint(string $chatEndpointUrl): string
+    {
+        $base = preg_replace('#/chat/completions/?$#', '', $chatEndpointUrl) ?? $chatEndpointUrl;
+
+        return rtrim($base, '/') . '/models';
+    }
+
+    /**
+     * Sends a JSON request to the provider and returns the decoded JSON object.
+     *
+     * Transient errors (HTTP 500/503) are retried with backoff. Failures are
+     * classified: {@link AIProviderClientException} for authentication and
+     * 4xx responses, {@link AIProviderServerException} for 5xx responses
+     * after retries, {@link AIProviderException} for transport and protocol
+     * failures.
+     *
+     * @param array<string, string> $headers
+     * @param array<string, mixed> $payload
+     * @return array<string, mixed>
+     */
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $requestBody = json_encode($payload);
+
+        if (!is_string($requestBody)) {
+            throw new AIProviderException(sprintf('Could not encode request body for %s.', $this->getName()));
+        }
+
+        return $this->sendRequest('POST', $url, $headers, $requestBody, $timeoutSeconds, $payload);
+    }
+
+    /**
+     * Sends a GET request to the provider and returns the decoded JSON object,
+     * used by the "test connection" probe. Failures are classified exactly as
+     * in {@link sendJsonRequest()}.
+     *
+     * @param array<string, string> $headers
+     * @return array<string, mixed>
+     */
+    protected function sendGetRequest(string $url, array $headers, int $timeoutSeconds = 10): array
+    {
+        return $this->sendRequest('GET', $url, $headers, null, $timeoutSeconds);
+    }
+
+    /**
+     * Performs the actual HTTP exchange, retrying transient errors and
+     * classifying failures. Shared by {@link sendJsonRequest()} and
+     * {@link sendGetRequest()}.
+     *
+     * @param array<string, string> $headers
+     * @param array<string, mixed>|null $debugPayload
+     * @return array<string, mixed>
+     */
+    private function sendRequest(
+        string $method,
+        string $url,
+        array $headers,
+        ?string $requestBody,
+        int $timeoutSeconds,
+        ?array $debugPayload = null
+    ): array {
+        $requestHeaders = [];
+        if ($requestBody !== null) {
+            $requestHeaders[] = 'Content-Type: application/json';
+        }
+        foreach ($headers as $name => $value) {
+            $requestHeaders[] = $name . ': ' . $value;
+        }
+
+        $retryDelays = self::TRANSIENT_ERROR_RETRY_DELAYS;
+        $startedAt = microtime(true);
+
+        $host = parse_url($url, PHP_URL_HOST);
+        $checkHostIsAllowed = !is_string($host) || !$this->isTrustedRequestHost($host);
+
+        for ($attempt = 0; $attempt <= count($retryDelays); $attempt++) {
+            $attemptStartedAt = microtime(true);
+            $this->logProviderRequestDebugMetadata(
+                $method,
+                $url,
+                $timeoutSeconds,
+                strlen($requestBody ?? ''),
+                $attempt + 1,
+                $debugPayload
+            );
+
+            try {
+                $response = Http::sendHttpRequestBy(
+                    Http::getTransportMethod(),
+                    $url,
+                    max(1, $timeoutSeconds),
+                    null,
+                    null,
+                    null,
+                    0,
+                    false,
+                    false,
+                    false,
+                    true,
+                    $method,
+                    null,
+                    null,
+                    $requestBody,
+                    $requestHeaders,
+                    null,
+                    $checkHostIsAllowed
+                );
+            } catch (Exception $e) {
+                $this->logProviderTransportDebugMetadata($method, $url, $timeoutSeconds, $attempt + 1, $e);
+
+                throw new AIProviderException(sprintf(
+                    'Could not connect to %s: %s',
+                    $this->getName(),
+                    $e->getMessage()
+                ), 0, $e);
+            }
+
+            if (!is_array($response)) {
+                throw new AIProviderException(sprintf('%s returned an invalid response.', $this->getName()));
+            }
+
+            $status = (int) ($response['status'] ?? 0);
+            $body = is_string($response['data'] ?? null) ? $response['data'] : '';
+            $decoded = $body !== '' ? json_decode($body, true) : null;
+
+            $this->logProviderResponseDebugMetadata(
+                $method,
+                $url,
+                $timeoutSeconds,
+                $status,
+                strlen($body),
+                (int) round((microtime(true) - $attemptStartedAt) * 1000),
+                $attempt + 1,
+                $debugPayload
+            );
+
+            if ($status >= 200 && $status < 300) {
+                if (!is_array($decoded)) {
+                    throw new AIProviderException(sprintf('%s returned invalid JSON.', $this->getName()));
+                }
+
+                $this->lastRequestExecutionTimeMs = (int) round((microtime(true) - $startedAt) * 1000);
+
+                return $decoded;
+            }
+
+            $providerError = $this->getProviderErrorMessage(is_array($decoded) ? $decoded : []);
+
+            if ($this->isAuthenticationError($providerError)) {
+                throw new AIProviderClientException(sprintf(
+                    '%s rejected the API key. Check the key and try again.',
+                    $this->getName()
+                ));
+            }
+
+            if ($this->shouldRetryTransientError($status, $attempt, $retryDelays)) {
+                sleep($retryDelays[$attempt]);
+                continue;
+            }
+
+            $errorSuffix = $providerError !== '' ? ': ' . substr($providerError, 0, 300) : '';
+            $message = sprintf('%s request failed%s.', $this->getName(), $errorSuffix);
+
+            if ($status >= 500) {
+                throw new AIProviderServerException($message);
+            }
+
+            if ($status >= 400) {
+                throw new AIProviderClientException($message);
+            }
+
+            throw new AIProviderException($message);
+        }
+
+        throw new AIProviderServerException(sprintf('%s request failed.', $this->getName()));
+    }
+
+    /**
+     * @param array<string, mixed> $response
+     */
+    private function getProviderErrorMessage(array $response): string
+    {
+        $message = '';
+
+        if (isset($response['error']) && is_string($response['error'])) {
+            $message = $response['error'];
+        } elseif (isset($response['error']) && is_array($response['error'])) {
+            $error = $response['error'];
+            if (isset($error['message']) && is_string($error['message'])) {
+                $message = $error['message'];
+            } elseif (isset($error['type']) && is_string($error['type'])) {
+                $message = $error['type'];
+            }
+        }
+
+        return $message;
+    }
+
+    /**
+     * Debug-only metadata for local provider testing. Intentionally does not
+     * log request/response content, headers, API keys, prompts, or model output.
+     *
+     * @param array<string, mixed>|null $payload
+     */
+    private function logProviderRequestDebugMetadata(
+        string $method,
+        string $url,
+        int $timeoutSeconds,
+        int $requestBytes,
+        int $attempt,
+        ?array $payload
+    ): void {
+        if (!Development::isEnabled()) {
+            return;
+        }
+
+        StaticContainer::get(LoggerInterface::class)->debug(
+            'AIProviders debug provider request metadata: provider={provider}, method={method}, '
+            . 'host={host}, path={path}, model={model}, thinking={thinking}, timeoutSeconds={timeoutSeconds}, '
+            . 'attempt={attempt}, requestBytes={requestBytes}',
+            array_merge($this->getProviderRequestDebugMetadata($url, $payload), [
+                'provider' => $this->getName(),
+                'method' => $method,
+                'timeoutSeconds' => $timeoutSeconds,
+                'attempt' => $attempt,
+                'requestBytes' => $requestBytes,
+            ])
+        );
+    }
+
+    /**
+     * @param array<string, mixed>|null $payload
+     */
+    private function logProviderResponseDebugMetadata(
+        string $method,
+        string $url,
+        int $timeoutSeconds,
+        int $status,
+        int $responseBytes,
+        int $durationMs,
+        int $attempt,
+        ?array $payload
+    ): void {
+        if (!Development::isEnabled()) {
+            return;
+        }
+
+        StaticContainer::get(LoggerInterface::class)->debug(
+            'AIProviders debug provider response metadata: provider={provider}, method={method}, '
+            . 'host={host}, path={path}, model={model}, thinking={thinking}, timeoutSeconds={timeoutSeconds}, '
+            . 'attempt={attempt}, status={status}, durationMs={durationMs}, responseBytes={responseBytes}',
+            array_merge($this->getProviderRequestDebugMetadata($url, $payload), [
+                'provider' => $this->getName(),
+                'method' => $method,
+                'timeoutSeconds' => $timeoutSeconds,
+                'attempt' => $attempt,
+                'status' => $status,
+                'durationMs' => $durationMs,
+                'responseBytes' => $responseBytes,
+            ])
+        );
+    }
+
+    private function logProviderTransportDebugMetadata(
+        string $method,
+        string $url,
+        int $timeoutSeconds,
+        int $attempt,
+        Exception $exception
+    ): void {
+        if (!Development::isEnabled()) {
+            return;
+        }
+
+        StaticContainer::get(LoggerInterface::class)->debug(
+            'AIProviders debug provider transport metadata: provider={provider}, method={method}, '
+            . 'host={host}, path={path}, timeoutSeconds={timeoutSeconds}, attempt={attempt}, '
+            . 'exceptionClass={exceptionClass}',
+            array_merge($this->getProviderRequestDebugMetadata($url, null), [
+                'provider' => $this->getName(),
+                'method' => $method,
+                'timeoutSeconds' => $timeoutSeconds,
+                'attempt' => $attempt,
+                'exceptionClass' => get_class($exception),
+            ])
+        );
+    }
+
+    /**
+     * @param array<string, mixed>|null $payload
+     * @return array{host: string, path: string, model: string, thinking: string}
+     */
+    private function getProviderRequestDebugMetadata(string $url, ?array $payload): array
+    {
+        $path = (string) parse_url($url, PHP_URL_PATH);
+
+        return [
+            'host' => (string) parse_url($url, PHP_URL_HOST),
+            'path' => $path,
+            'model' => $this->getDebugModel($payload, $path),
+            'thinking' => $this->getDebugThinking($payload),
+        ];
+    }
+
+    /**
+     * @param array<string, mixed>|null $payload
+     */
+    private function getDebugModel(?array $payload, string $path): string
+    {
+        if (isset($payload['model']) && is_string($payload['model'])) {
+            return $payload['model'];
+        }
+
+        if (preg_match('~/models/([^/:]+)~', $path, $matches)) {
+            return $matches[1];
+        }
+
+        return '';
+    }
+
+    /**
+     * @param array<string, mixed>|null $payload
+     */
+    private function getDebugThinking(?array $payload): string
+    {
+        if ($payload === null) {
+            return 'unknown';
+        }
+
+        if (isset($payload['reasoning_effort']) && is_string($payload['reasoning_effort'])) {
+            return $payload['reasoning_effort'] === 'none' ? 'no' : 'yes';
+        }
+
+        if (isset($payload['thinking']) && is_array($payload['thinking'])) {
+            return 'yes';
+        }
+
+        $thinkingBudget = $payload['generationConfig']['thinkingConfig']['thinkingBudget'] ?? null;
+        if (is_int($thinkingBudget) || is_float($thinkingBudget)) {
+            return $thinkingBudget > 0 ? 'yes' : 'no';
+        }
+
+        return 'unknown';
+    }
+
+    private function isAuthenticationError(string $message): bool
+    {
+        $message = strtolower($message);
+
+        return strpos($message, 'api key') !== false
+            || strpos($message, 'x-api-key') !== false
+            || strpos($message, 'authentication') !== false
+            || strpos($message, 'unauthorized') !== false
+            || strpos($message, 'invalid key') !== false;
+    }
+
+    /**
+     * @param int[] $retryDelays
+     */
+    private function shouldRetryTransientError(int $status, int $attempt, array $retryDelays): bool
+    {
+        return in_array($status, [500, 503], true)
+            && array_key_exists($attempt, $retryDelays);
+    }
+}
diff --git a/Provider/Claude.php b/Provider/Claude.php
new file mode 100644
index 0000000..d6dd27b
--- /dev/null
+++ b/Provider/Claude.php
@@ -0,0 +1,392 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Provider;
+
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\CanonicalMessage;
+
+/**
+ * @phpstan-import-type CanonicalMessageArray from CanonicalMessage
+ * @phpstan-import-type CanonicalContentBlockArray from CanonicalMessage
+ * @phpstan-import-type ToolCatalogEntryArray from AIConversationRequest
+ */
+class Claude extends AIProvider
+{
+    private const DEFAULT_MODEL = 'claude-haiku-4-5';
+    private const ANTHROPIC_VERSION = '2023-06-01';
+
+    // Anthropic requires budget_tokens >= 1024 and strictly < max_tokens; this
+    // headroom keeps room for the visible answer on top of the thinking budget.
+    private const THINKING_MIN_BUDGET = 1024;
+    private const THINKING_OUTPUT_HEADROOM = 1024;
+
+    public function __construct()
+    {
+        parent::__construct('claude', 'Claude', 'AIProviders_ClaudeDescription');
+    }
+
+    public function getDefaultEndpointUrl(): string
+    {
+        return 'https://api.anthropic.com/v1/messages';
+    }
+
+    public function getDefaultModel(): string
+    {
+        return self::DEFAULT_MODEL;
+    }
+
+    /**
+     * Custom Claude chat completion method.
+     * @see https://platform.claude.com/docs/en/api/messages/create
+     * @param array<string, string> $configuration
+     */
+    public function complete(AIRequest $request, array $configuration): AIProviderResponse
+    {
+        $model = $this->resolveModel($request);
+
+        $payload = [
+            'model' => $model,
+            'max_tokens' => $request->getMaxTokens(),
+            'temperature' => $request->getTemperature(),
+            'messages' => [
+                [
+                    'role' => 'user',
+                    'content' => $request->getUserPrompt(),
+                ],
+            ],
+        ];
+
+        $this->applyThinking($payload, $request);
+
+        $systemPrompt = $this->getSystemPrompt($request);
+        if ($systemPrompt !== null && $systemPrompt !== '') {
+            $payload['system'] = $systemPrompt;
+        }
+
+        $response = $this->sendJsonRequest(
+            $this->getEndpointUrl($configuration),
+            [
+                'anthropic-version' => self::ANTHROPIC_VERSION,
+                'x-api-key' => $this->getApiKey($configuration),
+            ],
+            $payload
+        );
+
+        $text = $response['content'][0]['text'] ?? '';
+        $stopReason = is_string($response['stop_reason'] ?? null) ? $response['stop_reason'] : null;
+
+        return $this->buildResponse(
+            $request,
+            $model,
+            is_string($text) ? $text : '',
+            isset($response['usage']['input_tokens']) ? (int) $response['usage']['input_tokens'] : null,
+            isset($response['usage']['output_tokens']) ? (int) $response['usage']['output_tokens'] : null,
+            $stopReason
+        );
+    }
+
+    /**
+     * Turns on Anthropic extended thinking when the request resolves to the
+     * thinking capability. Enabling it has three wire requirements: the
+     * `thinking` block with a budget of at least 1024 tokens, a `max_tokens`
+     * strictly larger than that budget (bumped here when needed), and no custom
+     * `temperature` (only the default is allowed with thinking), so it is
+     * dropped. Instant requests leave the payload untouched.
+     *
+     * @param array<string, mixed> $payload
+     */
+    private function applyThinking(array &$payload, AIRequest $request): void
+    {
+        if (!$this->wantsThinking($request)) {
+            return;
+        }
+
+        $budget = max(self::THINKING_MIN_BUDGET, $this->thinkingBudget($request));
+
+        $payload['thinking'] = ['type' => 'enabled', 'budget_tokens' => $budget];
+        $payload['max_tokens'] = max($request->getMaxTokens(), $budget + self::THINKING_OUTPUT_HEADROOM);
+        unset($payload['temperature']);
+    }
+
+    /**
+     * Validates credentials and reachability with a cheap models listing
+     * (`GET /v1/models`) instead of spending generation tokens.
+     *
+     * @see https://platform.claude.com/docs/en/api/models-list
+     * @param array<string, string> $configuration
+     */
+    public function verifyConnection(array $configuration): void
+    {
+        $modelsEndpoint = preg_replace(
+            '#/messages/?$#',
+            '/models',
+            $this->getEndpointUrl($configuration)
+        ) ?? $this->getEndpointUrl($configuration);
+
+        $this->sendGetRequest(
+            $modelsEndpoint,
+            [
+                'anthropic-version' => self::ANTHROPIC_VERSION,
+                'x-api-key' => $this->getApiKey($configuration),
+            ]
+        );
+    }
+
+    public function supportsConversations(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Runs one conversational round-trip against the Anthropic Messages API.
+     *
+     * The canonical message shape maps almost one-to-one onto the Anthropic
+     * wire format: roles, text/tool_use/tool_result blocks, and the
+     * end_turn/tool_use/max_tokens/stop_sequence stop reasons all match.
+     * Canonical 'tool' messages fold into 'user' messages carrying
+     * tool_result blocks; consecutive same-role messages are valid input
+     * (the API combines them), so no merging is needed.
+     *
+     * @see https://platform.claude.com/docs/en/api/messages/create
+     * @param array<string, string> $configuration
+     */
+    public function converse(AIConversationRequest $request, array $configuration): AIConversationResponse
+    {
+        $model = $this->resolveConversationModel($request);
+
+        $payload = [
+            'model' => $model,
+            'max_tokens' => $request->getMaxTokens(),
+            'temperature' => $request->getTemperature(),
+            'messages' => $this->canonicalMessagesToAnthropic($request->getMessages()),
+        ];
+
+        $systemPrompt = $request->getSystemPrompt();
+        if ($systemPrompt !== null && $systemPrompt !== '') {
+            $payload['system'] = $systemPrompt;
+        }
+
+        $tools = $this->toolCatalogToAnthropic($request->getTools());
+        if ($tools !== null) {
+            $payload['tools'] = $tools;
+        }
+
+        $response = $this->sendJsonRequest(
+            $this->getEndpointUrl($configuration),
+            [
+                'anthropic-version' => self::ANTHROPIC_VERSION,
+                'x-api-key' => $this->getApiKey($configuration),
+            ],
+            $payload,
+            $request->getTimeoutSeconds()
+        );
+
+        $rawContent = is_array($response['content'] ?? null) ? $response['content'] : [];
+        $stopReason = is_string($response['stop_reason'] ?? null) ? $response['stop_reason'] : '';
+
+        return $this->buildConversationResponse(
+            $model,
+            $this->anthropicContentToCanonical($rawContent),
+            $stopReason,
+            isset($response['usage']['input_tokens']) ? (int) $response['usage']['input_tokens'] : null,
+            isset($response['usage']['output_tokens']) ? (int) $response['usage']['output_tokens'] : null
+        );
+    }
+
+    /**
+     * @param list<CanonicalMessageArray> $messages canonical messages
+     * @return list<array{role: string, content: list<array<string, mixed>>}>
+     */
+    private function canonicalMessagesToAnthropic(array $messages): array
+    {
+        $anthropicMessages = [];
+        foreach ($messages as $message) {
+            // Anthropic uses two roles; canonical 'tool' rows carry their
+            // tool_result blocks under role=user so the tool_use/tool_result
+            // pairing survives the round trip.
+            $role = $message['role'] === 'assistant' ? 'assistant' : 'user';
+
+            $blocks = [];
+            foreach ($message['content'] as $block) {
+                $translated = $this->canonicalBlockToAnthropic($block);
+                if ($translated !== null) {
+                    $blocks[] = $translated;
+                }
+            }
+
+            $anthropicMessages[] = ['role' => $role, 'content' => $blocks];
+        }
+
+        return $anthropicMessages;
+    }
+
+    /**
+     * @param array<string, mixed> $block
+     * @return array<string, mixed>|null null when the block shape is unrecognised
+     */
+    private function canonicalBlockToAnthropic(array $block): ?array
+    {
+        $type = $block['type'] ?? null;
+
+        if ($type === 'text' && is_string($block['text'] ?? null)) {
+            return ['type' => 'text', 'text' => $block['text']];
+        }
+
+        if ($type === 'tool_use') {
+            $id = $block['id'] ?? null;
+            $name = $block['name'] ?? null;
+            $input = $block['input'] ?? [];
+            if (!is_string($id) || !is_string($name) || !is_array($input)) {
+                return null;
+            }
+
+            // tool_use.input must be a JSON object even when empty;
+            // json_decode collapses `{}` to `[]`, so coerce empty inputs back
+            // to stdClass so json_encode produces `{}` again.
+            return [
+                'type' => 'tool_use',
+                'id' => $id,
+                'name' => $name,
+                'input' => $input === [] ? new \stdClass() : $input,
+            ];
+        }
+
+        if ($type === 'tool_result') {
+            $toolUseId = $block['tool_use_id'] ?? null;
+            if (!is_string($toolUseId)) {
+                return null;
+            }
+            $structured = is_array($block['structuredContent'] ?? null) ? $block['structuredContent'] : null;
+            $mcpContent = is_array($block['content'] ?? null) ? $block['content'] : [];
+
+            return [
+                'type' => 'tool_result',
+                'tool_use_id' => $toolUseId,
+                'content' => $this->toolResultContentToAnthropic($structured, $mcpContent),
+                'is_error' => !empty($block['is_error']),
+            ];
+        }
+
+        return null;
+    }
+
+    /**
+     * Anthropic tool_result content is a list of text/image blocks. The
+     * tool's structured output, when present, is serialised into a single
+     * text block; otherwise each MCP content block is translated, with
+     * non-text blocks JSON-stringified so their data still reaches the model.
+     *
+     * @param array<string, mixed>|null $structured
+     * @param list<array<string, mixed>> $mcpContent
+     * @return list<array<string, mixed>>
+     */
+    private function toolResultContentToAnthropic(?array $structured, array $mcpContent): array
+    {
+        if ($structured !== null) {
+            $serialised = json_encode($structured);
+
+            return [['type' => 'text', 'text' => $serialised === false ? '' : $serialised]];
+        }
+
+        $blocks = [];
+        foreach ($mcpContent as $block) {
+            if (!is_array($block)) {
+                continue;
+            }
+            if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                $blocks[] = ['type' => 'text', 'text' => $block['text']];
+                continue;
+            }
+            $serialised = json_encode($block);
+            if ($serialised !== false) {
+                $blocks[] = ['type' => 'text', 'text' => $serialised];
+            }
+        }
+
+        if ($blocks === []) {
+            $blocks[] = ['type' => 'text', 'text' => ''];
+        }
+
+        return $blocks;
+    }
+
+    /**
+     * @param list<ToolCatalogEntryArray> $tools
+     * @return list<array{name: string, description: string, input_schema: array<string, mixed>}>|null
+     */
+    private function toolCatalogToAnthropic(array $tools): ?array
+    {
+        if ($tools === []) {
+            return null;
+        }
+
+        $anthropicTools = [];
+        foreach ($tools as $tool) {
+            $anthropicTools[] = [
+                'name' => $tool['name'],
+                'description' => $tool['description'],
+                'input_schema' => $tool['inputSchema'],
+            ];
+        }
+
+        return $anthropicTools;
+    }
+
+    /**
+     * @param list<mixed> $content Anthropic assistant content blocks
+     * @return list<CanonicalContentBlockArray> canonical assistant content blocks
+     */
+    private function anthropicContentToCanonical(array $content): array
+    {
+        $canonical = [];
+        foreach ($content as $block) {
+            if (!is_array($block)) {
+                continue;
+            }
+
+            if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                $canonical[] = ['type' => 'text', 'text' => $block['text']];
+                continue;
+            }
+
+            if (($block['type'] ?? null) === 'tool_use') {
+                $id = $block['id'] ?? null;
+                $name = $block['name'] ?? null;
+                $input = $block['input'] ?? [];
+                if (!is_string($id) || !is_string($name) || !is_array($input)) {
+                    continue;
+                }
+                $normalizedInput = [];
+                foreach ($input as $key => $value) {
+                    if (is_string($key)) {
+                        $normalizedInput[$key] = $value;
+                    }
+                }
+                $canonical[] = [
+                    'type' => 'tool_use',
+                    'id' => $id,
+                    'name' => $name,
+                    'input' => $normalizedInput,
+                ];
+                continue;
+            }
+
+            // Other block shapes (thinking, server tool results, …) are
+            // dropped until a canonical block type exists for them.
+        }
+
+        return $canonical;
+    }
+}
diff --git a/Provider/CustomProvider.php b/Provider/CustomProvider.php
new file mode 100644
index 0000000..bcb9a2c
--- /dev/null
+++ b/Provider/CustomProvider.php
@@ -0,0 +1,151 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Provider;
+
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\Exception\AIProviderClientException;
+
+class CustomProvider extends AIProvider
+{
+    public function __construct()
+    {
+        parent::__construct(
+            'custom-provider',
+            'Custom Provider',
+            'AIProviders_CustomProviderDescription',
+            true
+        );
+    }
+
+    /**
+     * Custom servers are expected to be OpenAI-compatible. The configured base
+     * URL must point at the API root (the part before `/chat/completions`),
+     * typically the `/v1` path. The API key is optional, because such servers
+     * commonly run without authentication. There is no built-in default model:
+     * the model comes from the request or the saved configuration (the admin
+     * picks one from the server's discovered models), so callers can target the
+     * exact alias a given server exposes.
+     *
+     * @param array<string, string> $configuration
+     */
+    public function complete(AIRequest $request, array $configuration): AIProviderResponse
+    {
+        return $this->completeChatCompletion(
+            $request->withModel($this->resolveConfiguredModel($request->getModel(), $configuration)),
+            $this->getChatCompletionsEndpoint($this->getEndpointUrl($configuration)),
+            $this->getBearerAuthorizationHeaders($configuration)
+        );
+    }
+
+    /**
+     * Validates the connection with the standard OpenAI-compatible
+     * `GET {base}/models` probe instead of spending generation tokens. The
+     * API key is optional; getBearerAuthorizationHeaders() omits the header
+     * when no key was provided.
+     *
+     * @param array<string, string> $configuration
+     */
+    public function verifyConnection(array $configuration): void
+    {
+        $this->listModels($configuration);
+    }
+
+    /**
+     * Discovers the models the configured server can serve via its standard
+     * OpenAI-compatible `GET {base}/models` listing. Doubles as the
+     * connection probe (it fails the same way an unreachable server would).
+     *
+     * @param array<string, string> $configuration
+     * @return list<string>
+     */
+    public function listModels(array $configuration): array
+    {
+        $response = $this->sendGetRequest(
+            $this->openAiCompatibleModelsEndpoint($this->getEndpointUrl($configuration)),
+            $this->getBearerAuthorizationHeaders($configuration)
+        );
+
+        $models = [];
+        foreach ($response['data'] ?? [] as $model) {
+            if (is_array($model) && isset($model['id']) && is_string($model['id']) && $model['id'] !== '') {
+                $models[] = $model['id'];
+            }
+        }
+
+        sort($models);
+
+        return $models;
+    }
+
+    public function supportsConversations(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Custom servers are expected to be OpenAI-compatible. The model comes from
+     * the request or the saved configuration (see {@link complete()}).
+     *
+     * @param array<string, string> $configuration
+     */
+    public function converse(AIConversationRequest $request, array $configuration): AIConversationResponse
+    {
+        return $this->converseChatCompletion(
+            $request->withModel($this->resolveConfiguredModel($request->getModel(), $configuration)),
+            $this->getChatCompletionsEndpoint($this->getEndpointUrl($configuration)),
+            $this->getBearerAuthorizationHeaders($configuration)
+        );
+    }
+
+    /**
+     * Resolves the model to send: the per-request model wins, otherwise the
+     * model saved in the provider configuration. There is no hardcoded fallback
+     * because model names are server-specific; a missing model is a clear
+     * configuration error rather than a silent wrong-model call.
+     *
+     * @param array<string, string> $configuration
+     */
+    private function resolveConfiguredModel(?string $requestModel, array $configuration): string
+    {
+        $model = $requestModel !== null && $requestModel !== ''
+            ? $requestModel
+            : trim($configuration['model'] ?? '');
+
+        if ($model === '') {
+            throw new AIProviderClientException(
+                'No model is configured for the custom provider. Select a model in the AI Providers settings.'
+            );
+        }
+
+        return $model;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function getExtraChatCompletionPayload(AIRequest $request): array
+    {
+        return ['think' => $this->wantsThinking($request)];
+    }
+
+    private function getChatCompletionsEndpoint(string $endpointUrl): string
+    {
+        if (preg_match('#/chat/completions/?$#', $endpointUrl)) {
+            return $endpointUrl;
+        }
+
+        return rtrim($endpointUrl, '/') . '/chat/completions';
+    }
+}
diff --git a/Provider/Gemini.php b/Provider/Gemini.php
new file mode 100644
index 0000000..caa1245
--- /dev/null
+++ b/Provider/Gemini.php
@@ -0,0 +1,520 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Provider;
+
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\CanonicalMessage;
+
+/**
+ * @phpstan-import-type CanonicalMessageArray from CanonicalMessage
+ * @phpstan-import-type CanonicalContentBlockArray from CanonicalMessage
+ * @phpstan-import-type ToolCatalogEntryArray from AIConversationRequest
+ */
+class Gemini extends AIProvider
+{
+    private const DEFAULT_MODEL = 'gemini-2.5-flash-lite';
+
+    public function __construct()
+    {
+        parent::__construct('gemini', 'Gemini', 'AIProviders_GeminiDescription');
+    }
+
+    public function getDefaultEndpointUrl(): string
+    {
+        return $this->getEndpointUrlForModel($this->getDefaultModel());
+    }
+
+    public function getDefaultModel(): string
+    {
+        return self::DEFAULT_MODEL;
+    }
+
+    /**
+     * Custom Gemini chat completion method.
+     * @see https://ai.google.dev/gemini-api/docs/text-generation
+     * @param array<string, string> $configuration
+     */
+    public function complete(AIRequest $request, array $configuration): AIProviderResponse
+    {
+        $model = $this->resolveModel($request);
+
+        $payload = [
+            'contents' => [
+                [
+                    'parts' => [
+                        [
+                            'text' => $request->getUserPrompt(),
+                        ],
+                    ],
+                ],
+            ],
+            'generationConfig' => [
+                'maxOutputTokens' => $request->getMaxTokens(),
+                'temperature' => $request->getTemperature(),
+                'thinkingConfig' => [
+                    'thinkingBudget' => $this->wantsThinking($request) ? $this->thinkingBudget($request) : 0,
+                ],
+            ],
+        ];
+
+        if ($request->isJsonResponse()) {
+            $payload['generationConfig']['responseMimeType'] = 'application/json';
+        }
+
+        $systemPrompt = $this->getSystemPrompt($request);
+        if ($systemPrompt !== null && $systemPrompt !== '') {
+            $payload['systemInstruction'] = [
+                'parts' => [
+                    [
+                        'text' => $systemPrompt,
+                    ],
+                ],
+            ];
+        }
+
+        $response = $this->sendJsonRequest(
+            $this->getEndpointUrlForModel($model),
+            [
+                'x-goog-api-key' => $this->getApiKey($configuration),
+            ],
+            $payload
+        );
+
+        $text = $response['candidates'][0]['content']['parts'][0]['text'] ?? '';
+
+        return $this->buildResponse(
+            $request,
+            $model,
+            is_string($text) ? $text : '',
+            isset($response['usageMetadata']['promptTokenCount']) ? (int) $response['usageMetadata']['promptTokenCount'] : null,
+            isset($response['usageMetadata']['candidatesTokenCount']) ? (int) $response['usageMetadata']['candidatesTokenCount'] : null
+        );
+    }
+
+    /**
+     * Validates credentials and reachability with a cheap models listing
+     * instead of spending generation tokens.
+     *
+     * @see https://ai.google.dev/api/models#method:-models.list
+     * @param array<string, string> $configuration
+     */
+    public function verifyConnection(array $configuration): void
+    {
+        $this->sendGetRequest(
+            'https://generativelanguage.googleapis.com/v1beta/models',
+            ['x-goog-api-key' => $this->getApiKey($configuration)]
+        );
+    }
+
+    public function supportsConversations(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Runs one conversational round-trip against the Gemini generateContent API.
+     *
+     * Gemini diverges from the canonical shape in two ways that this method
+     * reconciles. First, its roles are 'user' and 'model' (not 'assistant'),
+     * and canonical 'tool' result messages fold into 'user' messages carrying
+     * functionResponse parts. Second, and trickier, Gemini has no tool-call
+     * IDs: a functionResponse correlates with its functionCall purely by
+     * function NAME (and order). The canonical tool_result only carries the
+     * originating tool_use_id, so this method first walks the history building
+     * an id => name map from every assistant tool_use block, then resolves
+     * each tool_result's name from that map. On the way out, responses get a
+     * synthesized deterministic id per functionCall so the next turn's
+     * tool_result can be matched back through the same map.
+     *
+     * @see https://ai.google.dev/gemini-api/docs/function-calling
+     * @param array<string, string> $configuration
+     */
+    public function converse(AIConversationRequest $request, array $configuration): AIConversationResponse
+    {
+        $model = $this->resolveConversationModel($request);
+
+        $payload = [
+            'contents' => $this->canonicalMessagesToGemini($request->getMessages()),
+            'generationConfig' => [
+                'maxOutputTokens' => $request->getMaxTokens(),
+                'temperature' => $request->getTemperature(),
+            ],
+        ];
+
+        $systemPrompt = $request->getSystemPrompt();
+        if ($systemPrompt !== null && $systemPrompt !== '') {
+            $payload['systemInstruction'] = [
+                'parts' => [
+                    [
+                        'text' => $systemPrompt,
+                    ],
+                ],
+            ];
+        }
+
+        $tools = $this->toolCatalogToGemini($request->getTools());
+        if ($tools !== null) {
+            $payload['tools'] = $tools;
+        }
+
+        $response = $this->sendJsonRequest(
+            $this->getEndpointUrlForModel($model),
+            [
+                'x-goog-api-key' => $this->getApiKey($configuration),
+            ],
+            $payload,
+            $request->getTimeoutSeconds()
+        );
+
+        $parts = is_array($response['candidates'][0]['content']['parts'] ?? null)
+            ? $response['candidates'][0]['content']['parts']
+            : [];
+        $finishReason = is_string($response['candidates'][0]['finishReason'] ?? null)
+            ? $response['candidates'][0]['finishReason']
+            : '';
+
+        $content = $this->geminiPartsToCanonical($parts);
+        $stopReason = $this->resolveStopReason($content, $finishReason);
+
+        return $this->buildConversationResponse(
+            $model,
+            $content,
+            $stopReason,
+            isset($response['usageMetadata']['promptTokenCount']) ? (int) $response['usageMetadata']['promptTokenCount'] : null,
+            isset($response['usageMetadata']['candidatesTokenCount']) ? (int) $response['usageMetadata']['candidatesTokenCount'] : null
+        );
+    }
+
+    /**
+     * @param list<CanonicalMessageArray> $messages canonical messages
+     * @return list<array{role: string, parts: list<array<string, mixed>>}>
+     */
+    private function canonicalMessagesToGemini(array $messages): array
+    {
+        // Gemini correlates tool results to tool calls by function name, not
+        // id, so build an id => name map from all tool_use blocks first.
+        $toolUseNamesById = $this->buildToolUseNameLookup($messages);
+
+        $contents = [];
+        foreach ($messages as $message) {
+            $role = $message['role'];
+
+            if ($role === 'assistant') {
+                $parts = $this->assistantBlocksToGeminiParts($message['content']);
+                $contents[] = ['role' => 'model', 'parts' => $parts];
+                continue;
+            }
+
+            if ($role === 'tool') {
+                $parts = $this->toolResultBlocksToGeminiParts($message['content'], $toolUseNamesById);
+                $contents[] = ['role' => 'user', 'parts' => $parts];
+                continue;
+            }
+
+            // 'user' and any unknown role fold into a user message of text parts.
+            $parts = [];
+            foreach ($message['content'] as $block) {
+                if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                    $parts[] = ['text' => $block['text']];
+                }
+            }
+            $contents[] = ['role' => 'user', 'parts' => $parts];
+        }
+
+        return $contents;
+    }
+
+    /**
+     * Builds the tool_use id => name lookup used to resolve functionResponse
+     * names, since the canonical tool_result only carries the tool_use_id.
+     *
+     * @param list<CanonicalMessageArray> $messages
+     * @return array<string, string>
+     */
+    private function buildToolUseNameLookup(array $messages): array
+    {
+        $lookup = [];
+        foreach ($messages as $message) {
+            foreach (CanonicalMessage::toolUseBlocks($message['content']) as $block) {
+                $lookup[$block['id']] = $block['name'];
+            }
+        }
+
+        return $lookup;
+    }
+
+    /**
+     * @param list<CanonicalContentBlockArray> $blocks canonical assistant content blocks
+     * @return list<array<string, mixed>>
+     */
+    private function assistantBlocksToGeminiParts(array $blocks): array
+    {
+        $parts = [];
+        foreach ($blocks as $block) {
+            $type = $block['type'] ?? null;
+
+            if ($type === 'text' && is_string($block['text'] ?? null)) {
+                $parts[] = ['text' => $block['text']];
+                continue;
+            }
+
+            if ($type === 'tool_use') {
+                $name = $block['name'] ?? null;
+                $input = $block['input'] ?? [];
+                if (!is_string($name) || !is_array($input)) {
+                    continue;
+                }
+                // functionCall.args must be a JSON object even when empty;
+                // json_decode collapses `{}` to `[]`, so coerce empty inputs
+                // back to stdClass so json_encode produces `{}` again.
+                $parts[] = [
+                    'functionCall' => [
+                        'name' => $name,
+                        'args' => $input === [] ? new \stdClass() : $input,
+                    ],
+                ];
+            }
+        }
+
+        return $parts;
+    }
+
+    /**
+     * Translates canonical tool_result blocks into Gemini functionResponse
+     * parts, resolving each result's function name from the id => name lookup.
+     *
+     * @param list<CanonicalContentBlockArray> $blocks canonical tool_result blocks
+     * @param array<string, string> $toolUseNamesById
+     * @return list<array<string, mixed>>
+     */
+    private function toolResultBlocksToGeminiParts(array $blocks, array $toolUseNamesById): array
+    {
+        $parts = [];
+        foreach ($blocks as $block) {
+            if (($block['type'] ?? null) !== 'tool_result') {
+                continue;
+            }
+
+            $toolUseId = $block['tool_use_id'] ?? null;
+            // Gemini correlates by name; recover it from the prior tool_use
+            // block, falling back to a stable placeholder when unknown.
+            $name = is_string($toolUseId) && isset($toolUseNamesById[$toolUseId])
+                ? $toolUseNamesById[$toolUseId]
+                : 'unknown';
+
+            $structured = is_array($block['structuredContent'] ?? null) ? $block['structuredContent'] : null;
+            $mcpContent = is_array($block['content'] ?? null) ? $block['content'] : [];
+
+            $parts[] = [
+                'functionResponse' => [
+                    'name' => $name,
+                    'response' => $this->toolResultResponseObject($structured, $mcpContent, !empty($block['is_error'])),
+                ],
+            ];
+        }
+
+        return $parts;
+    }
+
+    /**
+     * Gemini expects functionResponse.response to be a JSON object. Structured
+     * output is used verbatim when present; otherwise the MCP content blocks
+     * are folded into a single {content: ...} object, with non-text blocks
+     * JSON-stringified so their data still reaches the model. An error flag is
+     * surfaced as {error: true}.
+     *
+     * @param array<string, mixed>|null $structured
+     * @param list<array<string, mixed>> $mcpContent
+     * @return array<string, mixed>
+     */
+    private function toolResultResponseObject(?array $structured, array $mcpContent, bool $isError): array
+    {
+        if ($structured !== null) {
+            $response = $structured;
+        } else {
+            $texts = [];
+            foreach ($mcpContent as $block) {
+                if (!is_array($block)) {
+                    continue;
+                }
+                if (($block['type'] ?? null) === 'text' && is_string($block['text'] ?? null)) {
+                    $texts[] = $block['text'];
+                    continue;
+                }
+                $serialised = json_encode($block);
+                if ($serialised !== false) {
+                    $texts[] = $serialised;
+                }
+            }
+            $response = ['content' => implode("\n", $texts)];
+        }
+
+        if ($isError) {
+            $response['error'] = true;
+        }
+
+        return $response;
+    }
+
+    /**
+     * @param list<ToolCatalogEntryArray> $tools
+     * @return list<array{functionDeclarations: list<array{name: string, description: string, parameters: array<string, mixed>}>}>|null
+     */
+    private function toolCatalogToGemini(array $tools): ?array
+    {
+        if ($tools === []) {
+            return null;
+        }
+
+        $declarations = [];
+        foreach ($tools as $tool) {
+            $declarations[] = [
+                'name' => $tool['name'],
+                'description' => $tool['description'],
+                'parameters' => $this->geminiParameterSchema($tool['inputSchema']),
+            ];
+        }
+
+        return [['functionDeclarations' => $declarations]];
+    }
+
+    /**
+     * Gemini's function-declaration parameters accept only a restricted subset
+     * of the OpenAPI 3.0 schema and reject standard JSON Schema keywords such as
+     * `additionalProperties` or `$schema` — and not just at the top level: it
+     * rejects them at every nesting depth (e.g. inside `properties[...]`). The
+     * shared {@see toToolParametersObjectSchema} only normalises the top level,
+     * which is all OpenAI needs, so Gemini layers a recursive strip on top.
+     *
+     * The removed keywords are validation hints only; the tool server
+     * re-validates arguments when the tool actually runs, so dropping them keeps
+     * the tool callable without loosening real enforcement.
+     *
+     * @param array<string, mixed> $schema
+     * @return array<string, mixed>
+     */
+    private function geminiParameterSchema(array $schema): array
+    {
+        return $this->stripGeminiUnsupportedKeywords(
+            $this->toToolParametersObjectSchema($schema)
+        );
+    }
+
+    /**
+     * Recursively removes JSON Schema keywords Gemini rejects anywhere in the
+     * tree, walking into `properties`, `items`, and `anyOf`/`oneOf`/`allOf`
+     * branches so nested object/array schemas are cleaned too.
+     *
+     * @param array<string, mixed> $schema
+     * @return array<string, mixed>
+     */
+    private function stripGeminiUnsupportedKeywords(array $schema): array
+    {
+        unset(
+            $schema['additionalProperties'],
+            $schema['$schema'],
+            $schema['$id'],
+            $schema['$ref'],
+            $schema['$defs'],
+            $schema['definitions'],
+            $schema['const'],
+            $schema['patternProperties'],
+            $schema['unevaluatedProperties']
+        );
+
+        foreach ($schema as $key => $value) {
+            if (is_array($value)) {
+                $schema[$key] = $this->stripGeminiUnsupportedKeywords($value);
+            }
+        }
+
+        return $schema;
+    }
+
+    /**
+     * @param list<mixed> $parts Gemini candidate content parts
+     * @return list<CanonicalContentBlockArray> canonical assistant content blocks
+     */
+    private function geminiPartsToCanonical(array $parts): array
+    {
+        $canonical = [];
+        foreach ($parts as $index => $part) {
+            if (!is_array($part)) {
+                continue;
+            }
+
+            if (is_string($part['text'] ?? null) && $part['text'] !== '') {
+                $canonical[] = ['type' => 'text', 'text' => $part['text']];
+                continue;
+            }
+
+            if (is_array($part['functionCall'] ?? null)) {
+                $call = $part['functionCall'];
+                $name = is_string($call['name'] ?? null) ? $call['name'] : '';
+                $args = is_array($call['args'] ?? null) ? $call['args'] : [];
+                $normalizedInput = array_filter($args, function ($key) {
+                    return is_string($key);
+                }, ARRAY_FILTER_USE_KEY);
+                // Gemini supplies no id; synthesize a deterministic one so the
+                // caller can echo it back and the id => name resolver can
+                // recover the function name on the next turn.
+                $canonical[] = [
+                    'type' => 'tool_use',
+                    'id' => sprintf('gemini-%d-%s', $index, $name),
+                    'name' => $name,
+                    'input' => $normalizedInput,
+                ];
+            }
+        }
+
+        return $canonical;
+    }
+
+    /**
+     * Any functionCall in the turn means the model wants a tool run; otherwise
+     * the Gemini finishReason maps onto the canonical stop reasons, passing
+     * unrecognised values through.
+     *
+     * @param list<CanonicalContentBlockArray> $content canonical assistant content blocks
+     */
+    private function resolveStopReason(array $content, string $finishReason): string
+    {
+        foreach ($content as $block) {
+            if (($block['type'] ?? null) === 'tool_use') {
+                return AIConversationResponse::STOP_TOOL_USE;
+            }
+        }
+
+        switch ($finishReason) {
+            case 'STOP':
+                return AIConversationResponse::STOP_END_TURN;
+            case 'MAX_TOKENS':
+                return AIConversationResponse::STOP_MAX_TOKENS;
+            case 'SAFETY':
+            case 'RECITATION':
+                return AIConversationResponse::STOP_GUARDRAIL_INTERVENED;
+            default:
+                return $finishReason;
+        }
+    }
+
+    private function getEndpointUrlForModel(string $model): string
+    {
+        return sprintf(
+            'https://generativelanguage.googleapis.com/v1beta/models/%s:generateContent',
+            $model
+        );
+    }
+}
diff --git a/Provider/OpenAI.php b/Provider/OpenAI.php
new file mode 100644
index 0000000..062409a
--- /dev/null
+++ b/Provider/OpenAI.php
@@ -0,0 +1,108 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\Provider;
+
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIRequest;
+
+class OpenAI extends AIProvider
+{
+    private const DEFAULT_MODEL = 'gpt-5.4-mini';
+
+    public function __construct()
+    {
+        parent::__construct('openai', 'OpenAI', 'AIProviders_OpenAIDescription');
+    }
+
+    public function getDefaultEndpointUrl(): string
+    {
+        return 'https://api.openai.com/v1/chat/completions';
+    }
+
+    public function getDefaultModel(): string
+    {
+        return self::DEFAULT_MODEL;
+    }
+
+    /**
+     * @param array<string, string> $configuration
+     */
+    public function complete(AIRequest $request, array $configuration): AIProviderResponse
+    {
+        return $this->completeChatCompletion(
+            $request,
+            $this->getEndpointUrl($configuration),
+            ['Authorization' => 'Bearer ' . $this->getApiKey($configuration)]
+        );
+    }
+
+    /**
+     * Validates credentials and reachability with a cheap models listing
+     * (`GET /v1/models`) instead of spending generation tokens.
+     *
+     * @param array<string, string> $configuration
+     */
+    public function verifyConnection(array $configuration): void
+    {
+        $this->sendGetRequest(
+            $this->openAiCompatibleModelsEndpoint($this->getEndpointUrl($configuration)),
+            ['Authorization' => 'Bearer ' . $this->getApiKey($configuration)]
+        );
+    }
+
+    public function supportsConversations(): bool
+    {
+        return true;
+    }
+
+    /**
+     * gpt-5 reasoning models expose thinking through `reasoning_effort` rather
+     * than a thinking budget: "none" disables reasoning for fast, cheap instant
+     * answers; "medium" turns it on for better reasoning. (Supported because
+     * gpt-5.4-mini is post-gpt-5.1, where "none" became valid.)
+     */
+    protected function getExtraChatCompletionPayload(AIRequest $request): array
+    {
+        return ['reasoning_effort' => $this->wantsThinking($request) ? 'medium' : 'none'];
+    }
+
+    /**
+     * gpt-5 reasoning models require `max_completion_tokens` and reject a custom
+     * `temperature` (only the default is allowed), so omit it.
+     */
+    protected function chatCompletionTokenLimitField(): string
+    {
+        return 'max_completion_tokens';
+    }
+
+    protected function chatCompletionSupportsTemperature(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Runs one conversational round-trip against the OpenAI Chat Completions API.
+     *
+     * @see https://platform.openai.com/docs/api-reference/chat/create
+     * @param array<string, string> $configuration
+     */
+    public function converse(AIConversationRequest $request, array $configuration): AIConversationResponse
+    {
+        return $this->converseChatCompletion(
+            $request,
+            $this->getEndpointUrl($configuration),
+            ['Authorization' => 'Bearer ' . $this->getApiKey($configuration)]
+        );
+    }
+}
diff --git a/README.md b/README.md
index ff36fa0..c45fef5 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,143 @@
-# plugin-AIProviders
-Configure AI providers and model defaults for Matomo AI features
+# AIProviders
+
+[![Tests](https://github.com/matomo-org/plugin-AIProviders/actions/workflows/matomo-tests.yml/badge.svg)](https://github.com/matomo-org/plugin-AIProviders/actions/workflows/matomo-tests.yml)
+[![Vue build check](https://github.com/matomo-org/plugin-AIProviders/actions/workflows/buildvue.yml/badge.svg)](https://github.com/matomo-org/plugin-AIProviders/actions/workflows/buildvue.yml)
+
+Configure AI provider connections and default model settings used by Matomo AI features.
+
+Built-in providers: Claude, OpenAI, Gemini, and a generic custom provider for OpenAI-compatible endpoints.
+
+## Configuration
+
+Settings are managed from **Administration > System > AI Providers**.
+
+The plugin stores the default provider, default capability level, and provider connection settings as Matomo system settings (not shown on the generic plugin settings page). API keys are only returned to the administration UI as masked state, not as secret values.
+
+On a managed environment, the default provider is forced and locked via the `[AIProviders] defaultProvider` config setting. There is nothing left to configure, so the AI Providers settings page and its admin menu entry are hidden entirely.
+
+### Custom provider and local LLM servers
+
+The generic custom provider talks to any **OpenAI-compatible** Chat Completions API. This includes hosted OpenAI-compatible services as well as local LLM servers such as Ollama, LM Studio, llama.cpp (`llama-server`), vLLM and LocalAI, which all expose the same `/v1/chat/completions` wire format.
+
+Two things matter when configuring it:
+
+- **API base URL.** Enter the URL up to and including the OpenAI-compatible API root — for most servers that is the `/v1` path. Matomo appends `/chat/completions` itself, so do not include it. Examples:
+  - Ollama: `http://localhost:11434/v1`
+  - LM Studio: `http://localhost:1234/v1`
+  - vLLM / llama.cpp: `http://localhost:8000/v1`
+
+  Note that the request leaves the Matomo server, not the browser. If Matomo runs in a container (e.g. Docker/ddev), `localhost` refers to the container — use the host gateway such as `host.docker.internal` instead.
+
+- **API key.** Optional for the custom provider. Many local servers run without authentication, so the key may be left blank; it is only sent (as `Authorization: Bearer …`) when provided.
+
+- **Model.** The "test connection" action probes `GET {base}/models` (rather than spending generation tokens) and populates the model picker from the result; the refresh button re-runs it. Pick the model to use, or type a name when the server does not expose a listing. The custom provider has **no built-in default model** — the model sent to the server is the per-request model (`AIRequest::withModel()`) if set, otherwise the saved configuration model. If neither is set, completions fail with a clear "no model configured" error rather than silently calling a wrong model.
+
+### Config-file credentials
+
+Provider connection settings can also be supplied from the `[AIProviders]` config section or environment variables instead of the administration UI. Per field, a config-file/environment value wins over the database value:
+
+```ini
+[AIProviders]
+openaiApiKey = "..."       ; or env MATOMO_AIPROVIDERS_OPENAI_API_KEY
+openaiEndpointUrl = "..."  ; or env MATOMO_AIPROVIDERS_OPENAI_ENDPOINT_URL
+```
+
+The config key is the provider ID verbatim plus the field suffix; the environment variable upper-cases the ID and replaces `-` with `_`. Credentials supplied this way never appear in the UI as secret values and cannot be edited or removed there.
+
+In a multi-tenant setup the `config.ini.php` is per tenant, so the `[AIProviders]` section is the natural place to give each tenant its own provider credentials and forced default. Environment variables are process-wide and shared across tenants, so prefer the config file when the value must differ per tenant.
+
+### Restricted providers and the provider selection allowlist
+
+A managed environment can demote providers to *restricted* (non-selectable) in the `AIProviders.filterAIProviders` event via `AIProvidersList::setSelectable()`. Restricted providers are hidden from every admin surface and can never become the default, but stay registered for completions.
+
+Plugins listed on the centrally managed allowlist may target a specific provider and model per request even though the default provider is forced — needed by features whose purpose is to query specific AI engines:
+
+```ini
+[AIProviders]
+defaultProvider = "openai"
+providerSelectionAllowlist[] = "ExamplePlugin"
+```
+
+In a managed environment this config is locked and centrally managed, so neither the allowlist nor the providers it unlocks can be influenced by users. Allowlisted callers get no silent fallback: requesting an unknown or unconfigured provider fails with a clear error rather than answering from the wrong engine.
+
+## Usage from other plugins
+
+Do not call this plugin's `API.php` from other plugins. Its public API methods exist only for the administration UI and only expose masked configuration values — adding prompt/completion methods there would expose them over Matomo's HTTP API to anyone with a valid token.
+
+Use the PHP service instead:
+
+```php
+use Piwik\Container\StaticContainer;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\AIProviderService;
+
+$service = StaticContainer::get(AIProviderService::class);
+$response = $service->complete(new AIRequest('why is the sky blue, answer in 7 words', 'YourPlugin'));
+$text = $response->getText();
+```
+
+Build the request with `AIRequest`: the first argument is the user prompt, the second is your plugin name (used for accountability). Optional settings such as a system prompt, model, max tokens, or temperature are set with the immutable `with*()` methods. The service resolves the provider (honouring a provider forced by a managed environment), calls it, and returns an `AIProviderResponse` with the completion text and, when the provider reports it, token usage.
+
+Credentials are resolved and used server-side by the service and are never returned to callers. Built-in providers default to low-latency models, which can be overridden per request with `AIRequest::withModel()` on self-managed instances. When a managed environment forces a provider from configuration, the service also ignores caller-provided provider and model overrides — unless the calling plugin is on the `providerSelectionAllowlist` (see above), in which case its requested provider and model are honoured.
+
+**Hard rule:** the values passed to `withProviderId()` and `withModel()` must come from plugin code constants or server-side configuration, never from request input. Forwarding request parameters would let any HTTP client pick the provider and model the server calls — on managed hosting that circumvents the centrally managed provider and its cost controls. If users may choose between engines in a UI, the request parameter must be a key into a server-side map defined by your plugin, never the provider/model string itself.
+
+`AIProviderResponse` exposes the provider, model, completion text, token usage, raw decoded provider response, reasoning level used, web-search usage, and execution time. Reasoning controls, web search, and thinking budgets are currently contract stubs only: callers may set them on `AIRequest`, but the built-in providers do not send provider-specific reasoning or web-search options yet and report `none` / `false` in the response.
+
+### JSON mode
+
+For structured output, call `withJsonResponse()` and read the decoded object with `getJsonData()`:
+
+```php
+$response = $service->complete(
+    (new AIRequest($prompt, 'Goals'))->withJsonResponse()
+);
+$data = $response->getJsonData(); // array, or null if the model did not return valid JSON
+```
+
+Each provider asks for JSON the best way it can — `response_format` (OpenAI-compatible), `responseMimeType` (Gemini) — and AIProviders always adds a system instruction to return a single JSON object, so it works for providers without a native option (for example Claude) too. The model can still occasionally return invalid JSON, so always handle a `null` from `getJsonData()`.
+
+## Conversations (multi-turn, tool calling)
+
+`complete()` is prompt-in/text-out. When your plugin maintains a back-and-forth conversation and dispatches tool calls itself (as AskMatomo does), use `AIConversationRequest` with `AIProviderService::converse()` instead. The service resolves the provider exactly like `complete()` (forced provider, allowlisted caller selection, then the configured default) and returns one assistant turn per call.
+
+```php
+use Piwik\Container\StaticContainer;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderService;
+
+$service = StaticContainer::get(AIProviderService::class);
+
+$messages = [
+    ['role' => 'user', 'content' => [['type' => 'text', 'text' => 'How many visits yesterday?']]],
+];
+
+$response = $service->converse(
+    (new AIConversationRequest($messages, 'YourPlugin'))
+        ->withSystemPrompt($systemPrompt)
+        ->withTools($toolCatalog) // optional; MCP-aligned shape, see below
+        ->withMaxTokens(2048)
+);
+
+if ($response->getStopReason() === AIConversationResponse::STOP_TOOL_USE) {
+    // Run the requested tool_use blocks, append this turn and the tool
+    // results to $messages, and call converse() again.
+}
+```
+
+Messages, tools, and the assistant's content all use one **provider-agnostic canonical shape** documented in [`CanonicalMessage`](CanonicalMessage.php). Each provider translates that shape to and from its own wire format inside `converse()`, so swapping the configured provider never changes how your plugin builds or stores a conversation. Running tools and appending their results to the history for the next call is the caller's responsibility — the service performs a single round-trip per call.
+
+`AIConversationResponse` exposes the assistant content blocks (`getContent()`), the stop reason mapped onto the `STOP_*` constants (`getStopReason()`), a text convenience (`getText()`), token usage, and the raw decoded provider response. Treat an unknown stop reason like `STOP_END_TURN`. Unlike `complete()`, an empty text turn is valid here: a turn may consist solely of `tool_use` blocks.
+
+Not every provider supports conversations. Gate conversational features on availability rather than calling `converse()` blindly:
+
+```php
+if (!$service->canConverse()) {
+    // Hide or disable the feature.
+}
+// When the reason matters for the UI:
+$availability = $service->getConversationAvailability(); // status + resolved provider
+```
+
+The same **hard rule** as for `AIRequest` applies: the values passed to `withProviderId()` and `withModel()` must come from plugin code constants or server-side configuration, never from request input.
diff --git a/lang/en.json b/lang/en.json
new file mode 100644
index 0000000..3d43a83
--- /dev/null
+++ b/lang/en.json
@@ -0,0 +1,43 @@
+{
+    "AIProviders": {
+        "ApiKey": "API key",
+        "ApiKeyAlreadyConfiguredPlaceholder": "Enter a new key to replace the key.",
+        "ApiKeyPlaceholder": "Enter your API key",
+        "BedrockDescription": "Managed AWS Bedrock access provided by Matomo Cloud.",
+        "ClaudeDescription": "Anthropic Claude models.",
+        "ClickTestConnectionToShowAvailableModels": "Click test connection to show available models.",
+        "ConfigurationIntro": "Configure AI providers and default AI behavior in Matomo.",
+        "CustomProviderDescription": "Use your own OpenAI compatible endpoint.",
+        "DefaultBadge": "Default",
+        "DefaultCapabilityLevel": "Default capability level",
+        "DefaultCapabilityLevelHelp": "Choose the default capability Matomo may use. Individual features can override this.",
+        "DefaultProvider": "Default provider",
+        "DefaultProviderHelp": "Connect providers and pick a default for Matomo to use. Individual features may override this and choose their preferred connected provider.",
+        "DefaultsTitle": "Change provider settings and default values",
+        "Disconnect": "Disconnect",
+        "DisconnectSuccess": "AI provider disconnected.",
+        "Disconnecting": "Disconnecting…",
+        "EndpointUrl": "API base URL",
+        "EndpointUrlPlaceholder": "Enter your base URL",
+        "GeminiDescription": "Google Gemini models.",
+        "InstantCapability": "Instant",
+        "InstantCapabilityDescription": "Fast and cost-effective for simple tasks.",
+        "ManagedConfigurationHelp": "AI provider settings are managed by Matomo Cloud and cannot be changed on this instance.",
+        "MenuTitle": "AI Providers",
+        "Model": "Model",
+        "NoDefaultProviderWarning": "No AI provider can be set as the default yet. Connect a provider first.",
+        "OpenAIDescription": "OpenAI models like GPT-5.5",
+        "RefreshModels": "Refresh models",
+        "RequestFailed": "AI provider request failed: %s",
+        "SettingsSaveSuccess": "AI provider settings saved.",
+        "StatusConnected": "Connected",
+        "StatusNotConnected": "Not connected",
+        "TestConnection": "Test connection",
+        "TestConnectionSuccess": "%1$s connection works.",
+        "TestingConnection": "Testing…",
+        "ThinkingCapability": "Thinking",
+        "ThinkingCapabilityDescription": "Better reasoning for complex tasks.",
+        "UnexpectedError": "Unexpected error. Please check the Matomo server logs.",
+        "UnsavedChanges": "You have unsaved changes."
+    }
+}
diff --git a/plugin.json b/plugin.json
new file mode 100644
index 0000000..2a12eb6
--- /dev/null
+++ b/plugin.json
@@ -0,0 +1,17 @@
+{
+  "name": "AIProviders",
+  "description": "Configure AI provider connections and default model settings used by Matomo AI features.",
+  "version": "5.0.0",
+  "theme": false,
+  "require": {
+    "matomo": ">=5.0.0-rc1,<6.0.0-b1"
+  },
+  "authors": [
+    {
+      "name": "InnoCraft",
+      "email": "contact@innocraft.com",
+      "homepage": "https://www.innocraft.com"
+    }
+  ],
+  "license": "GPL-3.0-or-later"
+}
diff --git a/templates/index.twig b/templates/index.twig
new file mode 100644
index 0000000..535ef3c
--- /dev/null
+++ b/templates/index.twig
@@ -0,0 +1,7 @@
+{% extends 'admin.twig' %}
+
+{% set title %}{{ 'AIProviders_MenuTitle'|translate }}{% endset %}
+
+{% block content %}
+    <div vue-entry="AIProviders.ManageAIProviders"></div>
+{% endblock %}
diff --git a/tests/Integration/ConfigurationTest.php b/tests/Integration/ConfigurationTest.php
new file mode 100644
index 0000000..6340f97
--- /dev/null
+++ b/tests/Integration/ConfigurationTest.php
@@ -0,0 +1,934 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Integration;
+
+use Piwik\Config;
+use Piwik\Container\StaticContainer;
+use Piwik\Piwik;
+use Piwik\Plugins\AIProviders\AIProvidersList;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\API;
+use Piwik\Plugins\AIProviders\AIProviderService;
+use Piwik\Plugins\AIProviders\Controller;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+use Piwik\Plugins\AIProviders\Provider\OpenAI;
+use Piwik\Tests\Framework\Fixture;
+use Piwik\Tests\Framework\Mock\FakeAccess;
+use Piwik\Tests\Framework\TestCase\IntegrationTestCase;
+
+/**
+ * @group AIProviders
+ * @group AIProvidersConfiguration
+ * @group Plugins
+ */
+class ConfigurationTest extends IntegrationTestCase
+{
+    /**
+     * @var API
+     */
+    private $api;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        // Ensure no forced configuration leaks between tests.
+        Config::getInstance()->AIProviders = [];
+
+        Fixture::createSuperUser();
+        $this->setSuperUser();
+
+        $this->api = API::getInstance();
+
+        // Reset stored settings to their defaults between tests.
+        $this->api->saveSettings('', Configuration::CAPABILITY_INSTANT, '{}');
+    }
+
+    public function tearDown(): void
+    {
+        Config::getInstance()->AIProviders = [];
+        putenv('MATOMO_AIPROVIDERS_OPENAI_API_KEY');
+
+        parent::tearDown();
+    }
+
+    public function testGetSettingsReturnsDefaultProviderConfiguration(): void
+    {
+        $settings = $this->api->getSettings();
+
+        $this->assertSame('', $settings['defaultProviderId']);
+        $this->assertSame(Configuration::CAPABILITY_INSTANT, $settings['defaultCapabilityLevel']);
+        $this->assertTrue($settings['canEditProviderConfiguration']);
+        $this->assertTrue($settings['canEditCapabilityLevel']);
+        $this->assertCount(4, $settings['providers']);
+
+        $customProvider = $this->getProvider($settings, 'custom-provider');
+        $this->assertSame('Custom Provider', $customProvider['name']);
+        $this->assertTrue($customProvider['supportsCustomEndpoint']);
+    }
+
+    public function testSaveSettingsCanBeCalledWithDefaultsBeforeAnyProviderIsConnected(): void
+    {
+        // Saving the form with nothing configured must not throw: an empty
+        // default provider and capability level are valid (see saveSettings()).
+        $settings = $this->api->saveSettings();
+
+        $this->assertSame('', $settings['defaultProviderId']);
+        $this->assertSame(Configuration::CAPABILITY_INSTANT, $settings['defaultCapabilityLevel']);
+    }
+
+    public function testSaveSettingsWithEmptyCapabilityLevelKeepsStoredValue(): void
+    {
+        $this->api->saveSettings('', Configuration::CAPABILITY_THINKING, '{}');
+
+        // An empty capability level leaves the stored value untouched rather
+        // than resetting it, so the capability can be saved independently.
+        $settings = $this->api->saveSettings('', '', '{}');
+
+        $this->assertSame(Configuration::CAPABILITY_THINKING, $settings['defaultCapabilityLevel']);
+    }
+
+    public function testSaveSettingsStoresApiKeyWithoutReturningIt(): void
+    {
+        $settings = $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_THINKING,
+            (string) json_encode([
+                'claude' => [
+                    'apiKey' => 'secret-claude-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $this->assertSame('claude', $settings['defaultProviderId']);
+        $this->assertSame(Configuration::CAPABILITY_THINKING, $settings['defaultCapabilityLevel']);
+
+        $claude = $this->getProvider($settings, 'claude');
+        $this->assertTrue($claude['configuration']['hasApiKey']);
+        $this->assertTrue($claude['configuration']['isUsable']);
+        $this->assertArrayNotHasKey('apiKey', $claude['configuration']);
+        $this->assertStringNotContainsString('secret-claude-key', (string) json_encode($settings));
+    }
+
+    public function testSaveSettingsKeepsApiKeyVerbatimWithoutSanitizing(): void
+    {
+        // The API disables automatic input sanitization ($autoSanitizeInputParams
+        // = false), so a key containing characters that sanitization would
+        // HTML-encode must be stored byte-for-byte intact.
+        $apiKey = 'secret&claude<key>"123"';
+
+        $settings = $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_THINKING,
+            (string) json_encode([
+                'claude' => [
+                    'apiKey' => $apiKey,
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $claude = $this->getProvider($settings, 'claude');
+        $this->assertTrue($claude['configuration']['hasApiKey']);
+
+        $stored = StaticContainer::get(Configuration::class)->getProviderConfiguration('claude');
+        $this->assertSame($apiKey, $stored['apiKey']);
+    }
+
+    public function testSaveSettingsPreservesExistingApiKeyWhenInputIsEmpty(): void
+    {
+        $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_THINKING,
+            (string) json_encode([
+                'claude' => [
+                    'apiKey' => 'secret-claude-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $settings = $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'claude' => [
+                    'apiKey' => '',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $claude = $this->getProvider($settings, 'claude');
+        $this->assertTrue($claude['configuration']['hasApiKey']);
+    }
+
+    public function testServiceReturnsServerSideDefaultProviderConfiguration(): void
+    {
+        $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_THINKING,
+            (string) json_encode([
+                'claude' => [
+                    'apiKey' => 'secret-claude-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $service = StaticContainer::get(AIProviderService::class);
+
+        $this->assertSame('claude', $service->getDefaultProvider()->getId());
+        $this->assertSame(Configuration::CAPABILITY_THINKING, $service->getDefaultCapabilityLevel());
+        // The stored credentials stay internal to the plugin; the service does
+        // not expose them. They are only resolvable through the Configuration.
+        $configuration = StaticContainer::get(Configuration::class);
+        $this->assertSame('secret-claude-key', $configuration->getProviderConfiguration('claude')['apiKey']);
+        $this->assertFalse(method_exists($service, 'getDefaultProviderConfiguration'));
+    }
+
+    public function testServiceCompletesRequestUsingConfiguredDefaultProvider(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => [
+                    'apiKey' => 'secret-openai-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+        $this->mockAIProviderResponse('Because molecules scatter blue light more strongly.');
+
+        $response = StaticContainer::get(AIProviderService::class)
+            ->complete(new AIRequest('why is the sky blue, answer in 7 words', 'Test'));
+
+        $this->assertSame('openai', $response->toArray()['providerId']);
+        $this->assertSame('Because molecules scatter blue light more strongly.', $response->getText());
+        $this->assertSame(12, $response->getInputTokens());
+        $this->assertSame(7, $response->getOutputTokens());
+        $this->assertSame(AIRequest::REASONING_NONE, $response->getReasoningLevel());
+        $this->assertFalse($response->isWebSearchEnabled());
+        $this->assertIsInt($response->getExecutionTimeMs());
+    }
+
+    public function testRequestForwardsSystemPromptModelAndOptionsToProvider(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => [
+                    'apiKey' => 'secret-openai-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $capturedBody = null;
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use (&$capturedBody): void {
+            $capturedBody = json_decode((string) $httpEventParams['body'], true);
+            $response = (string) json_encode([
+                'choices' => [['message' => ['content' => 'Blue light scatters most.']]],
+            ]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+
+        $request = (new AIRequest('why is the sky blue', 'Test'))
+            ->withSystemPrompt('You are concise.')
+            ->withModel('gpt-4o-mini')
+            ->withMaxTokens(64)
+            ->withTemperature(0.5)
+            ->withReasoningLevel('low')
+            ->withWebSearchEnabled(true);
+
+        $response = StaticContainer::get(AIProviderService::class)->complete($request);
+
+        $this->assertSame('Blue light scatters most.', $response->getText());
+        $this->assertSame(AIRequest::REASONING_NONE, $response->getReasoningLevel());
+        $this->assertFalse($response->isWebSearchEnabled());
+        $this->assertIsArray($capturedBody);
+        $this->assertSame('gpt-4o-mini', $capturedBody['model']);
+        $this->assertSame(64, $capturedBody['max_completion_tokens']);
+        $this->assertArrayNotHasKey('max_tokens', $capturedBody);
+        $this->assertArrayNotHasKey('temperature', $capturedBody);
+        $this->assertSame('none', $capturedBody['reasoning_effort']);
+        $this->assertSame(
+            [
+                ['role' => 'system', 'content' => 'You are concise.'],
+                ['role' => 'user', 'content' => 'why is the sky blue'],
+            ],
+            $capturedBody['messages']
+        );
+    }
+
+    public function testJsonResponseModeAsksProviderForJsonAndDecodesIt(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => [
+                    'apiKey' => 'secret-openai-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $capturedBody = null;
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use (&$capturedBody): void {
+            $capturedBody = json_decode((string) $httpEventParams['body'], true);
+            $response = (string) json_encode([
+                'choices' => [['message' => ['content' => '{"goals":[]}']]],
+            ]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+
+        $response = StaticContainer::get(AIProviderService::class)
+            ->complete((new AIRequest('Recommend goals for this site', 'Goals'))->withJsonResponse());
+
+        // The provider is asked for JSON natively …
+        $this->assertSame(['type' => 'json_object'], $capturedBody['response_format']);
+        // … and via a system instruction that mentions JSON (required by some providers).
+        $this->assertSame('system', $capturedBody['messages'][0]['role']);
+        $this->assertStringContainsString('JSON', $capturedBody['messages'][0]['content']);
+        // The response exposes the decoded object.
+        $this->assertSame(['goals' => []], $response->getJsonData());
+    }
+
+    public function testServiceUsesForcedProviderAndIgnoresRequestedProvider(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => [
+                    'apiKey' => 'secret-openai-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        // Simulate a managed environment forcing the provider from config.ini.php.
+        Config::getInstance()->AIProviders = ['defaultProvider' => 'openai'];
+        $this->mockAIProviderResponse('Because molecules scatter blue light more strongly.');
+
+        $response = StaticContainer::get(AIProviderService::class)
+            ->complete((new AIRequest('why is the sky blue', 'Test'))->withProviderId('claude'));
+
+        $this->assertSame('openai', $response->toArray()['providerId']);
+    }
+
+    public function testServiceIgnoresRequestedModelWhenProviderIsForced(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => [
+                    'apiKey' => 'secret-openai-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        Config::getInstance()->AIProviders = ['defaultProvider' => 'openai'];
+
+        $capturedBody = null;
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use (&$capturedBody): void {
+            $capturedBody = json_decode((string) $httpEventParams['body'], true);
+            $response = (string) json_encode([
+                'choices' => [['message' => ['content' => 'Forced provider default model used.']]],
+            ]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+
+        StaticContainer::get(AIProviderService::class)
+            ->complete((new AIRequest('why is the sky blue', 'Test'))->withModel('claude-haiku-4-5'));
+
+        $this->assertIsArray($capturedBody);
+        $this->assertSame('gpt-5.4-mini', $capturedBody['model']);
+    }
+
+    public function testAllowlistedCallerMaySelectProviderAndModelWhenProviderIsForced(): void
+    {
+        $this->saveOpenAiAndClaudeKeys();
+
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'openai',
+            'providerSelectionAllowlist' => ['ExamplePlugin'],
+        ];
+
+        $capturedUrl = null;
+        $capturedBody = null;
+        $this->mockClaudeResponse('Brand X is a well-known brand.', $capturedUrl, $capturedBody);
+
+        $response = StaticContainer::get(AIProviderService::class)->complete(
+            (new AIRequest('What do you know about brand X?', 'ExamplePlugin'))
+                ->withProviderId('claude')
+                ->withModel('claude-sonnet-4-5')
+        );
+
+        $this->assertSame('claude', $response->toArray()['providerId']);
+        $this->assertSame('https://api.anthropic.com/v1/messages', $capturedUrl);
+        $this->assertIsArray($capturedBody);
+        $this->assertSame('claude-sonnet-4-5', $capturedBody['model']);
+    }
+
+    public function testAllowlistOnlyAppliesToTheNamedCallerPlugin(): void
+    {
+        $this->saveOpenAiAndClaudeKeys();
+
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'openai',
+            'providerSelectionAllowlist' => ['ExamplePlugin'],
+        ];
+
+        // mockAIProviderResponse() asserts the OpenAI endpoint is called, so a
+        // request to Claude would fail this test.
+        $this->mockAIProviderResponse('Because molecules scatter blue light more strongly.');
+
+        $response = StaticContainer::get(AIProviderService::class)->complete(
+            (new AIRequest('why is the sky blue', 'Goals'))
+                ->withProviderId('claude')
+                ->withModel('claude-sonnet-4-5')
+        );
+
+        $this->assertSame('openai', $response->toArray()['providerId']);
+    }
+
+    public function testAllowlistedCallerRequestingUnknownProviderGetsClearError(): void
+    {
+        $this->saveOpenAiAndClaudeKeys();
+
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'openai',
+            'providerSelectionAllowlist' => ['ExamplePlugin'],
+        ];
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown AI provider "no-such-provider".');
+
+        StaticContainer::get(AIProviderService::class)->complete(
+            (new AIRequest('What do you know about brand X?', 'ExamplePlugin'))
+                ->withProviderId('no-such-provider')
+        );
+    }
+
+    public function testAllowlistedCallerRequestingUnconfiguredProviderFailsInsteadOfFallingBack(): void
+    {
+        // Only OpenAI is configured; Claude is requested. Falling back to the
+        // forced provider would silently answer from the wrong engine, so a
+        // clear error is expected instead.
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => ['apiKey' => 'secret-openai-key', 'endpointUrl' => ''],
+            ])
+        );
+
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'openai',
+            'providerSelectionAllowlist' => ['ExamplePlugin'],
+        ];
+
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('No API key is configured for Claude.');
+
+        StaticContainer::get(AIProviderService::class)->complete(
+            (new AIRequest('What do you know about brand X?', 'ExamplePlugin'))
+                ->withProviderId('claude')
+        );
+    }
+
+    public function testConfigFileApiKeyMakesProviderUsableWithoutStoredCredentials(): void
+    {
+        Config::getInstance()->AIProviders = ['openaiApiKey' => 'config-openai-key'];
+
+        $this->mockAIProviderResponse('Because molecules scatter blue light more strongly.');
+
+        $response = StaticContainer::get(AIProviderService::class)
+            ->complete(new AIRequest('why is the sky blue', 'Test'));
+
+        $this->assertSame('openai', $response->toArray()['providerId']);
+    }
+
+    public function testConfigFileApiKeyWinsOverStoredApiKey(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => ['apiKey' => 'stored-db-key', 'endpointUrl' => ''],
+            ])
+        );
+
+        Config::getInstance()->AIProviders = ['openaiApiKey' => 'config-openai-key'];
+
+        $configuration = StaticContainer::get(Configuration::class);
+
+        $this->assertSame('config-openai-key', $configuration->getProviderConfiguration('openai')['apiKey']);
+    }
+
+    public function testEnvironmentVariableSuppliesApiKey(): void
+    {
+        putenv('MATOMO_AIPROVIDERS_OPENAI_API_KEY=env-openai-key');
+
+        $configuration = StaticContainer::get(Configuration::class);
+
+        $this->assertSame('env-openai-key', $configuration->getProviderConfiguration('openai')['apiKey']);
+
+        // The config file wins over the environment variable.
+        Config::getInstance()->AIProviders = ['openaiApiKey' => 'config-openai-key'];
+
+        $this->assertSame('config-openai-key', $configuration->getProviderConfiguration('openai')['apiKey']);
+    }
+
+    public function testManagedFlowServesAllowlistedPluginThroughRestrictedProviderWithConfigCredentials(): void
+    {
+        // Full managed-environment setup: a forced provider, restricted basic providers,
+        // config-file credentials, and an allowlisted plugin targeting one of
+        // the restricted providers.
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'openai',
+            'openaiApiKey' => 'config-openai-key',
+            'claudeApiKey' => 'config-claude-key',
+            'providerSelectionAllowlist' => ['ExamplePlugin'],
+        ];
+        $this->restrictSelectableProvidersTo('openai');
+
+        $capturedUrl = null;
+        $capturedBody = null;
+        $capturedHeaders = null;
+        $this->mockClaudeResponse('Brand X is a well-known brand.', $capturedUrl, $capturedBody, $capturedHeaders);
+
+        $response = StaticContainer::get(AIProviderService::class)->complete(
+            (new AIRequest('What do you know about brand X?', 'ExamplePlugin'))
+                ->withProviderId('claude')
+                ->withModel('claude-sonnet-4-5')
+        );
+
+        $this->assertSame('claude', $response->toArray()['providerId']);
+        $this->assertSame('Brand X is a well-known brand.', $response->getText());
+        $this->assertSame('https://api.anthropic.com/v1/messages', $capturedUrl);
+        $this->assertSame('claude-sonnet-4-5', $capturedBody['model']);
+        $this->assertContains('x-api-key: config-claude-key', $capturedHeaders);
+    }
+
+    public function testRestrictedProvidersAreHiddenFromAdminSurfaces(): void
+    {
+        $this->restrictSelectableProvidersTo('openai');
+
+        $settings = $this->api->getSettings();
+        $settingsProviderIds = array_column($settings['providers'], 'id');
+
+        $statuses = StaticContainer::get(AIProviderService::class)->getAvailableProviderStatuses();
+        $statusProviderIds = array_column($statuses, 'id');
+
+        $this->assertSame(['openai'], $settingsProviderIds);
+        $this->assertSame(['openai'], $statusProviderIds);
+    }
+
+    public function testRestrictedProviderCannotBeTested(): void
+    {
+        $this->restrictSelectableProvidersTo('openai');
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown AI provider "claude".');
+
+        $this->api->testConnection(
+            'claude',
+            (string) json_encode([
+                'apiKey' => 'secret-claude-key',
+                'endpointUrl' => '',
+            ])
+        );
+    }
+
+    public function testRestrictedProviderCannotBeDisconnected(): void
+    {
+        $this->restrictSelectableProvidersTo('openai');
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown AI provider "claude".');
+
+        $this->api->disconnectProvider('claude');
+    }
+
+    public function testRestrictedProviderCannotBeSavedAsDefault(): void
+    {
+        $this->restrictSelectableProvidersTo('openai');
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown AI provider "claude".');
+
+        $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'claude' => ['apiKey' => 'secret-claude-key', 'endpointUrl' => ''],
+            ])
+        );
+    }
+
+    public function testRestrictedProviderIsNotEligibleAsDefault(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => ['apiKey' => 'secret-openai-key', 'endpointUrl' => ''],
+            ])
+        );
+
+        // After the saved default provider becomes restricted, resolution must
+        // not pick it (or any other restricted provider) as the default.
+        $this->restrictSelectableProvidersTo('claude');
+
+        $settings = $this->api->getSettings();
+
+        $this->assertSame('', $settings['defaultProviderId']);
+    }
+
+    public function testDuplicateProviderRegistrationKeepsFirstSelectableFlag(): void
+    {
+        $providers = new AIProvidersList();
+        $providers->addProvider(new OpenAI(), false);
+        $providers->addProvider(new OpenAI());
+
+        $this->assertCount(1, $providers->getProviders());
+        $this->assertFalse($providers->isSelectable('openai'));
+        $this->assertSame([], $providers->getSelectableProviders());
+    }
+
+    public function testForcedDefaultProviderFromConfigLocksConfiguration(): void
+    {
+        Config::getInstance()->AIProviders = ['defaultProvider' => 'openai'];
+
+        $settings = $this->api->getSettings();
+
+        $this->assertSame('openai', $settings['defaultProviderId']);
+        $this->assertFalse($settings['canEditProviderConfiguration']);
+        $this->assertFalse($settings['canEditCapabilityLevel']);
+    }
+
+    public function testManagedModeMakesSettingsPageUnavailable(): void
+    {
+        Config::getInstance()->AIProviders = ['defaultProvider' => 'openai'];
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('managed');
+
+        StaticContainer::get(Controller::class)->index();
+    }
+
+    public function testProvidersCannotBeOverwritten(): void
+    {
+        $providers = new AIProvidersList();
+        $first = new OpenAI();
+
+        $this->assertTrue($providers->addProvider($first));
+        // A duplicate ID is rejected and reported via the return value.
+        $this->assertFalse($providers->addProvider(new OpenAI()));
+
+        $this->assertCount(1, $providers->getProviders());
+        $this->assertSame($first, $providers->getProvider('openai'));
+    }
+
+    public function testApiTestsConnectionWithUnsavedProviderConfiguration(): void
+    {
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ): void {
+            $this->assertSame('https://api.openai.com/v1/models', $url);
+            $this->assertSame('GET', $httpEventParams['httpMethod']);
+
+            $response = (string) json_encode(['data' => [['id' => 'gpt-4.1-mini']]]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+
+        $response = $this->api->testConnection(
+            'openai',
+            (string) json_encode([
+                'apiKey' => 'secret-openai-key',
+                'endpointUrl' => '',
+            ])
+        );
+
+        $this->assertSame('openai', $response['providerId']);
+        $this->assertSame('OpenAI', $response['providerName']);
+    }
+
+    public function testApiRetriesTransientProviderErrors(): void
+    {
+        $requests = 0;
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use (&$requests): void {
+            $this->assertSame(
+                'https://generativelanguage.googleapis.com/v1beta/models',
+                $url
+            );
+            $this->assertSame('GET', $httpEventParams['httpMethod']);
+
+            $requests++;
+
+            if ($requests === 1) {
+                $response = (string) json_encode([
+                    'error' => [
+                        'code' => 503,
+                        'message' => 'This model is currently experiencing high demand.',
+                        'status' => 'UNAVAILABLE',
+                    ],
+                ]);
+                $status = 503;
+                $headers = ['Content-Type' => 'application/json'];
+                return;
+            }
+
+            $response = (string) json_encode(['models' => [['name' => 'models/gemini-2.5-flash']]]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+
+        $response = $this->api->testConnection(
+            'gemini',
+            (string) json_encode([
+                'apiKey' => 'secret-gemini-key',
+                'endpointUrl' => '',
+            ])
+        );
+
+        $this->assertSame(2, $requests);
+        $this->assertSame('gemini', $response['providerId']);
+        $this->assertSame('Gemini', $response['providerName']);
+    }
+
+    public function testDisconnectProviderRemovesStoredApiKey(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => [
+                    'apiKey' => 'secret-openai-key',
+                    'endpointUrl' => '',
+                ],
+            ])
+        );
+
+        $settings = $this->api->disconnectProvider('openai');
+        $openAI = $this->getProvider($settings, 'openai');
+
+        $this->assertSame('', $settings['defaultProviderId']);
+        $this->assertFalse($openAI['configuration']['hasApiKey']);
+    }
+
+    public function testSaveSettingsRejectsUnconfiguredDefaultProvider(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('AI provider "openai" is not configured.');
+
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            '{}'
+        );
+    }
+
+    public function testSaveSettingsRejectsUnknownProvider(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown AI provider');
+
+        $this->api->saveSettings(
+            'unknown-provider',
+            Configuration::CAPABILITY_INSTANT,
+            '{}'
+        );
+    }
+
+    public function testGetSettingsRequiresSuperUserAccess(): void
+    {
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('checkUserHasSuperUserAccess');
+
+        $this->setAnonymousUser();
+        $this->api->getSettings();
+    }
+
+    /**
+     * @param array<string, mixed> $settings
+     * @return array<string, mixed>
+     */
+    private function getProvider(array $settings, string $providerId): array
+    {
+        foreach ($settings['providers'] as $provider) {
+            if ($provider['id'] === $providerId) {
+                return $provider;
+            }
+        }
+
+        $this->fail(sprintf('Provider "%s" was not found.', $providerId));
+    }
+
+    private function setSuperUser(): void
+    {
+        FakeAccess::clearAccess(true);
+    }
+
+    private function setAnonymousUser(): void
+    {
+        FakeAccess::clearAccess();
+        FakeAccess::$identity = 'anonymous';
+    }
+
+    /**
+     * Stores credentials for OpenAI and Claude while the instance is still
+     * unmanaged, so managed-mode tests can then force a provider via config.
+     */
+    private function saveOpenAiAndClaudeKeys(): void
+    {
+        $this->api->saveSettings(
+            'openai',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'openai' => ['apiKey' => 'secret-openai-key', 'endpointUrl' => ''],
+                'claude' => ['apiKey' => 'secret-claude-key', 'endpointUrl' => ''],
+            ])
+        );
+    }
+
+    /**
+     * Demotes every provider except the given one to non-selectable, the same
+     * way a managed environment restricts providers.
+     */
+    private function restrictSelectableProvidersTo(string $selectableProviderId): void
+    {
+        Piwik::addAction(
+            'AIProviders.filterAIProviders',
+            function (AIProvidersList $providers) use ($selectableProviderId): void {
+                foreach ($providers->getProviders() as $provider) {
+                    if ($provider->getId() !== $selectableProviderId) {
+                        $providers->setSelectable($provider->getId(), false);
+                    }
+                }
+            }
+        );
+    }
+
+    /**
+     * @param string|null $capturedUrl Set to the requested URL.
+     * @param array<string, mixed>|null $capturedBody Set to the decoded request body.
+     * @param array<int, string>|null $capturedHeaders Set to the sent request headers.
+     */
+    private function mockClaudeResponse(
+        string $text,
+        ?string &$capturedUrl,
+        ?array &$capturedBody,
+        ?array &$capturedHeaders = null
+    ): void {
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use (
+            $text,
+            &$capturedUrl,
+            &$capturedBody,
+            &$capturedHeaders
+): void {
+            $capturedUrl = $url;
+            $capturedBody = json_decode((string) $httpEventParams['body'], true);
+            $capturedHeaders = $httpEventParams['headers'];
+
+            $response = (string) json_encode([
+                'content' => [['text' => $text]],
+                'usage' => ['input_tokens' => 15, 'output_tokens' => 9],
+            ]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+    }
+
+    private function mockAIProviderResponse(string $text): void
+    {
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use ($text): void {
+            $this->assertSame('https://api.openai.com/v1/chat/completions', $url);
+            $this->assertSame('POST', $httpEventParams['httpMethod']);
+
+            $response = (string) json_encode([
+                'choices' => [
+                    [
+                        'message' => [
+                            'content' => $text,
+                        ],
+                    ],
+                ],
+                'usage' => [
+                    'prompt_tokens' => 12,
+                    'completion_tokens' => 7,
+                ],
+            ]);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+    }
+
+    public function provideContainerConfig(): array
+    {
+        return [
+            'Piwik\Access' => new FakeAccess(),
+        ];
+    }
+}
diff --git a/tests/Integration/ConverseServiceTest.php b/tests/Integration/ConverseServiceTest.php
new file mode 100644
index 0000000..ca075e6
--- /dev/null
+++ b/tests/Integration/ConverseServiceTest.php
@@ -0,0 +1,359 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Integration;
+
+use Piwik\Config;
+use Piwik\Container\StaticContainer;
+use Piwik\Piwik;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIProviderService;
+use Piwik\Plugins\AIProviders\AIProvidersList;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\API;
+use Piwik\Plugins\AIProviders\Exception\AIProviderClientException;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+use Piwik\Plugins\AIProviders\Provider\AIProvider;
+use Piwik\Tests\Framework\Fixture;
+use Piwik\Tests\Framework\Mock\FakeAccess;
+use Piwik\Tests\Framework\TestCase\IntegrationTestCase;
+
+/**
+ * Service-level coverage for {@link AIProviderService::converse()} and
+ * {@link AIProviderService::canConverse()}: provider resolution, the
+ * conversation-capability guard, and the managed (forced provider) flow.
+ *
+ * @group AIProviders
+ * @group AIProvidersConverse
+ * @group Plugins
+ */
+class ConverseServiceTest extends IntegrationTestCase
+{
+    /**
+     * @var API
+     */
+    private $api;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        // Ensure no forced configuration leaks between tests.
+        Config::getInstance()->AIProviders = [];
+
+        Fixture::createSuperUser();
+        FakeAccess::clearAccess(true);
+
+        $this->api = API::getInstance();
+
+        // Reset stored settings to their defaults between tests.
+        $this->api->saveSettings('', Configuration::CAPABILITY_INSTANT, '{}');
+    }
+
+    public function tearDown(): void
+    {
+        Config::getInstance()->AIProviders = [];
+
+        parent::tearDown();
+    }
+
+    public function testConverseRoutesToConfiguredDefaultProvider(): void
+    {
+        $this->configureClaudeAsDefaultProvider();
+
+        $capturedUrl = null;
+        $capturedBody = null;
+        $this->mockClaudeConverseResponse(
+            [
+                'content' => [['type' => 'text', 'text' => 'Hello back.']],
+                'stop_reason' => 'end_turn',
+                'usage' => ['input_tokens' => 5, 'output_tokens' => 2],
+            ],
+            $capturedUrl,
+            $capturedBody
+        );
+
+        $request = (new AIConversationRequest(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            'Test'
+        ))->withSystemPrompt('You are concise.');
+
+        $response = StaticContainer::get(AIProviderService::class)->converse($request);
+
+        $this->assertSame('claude', $response->getProviderId());
+        $this->assertSame([['type' => 'text', 'text' => 'Hello back.']], $response->getContent());
+        $this->assertSame('Hello back.', $response->getText());
+        $this->assertSame(AIConversationResponse::STOP_END_TURN, $response->getStopReason());
+        $this->assertSame(5, $response->getInputTokens());
+        $this->assertSame(2, $response->getOutputTokens());
+        $this->assertIsInt($response->getExecutionTimeMs());
+
+        $this->assertSame('https://api.anthropic.com/v1/messages', $capturedUrl);
+        $this->assertIsArray($capturedBody);
+        $this->assertSame('claude-haiku-4-5', $capturedBody['model']);
+        $this->assertSame('You are concise.', $capturedBody['system']);
+        $this->assertSame(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            $capturedBody['messages']
+        );
+    }
+
+    public function testConverseAllowsToolOnlyTurnsWithEmptyText(): void
+    {
+        // Unlike complete(), an empty text response is valid for converse():
+        // a turn may consist solely of tool_use blocks.
+        $this->configureClaudeAsDefaultProvider();
+
+        $capturedUrl = null;
+        $capturedBody = null;
+        $this->mockClaudeConverseResponse(
+            [
+                'content' => [
+                    ['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'matomo_site_list', 'input' => []],
+                ],
+                'stop_reason' => 'tool_use',
+                'usage' => ['input_tokens' => 5, 'output_tokens' => 2],
+            ],
+            $capturedUrl,
+            $capturedBody
+        );
+
+        $response = StaticContainer::get(AIProviderService::class)->converse(
+            new AIConversationRequest(
+                [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'List my sites']]]],
+                'Test'
+            )
+        );
+
+        $this->assertSame('', $response->getText());
+        $this->assertSame(AIConversationResponse::STOP_TOOL_USE, $response->getStopReason());
+        $this->assertSame(
+            [['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'matomo_site_list', 'input' => []]],
+            $response->getContent()
+        );
+    }
+
+    public function testForcedProviderOverridesRequestedProviderAndStripsModel(): void
+    {
+        // Simulate a managed environment forcing a conversation-capable
+        // provider with config-file credentials.
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'claude',
+            'claudeApiKey' => 'config-claude-key',
+        ];
+
+        $capturedUrl = null;
+        $capturedBody = null;
+        $this->mockClaudeConverseResponse(
+            [
+                'content' => [['type' => 'text', 'text' => 'Forced provider answered.']],
+                'stop_reason' => 'end_turn',
+                'usage' => ['input_tokens' => 5, 'output_tokens' => 2],
+            ],
+            $capturedUrl,
+            $capturedBody
+        );
+
+        // The caller is not on the providerSelectionAllowlist, so both the
+        // requested provider and the requested model are overridden.
+        $response = StaticContainer::get(AIProviderService::class)->converse(
+            (new AIConversationRequest(
+                [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+                'Goals'
+            ))
+                ->withProviderId('openai')
+                ->withModel('gpt-4o')
+        );
+
+        $this->assertSame('claude', $response->getProviderId());
+        $this->assertSame('https://api.anthropic.com/v1/messages', $capturedUrl);
+        $this->assertIsArray($capturedBody);
+        // The requested model was stripped, so the forced provider's default is used.
+        $this->assertSame('claude-haiku-4-5', $capturedBody['model']);
+    }
+
+    public function testAllowlistedCallerMaySelectProviderAndModelWhenProviderIsForced(): void
+    {
+        Config::getInstance()->AIProviders = [
+            'defaultProvider' => 'openai',
+            'openaiApiKey' => 'config-openai-key',
+            'claudeApiKey' => 'config-claude-key',
+            'providerSelectionAllowlist' => ['ExamplePlugin'],
+        ];
+
+        $capturedUrl = null;
+        $capturedBody = null;
+        $this->mockClaudeConverseResponse(
+            [
+                'content' => [['type' => 'text', 'text' => 'Allowlisted answer.']],
+                'stop_reason' => 'end_turn',
+                'usage' => ['input_tokens' => 5, 'output_tokens' => 2],
+            ],
+            $capturedUrl,
+            $capturedBody
+        );
+
+        $response = StaticContainer::get(AIProviderService::class)->converse(
+            (new AIConversationRequest(
+                [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+                'ExamplePlugin'
+            ))
+                ->withProviderId('claude')
+                ->withModel('claude-sonnet-4-5')
+        );
+
+        $this->assertSame('claude', $response->getProviderId());
+        $this->assertSame('https://api.anthropic.com/v1/messages', $capturedUrl);
+        $this->assertIsArray($capturedBody);
+        $this->assertSame('claude-sonnet-4-5', $capturedBody['model']);
+    }
+
+    public function testConverseThrowsForProviderWithoutConversationSupport(): void
+    {
+        // All built-in providers now implement converse(); register a
+        // completion-only provider and force it as default to exercise the
+        // capability guard.
+        $this->forceCompletionOnlyDefaultProvider();
+
+        $this->expectException(AIProviderClientException::class);
+        $this->expectExceptionMessage('Completion Only does not support multi-turn conversations.');
+
+        StaticContainer::get(AIProviderService::class)->converse(
+            new AIConversationRequest(
+                [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+                'Test'
+            )
+        );
+    }
+
+    public function testCanConverseIsFalseWithoutConfiguredDefaultProvider(): void
+    {
+        $this->assertFalse(StaticContainer::get(AIProviderService::class)->canConverse());
+    }
+
+    public function testCanConverseIsFalseWhenDefaultProviderDoesNotSupportConversations(): void
+    {
+        $this->forceCompletionOnlyDefaultProvider();
+
+        $service = StaticContainer::get(AIProviderService::class);
+        $this->assertFalse($service->canConverse());
+        $this->assertSame(
+            AIProviderService::CONVERSATION_PROVIDER_UNSUPPORTED,
+            $service->getConversationAvailability()['status']
+        );
+    }
+
+    public function testCanConverseIsFalseWhenConversationCapableProviderIsNotConfigured(): void
+    {
+        // A managed environment forces Claude, but no credentials are available.
+        Config::getInstance()->AIProviders = ['defaultProvider' => 'claude'];
+
+        $this->assertFalse(StaticContainer::get(AIProviderService::class)->canConverse());
+    }
+
+    public function testCanConverseIsTrueWhenDefaultProviderIsConfiguredAndConversationCapable(): void
+    {
+        $this->configureClaudeAsDefaultProvider();
+
+        $this->assertTrue(StaticContainer::get(AIProviderService::class)->canConverse());
+    }
+
+    private function configureClaudeAsDefaultProvider(): void
+    {
+        $this->api->saveSettings(
+            'claude',
+            Configuration::CAPABILITY_INSTANT,
+            (string) json_encode([
+                'claude' => ['apiKey' => 'secret-claude-key', 'endpointUrl' => ''],
+            ])
+        );
+    }
+
+    /**
+     * Registers a completion-only provider and forces it as the default, so
+     * the conversation-capability guard can be exercised even though every
+     * built-in provider now supports conversations.
+     */
+    private function forceCompletionOnlyDefaultProvider(): void
+    {
+        Piwik::addAction('AIProviders.addAIProviders', function (AIProvidersList $providers): void {
+            $providers->addProvider(new CompletionOnlyTestProvider());
+        });
+
+        Config::getInstance()->AIProviders = ['defaultProvider' => CompletionOnlyTestProvider::ID];
+    }
+
+    /**
+     * Mocks the Anthropic Messages endpoint for converse() calls.
+     *
+     * @param array<string, mixed> $responseBody Decoded provider response to return.
+     * @param string|null $capturedUrl Set to the requested URL.
+     * @param array<string, mixed>|null $capturedBody Set to the decoded request body.
+     */
+    private function mockClaudeConverseResponse(
+        array $responseBody,
+        ?string &$capturedUrl,
+        ?array &$capturedBody
+    ): void {
+        Piwik::addAction('Http.sendHttpRequest', function (
+            string $url,
+            array $httpEventParams,
+            ?string &$response,
+            ?int &$status,
+            array &$headers
+        ) use (
+            $responseBody,
+            &$capturedUrl,
+            &$capturedBody
+        ): void {
+            $capturedUrl = $url;
+            $capturedBody = json_decode((string) $httpEventParams['body'], true);
+
+            $response = (string) json_encode($responseBody);
+            $status = 200;
+            $headers = ['Content-Type' => 'application/json'];
+        });
+    }
+
+    public function provideContainerConfig(): array
+    {
+        return [
+            'Piwik\Access' => new FakeAccess(),
+        ];
+    }
+}
+
+/**
+ * A provider that only implements completions, used to exercise the
+ * conversation-capability guard now that every built-in provider supports
+ * conversations.
+ */
+class CompletionOnlyTestProvider extends AIProvider
+{
+    public const ID = 'completion-only';
+
+    public function __construct()
+    {
+        parent::__construct(self::ID, 'Completion Only', 'Completion-only test provider.');
+    }
+
+    public function isConfigured(array $configuration): bool
+    {
+        return true;
+    }
+
+    public function complete(AIRequest $request, array $configuration): AIProviderResponse
+    {
+        return new AIProviderResponse($this->getId(), $this->getName(), 'test-model', 'ok');
+    }
+}
diff --git a/tests/Unit/AIConversationRequestTest.php b/tests/Unit/AIConversationRequestTest.php
new file mode 100644
index 0000000..66302b3
--- /dev/null
+++ b/tests/Unit/AIConversationRequestTest.php
@@ -0,0 +1,119 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIRequest;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @group AIProviders
+ */
+class AIConversationRequestTest extends TestCase
+{
+    public function testProvidesRequiredValuesAndSensibleDefaults(): void
+    {
+        $messages = [
+            ['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]],
+        ];
+
+        $request = new AIConversationRequest($messages, 'AskMatomo');
+
+        $this->assertSame($messages, $request->getMessages());
+        $this->assertSame('AskMatomo', $request->getCallerPluginName());
+        $this->assertNull($request->getSystemPrompt());
+        $this->assertNull($request->getProviderId());
+        $this->assertNull($request->getModel());
+        $this->assertNull($request->getFeatureKey());
+        $this->assertSame([], $request->getTools());
+        $this->assertSame(AIConversationRequest::DEFAULT_MAX_TOKENS, $request->getMaxTokens());
+        $this->assertSame(2048, $request->getMaxTokens());
+        $this->assertSame(AIRequest::DEFAULT_TEMPERATURE, $request->getTemperature());
+        $this->assertSame(0.2, $request->getTemperature());
+        $this->assertSame(AIConversationRequest::DEFAULT_TIMEOUT_SECONDS, $request->getTimeoutSeconds());
+        $this->assertSame(60, $request->getTimeoutSeconds());
+    }
+
+    public function testWithMethodsReturnImmutableCopies(): void
+    {
+        $request = new AIConversationRequest(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            'AskMatomo'
+        );
+
+        $tools = [
+            [
+                'name' => 'matomo_site_list',
+                'description' => 'Lists sites',
+                'inputSchema' => ['type' => 'object'],
+            ],
+        ];
+
+        $modified = $request
+            ->withSystemPrompt('System')
+            ->withTools($tools)
+            ->withProviderId('claude')
+            ->withModel('claude-haiku-4-5')
+            ->withFeatureKey('chat')
+            ->withMaxTokens(4096)
+            ->withTemperature(0.7)
+            ->withTimeoutSeconds(120);
+
+        // The original request is unchanged.
+        $this->assertNull($request->getSystemPrompt());
+        $this->assertSame([], $request->getTools());
+        $this->assertNull($request->getProviderId());
+        $this->assertNull($request->getModel());
+        $this->assertNull($request->getFeatureKey());
+        $this->assertSame(AIConversationRequest::DEFAULT_MAX_TOKENS, $request->getMaxTokens());
+        $this->assertSame(AIRequest::DEFAULT_TEMPERATURE, $request->getTemperature());
+        $this->assertSame(AIConversationRequest::DEFAULT_TIMEOUT_SECONDS, $request->getTimeoutSeconds());
+
+        // The derived request carries the new values.
+        $this->assertSame('System', $modified->getSystemPrompt());
+        $this->assertSame($tools, $modified->getTools());
+        $this->assertSame('claude', $modified->getProviderId());
+        $this->assertSame('claude-haiku-4-5', $modified->getModel());
+        $this->assertSame('chat', $modified->getFeatureKey());
+        $this->assertSame(4096, $modified->getMaxTokens());
+        $this->assertSame(0.7, $modified->getTemperature());
+        $this->assertSame(120, $modified->getTimeoutSeconds());
+
+        // The messages and caller plugin carry over to derived requests.
+        $this->assertSame($request->getMessages(), $modified->getMessages());
+        $this->assertSame('AskMatomo', $modified->getCallerPluginName());
+    }
+
+    public function testEachWithMethodReturnsANewInstance(): void
+    {
+        $request = new AIConversationRequest([], 'AskMatomo');
+
+        $this->assertNotSame($request, $request->withSystemPrompt('System'));
+        $this->assertNotSame($request, $request->withTools([]));
+        $this->assertNotSame($request, $request->withProviderId('claude'));
+        $this->assertNotSame($request, $request->withModel('claude-haiku-4-5'));
+        $this->assertNotSame($request, $request->withFeatureKey('chat'));
+        $this->assertNotSame($request, $request->withMaxTokens(1));
+        $this->assertNotSame($request, $request->withTemperature(0.5));
+        $this->assertNotSame($request, $request->withTimeoutSeconds(10));
+    }
+
+    public function testWithTimeoutSecondsClampsToAtLeastOneSecond(): void
+    {
+        $request = new AIConversationRequest([], 'AskMatomo');
+
+        $this->assertSame(1, $request->withTimeoutSeconds(0)->getTimeoutSeconds());
+        $this->assertSame(1, $request->withTimeoutSeconds(-5)->getTimeoutSeconds());
+        $this->assertSame(1, $request->withTimeoutSeconds(1)->getTimeoutSeconds());
+        $this->assertSame(30, $request->withTimeoutSeconds(30)->getTimeoutSeconds());
+    }
+}
diff --git a/tests/Unit/AIConversationResponseTest.php b/tests/Unit/AIConversationResponseTest.php
new file mode 100644
index 0000000..19cbcc2
--- /dev/null
+++ b/tests/Unit/AIConversationResponseTest.php
@@ -0,0 +1,98 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use Piwik\Plugins\AIProviders\AIConversationResponse;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @group AIProviders
+ */
+class AIConversationResponseTest extends TestCase
+{
+    public function testProvidesConstructorValuesThroughGetters(): void
+    {
+        $content = [
+            ['type' => 'text', 'text' => 'Hello!'],
+            ['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'matomo_site_list', 'input' => []],
+        ];
+
+        $response = new AIConversationResponse(
+            'claude',
+            'Claude',
+            'claude-haiku-4-5',
+            $content,
+            AIConversationResponse::STOP_TOOL_USE,
+            12,
+            7,
+            450
+        );
+
+        $this->assertSame('claude', $response->getProviderId());
+        $this->assertSame('Claude', $response->getProviderName());
+        $this->assertSame('claude-haiku-4-5', $response->getModel());
+        $this->assertSame($content, $response->getContent());
+        $this->assertSame(AIConversationResponse::STOP_TOOL_USE, $response->getStopReason());
+        $this->assertSame(12, $response->getInputTokens());
+        $this->assertSame(7, $response->getOutputTokens());
+        $this->assertSame(450, $response->getExecutionTimeMs());
+    }
+
+    public function testTokensAndExecutionTimeDefaultToNull(): void
+    {
+        $response = new AIConversationResponse(
+            'claude',
+            'Claude',
+            'claude-haiku-4-5',
+            [],
+            AIConversationResponse::STOP_END_TURN
+        );
+
+        $this->assertNull($response->getInputTokens());
+        $this->assertNull($response->getOutputTokens());
+        $this->assertNull($response->getExecutionTimeMs());
+    }
+
+    public function testGetTextConcatenatesTextBlocksAndIgnoresOtherBlocks(): void
+    {
+        $response = new AIConversationResponse(
+            'claude',
+            'Claude',
+            'claude-haiku-4-5',
+            [
+                ['type' => 'text', 'text' => 'First paragraph.'],
+                ['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'matomo_site_list', 'input' => []],
+                ['type' => 'text', 'text' => 12345],
+                ['type' => 'text'],
+                ['type' => 'text', 'text' => 'Second paragraph.'],
+            ],
+            AIConversationResponse::STOP_TOOL_USE
+        );
+
+        // Text blocks are joined with a newline; tool_use blocks and text
+        // blocks without a string text value are ignored.
+        $this->assertSame("First paragraph.\nSecond paragraph.", $response->getText());
+    }
+
+    public function testGetTextReturnsEmptyStringForToolOnlyTurn(): void
+    {
+        $response = new AIConversationResponse(
+            'claude',
+            'Claude',
+            'claude-haiku-4-5',
+            [['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'matomo_site_list', 'input' => []]],
+            AIConversationResponse::STOP_TOOL_USE
+        );
+
+        $this->assertSame('', $response->getText());
+    }
+}
diff --git a/tests/Unit/AIProvidersListTest.php b/tests/Unit/AIProvidersListTest.php
new file mode 100644
index 0000000..14b43ef
--- /dev/null
+++ b/tests/Unit/AIProvidersListTest.php
@@ -0,0 +1,97 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\AIProviders\AIProvidersList;
+use Piwik\Plugins\AIProviders\Provider\Claude;
+use Piwik\Plugins\AIProviders\Provider\OpenAI;
+
+/**
+ * @group AIProviders
+ * @group AIProvidersList
+ * @group Plugins
+ */
+class AIProvidersListTest extends TestCase
+{
+    public function testProvidersAreSelectableByDefault(): void
+    {
+        $providers = new AIProvidersList();
+        $providers->addProvider(new OpenAI());
+
+        $this->assertTrue($providers->isSelectable('openai'));
+        $this->assertCount(1, $providers->getSelectableProviders());
+    }
+
+    public function testAddProviderReportsWhetherTheProviderWasAdded(): void
+    {
+        $providers = new AIProvidersList();
+
+        $this->assertTrue($providers->addProvider(new OpenAI()));
+        // A second registration for the same ID is ignored, reported as false.
+        $this->assertFalse($providers->addProvider(new OpenAI()));
+        $this->assertCount(1, $providers->getProviders());
+    }
+
+    public function testProviderCanBeRegisteredAsRestricted(): void
+    {
+        $providers = new AIProvidersList();
+        $providers->addProvider(new OpenAI(), false);
+
+        $this->assertTrue($providers->hasProvider('openai'));
+        $this->assertFalse($providers->isSelectable('openai'));
+        $this->assertSame([], $providers->getSelectableProviders());
+        $this->assertCount(1, $providers->getProviders());
+    }
+
+    public function testSetSelectableDemotesAndPromotesRegisteredProviders(): void
+    {
+        $providers = new AIProvidersList();
+        $providers->addProvider(new OpenAI());
+        $providers->addProvider(new Claude());
+
+        $providers->setSelectable('claude', false);
+
+        $this->assertFalse($providers->isSelectable('claude'));
+        $this->assertTrue($providers->isSelectable('openai'));
+        $this->assertCount(2, $providers->getProviders());
+        $this->assertCount(1, $providers->getSelectableProviders());
+        $this->assertSame('openai', $providers->getSelectableProviders()[0]->getId());
+
+        $providers->setSelectable('claude', true);
+
+        $this->assertTrue($providers->isSelectable('claude'));
+        $this->assertCount(2, $providers->getSelectableProviders());
+    }
+
+    public function testSetSelectableIgnoresUnknownProviders(): void
+    {
+        $providers = new AIProvidersList();
+
+        $providers->setSelectable('unknown', true);
+
+        $this->assertFalse($providers->isSelectable('unknown'));
+        $this->assertFalse($providers->hasProvider('unknown'));
+    }
+
+    public function testRemoveProviderForgetsSelectableFlag(): void
+    {
+        $providers = new AIProvidersList();
+        $providers->addProvider(new OpenAI());
+
+        $providers->removeProvider('openai');
+
+        $this->assertFalse($providers->hasProvider('openai'));
+        $this->assertFalse($providers->isSelectable('openai'));
+        $this->assertSame([], $providers->getSelectableProviders());
+    }
+}
diff --git a/tests/Unit/AIRequestTest.php b/tests/Unit/AIRequestTest.php
new file mode 100644
index 0000000..7c024fc
--- /dev/null
+++ b/tests/Unit/AIRequestTest.php
@@ -0,0 +1,76 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use Piwik\Plugins\AIProviders\AIRequest;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @group AIProviders
+ */
+class AIRequestTest extends TestCase
+{
+    public function testProvidesRequiredValuesAndSensibleDefaults(): void
+    {
+        $request = new AIRequest('Summarise this report.', 'Goals');
+
+        $this->assertSame('Summarise this report.', $request->getUserPrompt());
+        $this->assertSame('Goals', $request->getCallerPluginName());
+        $this->assertNull($request->getSystemPrompt());
+        $this->assertNull($request->getProviderId());
+        $this->assertNull($request->getModel());
+        $this->assertNull($request->getCapabilityLevel());
+        $this->assertNull($request->getFeatureKey());
+        $this->assertNull($request->getIdSite());
+        $this->assertSame(AIRequest::DEFAULT_MAX_TOKENS, $request->getMaxTokens());
+        $this->assertSame(AIRequest::DEFAULT_TEMPERATURE, $request->getTemperature());
+        $this->assertSame(AIRequest::REASONING_NONE, $request->getReasoningLevel());
+        $this->assertFalse($request->isWebSearchEnabled());
+        $this->assertNull($request->getThinkingBudget());
+    }
+
+    public function testWithMethodsReturnImmutableCopies(): void
+    {
+        $request = new AIRequest('Prompt', 'Goals');
+
+        $modified = $request
+            ->withSystemPrompt('System')
+            ->withProviderId('claude')
+            ->withModel('claude-haiku-4-5')
+            ->withCapabilityLevel('thinking')
+            ->withFeatureKey('goal-recommendation')
+            ->withIdSite(3)
+            ->withMaxTokens(256)
+            ->withTemperature(0.7)
+            ->withReasoningLevel('low')
+            ->withWebSearchEnabled(true)
+            ->withThinkingBudget(128);
+
+        // The original request is unchanged.
+        $this->assertNull($request->getSystemPrompt());
+        $this->assertNull($request->getProviderId());
+        $this->assertSame(AIRequest::DEFAULT_MAX_TOKENS, $request->getMaxTokens());
+
+        // The derived request carries the new values.
+        $this->assertSame('System', $modified->getSystemPrompt());
+        $this->assertSame('claude', $modified->getProviderId());
+        $this->assertSame('claude-haiku-4-5', $modified->getModel());
+        $this->assertSame('thinking', $modified->getCapabilityLevel());
+        $this->assertSame('goal-recommendation', $modified->getFeatureKey());
+        $this->assertSame(3, $modified->getIdSite());
+        $this->assertSame(256, $modified->getMaxTokens());
+        $this->assertSame(0.7, $modified->getTemperature());
+        $this->assertSame('low', $modified->getReasoningLevel());
+        $this->assertTrue($modified->isWebSearchEnabled());
+        $this->assertSame(128, $modified->getThinkingBudget());
+    }
+}
diff --git a/tests/Unit/CapabilityThinkingTest.php b/tests/Unit/CapabilityThinkingTest.php
new file mode 100644
index 0000000..b69eaa8
--- /dev/null
+++ b/tests/Unit/CapabilityThinkingTest.php
@@ -0,0 +1,183 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\Model\Configuration;
+use Piwik\Plugins\AIProviders\Provider\Claude;
+use Piwik\Plugins\AIProviders\Provider\CustomProvider;
+use Piwik\Plugins\AIProviders\Provider\Gemini;
+use Piwik\Plugins\AIProviders\Provider\OpenAI;
+
+/**
+ * Verifies how the instant/thinking capability level maps onto each provider's
+ * complete() wire format, and that an explicit per-request thinking budget
+ * overrides the capability.
+ *
+ * @group AIProviders
+ * @group Plugins
+ */
+class CapabilityThinkingTest extends TestCase
+{
+    private const OPENAI_CONFIG = ['apiKey' => 'k', 'endpointUrl' => ''];
+    private const CLAUDE_CONFIG = ['apiKey' => 'k', 'endpointUrl' => ''];
+    private const GEMINI_CONFIG = ['apiKey' => 'k', 'endpointUrl' => ''];
+    private const CUSTOM_CONFIG = ['apiKey' => '', 'endpointUrl' => 'http://localhost:1234/v1', 'model' => 'local-model'];
+
+    public function testOpenAiInstantDisablesReasoning(): void
+    {
+        $openAI = new RecordingCompleteOpenAI();
+
+        $openAI->complete($this->instantRequest(), self::OPENAI_CONFIG);
+
+        $this->assertSame('none', $openAI->sentPayload['reasoning_effort']);
+    }
+
+    public function testOpenAiThinkingEnablesReasoning(): void
+    {
+        $openAI = new RecordingCompleteOpenAI();
+
+        $openAI->complete($this->thinkingRequest(), self::OPENAI_CONFIG);
+
+        $this->assertSame('medium', $openAI->sentPayload['reasoning_effort']);
+    }
+
+    public function testClaudeInstantSendsNoThinkingBlock(): void
+    {
+        $claude = new RecordingCompleteClaude();
+
+        $claude->complete($this->instantRequest(), self::CLAUDE_CONFIG);
+
+        $this->assertArrayNotHasKey('thinking', $claude->sentPayload);
+        $this->assertArrayHasKey('temperature', $claude->sentPayload);
+    }
+
+    public function testClaudeThinkingEnablesThinkingBumpsMaxTokensAndDropsTemperature(): void
+    {
+        $claude = new RecordingCompleteClaude();
+
+        // Default max_tokens (1024) is below the thinking budget, so it must be
+        // bumped above the budget; temperature must be dropped.
+        $claude->complete($this->thinkingRequest(), self::CLAUDE_CONFIG);
+
+        // The default thinking budget (2048) is used when none is given.
+        $this->assertSame(['type' => 'enabled', 'budget_tokens' => 2048], $claude->sentPayload['thinking']);
+        $this->assertGreaterThan(2048, $claude->sentPayload['max_tokens']);
+        $this->assertArrayNotHasKey('temperature', $claude->sentPayload);
+    }
+
+    public function testGeminiInstantDisablesThinkingBudget(): void
+    {
+        $gemini = new RecordingCompleteGemini();
+
+        $gemini->complete($this->instantRequest(), self::GEMINI_CONFIG);
+
+        $this->assertSame(0, $gemini->sentPayload['generationConfig']['thinkingConfig']['thinkingBudget']);
+    }
+
+    public function testGeminiThinkingSetsPositiveThinkingBudget(): void
+    {
+        $gemini = new RecordingCompleteGemini();
+
+        $gemini->complete($this->thinkingRequest(), self::GEMINI_CONFIG);
+
+        $this->assertGreaterThan(0, $gemini->sentPayload['generationConfig']['thinkingConfig']['thinkingBudget']);
+    }
+
+    public function testCustomProviderMapsCapabilityOntoThinkFlag(): void
+    {
+        $custom = new RecordingCompleteCustomProvider();
+
+        $custom->complete($this->instantRequest(), self::CUSTOM_CONFIG);
+        $this->assertFalse($custom->sentPayload['think']);
+
+        $custom->complete($this->thinkingRequest(), self::CUSTOM_CONFIG);
+        $this->assertTrue($custom->sentPayload['think']);
+    }
+
+    public function testExplicitZeroBudgetForcesInstantEvenWhenCapabilityIsThinking(): void
+    {
+        $openAI = new RecordingCompleteOpenAI();
+
+        // Thinking capability, but the caller pins the budget to 0.
+        $request = (new AIRequest('hi', 'Test'))
+            ->withCapabilityLevel(Configuration::CAPABILITY_THINKING)
+            ->withThinkingBudget(0);
+
+        $openAI->complete($request, self::OPENAI_CONFIG);
+
+        $this->assertSame('none', $openAI->sentPayload['reasoning_effort']);
+    }
+
+    private function instantRequest(): AIRequest
+    {
+        return (new AIRequest('hi', 'Test'))->withCapabilityLevel(Configuration::CAPABILITY_INSTANT);
+    }
+
+    private function thinkingRequest(): AIRequest
+    {
+        return (new AIRequest('hi', 'Test'))->withCapabilityLevel(Configuration::CAPABILITY_THINKING);
+    }
+}
+
+class RecordingCompleteOpenAI extends OpenAI
+{
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentPayload = $payload;
+
+        return ['choices' => [['message' => ['content' => 'ok'], 'finish_reason' => 'stop']]];
+    }
+}
+
+class RecordingCompleteClaude extends Claude
+{
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentPayload = $payload;
+
+        return ['content' => [['text' => 'ok']], 'stop_reason' => 'end_turn'];
+    }
+}
+
+class RecordingCompleteGemini extends Gemini
+{
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentPayload = $payload;
+
+        return ['candidates' => [['content' => ['parts' => [['text' => 'ok']]]]]];
+    }
+}
+
+class RecordingCompleteCustomProvider extends CustomProvider
+{
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentPayload = $payload;
+
+        return ['choices' => [['message' => ['content' => 'ok'], 'finish_reason' => 'stop']]];
+    }
+}
diff --git a/tests/Unit/ClaudeConverseTest.php b/tests/Unit/ClaudeConverseTest.php
new file mode 100644
index 0000000..2979181
--- /dev/null
+++ b/tests/Unit/ClaudeConverseTest.php
@@ -0,0 +1,431 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIProviderResponse;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\Exception\AIProviderClientException;
+use Piwik\Plugins\AIProviders\Provider\AIProvider;
+use Piwik\Plugins\AIProviders\Provider\Claude;
+
+/**
+ * Tests the full converse() translation between the canonical message shape
+ * and the Anthropic Messages API wire format, with HTTP replaced by a
+ * recording sendJsonRequest() override.
+ *
+ * @group AIProviders
+ * @group Plugins
+ */
+class ClaudeConverseTest extends TestCase
+{
+    private const CONFIGURATION = ['apiKey' => 'secret-claude-key', 'endpointUrl' => ''];
+
+    public function testPayloadUsesDefaultModelEndpointHeadersAndRequestDefaults(): void
+    {
+        $claude = new RecordingClaude();
+
+        $claude->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('https://api.anthropic.com/v1/messages', $claude->sentUrl);
+        $this->assertSame(
+            [
+                'anthropic-version' => '2023-06-01',
+                'x-api-key' => 'secret-claude-key',
+            ],
+            $claude->sentHeaders
+        );
+        $this->assertSame('claude-haiku-4-5', $claude->sentPayload['model']);
+        $this->assertSame(AIConversationRequest::DEFAULT_MAX_TOKENS, $claude->sentPayload['max_tokens']);
+        $this->assertSame(AIRequest::DEFAULT_TEMPERATURE, $claude->sentPayload['temperature']);
+        $this->assertSame(AIConversationRequest::DEFAULT_TIMEOUT_SECONDS, $claude->sentTimeoutSeconds);
+        // No system prompt was set, so the payload carries no system key.
+        $this->assertArrayNotHasKey('system', $claude->sentPayload);
+        $this->assertSame(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            $claude->sentPayload['messages']
+        );
+    }
+
+    public function testPayloadHonoursRequestedModelOptionsSystemPromptAndTimeout(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = $this->simpleRequest()
+            ->withModel('claude-sonnet-4-5')
+            ->withSystemPrompt('You are concise.')
+            ->withMaxTokens(512)
+            ->withTemperature(0.9)
+            ->withTimeoutSeconds(120);
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        $this->assertSame('claude-sonnet-4-5', $claude->sentPayload['model']);
+        $this->assertSame('You are concise.', $claude->sentPayload['system']);
+        $this->assertSame(512, $claude->sentPayload['max_tokens']);
+        $this->assertSame(0.9, $claude->sentPayload['temperature']);
+        $this->assertSame(120, $claude->sentTimeoutSeconds);
+    }
+
+    public function testMessagesTranslateToAnthropicRolesAndBlocks(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = new AIConversationRequest(
+            [
+                ['role' => 'user', 'content' => [['type' => 'text', 'text' => 'delete site 1']]],
+                [
+                    'role' => 'assistant',
+                    'content' => [
+                        ['type' => 'text', 'text' => 'Deleting it now.'],
+                        ['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'del', 'input' => []],
+                    ],
+                ],
+                [
+                    'role' => 'tool',
+                    'content' => [[
+                        'type' => 'tool_result',
+                        'tool_use_id' => 'tu_1',
+                        'content' => [['type' => 'text', 'text' => 'deleted']],
+                        'structuredContent' => null,
+                        'is_error' => false,
+                    ]],
+                ],
+            ],
+            'AskMatomo'
+        );
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        $messages = $claude->sentPayload['messages'];
+
+        $this->assertCount(3, $messages);
+        // The canonical 'tool' role folds into a 'user' message so the
+        // tool_use/tool_result pairing survives the round trip.
+        $this->assertSame(['user', 'assistant', 'user'], array_column($messages, 'role'));
+
+        $this->assertSame([['type' => 'text', 'text' => 'delete site 1']], $messages[0]['content']);
+
+        $this->assertSame('text', $messages[1]['content'][0]['type']);
+        $this->assertSame('tool_use', $messages[1]['content'][1]['type']);
+        $this->assertSame('tu_1', $messages[1]['content'][1]['id']);
+        $this->assertSame('del', $messages[1]['content'][1]['name']);
+
+        // Empty tool_use input must encode as a JSON object, not an array.
+        $this->assertStringContainsString('"input":{}', (string) json_encode($claude->sentPayload));
+
+        $this->assertSame(
+            [[
+                'type' => 'tool_result',
+                'tool_use_id' => 'tu_1',
+                'content' => [['type' => 'text', 'text' => 'deleted']],
+                'is_error' => false,
+            ]],
+            $messages[2]['content']
+        );
+    }
+
+    public function testNonEmptyToolUseInputIsForwardedAsIs(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'assistant',
+                'content' => [['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'del', 'input' => ['idSite' => 1]]],
+            ]],
+            'AskMatomo'
+        );
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            ['idSite' => 1],
+            $claude->sentPayload['messages'][0]['content'][0]['input']
+        );
+    }
+
+    public function testToolResultStructuredContentBecomesSingleJsonTextBlock(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_1',
+                    'content' => [['type' => 'text', 'text' => '{"sites":[{"idsite":1}]}']],
+                    'structuredContent' => ['sites' => [['idsite' => 1]]],
+                    'is_error' => false,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        // structuredContent wins over the MCP text echo and is serialised
+        // into a single text block.
+        $this->assertSame(
+            [['type' => 'text', 'text' => '{"sites":[{"idsite":1}]}']],
+            $claude->sentPayload['messages'][0]['content'][0]['content']
+        );
+    }
+
+    public function testToolResultTranslatesMcpBlocksAndStringifiesNonTextBlocks(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_1',
+                    'content' => [
+                        ['type' => 'text', 'text' => 'plain text payload'],
+                        ['type' => 'resource_link', 'uri' => 'https://example.org/report'],
+                    ],
+                    'structuredContent' => null,
+                    'is_error' => false,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [
+                ['type' => 'text', 'text' => 'plain text payload'],
+                ['type' => 'text', 'text' => '{"type":"resource_link","uri":"https:\/\/example.org\/report"}'],
+            ],
+            $claude->sentPayload['messages'][0]['content'][0]['content']
+        );
+    }
+
+    public function testEmptyToolResultContentBecomesEmptyTextBlockAndErrorFlagPassesThrough(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_1',
+                    'content' => [],
+                    'structuredContent' => null,
+                    'is_error' => true,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [
+                'type' => 'tool_result',
+                'tool_use_id' => 'tu_1',
+                'content' => [['type' => 'text', 'text' => '']],
+                'is_error' => true,
+            ],
+            $claude->sentPayload['messages'][0]['content'][0]
+        );
+    }
+
+    public function testToolsAreOmittedWhenCatalogueIsEmpty(): void
+    {
+        $claude = new RecordingClaude();
+
+        $claude->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertArrayNotHasKey('tools', $claude->sentPayload);
+    }
+
+    public function testToolCatalogueTranslatesToAnthropicToolsWithoutMcpHints(): void
+    {
+        $claude = new RecordingClaude();
+
+        $request = $this->simpleRequest()->withTools([
+            [
+                'name' => 'matomo_site_list',
+                'title' => null,
+                'description' => 'Lists sites',
+                'inputSchema' => ['type' => 'object', 'properties' => ['idSite' => ['type' => 'integer']]],
+                'outputSchema' => null,
+                'readOnly' => true,
+                'destructive' => false,
+                'idempotent' => true,
+                'openWorld' => null,
+            ],
+        ]);
+
+        $claude->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [[
+                'name' => 'matomo_site_list',
+                'description' => 'Lists sites',
+                'input_schema' => ['type' => 'object', 'properties' => ['idSite' => ['type' => 'integer']]],
+            ]],
+            $claude->sentPayload['tools']
+        );
+        // The MCP annotation hints stay in the catalogue for the caller's
+        // approval flow and must not reach the provider.
+        $this->assertSame(
+            ['name', 'description', 'input_schema'],
+            array_keys($claude->sentPayload['tools'][0])
+        );
+    }
+
+    public function testResponseContentIsParsedIntoCanonicalBlocks(): void
+    {
+        $claude = new RecordingClaude();
+        $claude->cannedResponse = [
+            'content' => [
+                ['type' => 'thinking', 'thinking' => 'Let me check the sites.'],
+                ['type' => 'text', 'text' => 'Checking your sites now.'],
+                ['type' => 'tool_use', 'id' => 'tu_42', 'name' => 'matomo_site_list', 'input' => ['idSite' => 1]],
+            ],
+            'stop_reason' => 'tool_use',
+            'usage' => ['input_tokens' => 12, 'output_tokens' => 7],
+        ];
+
+        $response = $claude->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        // Unknown block types (thinking, …) are dropped; text and tool_use
+        // blocks come back in the canonical shape.
+        $this->assertSame(
+            [
+                ['type' => 'text', 'text' => 'Checking your sites now.'],
+                ['type' => 'tool_use', 'id' => 'tu_42', 'name' => 'matomo_site_list', 'input' => ['idSite' => 1]],
+            ],
+            $response->getContent()
+        );
+        $this->assertSame('tool_use', $response->getStopReason());
+        $this->assertSame(12, $response->getInputTokens());
+        $this->assertSame(7, $response->getOutputTokens());
+        $this->assertSame('claude', $response->getProviderId());
+        $this->assertSame('Claude', $response->getProviderName());
+        $this->assertSame('claude-haiku-4-5', $response->getModel());
+    }
+
+    public function testUnknownStopReasonPassesThrough(): void
+    {
+        $claude = new RecordingClaude();
+        $claude->cannedResponse = [
+            'content' => [['type' => 'text', 'text' => 'Hi.']],
+            'stop_reason' => 'refusal',
+            'usage' => ['input_tokens' => 1, 'output_tokens' => 1],
+        ];
+
+        $response = $claude->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('refusal', $response->getStopReason());
+    }
+
+    public function testMissingUsageYieldsNullTokenCounts(): void
+    {
+        $claude = new RecordingClaude();
+        $claude->cannedResponse = [
+            'content' => [['type' => 'text', 'text' => 'Hi.']],
+            'stop_reason' => 'end_turn',
+        ];
+
+        $response = $claude->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertNull($response->getInputTokens());
+        $this->assertNull($response->getOutputTokens());
+    }
+
+    public function testClaudeSupportsConversations(): void
+    {
+        $this->assertTrue((new Claude())->supportsConversations());
+    }
+
+    public function testProvidersWithoutConverseOverrideRejectConversations(): void
+    {
+        $provider = new MinimalCompletionOnlyProvider();
+
+        $this->assertFalse($provider->supportsConversations());
+
+        $this->expectException(AIProviderClientException::class);
+        $this->expectExceptionMessage('Completion Only does not support multi-turn conversations.');
+
+        $provider->converse($this->simpleRequest(), self::CONFIGURATION);
+    }
+
+    private function simpleRequest(): AIConversationRequest
+    {
+        return new AIConversationRequest(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            'AskMatomo'
+        );
+    }
+}
+
+/**
+ * Records the wire request instead of performing HTTP and returns a canned
+ * decoded response.
+ */
+class RecordingClaude extends Claude
+{
+    /** @var string|null */
+    public $sentUrl = null;
+
+    /** @var array<string, string> */
+    public $sentHeaders = [];
+
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    /** @var int|null */
+    public $sentTimeoutSeconds = null;
+
+    /** @var array<string, mixed> */
+    public $cannedResponse = [
+        'content' => [['type' => 'text', 'text' => 'Hi there.']],
+        'stop_reason' => 'end_turn',
+        'usage' => ['input_tokens' => 3, 'output_tokens' => 4],
+    ];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentUrl = $url;
+        $this->sentHeaders = $headers;
+        $this->sentPayload = $payload;
+        $this->sentTimeoutSeconds = $timeoutSeconds;
+
+        return $this->cannedResponse;
+    }
+}
+
+/**
+ * Minimal provider that does not override converse(), to test the base-class
+ * default behaviour.
+ */
+class MinimalCompletionOnlyProvider extends AIProvider
+{
+    public function __construct()
+    {
+        parent::__construct('completion-only', 'Completion Only', 'Test-only provider');
+    }
+
+    public function complete(AIRequest $request, array $configuration): AIProviderResponse
+    {
+        return $this->buildResponse($request, 'test-model', 'canned completion');
+    }
+}
diff --git a/tests/Unit/CustomProviderConverseTest.php b/tests/Unit/CustomProviderConverseTest.php
new file mode 100644
index 0000000..0f2811f
--- /dev/null
+++ b/tests/Unit/CustomProviderConverseTest.php
@@ -0,0 +1,138 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\Exception\AIProviderClientException;
+use Piwik\Plugins\AIProviders\Provider\CustomProvider;
+
+/**
+ * Tests CustomProvider's converse() wiring: the /chat/completions endpoint
+ * resolution that is unique to this provider, and that a request is dispatched
+ * through the shared OpenAI-compatible chat-completion path. The canonical
+ * message/tool translation and response parsing are shared with OpenAI and
+ * covered in full by {@see OpenAIConverseTest}.
+ *
+ * @group AIProviders
+ * @group Plugins
+ */
+class CustomProviderConverseTest extends TestCase
+{
+    private const CONFIGURATION = [
+        'apiKey' => 'secret-custom-key',
+        'endpointUrl' => 'https://llm.example.org/v1',
+        'model' => 'llama3.2',
+    ];
+
+    public function testPayloadUsesResolvedEndpointHeadersConfiguredModelAndRequestDefaults(): void
+    {
+        $custom = new RecordingCustomProvider();
+
+        $custom->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        // The configured endpoint gets /chat/completions appended.
+        $this->assertSame('https://llm.example.org/v1/chat/completions', $custom->sentUrl);
+        $this->assertSame(['Authorization' => 'Bearer secret-custom-key'], $custom->sentHeaders);
+        $this->assertSame('llama3.2', $custom->sentPayload['model']);
+        $this->assertSame(AIConversationRequest::DEFAULT_MAX_TOKENS, $custom->sentPayload['max_tokens']);
+        $this->assertSame(AIRequest::DEFAULT_TEMPERATURE, $custom->sentPayload['temperature']);
+        $this->assertSame(AIConversationRequest::DEFAULT_TIMEOUT_SECONDS, $custom->sentTimeoutSeconds);
+        $this->assertSame(
+            [['role' => 'user', 'content' => 'Hello']],
+            $custom->sentPayload['messages']
+        );
+    }
+
+    public function testCompleteDisablesThinkingWhenThinkingBudgetIsZero(): void
+    {
+        $custom = new RecordingCustomProvider();
+
+        $custom->complete((new AIRequest('Recommend goals', 'Goals'))->withThinkingBudget(0), self::CONFIGURATION);
+
+        $this->assertFalse($custom->sentPayload['think']);
+    }
+
+    public function testEndpointWithChatCompletionsSuffixIsLeftIntact(): void
+    {
+        $custom = new RecordingCustomProvider();
+
+        $custom->converse($this->simpleRequest(), [
+            'apiKey' => 'secret-custom-key',
+            'endpointUrl' => 'https://llm.example.org/v1/chat/completions',
+            'model' => 'llama3.2',
+        ]);
+
+        $this->assertSame('https://llm.example.org/v1/chat/completions', $custom->sentUrl);
+    }
+
+    public function testConverseThrowsWhenNoModelIsConfiguredOrRequested(): void
+    {
+        $custom = new RecordingCustomProvider();
+
+        $this->expectException(AIProviderClientException::class);
+
+        $custom->converse($this->simpleRequest(), [
+            'apiKey' => 'secret-custom-key',
+            'endpointUrl' => 'https://llm.example.org/v1',
+        ]);
+    }
+
+    public function testCustomProviderSupportsConversations(): void
+    {
+        $this->assertTrue((new CustomProvider())->supportsConversations());
+    }
+
+    private function simpleRequest(): AIConversationRequest
+    {
+        return new AIConversationRequest(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            'AskMatomo'
+        );
+    }
+}
+
+/**
+ * Records the wire request instead of performing HTTP and returns a canned
+ * decoded response.
+ */
+class RecordingCustomProvider extends CustomProvider
+{
+    /** @var string|null */
+    public $sentUrl = null;
+
+    /** @var array<string, string> */
+    public $sentHeaders = [];
+
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    /** @var int|null */
+    public $sentTimeoutSeconds = null;
+
+    /** @var array<string, mixed> */
+    public $cannedResponse = [
+        'choices' => [['message' => ['role' => 'assistant', 'content' => 'Hi there.'], 'finish_reason' => 'stop']],
+        'usage' => ['prompt_tokens' => 3, 'completion_tokens' => 4],
+    ];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentUrl = $url;
+        $this->sentHeaders = $headers;
+        $this->sentPayload = $payload;
+        $this->sentTimeoutSeconds = $timeoutSeconds;
+
+        return $this->cannedResponse;
+    }
+}
diff --git a/tests/Unit/GeminiConverseTest.php b/tests/Unit/GeminiConverseTest.php
new file mode 100644
index 0000000..6c8959c
--- /dev/null
+++ b/tests/Unit/GeminiConverseTest.php
@@ -0,0 +1,529 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\Provider\Gemini;
+
+/**
+ * Tests the full converse() translation between the canonical message shape
+ * and the Gemini generateContent API wire format, with HTTP replaced by a
+ * recording sendJsonRequest() override.
+ *
+ * @group AIProviders
+ * @group Plugins
+ */
+class GeminiConverseTest extends TestCase
+{
+    private const CONFIGURATION = ['apiKey' => 'secret-gemini-key', 'endpointUrl' => ''];
+
+    public function testPayloadUsesDefaultModelEndpointHeadersAndRequestDefaults(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertStringContainsString('gemini-2.5-flash', $gemini->sentUrl);
+        $this->assertStringContainsString(':generateContent', $gemini->sentUrl);
+        $this->assertSame(['x-goog-api-key' => 'secret-gemini-key'], $gemini->sentHeaders);
+        $this->assertSame(
+            AIConversationRequest::DEFAULT_MAX_TOKENS,
+            $gemini->sentPayload['generationConfig']['maxOutputTokens']
+        );
+        $this->assertSame(
+            AIRequest::DEFAULT_TEMPERATURE,
+            $gemini->sentPayload['generationConfig']['temperature']
+        );
+        $this->assertSame(AIConversationRequest::DEFAULT_TIMEOUT_SECONDS, $gemini->sentTimeoutSeconds);
+        // No system prompt was set, so the payload carries no systemInstruction.
+        $this->assertArrayNotHasKey('systemInstruction', $gemini->sentPayload);
+        $this->assertSame(
+            [['role' => 'user', 'parts' => [['text' => 'Hello']]]],
+            $gemini->sentPayload['contents']
+        );
+    }
+
+    public function testPayloadHonoursRequestedModelOptionsSystemPromptAndTimeout(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = $this->simpleRequest()
+            ->withModel('gemini-2.5-pro')
+            ->withSystemPrompt('You are concise.')
+            ->withMaxTokens(512)
+            ->withTemperature(0.9)
+            ->withTimeoutSeconds(120);
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $this->assertStringContainsString('gemini-2.5-pro', $gemini->sentUrl);
+        $this->assertSame(
+            ['parts' => [['text' => 'You are concise.']]],
+            $gemini->sentPayload['systemInstruction']
+        );
+        $this->assertSame(512, $gemini->sentPayload['generationConfig']['maxOutputTokens']);
+        $this->assertSame(0.9, $gemini->sentPayload['generationConfig']['temperature']);
+        $this->assertSame(120, $gemini->sentTimeoutSeconds);
+    }
+
+    public function testMessagesTranslateToGeminiRolesAndParts(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = new AIConversationRequest(
+            [
+                ['role' => 'user', 'content' => [['type' => 'text', 'text' => 'delete site 1']]],
+                [
+                    'role' => 'assistant',
+                    'content' => [
+                        ['type' => 'text', 'text' => 'Deleting it now.'],
+                        ['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'del', 'input' => []],
+                    ],
+                ],
+                [
+                    'role' => 'tool',
+                    'content' => [[
+                        'type' => 'tool_result',
+                        'tool_use_id' => 'tu_1',
+                        'content' => [['type' => 'text', 'text' => 'deleted']],
+                        'structuredContent' => null,
+                        'is_error' => false,
+                    ]],
+                ],
+            ],
+            'AskMatomo'
+        );
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $contents = $gemini->sentPayload['contents'];
+
+        $this->assertCount(3, $contents);
+        // Canonical 'assistant' becomes Gemini 'model'; the 'tool' result folds
+        // into a 'user' message carrying a functionResponse part.
+        $this->assertSame(['user', 'model', 'user'], array_column($contents, 'role'));
+
+        $this->assertSame([['text' => 'delete site 1']], $contents[0]['parts']);
+
+        $this->assertSame(['text' => 'Deleting it now.'], $contents[1]['parts'][0]);
+        $this->assertSame('del', $contents[1]['parts'][1]['functionCall']['name']);
+
+        // Empty tool_use input must encode as a JSON object, not an array.
+        $this->assertStringContainsString('"args":{}', (string) json_encode($gemini->sentPayload));
+
+        // The tool_result resolves its function name from the prior tool_use.
+        $this->assertSame(
+            [[
+                'functionResponse' => [
+                    'name' => 'del',
+                    'response' => ['content' => 'deleted'],
+                ],
+            ]],
+            $contents[2]['parts']
+        );
+    }
+
+    public function testNonEmptyToolUseInputIsForwardedAsArgs(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'assistant',
+                'content' => [['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'del', 'input' => ['idSite' => 1]]],
+            ]],
+            'AskMatomo'
+        );
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            ['idSite' => 1],
+            $gemini->sentPayload['contents'][0]['parts'][0]['functionCall']['args']
+        );
+    }
+
+    public function testToolResultNameFallsBackToUnknownWhenUnresolvable(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_missing',
+                    'content' => [['type' => 'text', 'text' => 'done']],
+                    'structuredContent' => null,
+                    'is_error' => false,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            'unknown',
+            $gemini->sentPayload['contents'][0]['parts'][0]['functionResponse']['name']
+        );
+    }
+
+    public function testToolResultStructuredContentBecomesResponseObject(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_1',
+                    'content' => [['type' => 'text', 'text' => '{"sites":[{"idsite":1}]}']],
+                    'structuredContent' => ['sites' => [['idsite' => 1]]],
+                    'is_error' => false,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        // structuredContent is used verbatim as the response object.
+        $this->assertSame(
+            ['sites' => [['idsite' => 1]]],
+            $gemini->sentPayload['contents'][0]['parts'][0]['functionResponse']['response']
+        );
+    }
+
+    public function testToolResultMcpTextFallbackIsWrappedInObjectAndErrorReflected(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_1',
+                    'content' => [
+                        ['type' => 'text', 'text' => 'plain text payload'],
+                        ['type' => 'resource_link', 'uri' => 'https://example.org/report'],
+                    ],
+                    'structuredContent' => null,
+                    'is_error' => true,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [
+                'content' => "plain text payload\n{\"type\":\"resource_link\",\"uri\":\"https:\/\/example.org\/report\"}",
+                'error' => true,
+            ],
+            $gemini->sentPayload['contents'][0]['parts'][0]['functionResponse']['response']
+        );
+    }
+
+    public function testToolsAreOmittedWhenCatalogueIsEmpty(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertArrayNotHasKey('tools', $gemini->sentPayload);
+    }
+
+    public function testToolCatalogueTranslatesToFunctionDeclarationsWithoutMcpHints(): void
+    {
+        $gemini = new RecordingGemini();
+
+        $request = $this->simpleRequest()->withTools([
+            [
+                'name' => 'matomo_site_list',
+                'title' => null,
+                'description' => 'Lists sites',
+                'inputSchema' => ['type' => 'object', 'properties' => ['idSite' => ['type' => 'integer']]],
+                'outputSchema' => null,
+                'readOnly' => true,
+                'destructive' => false,
+                'idempotent' => true,
+                'openWorld' => null,
+            ],
+        ]);
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [[
+                'functionDeclarations' => [[
+                    'name' => 'matomo_site_list',
+                    'description' => 'Lists sites',
+                    'parameters' => ['type' => 'object', 'properties' => ['idSite' => ['type' => 'integer']]],
+                ]],
+            ]],
+            $gemini->sentPayload['tools']
+        );
+        // The MCP annotation hints must not reach the provider.
+        $this->assertSame(
+            ['name', 'description', 'parameters'],
+            array_keys($gemini->sentPayload['tools'][0]['functionDeclarations'][0])
+        );
+    }
+
+    public function testToolSchemaUnsupportedKeywordsAreStrippedForGemini(): void
+    {
+        // Gemini's function declaration schema accepts only a restricted subset
+        // of OpenAPI 3.0 and rejects standard JSON Schema keywords such as
+        // top-level oneOf/anyOf/allOf/not/enum/const AND additionalProperties at
+        // every nesting depth (the real API errors on
+        // parameters.properties[...].additionalProperties). They are
+        // validation-only constraints re-checked by the tool server on call, so
+        // they are dropped rather than failing the turn.
+        $gemini = new RecordingGemini();
+
+        $request = $this->simpleRequest()->withTools([
+            [
+                'name' => 'matomo_api_call_create',
+                'title' => null,
+                'description' => 'Creates an API call',
+                'inputSchema' => [
+                    '$schema' => 'http://json-schema.org/draft-07/schema#',
+                    'type' => 'object',
+                    'properties' => [
+                        'method' => ['type' => 'string'],
+                        'filter' => [
+                            'type' => 'object',
+                            'properties' => ['name' => ['type' => 'string']],
+                            'additionalProperties' => false,
+                        ],
+                    ],
+                    'not' => ['anyOf' => [['required' => ['method']]]],
+                    'additionalProperties' => false,
+                ],
+                'outputSchema' => null,
+                'readOnly' => false,
+                'destructive' => false,
+                'idempotent' => false,
+                'openWorld' => null,
+            ],
+        ]);
+
+        $gemini->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [
+                'type' => 'object',
+                'properties' => [
+                    'method' => ['type' => 'string'],
+                    'filter' => [
+                        'type' => 'object',
+                        'properties' => ['name' => ['type' => 'string']],
+                    ],
+                ],
+            ],
+            $gemini->sentPayload['tools'][0]['functionDeclarations'][0]['parameters']
+        );
+    }
+
+    public function testResponsePartsAreParsedIntoCanonicalBlocks(): void
+    {
+        $gemini = new RecordingGemini();
+        $gemini->cannedResponse = [
+            'candidates' => [[
+                'content' => [
+                    'parts' => [
+                        ['text' => 'Checking your sites now.'],
+                        ['functionCall' => ['name' => 'matomo_site_list', 'args' => ['idSite' => 1]]],
+                    ],
+                ],
+                'finishReason' => 'STOP',
+            ]],
+            'usageMetadata' => ['promptTokenCount' => 12, 'candidatesTokenCount' => 7],
+        ];
+
+        $response = $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $content = $response->getContent();
+
+        $this->assertSame(['type' => 'text', 'text' => 'Checking your sites now.'], $content[0]);
+        $this->assertSame('tool_use', $content[1]['type']);
+        $this->assertSame('matomo_site_list', $content[1]['name']);
+        $this->assertSame(['idSite' => 1], $content[1]['input']);
+        // The synthesized id is present and non-empty.
+        $this->assertNotSame('', $content[1]['id']);
+        $this->assertIsString($content[1]['id']);
+
+        // A functionCall forces tool_use even though finishReason was STOP.
+        $this->assertSame('tool_use', $response->getStopReason());
+        $this->assertSame(12, $response->getInputTokens());
+        $this->assertSame(7, $response->getOutputTokens());
+        $this->assertSame('gemini', $response->getProviderId());
+        $this->assertSame('gemini-2.5-flash-lite', $response->getModel());
+    }
+
+    public function testSynthesizedIdResolvesBackToFunctionNameOnFollowUpTurn(): void
+    {
+        $gemini = new RecordingGemini();
+        $gemini->cannedResponse = [
+            'candidates' => [[
+                'content' => ['parts' => [
+                    ['functionCall' => ['name' => 'matomo_site_list', 'args' => ['idSite' => 1]]],
+                ]],
+                'finishReason' => 'STOP',
+            ]],
+        ];
+
+        $first = $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+        $synthesizedId = $first->getContent()[0]['id'];
+
+        // Feed the assistant tool_use plus a matching tool_result back in.
+        $followUp = new AIConversationRequest(
+            [
+                ['role' => 'assistant', 'content' => $first->getContent()],
+                ['role' => 'tool', 'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => $synthesizedId,
+                    'content' => [['type' => 'text', 'text' => 'ok']],
+                    'structuredContent' => null,
+                    'is_error' => false,
+                ]]],
+            ],
+            'AskMatomo'
+        );
+
+        $gemini->converse($followUp, self::CONFIGURATION);
+
+        // The result correlates back to the original function name.
+        $this->assertSame(
+            'matomo_site_list',
+            $gemini->sentPayload['contents'][1]['parts'][0]['functionResponse']['name']
+        );
+    }
+
+    public function testFinishReasonStopWithoutCallsYieldsEndTurn(): void
+    {
+        $gemini = new RecordingGemini();
+        $gemini->cannedResponse = [
+            'candidates' => [[
+                'content' => ['parts' => [['text' => 'All done.']]],
+                'finishReason' => 'STOP',
+            ]],
+        ];
+
+        $response = $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('end_turn', $response->getStopReason());
+    }
+
+    public function testFinishReasonMaxTokensMapsToMaxTokens(): void
+    {
+        $gemini = new RecordingGemini();
+        $gemini->cannedResponse = [
+            'candidates' => [[
+                'content' => ['parts' => [['text' => 'Truncated']]],
+                'finishReason' => 'MAX_TOKENS',
+            ]],
+        ];
+
+        $response = $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('max_tokens', $response->getStopReason());
+    }
+
+    public function testUnknownFinishReasonPassesThrough(): void
+    {
+        $gemini = new RecordingGemini();
+        $gemini->cannedResponse = [
+            'candidates' => [[
+                'content' => ['parts' => [['text' => 'Hi.']]],
+                'finishReason' => 'OTHER',
+            ]],
+        ];
+
+        $response = $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('OTHER', $response->getStopReason());
+    }
+
+    public function testMissingUsageYieldsNullTokenCounts(): void
+    {
+        $gemini = new RecordingGemini();
+        $gemini->cannedResponse = [
+            'candidates' => [[
+                'content' => ['parts' => [['text' => 'Hi.']]],
+                'finishReason' => 'STOP',
+            ]],
+        ];
+
+        $response = $gemini->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertNull($response->getInputTokens());
+        $this->assertNull($response->getOutputTokens());
+    }
+
+    public function testGeminiSupportsConversations(): void
+    {
+        $this->assertTrue((new Gemini())->supportsConversations());
+    }
+
+    private function simpleRequest(): AIConversationRequest
+    {
+        return new AIConversationRequest(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            'AskMatomo'
+        );
+    }
+}
+
+/**
+ * Records the wire request instead of performing HTTP and returns a canned
+ * decoded response.
+ */
+class RecordingGemini extends Gemini
+{
+    /** @var string|null */
+    public $sentUrl = null;
+
+    /** @var array<string, string> */
+    public $sentHeaders = [];
+
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    /** @var int|null */
+    public $sentTimeoutSeconds = null;
+
+    /** @var array<string, mixed> */
+    public $cannedResponse = [
+        'candidates' => [[
+            'content' => ['parts' => [['text' => 'Hi there.']]],
+            'finishReason' => 'STOP',
+        ]],
+        'usageMetadata' => ['promptTokenCount' => 3, 'candidatesTokenCount' => 4],
+    ];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentUrl = $url;
+        $this->sentHeaders = $headers;
+        $this->sentPayload = $payload;
+        $this->sentTimeoutSeconds = $timeoutSeconds;
+
+        return $this->cannedResponse;
+    }
+}
diff --git a/tests/Unit/OpenAIConverseTest.php b/tests/Unit/OpenAIConverseTest.php
new file mode 100644
index 0000000..2d754fc
--- /dev/null
+++ b/tests/Unit/OpenAIConverseTest.php
@@ -0,0 +1,485 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\AIProviders\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\AIProviders\AIConversationRequest;
+use Piwik\Plugins\AIProviders\AIRequest;
+use Piwik\Plugins\AIProviders\Provider\OpenAI;
+
+/**
+ * Tests the full converse() translation between the canonical message shape
+ * and the OpenAI Chat Completions API wire format, with HTTP replaced by a
+ * recording sendJsonRequest() override.
+ *
+ * @group AIProviders
+ * @group Plugins
+ */
+class OpenAIConverseTest extends TestCase
+{
+    private const CONFIGURATION = ['apiKey' => 'secret-openai-key', 'endpointUrl' => ''];
+
+    public function testPayloadUsesDefaultModelEndpointHeadersAndRequestDefaults(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('https://api.openai.com/v1/chat/completions', $openAI->sentUrl);
+        $this->assertSame(['Authorization' => 'Bearer secret-openai-key'], $openAI->sentHeaders);
+        $this->assertSame('gpt-5.4-mini', $openAI->sentPayload['model']);
+        $this->assertSame(AIConversationRequest::DEFAULT_MAX_TOKENS, $openAI->sentPayload['max_completion_tokens']);
+        $this->assertArrayNotHasKey('max_tokens', $openAI->sentPayload);
+        $this->assertArrayNotHasKey('temperature', $openAI->sentPayload);
+        $this->assertSame(AIConversationRequest::DEFAULT_TIMEOUT_SECONDS, $openAI->sentTimeoutSeconds);
+        // No system prompt was set, so the messages start with the user turn.
+        $this->assertSame(
+            [['role' => 'user', 'content' => 'Hello']],
+            $openAI->sentPayload['messages']
+        );
+    }
+
+    public function testPayloadHonoursRequestedModelOptionsSystemPromptAndTimeout(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $request = $this->simpleRequest()
+            ->withModel('gpt-4o')
+            ->withSystemPrompt('You are concise.')
+            ->withMaxTokens(512)
+            ->withTemperature(0.9)
+            ->withTimeoutSeconds(120);
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $this->assertSame('gpt-4o', $openAI->sentPayload['model']);
+        $this->assertSame(512, $openAI->sentPayload['max_completion_tokens']);
+        $this->assertArrayNotHasKey('temperature', $openAI->sentPayload);
+        $this->assertSame(120, $openAI->sentTimeoutSeconds);
+        // The system prompt is prepended as the first message.
+        $this->assertSame(
+            ['role' => 'system', 'content' => 'You are concise.'],
+            $openAI->sentPayload['messages'][0]
+        );
+    }
+
+    public function testSystemMessageOmittedWhenNotSet(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertNotSame('system', $openAI->sentPayload['messages'][0]['role']);
+    }
+
+    public function testAssistantTextAndToolCallsTranslateWithJsonStringArguments(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $request = new AIConversationRequest(
+            [
+                ['role' => 'user', 'content' => [['type' => 'text', 'text' => 'delete site 1']]],
+                [
+                    'role' => 'assistant',
+                    'content' => [
+                        ['type' => 'text', 'text' => 'Deleting it now.'],
+                        ['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'del', 'input' => ['idSite' => 1]],
+                        ['type' => 'tool_use', 'id' => 'tu_2', 'name' => 'noop', 'input' => []],
+                    ],
+                ],
+            ],
+            'AskMatomo'
+        );
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $messages = $openAI->sentPayload['messages'];
+
+        $this->assertSame('user', $messages[0]['role']);
+        $this->assertSame('delete site 1', $messages[0]['content']);
+
+        $assistant = $messages[1];
+        $this->assertSame('assistant', $assistant['role']);
+        $this->assertSame('Deleting it now.', $assistant['content']);
+
+        // arguments must be a JSON string, and empty input encodes as '{}'.
+        $this->assertSame(
+            [
+                [
+                    'id' => 'tu_1',
+                    'type' => 'function',
+                    'function' => ['name' => 'del', 'arguments' => '{"idSite":1}'],
+                ],
+                [
+                    'id' => 'tu_2',
+                    'type' => 'function',
+                    'function' => ['name' => 'noop', 'arguments' => '{}'],
+                ],
+            ],
+            $assistant['tool_calls']
+        );
+        $this->assertIsString($assistant['tool_calls'][0]['function']['arguments']);
+    }
+
+    public function testAssistantWithNoTextEmitsEmptyStringContent(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'assistant',
+                'content' => [['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'del', 'input' => []]],
+            ]],
+            'AskMatomo'
+        );
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $assistant = $openAI->sentPayload['messages'][0];
+        $this->assertSame('', $assistant['content']);
+        $this->assertArrayHasKey('tool_calls', $assistant);
+    }
+
+    public function testToolMessageWithTwoResultsExpandsIntoTwoToolMessages(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [
+                    [
+                        'type' => 'tool_result',
+                        'tool_use_id' => 'tu_1',
+                        'content' => [['type' => 'text', 'text' => '{"sites":[{"idsite":1}]}']],
+                        'structuredContent' => ['sites' => [['idsite' => 1]]],
+                        'is_error' => false,
+                    ],
+                    [
+                        'type' => 'tool_result',
+                        'tool_use_id' => 'tu_2',
+                        'content' => [
+                            ['type' => 'text', 'text' => 'plain text payload'],
+                            ['type' => 'resource_link', 'uri' => 'https://example.org/report'],
+                        ],
+                        'structuredContent' => null,
+                        'is_error' => false,
+                    ],
+                ],
+            ]],
+            'AskMatomo'
+        );
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $messages = $openAI->sentPayload['messages'];
+
+        $this->assertCount(2, $messages);
+        // structuredContent wins over the MCP text echo and is serialised.
+        $this->assertSame(
+            ['role' => 'tool', 'tool_call_id' => 'tu_1', 'content' => '{"sites":[{"idsite":1}]}'],
+            $messages[0]
+        );
+        // MCP text fallback: text blocks concatenated, non-text JSON-encoded.
+        $this->assertSame(
+            [
+                'role' => 'tool',
+                'tool_call_id' => 'tu_2',
+                'content' => "plain text payload\n" . '{"type":"resource_link","uri":"https:\/\/example.org\/report"}',
+            ],
+            $messages[1]
+        );
+    }
+
+    public function testEmptyToolResultContentBecomesEmptyString(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $request = new AIConversationRequest(
+            [[
+                'role' => 'tool',
+                'content' => [[
+                    'type' => 'tool_result',
+                    'tool_use_id' => 'tu_1',
+                    'content' => [],
+                    'structuredContent' => null,
+                    'is_error' => true,
+                ]],
+            ]],
+            'AskMatomo'
+        );
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            ['role' => 'tool', 'tool_call_id' => 'tu_1', 'content' => ''],
+            $openAI->sentPayload['messages'][0]
+        );
+    }
+
+    public function testToolsAreOmittedWhenCatalogueIsEmpty(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertArrayNotHasKey('tools', $openAI->sentPayload);
+    }
+
+    public function testToolCatalogueTranslatesToOpenAIToolsWithoutMcpHints(): void
+    {
+        $openAI = new RecordingOpenAI();
+
+        $request = $this->simpleRequest()->withTools([
+            [
+                'name' => 'matomo_site_list',
+                'title' => null,
+                'description' => 'Lists sites',
+                'inputSchema' => ['type' => 'object', 'properties' => ['idSite' => ['type' => 'integer']]],
+                'outputSchema' => null,
+                'readOnly' => true,
+                'destructive' => false,
+                'idempotent' => true,
+                'openWorld' => null,
+            ],
+        ]);
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [[
+                'type' => 'function',
+                'function' => [
+                    'name' => 'matomo_site_list',
+                    'description' => 'Lists sites',
+                    'parameters' => ['type' => 'object', 'properties' => ['idSite' => ['type' => 'integer']]],
+                ],
+            ]],
+            $openAI->sentPayload['tools']
+        );
+        // The MCP annotation hints must not reach the provider.
+        $this->assertSame(
+            ['name', 'description', 'parameters'],
+            array_keys($openAI->sentPayload['tools'][0]['function'])
+        );
+    }
+
+    public function testToolSchemaTopLevelConstraintsAreStrippedForOpenAI(): void
+    {
+        // OpenAI rejects top-level oneOf/anyOf/allOf/not/enum/const and requires
+        // a top-level object type. These are validation-only constraints (the
+        // tool server re-validates on call), so they are dropped rather than
+        // failing the whole turn.
+        $openAI = new RecordingOpenAI();
+
+        $request = $this->simpleRequest()->withTools([
+            [
+                'name' => 'matomo_api_call_create',
+                'title' => null,
+                'description' => 'Creates an API call',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => ['method' => ['type' => 'string']],
+                    'not' => ['anyOf' => [['required' => ['method']]]],
+                    'additionalProperties' => false,
+                ],
+                'outputSchema' => null,
+                'readOnly' => false,
+                'destructive' => false,
+                'idempotent' => false,
+                'openWorld' => null,
+            ],
+        ]);
+
+        $openAI->converse($request, self::CONFIGURATION);
+
+        $this->assertSame(
+            [
+                'type' => 'object',
+                'properties' => ['method' => ['type' => 'string']],
+                'additionalProperties' => false,
+            ],
+            $openAI->sentPayload['tools'][0]['function']['parameters']
+        );
+    }
+
+    public function testResponseTextAndToolCallsAreParsedIntoCanonicalBlocks(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [[
+                'message' => [
+                    'role' => 'assistant',
+                    'content' => 'Checking your sites now.',
+                    'tool_calls' => [[
+                        'id' => 'tu_42',
+                        'type' => 'function',
+                        'function' => ['name' => 'matomo_site_list', 'arguments' => '{"idSite":1}'],
+                    ]],
+                ],
+                'finish_reason' => 'tool_calls',
+            ]],
+            'usage' => ['prompt_tokens' => 12, 'completion_tokens' => 7],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame(
+            [
+                ['type' => 'text', 'text' => 'Checking your sites now.'],
+                ['type' => 'tool_use', 'id' => 'tu_42', 'name' => 'matomo_site_list', 'input' => ['idSite' => 1]],
+            ],
+            $response->getContent()
+        );
+        $this->assertSame('tool_use', $response->getStopReason());
+        $this->assertSame(12, $response->getInputTokens());
+        $this->assertSame(7, $response->getOutputTokens());
+        $this->assertSame('openai', $response->getProviderId());
+        $this->assertSame('OpenAI', $response->getProviderName());
+        $this->assertSame('gpt-5.4-mini', $response->getModel());
+    }
+
+    public function testBlankToolCallArgumentsDecodeToEmptyInput(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [[
+                'message' => [
+                    'role' => 'assistant',
+                    'content' => null,
+                    'tool_calls' => [[
+                        'id' => 'tu_1',
+                        'type' => 'function',
+                        'function' => ['name' => 'noop', 'arguments' => ''],
+                    ]],
+                ],
+                'finish_reason' => 'tool_calls',
+            ]],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame(
+            [['type' => 'tool_use', 'id' => 'tu_1', 'name' => 'noop', 'input' => []]],
+            $response->getContent()
+        );
+    }
+
+    public function testFinishReasonStopMapsToEndTurn(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [['message' => ['content' => 'Done.'], 'finish_reason' => 'stop']],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('end_turn', $response->getStopReason());
+    }
+
+    public function testFinishReasonLengthMapsToMaxTokens(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [['message' => ['content' => 'Trunc'], 'finish_reason' => 'length']],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('max_tokens', $response->getStopReason());
+    }
+
+    public function testUnknownFinishReasonPassesThrough(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [['message' => ['content' => 'Hi.'], 'finish_reason' => 'function_call']],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('function_call', $response->getStopReason());
+    }
+
+    public function testFinishReasonContentFilterMapsToGuardrail(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [['message' => ['content' => 'Blocked.'], 'finish_reason' => 'content_filter']],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertSame('guardrail_intervened', $response->getStopReason());
+    }
+
+    public function testMissingUsageYieldsNullTokenCounts(): void
+    {
+        $openAI = new RecordingOpenAI();
+        $openAI->cannedResponse = [
+            'choices' => [['message' => ['content' => 'Hi.'], 'finish_reason' => 'stop']],
+        ];
+
+        $response = $openAI->converse($this->simpleRequest(), self::CONFIGURATION);
+
+        $this->assertNull($response->getInputTokens());
+        $this->assertNull($response->getOutputTokens());
+    }
+
+    public function testOpenAISupportsConversations(): void
+    {
+        $this->assertTrue((new OpenAI())->supportsConversations());
+    }
+
+    private function simpleRequest(): AIConversationRequest
+    {
+        return new AIConversationRequest(
+            [['role' => 'user', 'content' => [['type' => 'text', 'text' => 'Hello']]]],
+            'AskMatomo'
+        );
+    }
+}
+
+/**
+ * Records the wire request instead of performing HTTP and returns a canned
+ * decoded response.
+ */
+class RecordingOpenAI extends OpenAI
+{
+    /** @var string|null */
+    public $sentUrl = null;
+
+    /** @var array<string, string> */
+    public $sentHeaders = [];
+
+    /** @var array<string, mixed> */
+    public $sentPayload = [];
+
+    /** @var int|null */
+    public $sentTimeoutSeconds = null;
+
+    /** @var array<string, mixed> */
+    public $cannedResponse = [
+        'choices' => [['message' => ['role' => 'assistant', 'content' => 'Hi there.'], 'finish_reason' => 'stop']],
+        'usage' => ['prompt_tokens' => 3, 'completion_tokens' => 4],
+    ];
+
+    protected function sendJsonRequest(string $url, array $headers, array $payload, int $timeoutSeconds = 30): array
+    {
+        $this->sentUrl = $url;
+        $this->sentHeaders = $headers;
+        $this->sentPayload = $payload;
+        $this->sentTimeoutSeconds = $timeoutSeconds;
+
+        return $this->cannedResponse;
+    }
+}
diff --git a/vue/dist/AIProviders.css b/vue/dist/AIProviders.css
new file mode 100644
index 0000000..fcfd7a0
--- /dev/null
+++ b/vue/dist/AIProviders.css
@@ -0,0 +1 @@
+.ai-providers-card{position:relative;display:flex;flex-direction:column;overflow:hidden;background:var(--theme-color-background-contrast);border:1px solid var(--ai-providers-border);border-radius:6px;cursor:pointer;transition:border-color .12s ease}.ai-providers-card:hover:not(.is-not-usable):not(.is-selected){border-color:var(--ai-providers-border-strong)}.ai-providers-card.is-selected{background:var(--ai-providers-accent);border-color:var(--ai-providers-accent);margin-top:-24px}.ai-providers-card.is-not-usable{cursor:default}.ai-providers-card:active,.ai-providers-card:focus,.ai-providers-card:focus-visible{outline:none;box-shadow:none}.ai-providers-card .form-group{margin-bottom:12px;border:0}.ai-providers-card .input-field{margin-top:0;margin-bottom:0}.ai-providers-card .matomo-form-field{border:0;margin-left:0;margin-right:0;margin-top:32px}.ai-providers-card .matomo-form-field>.col{padding-left:0!important;padding-right:0!important}.ai-providers-card .input-field.col>label,.ai-providers-card .input-field>label,.ai-providers-card .matomo-field-select>.select-wrapper+label,.ai-providers-card .matomo-field-select>label{left:0!important}.ai-providers-card .input-field>input{padding-left:0;margin-left:0;width:100%;box-sizing:border-box}.ai-providers-card-inner{display:flex;flex-direction:column;flex:1;padding:16px}.ai-providers-card.is-selected .ai-providers-card-inner{background:var(--theme-color-background-contrast);border-radius:6px 6px 5px 5px;margin:0 1px 1px}.ai-providers-card-default{min-height:24px;padding:5px 12px;background-color:var(--ai-providers-accent);color:var(--theme-color-brand-contrast);font-size:10px;font-weight:700;line-height:1.5;text-transform:uppercase}.ai-providers-card-header{display:flex;align-items:center;gap:12px;margin-bottom:8px}.ai-providers-card-name{color:var(--ai-providers-heading);font-weight:600;font-size:15px}.ai-providers-card-description{color:var(--ai-providers-text-muted);font-size:13px;line-height:1.5;margin:0 0 16px}.ai-providers-refresh-models{display:inline-flex;align-items:center;gap:6px;margin-top:4px;padding:0;font-size:12px}.ai-providers-refresh-models[disabled]{pointer-events:none;cursor:not-allowed;color:var(--theme-color-text-on-disabled)}.ai-providers-refresh-models .icon-reload{font-size:12px}.ai-providers-card-model-help{color:var(--ai-providers-text-muted);font-size:12px;line-height:1.5;margin:0}.ai-providers-card-status{display:flex;align-items:center;gap:8px;margin:4px 0 0;color:var(--ai-providers-text-muted);font-size:13px;line-height:1.5}.ai-providers-card-status.is-connected,.ai-providers-card-status.is-connected .ai-providers-status-icon{color:var(--ai-providers-accent)}.ai-providers-status-icon{font-size:14px;line-height:1;color:var(--ai-providers-border-strong);flex:none}.ai-providers-card-actions{display:flex;flex-direction:column;align-items:stretch;justify-content:flex-start;gap:12px;margin-top:auto;padding-top:16px}.ai-providers-card-actions .btn,.ai-providers-card-actions .btn-flat{white-space:nowrap}.ai-providers-card-actions .btn-flat[disabled]{pointer-events:none;cursor:not-allowed;color:var(--theme-color-text-on-disabled)}.ai-providers-page{position:relative;--ai-providers-border:var(--theme-color-border-light);--ai-providers-border-strong:var(--theme-color-border);--ai-providers-accent:var(--theme-color-brand);--ai-providers-text-muted:var(--theme-color-text-light);--ai-providers-heading:var(--theme-color-headline-alternative)}.ai-providers-page h2,.ai-providers-page h3,.ai-providers-page h4{color:var(--ai-providers-heading);margin:0;padding:0}.ai-providers-page-header{margin-bottom:24px}.ai-providers-page-title{font-size:22px;line-height:1.3}.ai-providers-page-subtitle{color:var(--ai-providers-text-muted);font-size:14px;line-height:1.5;margin:4px 0 0}.ai-providers-defaults-title{font-size:18px;line-height:1.4;margin-bottom:24px!important}.ai-providers-subsection-title{font-size:15px;font-weight:600;line-height:1.4}.ai-providers-section+.ai-providers-section{margin-top:24px;padding-top:24px;border-top:1px solid var(--ai-providers-border)}.ai-providers-section-help{color:var(--ai-providers-text-muted);margin:4px 0 16px}.ai-providers-capability-cards,.ai-providers-cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:16px}.ai-providers-cards{padding-top:24px;margin-top:32px}.ai-providers-default-warning{margin-top:16px}.ai-providers-capability-card{display:flex;flex-direction:column;padding:16px;background:var(--theme-color-background-contrast);border:1px solid var(--ai-providers-border);border-radius:6px;cursor:pointer;transition:border-color .12s ease,box-shadow .12s ease,background-color .12s ease}.ai-providers-capability-card:hover{border-color:var(--ai-providers-border-strong)}.ai-providers-capability-card.is-selected{border-color:var(--ai-providers-accent);box-shadow:0 0 0 1px var(--ai-providers-accent) inset;background:var(--theme-color-background-tinyContrast)}.ai-providers-capability-header{margin-bottom:8px}.ai-providers-capability-label{color:var(--ai-providers-heading);font-weight:600;font-size:15px}.ai-providers-capability-description{color:var(--ai-providers-text-muted);font-size:13px;line-height:1.5}.ai-providers-content{position:relative}.ai-providers-unsaved-changes{position:absolute;top:16px;right:16px;display:inline-flex;align-items:center;gap:6px;color:var(--ai-providers-text-muted);font-size:12px;font-style:italic;visibility:hidden;opacity:0;transition:opacity .15s ease}.ai-providers-unsaved-changes:before{content:"";width:6px;height:6px;border-radius:50%;background:var(--ai-providers-accent)}.ai-providers-unsaved-changes.is-visible{visibility:visible;opacity:1}.ai-providers-footer{display:flex;flex-wrap:wrap;justify-content:flex-end;align-items:center;gap:12px;margin-top:24px}.ai-providers-cancel{background:transparent;color:var(--theme-color-text);border:1px solid var(--ai-providers-border-strong);box-shadow:none;transition:background-color .15s ease,border-color .15s ease}.ai-providers-cancel:focus,.ai-providers-cancel:hover{background:var(--theme-color-background-tinyContrast);border-color:var(--theme-color-text-light);color:var(--theme-color-text)}.ai-providers-cancel:disabled{opacity:.45;cursor:not-allowed;background:transparent;border-color:var(--ai-providers-border)}
\ No newline at end of file
diff --git a/vue/dist/AIProviders.umd.js b/vue/dist/AIProviders.umd.js
new file mode 100644
index 0000000..e25ffd5
--- /dev/null
+++ b/vue/dist/AIProviders.umd.js
@@ -0,0 +1,784 @@
+(function webpackUniversalModuleDefinition(root, factory) {
+	if(typeof exports === 'object' && typeof module === 'object')
+		module.exports = factory(require("CoreHome"), require("vue"), require("CorePluginsAdmin"));
+	else if(typeof define === 'function' && define.amd)
+		define(["CoreHome", , "CorePluginsAdmin"], factory);
+	else if(typeof exports === 'object')
+		exports["AIProviders"] = factory(require("CoreHome"), require("vue"), require("CorePluginsAdmin"));
+	else
+		root["AIProviders"] = factory(root["CoreHome"], root["Vue"], root["CorePluginsAdmin"]);
+})((typeof self !== 'undefined' ? self : this), function(__WEBPACK_EXTERNAL_MODULE__19dc__, __WEBPACK_EXTERNAL_MODULE__8bbf__, __WEBPACK_EXTERNAL_MODULE_a5a2__) {
+return /******/ (function(modules) { // webpackBootstrap
+/******/ 	// The module cache
+/******/ 	var installedModules = {};
+/******/
+/******/ 	// The require function
+/******/ 	function __webpack_require__(moduleId) {
+/******/
+/******/ 		// Check if module is in cache
+/******/ 		if(installedModules[moduleId]) {
+/******/ 			return installedModules[moduleId].exports;
+/******/ 		}
+/******/ 		// Create a new module (and put it into the cache)
+/******/ 		var module = installedModules[moduleId] = {
+/******/ 			i: moduleId,
+/******/ 			l: false,
+/******/ 			exports: {}
+/******/ 		};
+/******/
+/******/ 		// Execute the module function
+/******/ 		modules[moduleId].call(module.exports, module, module.exports, __webpack_require__);
+/******/
+/******/ 		// Flag the module as loaded
+/******/ 		module.l = true;
+/******/
+/******/ 		// Return the exports of the module
+/******/ 		return module.exports;
+/******/ 	}
+/******/
+/******/
+/******/ 	// expose the modules object (__webpack_modules__)
+/******/ 	__webpack_require__.m = modules;
+/******/
+/******/ 	// expose the module cache
+/******/ 	__webpack_require__.c = installedModules;
+/******/
+/******/ 	// define getter function for harmony exports
+/******/ 	__webpack_require__.d = function(exports, name, getter) {
+/******/ 		if(!__webpack_require__.o(exports, name)) {
+/******/ 			Object.defineProperty(exports, name, { enumerable: true, get: getter });
+/******/ 		}
+/******/ 	};
+/******/
+/******/ 	// define __esModule on exports
+/******/ 	__webpack_require__.r = function(exports) {
+/******/ 		if(typeof Symbol !== 'undefined' && Symbol.toStringTag) {
+/******/ 			Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+/******/ 		}
+/******/ 		Object.defineProperty(exports, '__esModule', { value: true });
+/******/ 	};
+/******/
+/******/ 	// create a fake namespace object
+/******/ 	// mode & 1: value is a module id, require it
+/******/ 	// mode & 2: merge all properties of value into the ns
+/******/ 	// mode & 4: return value when already ns object
+/******/ 	// mode & 8|1: behave like require
+/******/ 	__webpack_require__.t = function(value, mode) {
+/******/ 		if(mode & 1) value = __webpack_require__(value);
+/******/ 		if(mode & 8) return value;
+/******/ 		if((mode & 4) && typeof value === 'object' && value && value.__esModule) return value;
+/******/ 		var ns = Object.create(null);
+/******/ 		__webpack_require__.r(ns);
+/******/ 		Object.defineProperty(ns, 'default', { enumerable: true, value: value });
+/******/ 		if(mode & 2 && typeof value != 'string') for(var key in value) __webpack_require__.d(ns, key, function(key) { return value[key]; }.bind(null, key));
+/******/ 		return ns;
+/******/ 	};
+/******/
+/******/ 	// getDefaultExport function for compatibility with non-harmony modules
+/******/ 	__webpack_require__.n = function(module) {
+/******/ 		var getter = module && module.__esModule ?
+/******/ 			function getDefault() { return module['default']; } :
+/******/ 			function getModuleExports() { return module; };
+/******/ 		__webpack_require__.d(getter, 'a', getter);
+/******/ 		return getter;
+/******/ 	};
+/******/
+/******/ 	// Object.prototype.hasOwnProperty.call
+/******/ 	__webpack_require__.o = function(object, property) { return Object.prototype.hasOwnProperty.call(object, property); };
+/******/
+/******/ 	// __webpack_public_path__
+/******/ 	__webpack_require__.p = "plugins/AIProviders/vue/dist/";
+/******/
+/******/
+/******/ 	// Load entry module and return exports
+/******/ 	return __webpack_require__(__webpack_require__.s = "fae3");
+/******/ })
+/************************************************************************/
+/******/ ({
+
+/***/ "19dc":
+/***/ (function(module, exports) {
+
+module.exports = __WEBPACK_EXTERNAL_MODULE__19dc__;
+
+/***/ }),
+
+/***/ "20f9":
+/***/ (function(module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+/* harmony import */ var _node_modules_vue_cli_service_node_modules_mini_css_extract_plugin_dist_loader_js_ref_11_oneOf_1_0_node_modules_vue_cli_service_node_modules_css_loader_dist_cjs_js_ref_11_oneOf_1_1_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_stylePostLoader_js_node_modules_postcss_loader_src_index_js_ref_11_oneOf_1_2_node_modules_less_loader_dist_cjs_js_ref_11_oneOf_1_3_node_modules_vue_cli_service_node_modules_cache_loader_dist_cjs_js_ref_1_0_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_index_js_ref_1_1_ManageAIProviders_vue_vue_type_style_index_0_id_2cc0a4ac_lang_less__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__("bce2");
+/* harmony import */ var _node_modules_vue_cli_service_node_modules_mini_css_extract_plugin_dist_loader_js_ref_11_oneOf_1_0_node_modules_vue_cli_service_node_modules_css_loader_dist_cjs_js_ref_11_oneOf_1_1_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_stylePostLoader_js_node_modules_postcss_loader_src_index_js_ref_11_oneOf_1_2_node_modules_less_loader_dist_cjs_js_ref_11_oneOf_1_3_node_modules_vue_cli_service_node_modules_cache_loader_dist_cjs_js_ref_1_0_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_index_js_ref_1_1_ManageAIProviders_vue_vue_type_style_index_0_id_2cc0a4ac_lang_less__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(_node_modules_vue_cli_service_node_modules_mini_css_extract_plugin_dist_loader_js_ref_11_oneOf_1_0_node_modules_vue_cli_service_node_modules_css_loader_dist_cjs_js_ref_11_oneOf_1_1_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_stylePostLoader_js_node_modules_postcss_loader_src_index_js_ref_11_oneOf_1_2_node_modules_less_loader_dist_cjs_js_ref_11_oneOf_1_3_node_modules_vue_cli_service_node_modules_cache_loader_dist_cjs_js_ref_1_0_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_index_js_ref_1_1_ManageAIProviders_vue_vue_type_style_index_0_id_2cc0a4ac_lang_less__WEBPACK_IMPORTED_MODULE_0__);
+/* unused harmony reexport * */
+
+
+/***/ }),
+
+/***/ "8bbf":
+/***/ (function(module, exports) {
+
+module.exports = __WEBPACK_EXTERNAL_MODULE__8bbf__;
+
+/***/ }),
+
+/***/ "a112":
+/***/ (function(module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+/* harmony import */ var _node_modules_vue_cli_service_node_modules_mini_css_extract_plugin_dist_loader_js_ref_11_oneOf_1_0_node_modules_vue_cli_service_node_modules_css_loader_dist_cjs_js_ref_11_oneOf_1_1_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_stylePostLoader_js_node_modules_postcss_loader_src_index_js_ref_11_oneOf_1_2_node_modules_less_loader_dist_cjs_js_ref_11_oneOf_1_3_node_modules_vue_cli_service_node_modules_cache_loader_dist_cjs_js_ref_1_0_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_index_js_ref_1_1_ProviderCard_vue_vue_type_style_index_0_id_7e6b71a9_lang_less__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__("ecdc");
+/* harmony import */ var _node_modules_vue_cli_service_node_modules_mini_css_extract_plugin_dist_loader_js_ref_11_oneOf_1_0_node_modules_vue_cli_service_node_modules_css_loader_dist_cjs_js_ref_11_oneOf_1_1_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_stylePostLoader_js_node_modules_postcss_loader_src_index_js_ref_11_oneOf_1_2_node_modules_less_loader_dist_cjs_js_ref_11_oneOf_1_3_node_modules_vue_cli_service_node_modules_cache_loader_dist_cjs_js_ref_1_0_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_index_js_ref_1_1_ProviderCard_vue_vue_type_style_index_0_id_7e6b71a9_lang_less__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(_node_modules_vue_cli_service_node_modules_mini_css_extract_plugin_dist_loader_js_ref_11_oneOf_1_0_node_modules_vue_cli_service_node_modules_css_loader_dist_cjs_js_ref_11_oneOf_1_1_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_stylePostLoader_js_node_modules_postcss_loader_src_index_js_ref_11_oneOf_1_2_node_modules_less_loader_dist_cjs_js_ref_11_oneOf_1_3_node_modules_vue_cli_service_node_modules_cache_loader_dist_cjs_js_ref_1_0_node_modules_vue_cli_service_node_modules_vue_loader_v16_dist_index_js_ref_1_1_ProviderCard_vue_vue_type_style_index_0_id_7e6b71a9_lang_less__WEBPACK_IMPORTED_MODULE_0__);
+/* unused harmony reexport * */
+
+
+/***/ }),
+
+/***/ "a5a2":
+/***/ (function(module, exports) {
+
+module.exports = __WEBPACK_EXTERNAL_MODULE_a5a2__;
+
+/***/ }),
+
+/***/ "bce2":
+/***/ (function(module, exports, __webpack_require__) {
+
+// extracted by mini-css-extract-plugin
+
+/***/ }),
+
+/***/ "ecdc":
+/***/ (function(module, exports, __webpack_require__) {
+
+// extracted by mini-css-extract-plugin
+
+/***/ }),
+
+/***/ "fae3":
+/***/ (function(module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+// ESM COMPAT FLAG
+__webpack_require__.r(__webpack_exports__);
+
+// EXPORTS
+__webpack_require__.d(__webpack_exports__, "ManageAIProviders", function() { return /* reexport */ ManageAIProviders; });
+
+// CONCATENATED MODULE: ./node_modules/@vue/cli-service/lib/commands/build/setPublicPath.js
+// This file is imported into lib/wc client bundles.
+
+if (typeof window !== 'undefined') {
+  var currentScript = window.document.currentScript
+  if (false) { var getCurrentScript; }
+
+  var src = currentScript && currentScript.src.match(/(.+\/)[^/]+\.js(\?.*)?$/)
+  if (src) {
+    __webpack_require__.p = src[1] // eslint-disable-line
+  }
+}
+
+// Indicate to webpack that this file can be concatenated
+/* harmony default export */ var setPublicPath = (null);
+
+// EXTERNAL MODULE: external {"commonjs":"vue","commonjs2":"vue","root":"Vue"}
+var external_commonjs_vue_commonjs2_vue_root_Vue_ = __webpack_require__("8bbf");
+
+// EXTERNAL MODULE: external "CoreHome"
+var external_CoreHome_ = __webpack_require__("19dc");
+
+// EXTERNAL MODULE: external "CorePluginsAdmin"
+var external_CorePluginsAdmin_ = __webpack_require__("a5a2");
+
+// CONCATENATED MODULE: ./node_modules/@vue/cli-plugin-typescript/node_modules/cache-loader/dist/cjs.js??ref--15-0!./node_modules/babel-loader/lib!./node_modules/@vue/cli-plugin-typescript/node_modules/ts-loader??ref--15-2!./node_modules/@vue/cli-service/node_modules/cache-loader/dist/cjs.js??ref--1-0!./node_modules/@vue/cli-service/node_modules/vue-loader-v16/dist??ref--1-1!./plugins/AIProviders/vue/src/components/ProviderCard.vue?vue&type=script&setup=true&lang=ts
+
+
+const _hoisted_1 = ["aria-checked", "aria-disabled", "tabindex"];
+const _hoisted_2 = {
+  key: 0,
+  class: "ai-providers-card-default"
+};
+const _hoisted_3 = {
+  class: "ai-providers-card-inner"
+};
+const _hoisted_4 = {
+  class: "ai-providers-card-header"
+};
+const _hoisted_5 = {
+  class: "ai-providers-card-name"
+};
+const _hoisted_6 = {
+  class: "ai-providers-card-description"
+};
+const _hoisted_7 = {
+  key: 1,
+  class: "ai-providers-card-model"
+};
+const _hoisted_8 = {
+  key: 1,
+  class: "ai-providers-card-model-help"
+};
+const _hoisted_9 = ["disabled", "title"];
+const _hoisted_10 = /*#__PURE__*/Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("span", {
+  "aria-hidden": "true",
+  class: "icon icon-reload"
+}, null, -1);
+const _hoisted_11 = {
+  class: "ai-providers-card-actions"
+};
+const _hoisted_12 = ["disabled"];
+const _hoisted_13 = ["disabled"];
+
+
+
+/* harmony default export */ var ProviderCardvue_type_script_setup_true_lang_ts = (/*#__PURE__*/Object(external_commonjs_vue_commonjs2_vue_root_Vue_["defineComponent"])({
+  __name: 'ProviderCard',
+  props: {
+    provider: null,
+    configuration: null,
+    availableModels: null,
+    selected: {
+      type: Boolean
+    },
+    usableAsDefault: {
+      type: Boolean
+    },
+    canEdit: {
+      type: Boolean
+    },
+    isTesting: {
+      type: Boolean
+    },
+    isDisconnecting: {
+      type: Boolean
+    }
+  },
+  emits: ["select", "update:apiKey", "update:endpointUrl", "update:model", "test", "disconnect"],
+  setup(__props, {
+    emit
+  }) {
+    const props = __props;
+    /* eslint-disable func-call-spacing, no-spaced-func */
+    /* eslint-enable func-call-spacing, no-spaced-func */
+    const hasPendingKey = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      var _props$configuration$, _props$configuration;
+      return ((_props$configuration$ = (_props$configuration = props.configuration) === null || _props$configuration === void 0 ? void 0 : _props$configuration.apiKey) !== null && _props$configuration$ !== void 0 ? _props$configuration$ : '') !== '';
+    });
+    const hasEndpointUrl = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      var _props$configuration$2, _props$configuration2;
+      return ((_props$configuration$2 = (_props$configuration2 = props.configuration) === null || _props$configuration2 === void 0 ? void 0 : _props$configuration2.endpointUrl) !== null && _props$configuration$2 !== void 0 ? _props$configuration$2 : '') !== '';
+    });
+    // Custom endpoints may run without a key, so reaching the server only needs the
+    // URL; fixed hosted providers need a key (pending or already stored).
+    const canTest = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => props.provider.supportsCustomEndpoint ? hasEndpointUrl.value : hasPendingKey.value || props.provider.configuration.hasApiKey);
+    const modelOptions = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      const options = {};
+      props.availableModels.forEach(model => {
+        options[model] = model;
+      });
+      return options;
+    });
+    function selectProvider() {
+      if (props.usableAsDefault) {
+        emit('select');
+      }
+    }
+    return (_ctx, _cache) => {
+      var _props$configuration3, _props$configuration4, _props$configuration5;
+      return Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", {
+        "aria-checked": __props.selected,
+        "aria-disabled": !__props.usableAsDefault,
+        class: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["normalizeClass"])([{
+          'is-selected': __props.selected,
+          'is-not-usable': !__props.usableAsDefault
+        }, "ai-providers-card"]),
+        role: "radio",
+        tabindex: __props.usableAsDefault ? 0 : -1,
+        onClick: _cache[6] || (_cache[6] = $event => selectProvider()),
+        onKeydown: [_cache[7] || (_cache[7] = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withKeys"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withModifiers"])($event => selectProvider(), ["prevent"]), ["enter"])), _cache[8] || (_cache[8] = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withKeys"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withModifiers"])($event => selectProvider(), ["prevent"]), ["space"]))]
+      }, [__props.selected ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", _hoisted_2, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultBadge')), 1)) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", _hoisted_3, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", _hoisted_4, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("span", _hoisted_5, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(__props.provider.name), 1)]), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("p", _hoisted_6, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])(__props.provider.description)), 1), __props.canEdit ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])(external_commonjs_vue_commonjs2_vue_root_Vue_["Fragment"], {
+        key: 0
+      }, [__props.provider.supportsCustomEndpoint ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CorePluginsAdmin_["Field"]), {
+        key: 0,
+        "model-value": (_props$configuration3 = __props.configuration) === null || _props$configuration3 === void 0 ? void 0 : _props$configuration3.endpointUrl,
+        name: `endpointUrl-${__props.provider.id}`,
+        title: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_EndpointUrl'),
+        placeholder: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_EndpointUrlPlaceholder'),
+        autocomplete: "off",
+        "full-width": "",
+        uicontrol: "text",
+        "onUpdate:modelValue": _cache[0] || (_cache[0] = $event => emit('update:endpointUrl', `${$event}`))
+      }, null, 8, ["model-value", "name", "title", "placeholder"])) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withDirectives"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createVNode"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CorePluginsAdmin_["Field"]), {
+        "model-value": (_props$configuration4 = __props.configuration) === null || _props$configuration4 === void 0 ? void 0 : _props$configuration4.apiKey,
+        name: `apiKey-${__props.provider.id}`,
+        placeholder: __props.provider.configuration.hasApiKey ? Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_ApiKeyAlreadyConfiguredPlaceholder') : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_ApiKeyPlaceholder'),
+        title: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_ApiKey'),
+        autocomplete: "new-password",
+        "full-width": "",
+        uicontrol: "password",
+        "onUpdate:modelValue": _cache[1] || (_cache[1] = $event => emit('update:apiKey', `${$event}`))
+      }, null, 8, ["model-value", "name", "placeholder", "title"]), [[Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["AutoClearPassword"])]]), __props.provider.supportsCustomEndpoint ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", _hoisted_7, [__props.availableModels.length ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CorePluginsAdmin_["Field"]), {
+        key: 0,
+        "model-value": (_props$configuration5 = __props.configuration) === null || _props$configuration5 === void 0 ? void 0 : _props$configuration5.model,
+        name: `model-${__props.provider.id}`,
+        title: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_Model'),
+        options: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(modelOptions),
+        "full-width": "",
+        uicontrol: "select",
+        "onUpdate:modelValue": _cache[2] || (_cache[2] = $event => emit('update:model', `${$event}`))
+      }, null, 8, ["model-value", "name", "title", "options"])) : (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("p", _hoisted_8, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_ClickTestConnectionToShowAvailableModels')), 1)), __props.availableModels.length ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("button", {
+        key: 2,
+        class: "btn-flat ai-providers-refresh-models",
+        type: "button",
+        disabled: __props.isTesting || !Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(canTest),
+        title: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_RefreshModels'),
+        onClick: _cache[3] || (_cache[3] = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withModifiers"])($event => emit('test'), ["prevent", "stop"]))
+      }, [_hoisted_10, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createTextVNode"])(" " + Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_RefreshModels')), 1)], 8, _hoisted_9)) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true)])) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", {
+        class: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["normalizeClass"])([{
+          'is-connected': __props.provider.configuration.isUsable
+        }, "ai-providers-card-status"])
+      }, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("span", {
+        "aria-hidden": "true",
+        class: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["normalizeClass"])(["icon ai-providers-status-icon", __props.provider.configuration.isUsable ? 'icon-ok' : 'icon-minus'])
+      }, null, 2), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createTextVNode"])(" " + Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(__props.provider.configuration.isUsable ? Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_StatusConnected') : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_StatusNotConnected')), 1)], 2), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", _hoisted_11, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("button", {
+        class: "btn btn-small",
+        type: "button",
+        disabled: __props.isTesting || !Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(canTest),
+        onClick: _cache[4] || (_cache[4] = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withModifiers"])($event => emit('test'), ["prevent", "stop"]))
+      }, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(__props.isTesting ? Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_TestingConnection') : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_TestConnection')), 9, _hoisted_12), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("button", {
+        class: "btn-flat",
+        type: "button",
+        disabled: __props.isDisconnecting || !__props.provider.configuration.hasApiKey,
+        onClick: _cache[5] || (_cache[5] = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withModifiers"])($event => emit('disconnect'), ["prevent", "stop"]))
+      }, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(__props.isDisconnecting ? Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_Disconnecting') : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_Disconnect')), 9, _hoisted_13)])], 64)) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true)])], 42, _hoisted_1);
+    };
+  }
+}));
+// CONCATENATED MODULE: ./plugins/AIProviders/vue/src/components/ProviderCard.vue?vue&type=script&setup=true&lang=ts
+ 
+// EXTERNAL MODULE: ./plugins/AIProviders/vue/src/components/ProviderCard.vue?vue&type=style&index=0&id=7e6b71a9&lang=less
+var ProviderCardvue_type_style_index_0_id_7e6b71a9_lang_less = __webpack_require__("a112");
+
+// CONCATENATED MODULE: ./plugins/AIProviders/vue/src/components/ProviderCard.vue
+
+
+
+
+
+/* harmony default export */ var ProviderCard = (ProviderCardvue_type_script_setup_true_lang_ts);
+// CONCATENATED MODULE: ./node_modules/@vue/cli-plugin-typescript/node_modules/cache-loader/dist/cjs.js??ref--15-0!./node_modules/babel-loader/lib!./node_modules/@vue/cli-plugin-typescript/node_modules/ts-loader??ref--15-2!./node_modules/@vue/cli-service/node_modules/cache-loader/dist/cjs.js??ref--1-0!./node_modules/@vue/cli-service/node_modules/vue-loader-v16/dist??ref--1-1!./plugins/AIProviders/vue/src/ManageAIProviders.vue?vue&type=script&setup=true&lang=ts
+
+
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_1 = {
+  class: "ai-providers-page"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_2 = {
+  class: "ai-providers-page-header"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_3 = {
+  class: "ai-providers-page-title"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_4 = {
+  class: "ai-providers-page-subtitle"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_5 = {
+  class: "ai-providers"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_6 = {
+  class: "ai-providers-defaults-title"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_7 = {
+  class: "ai-providers-section"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_8 = {
+  class: "ai-providers-subsection-title"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_9 = {
+  class: "ai-providers-section-help"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_10 = ["aria-label"];
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_11 = {
+  key: 1,
+  class: "ai-providers-section"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_12 = {
+  class: "ai-providers-subsection-title"
+};
+const ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_13 = {
+  class: "ai-providers-section-help"
+};
+const _hoisted_14 = ["aria-label"];
+const _hoisted_15 = {
+  class: "ai-providers-capability-header"
+};
+const _hoisted_16 = ["value"];
+const _hoisted_17 = {
+  class: "ai-providers-capability-label"
+};
+const _hoisted_18 = {
+  key: 0,
+  class: "ai-providers-capability-description"
+};
+const _hoisted_19 = {
+  key: 2,
+  class: "ai-providers-footer"
+};
+const _hoisted_20 = ["disabled"];
+
+
+
+
+/* harmony default export */ var ManageAIProvidersvue_type_script_setup_true_lang_ts = (/*#__PURE__*/Object(external_commonjs_vue_commonjs2_vue_root_Vue_["defineComponent"])({
+  __name: 'ManageAIProviders',
+  setup(__props) {
+    const settings = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])(null);
+    const isLoading = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])(false);
+    const isSaving = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])(false);
+    const defaultProviderId = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])('');
+    const defaultCapabilityLevel = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])('');
+    const providerConfigurations = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])({});
+    // Models discovered per provider from the last "test connection"/refresh, used
+    // to populate the model picker.
+    const availableModels = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])({});
+    const testingProviders = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])({});
+    const disconnectingProviders = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])({});
+    const providers = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      var _settings$value;
+      return ((_settings$value = settings.value) === null || _settings$value === void 0 ? void 0 : _settings$value.providers) || [];
+    });
+    const hasUsableProvider = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => providers.value.some(provider => provider.configuration.isUsable));
+    const canEditCapabilityLevel = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      var _settings$value2;
+      return !!((_settings$value2 = settings.value) !== null && _settings$value2 !== void 0 && _settings$value2.canEditCapabilityLevel);
+    });
+    const canEditProviderConfiguration = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      var _settings$value3;
+      return !!((_settings$value3 = settings.value) !== null && _settings$value3 !== void 0 && _settings$value3.canEditProviderConfiguration);
+    });
+    // Snapshot of the saved state, used to detect unsaved changes.
+    const savedSnapshot = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["ref"])('');
+    const capabilityLevelOptions = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => {
+      var _settings$value4;
+      const capabilityLevels = ((_settings$value4 = settings.value) === null || _settings$value4 === void 0 ? void 0 : _settings$value4.capabilityLevels) || {};
+      return Object.entries(capabilityLevels).map(([id, keys]) => ({
+        id,
+        label: Object(external_CoreHome_["translate"])(keys.label),
+        description: keys.description ? Object(external_CoreHome_["translate"])(keys.description) : ''
+      }));
+    });
+    // Serializes everything the user can edit, so it can be compared to the saved snapshot.
+    function serializeEditableState() {
+      return JSON.stringify({
+        defaultProviderId: defaultProviderId.value,
+        defaultCapabilityLevel: defaultCapabilityLevel.value,
+        providerConfigurations: providerConfigurations.value
+      });
+    }
+    const hasUnsavedChanges = Object(external_commonjs_vue_commonjs2_vue_root_Vue_["computed"])(() => !!settings.value && serializeEditableState() !== savedSnapshot.value);
+    /**
+     * Applies the given settings to the component state.
+     * @param nextSettings
+     */
+    function applySettings(nextSettings) {
+      settings.value = nextSettings;
+      defaultProviderId.value = nextSettings.defaultProviderId;
+      defaultCapabilityLevel.value = nextSettings.defaultCapabilityLevel;
+      const nextProviderConfigurations = {};
+      nextSettings.providers.forEach(provider => {
+        const savedModel = provider.configuration.model || '';
+        nextProviderConfigurations[provider.id] = {
+          apiKey: '',
+          endpointUrl: provider.configuration.endpointUrl || '',
+          model: savedModel
+        };
+      });
+      providerConfigurations.value = nextProviderConfigurations;
+      availableModels.value = {};
+      // Capture the freshly applied state as the baseline for unsaved-change detection.
+      savedSnapshot.value = serializeEditableState();
+    }
+    function markProviderUsable(providerId) {
+      if (!settings.value) {
+        return;
+      }
+      const provider = settings.value.providers.find(p => p.id === providerId);
+      if (provider) {
+        provider.configuration = Object.assign(Object.assign({}, provider.configuration), {}, {
+          hasApiKey: true,
+          isUsable: true
+        });
+      }
+      if (!defaultProviderId.value) {
+        defaultProviderId.value = providerId;
+      }
+    }
+    function getCleanErrorMessage(error) {
+      let message = '';
+      if (error && typeof error === 'object' && 'message' in error) {
+        message = `${error.message}`;
+      } else {
+        message = `${error}`;
+      }
+      return message.replace(/\s*#\d+\s+[\s\S]*$/, '').replace(/\s+/g, ' ').trim();
+    }
+    // Notification IDs may only contain word characters (alphanumerics + underscore),
+    // see core/Notification/Manager.php::checkId(). Provider IDs can contain other
+    // characters (e.g. hyphens), so sanitize before using them in a notification ID.
+    function notificationId(id) {
+      return id.replace(/[^\w]/g, '_');
+    }
+    function showErrorNotification(error, id) {
+      const cleaned = getCleanErrorMessage(error);
+      const isUseful = cleaned && cleaned !== 'Something went wrong';
+      const message = isUseful ? Object(external_CoreHome_["translate"])('AIProviders_RequestFailed', cleaned) : Object(external_CoreHome_["translate"])('AIProviders_UnexpectedError');
+      return external_CoreHome_["NotificationsStore"].show({
+        message,
+        type: 'transient',
+        id,
+        context: 'error'
+      });
+    }
+    function updateModel(providerId, model) {
+      providerConfigurations.value[providerId] = Object.assign(Object.assign({}, providerConfigurations.value[providerId]), {}, {
+        model
+      });
+    }
+    async function fetchAvailableModels(providerId, showNotifications) {
+      testingProviders.value[providerId] = true;
+      try {
+        const response = await external_CoreHome_["AjaxHelper"].post({
+          method: 'AIProviders.testConnection'
+        }, {
+          providerId,
+          providerConfiguration: JSON.stringify(providerConfigurations.value[providerId] || {})
+        }, {
+          withTokenInUrl: true,
+          createErrorNotification: false
+        });
+        markProviderUsable(providerId);
+        if (response.models && response.models.length) {
+          var _providerConfiguratio;
+          availableModels.value[providerId] = response.models;
+          // Default to the first discovered model when none is selected yet.
+          if (!((_providerConfiguratio = providerConfigurations.value[providerId]) !== null && _providerConfiguratio !== void 0 && _providerConfiguratio.model)) {
+            updateModel(providerId, response.models[0]);
+          }
+        }
+        if (showNotifications) {
+          external_CoreHome_["NotificationsStore"].show({
+            message: Object(external_CoreHome_["translate"])('AIProviders_TestConnectionSuccess', response.providerName),
+            type: 'transient',
+            id: notificationId(`aiProvidersTest-${providerId}`),
+            context: 'success'
+          });
+        }
+      } catch (error) {
+        if (showNotifications) {
+          showErrorNotification(error, notificationId(`aiProvidersTestError-${providerId}`));
+        }
+      } finally {
+        testingProviders.value[providerId] = false;
+      }
+    }
+    async function loadSettings() {
+      isLoading.value = true;
+      try {
+        const response = await external_CoreHome_["AjaxHelper"].fetch({
+          method: 'AIProviders.getSettings'
+        }, {
+          createErrorNotification: false
+        });
+        applySettings(response);
+        response.providers.filter(provider => provider.supportsCustomEndpoint && provider.configuration.isUsable).forEach(provider => {
+          fetchAvailableModels(provider.id, false);
+        });
+      } catch (error) {
+        showErrorNotification(error, 'aiProvidersLoadError');
+      } finally {
+        isLoading.value = false;
+      }
+    }
+    function updateApiKey(providerId, apiKey) {
+      providerConfigurations.value[providerId] = Object.assign(Object.assign({}, providerConfigurations.value[providerId]), {}, {
+        apiKey
+      });
+    }
+    function updateEndpointUrl(providerId, endpointUrl) {
+      providerConfigurations.value[providerId] = Object.assign(Object.assign({}, providerConfigurations.value[providerId]), {}, {
+        endpointUrl
+      });
+      availableModels.value[providerId] = [];
+    }
+    async function disconnectProvider(providerId) {
+      disconnectingProviders.value[providerId] = true;
+      try {
+        const response = await external_CoreHome_["AjaxHelper"].post({
+          method: 'AIProviders.disconnectProvider'
+        }, {
+          providerId
+        }, {
+          withTokenInUrl: true,
+          createErrorNotification: false
+        });
+        applySettings(response);
+        external_CoreHome_["NotificationsStore"].show({
+          message: Object(external_CoreHome_["translate"])('AIProviders_DisconnectSuccess'),
+          type: 'transient',
+          id: notificationId(`aiProvidersDisconnect-${providerId}`),
+          context: 'success'
+        });
+      } catch (error) {
+        showErrorNotification(error, notificationId(`aiProvidersDisconnectError-${providerId}`));
+      } finally {
+        disconnectingProviders.value[providerId] = false;
+      }
+    }
+    async function testConnection(providerId) {
+      await fetchAvailableModels(providerId, true);
+    }
+    function cancelChanges() {
+      if (settings.value) {
+        applySettings(settings.value);
+      }
+    }
+    /**
+     * Saves the current settings to the server.
+     */
+    async function saveSettings() {
+      isSaving.value = true;
+      try {
+        const response = await external_CoreHome_["AjaxHelper"].post({
+          method: 'AIProviders.saveSettings'
+        }, {
+          defaultProviderId: defaultProviderId.value,
+          defaultCapabilityLevel: defaultCapabilityLevel.value,
+          providerConfigurations: JSON.stringify(providerConfigurations.value)
+        }, {
+          withTokenInUrl: true,
+          createErrorNotification: false
+        });
+        applySettings(response);
+        const notificationInstanceId = external_CoreHome_["NotificationsStore"].show({
+          message: Object(external_CoreHome_["translate"])('AIProviders_SettingsSaveSuccess'),
+          type: 'transient',
+          id: 'aiProvidersSettings',
+          context: 'success'
+        });
+        external_CoreHome_["NotificationsStore"].scrollToNotification(notificationInstanceId);
+      } catch (error) {
+        const notificationInstanceId = showErrorNotification(error, 'aiProvidersSettingsError');
+        external_CoreHome_["NotificationsStore"].scrollToNotification(notificationInstanceId);
+      } finally {
+        isSaving.value = false;
+      }
+    }
+    Object(external_commonjs_vue_commonjs2_vue_root_Vue_["onMounted"])(loadSettings);
+    return (_ctx, _cache) => {
+      return Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_1, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("header", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_2, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("h2", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_3, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createVNode"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["EnrichedHeadline"]), null, {
+        default: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withCtx"])(() => [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createTextVNode"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_MenuTitle')), 1)]),
+        _: 1
+      })]), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("p", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_4, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_ConfigurationIntro')), 1)]), isLoading.value ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["ActivityIndicator"]), {
+        key: 0,
+        loading: isLoading.value
+      }, null, 8, ["loading"])) : settings.value ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["ContentBlock"]), {
+        key: 1,
+        class: "ai-providers-content"
+      }, {
+        default: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withCtx"])(() => [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("span", {
+          class: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["normalizeClass"])(["ai-providers-unsaved-changes", {
+            'is-visible': Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(hasUnsavedChanges)
+          }])
+        }, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_UnsavedChanges')), 3), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withDirectives"])((Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_5, [!Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(canEditProviderConfiguration) ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["Alert"]), {
+          key: 0,
+          severity: "info"
+        }, {
+          default: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withCtx"])(() => [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createTextVNode"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_ManagedConfigurationHelp')), 1)]),
+          _: 1
+        })) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("h3", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_6, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultsTitle')), 1), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("section", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_7, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("h4", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_8, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultProvider')), 1), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("p", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_9, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultProviderHelp')), 1), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", {
+          "aria-label": Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultProvider'),
+          class: "ai-providers-cards",
+          role: "radiogroup"
+        }, [(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(true), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])(external_commonjs_vue_commonjs2_vue_root_Vue_["Fragment"], null, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["renderList"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(providers), provider => {
+          return Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(ProviderCard, {
+            key: provider.id,
+            "available-models": availableModels.value[provider.id] || [],
+            "can-edit": Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(canEditProviderConfiguration),
+            configuration: providerConfigurations.value[provider.id],
+            "is-disconnecting": !!disconnectingProviders.value[provider.id],
+            "is-testing": !!testingProviders.value[provider.id],
+            provider: provider,
+            selected: defaultProviderId.value === provider.id,
+            "usable-as-default": provider.configuration.isUsable,
+            onDisconnect: $event => disconnectProvider(provider.id),
+            onSelect: $event => provider.configuration.isUsable ? defaultProviderId.value = provider.id : null,
+            onTest: $event => testConnection(provider.id),
+            "onUpdate:apiKey": $event => updateApiKey(provider.id, $event),
+            "onUpdate:endpointUrl": $event => updateEndpointUrl(provider.id, $event),
+            "onUpdate:model": $event => updateModel(provider.id, $event)
+          }, null, 8, ["available-models", "can-edit", "configuration", "is-disconnecting", "is-testing", "provider", "selected", "usable-as-default", "onDisconnect", "onSelect", "onTest", "onUpdate:apiKey", "onUpdate:endpointUrl", "onUpdate:model"]);
+        }), 128))], 8, ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_10), !Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(hasUsableProvider) ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createBlock"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["Alert"]), {
+          key: 0,
+          class: "ai-providers-default-warning",
+          severity: "warning"
+        }, {
+          default: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withCtx"])(() => [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createTextVNode"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_NoDefaultProviderWarning')), 1)]),
+          _: 1
+        })) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true)]), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(canEditCapabilityLevel) ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("section", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_11, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("h4", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_12, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultCapabilityLevel')), 1), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("p", ManageAIProvidersvue_type_script_setup_true_lang_ts_hoisted_13, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultCapabilityLevelHelp')), 1), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", {
+          "aria-label": Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('AIProviders_DefaultCapabilityLevel'),
+          class: "ai-providers-capability-cards",
+          role: "radiogroup"
+        }, [(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(true), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])(external_commonjs_vue_commonjs2_vue_root_Vue_["Fragment"], null, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["renderList"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(capabilityLevelOptions), capability => {
+          return Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("label", {
+            key: capability.id,
+            class: Object(external_commonjs_vue_commonjs2_vue_root_Vue_["normalizeClass"])([{
+              'is-selected': defaultCapabilityLevel.value === capability.id
+            }, "ai-providers-capability-card"])
+          }, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("div", _hoisted_15, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["withDirectives"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("input", {
+            "onUpdate:modelValue": _cache[0] || (_cache[0] = $event => defaultCapabilityLevel.value = $event),
+            value: capability.id,
+            name: "defaultCapabilityLevel",
+            type: "radio"
+          }, null, 8, _hoisted_16), [[external_commonjs_vue_commonjs2_vue_root_Vue_["vModelRadio"], defaultCapabilityLevel.value]]), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("span", _hoisted_17, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(capability.label), 1)]), capability.description ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", _hoisted_18, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(capability.description), 1)) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true)], 2);
+        }), 128))], 8, _hoisted_14)])) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true)])), [[Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CorePluginsAdmin_["Form"])]])]),
+        _: 1
+      })) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true), settings.value ? (Object(external_commonjs_vue_commonjs2_vue_root_Vue_["openBlock"])(), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementBlock"])("div", _hoisted_19, [Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createElementVNode"])("button", {
+        disabled: isSaving.value || !Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(hasUnsavedChanges),
+        class: "btn ai-providers-cancel",
+        type: "button",
+        onClick: _cache[1] || (_cache[1] = $event => cancelChanges())
+      }, Object(external_commonjs_vue_commonjs2_vue_root_Vue_["toDisplayString"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CoreHome_["translate"])('General_Cancel')), 9, _hoisted_20), Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createVNode"])(Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(external_CorePluginsAdmin_["SaveButton"]), {
+        disabled: !Object(external_commonjs_vue_commonjs2_vue_root_Vue_["unref"])(hasUnsavedChanges),
+        saving: isSaving.value,
+        onConfirm: _cache[2] || (_cache[2] = $event => saveSettings())
+      }, null, 8, ["disabled", "saving"])])) : Object(external_commonjs_vue_commonjs2_vue_root_Vue_["createCommentVNode"])("", true)]);
+    };
+  }
+}));
+// CONCATENATED MODULE: ./plugins/AIProviders/vue/src/ManageAIProviders.vue?vue&type=script&setup=true&lang=ts
+ 
+// EXTERNAL MODULE: ./plugins/AIProviders/vue/src/ManageAIProviders.vue?vue&type=style&index=0&id=2cc0a4ac&lang=less
+var ManageAIProvidersvue_type_style_index_0_id_2cc0a4ac_lang_less = __webpack_require__("20f9");
+
+// CONCATENATED MODULE: ./plugins/AIProviders/vue/src/ManageAIProviders.vue
+
+
+
+
+
+/* harmony default export */ var ManageAIProviders = (ManageAIProvidersvue_type_script_setup_true_lang_ts);
+// CONCATENATED MODULE: ./plugins/AIProviders/vue/src/index.ts
+/*!
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+// CONCATENATED MODULE: ./node_modules/@vue/cli-service/lib/commands/build/entry-lib-no-default.js
+
+
+
+
+/***/ })
+
+/******/ });
+});
+//# sourceMappingURL=AIProviders.umd.js.map
\ No newline at end of file
diff --git a/vue/dist/AIProviders.umd.min.js b/vue/dist/AIProviders.umd.min.js
new file mode 100644
index 0000000..245060d
--- /dev/null
+++ b/vue/dist/AIProviders.umd.min.js
@@ -0,0 +1,2 @@
+(function(e,t){"object"===typeof exports&&"object"===typeof module?module.exports=t(require("CoreHome"),require("vue"),require("CorePluginsAdmin")):"function"===typeof define&&define.amd?define(["CoreHome",,"CorePluginsAdmin"],t):"object"===typeof exports?exports["AIProviders"]=t(require("CoreHome"),require("vue"),require("CorePluginsAdmin")):e["AIProviders"]=t(e["CoreHome"],e["Vue"],e["CorePluginsAdmin"])})("undefined"!==typeof self?self:this,(function(e,t,r){return function(e){var t={};function r(i){if(t[i])return t[i].exports;var o=t[i]={i:i,l:!1,exports:{}};return e[i].call(o.exports,o,o.exports,r),o.l=!0,o.exports}return r.m=e,r.c=t,r.d=function(e,t,i){r.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:i})},r.r=function(e){"undefined"!==typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"===typeof e&&e&&e.__esModule)return e;var i=Object.create(null);if(r.r(i),Object.defineProperty(i,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(i,o,function(t){return e[t]}.bind(null,o));return i},r.n=function(e){var t=e&&e.__esModule?function(){return e["default"]}:function(){return e};return r.d(t,"a",t),t},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r.p="plugins/AIProviders/vue/dist/",r(r.s="fae3")}({"19dc":function(t,r){t.exports=e},"20f9":function(e,t,r){"use strict";r("bce2")},"8bbf":function(e,r){e.exports=t},a112:function(e,t,r){"use strict";r("ecdc")},a5a2:function(e,t){e.exports=r},bce2:function(e,t,r){},ecdc:function(e,t,r){},fae3:function(e,t,r){"use strict";if(r.r(t),r.d(t,"ManageAIProviders",(function(){return z})),"undefined"!==typeof window){var i=window.document.currentScript,o=i&&i.src.match(/(.+\/)[^/]+\.js(\?.*)?$/);o&&(r.p=o[1])}var n=r("8bbf"),a=r("19dc"),c=r("a5a2");const l=["aria-checked","aria-disabled","tabindex"],s={key:0,class:"ai-providers-card-default"},d={class:"ai-providers-card-inner"},u={class:"ai-providers-card-header"},b={class:"ai-providers-card-name"},p={class:"ai-providers-card-description"},v={key:1,class:"ai-providers-card-model"},f={key:1,class:"ai-providers-card-model-help"},j=["disabled","title"],O=Object(n["createElementVNode"])("span",{"aria-hidden":"true",class:"icon icon-reload"},null,-1),m={class:"ai-providers-card-actions"},g=["disabled"],y=["disabled"];var h=Object(n["defineComponent"])({__name:"ProviderCard",props:{provider:null,configuration:null,availableModels:null,selected:{type:Boolean},usableAsDefault:{type:Boolean},canEdit:{type:Boolean},isTesting:{type:Boolean},isDisconnecting:{type:Boolean}},emits:["select","update:apiKey","update:endpointUrl","update:model","test","disconnect"],setup(e,{emit:t}){const r=e,i=Object(n["computed"])(()=>{var e,t;return""!==(null!==(e=null===(t=r.configuration)||void 0===t?void 0:t.apiKey)&&void 0!==e?e:"")}),o=Object(n["computed"])(()=>{var e,t;return""!==(null!==(e=null===(t=r.configuration)||void 0===t?void 0:t.endpointUrl)&&void 0!==e?e:"")}),h=Object(n["computed"])(()=>r.provider.supportsCustomEndpoint?o.value:i.value||r.provider.configuration.hasApiKey),P=Object(n["computed"])(()=>{const e={};return r.availableModels.forEach(t=>{e[t]=t}),e});function k(){r.usableAsDefault&&t("select")}return(r,i)=>{var o,A,C;return Object(n["openBlock"])(),Object(n["createElementBlock"])("div",{"aria-checked":e.selected,"aria-disabled":!e.usableAsDefault,class:Object(n["normalizeClass"])([{"is-selected":e.selected,"is-not-usable":!e.usableAsDefault},"ai-providers-card"]),role:"radio",tabindex:e.usableAsDefault?0:-1,onClick:i[6]||(i[6]=e=>k()),onKeydown:[i[7]||(i[7]=Object(n["withKeys"])(Object(n["withModifiers"])(e=>k(),["prevent"]),["enter"])),i[8]||(i[8]=Object(n["withKeys"])(Object(n["withModifiers"])(e=>k(),["prevent"]),["space"]))]},[e.selected?(Object(n["openBlock"])(),Object(n["createElementBlock"])("div",s,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_DefaultBadge")),1)):Object(n["createCommentVNode"])("",!0),Object(n["createElementVNode"])("div",d,[Object(n["createElementVNode"])("div",u,[Object(n["createElementVNode"])("span",b,Object(n["toDisplayString"])(e.provider.name),1)]),Object(n["createElementVNode"])("p",p,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])(e.provider.description)),1),e.canEdit?(Object(n["openBlock"])(),Object(n["createElementBlock"])(n["Fragment"],{key:0},[e.provider.supportsCustomEndpoint?(Object(n["openBlock"])(),Object(n["createBlock"])(Object(n["unref"])(c["Field"]),{key:0,"model-value":null===(o=e.configuration)||void 0===o?void 0:o.endpointUrl,name:"endpointUrl-"+e.provider.id,title:Object(n["unref"])(a["translate"])("AIProviders_EndpointUrl"),placeholder:Object(n["unref"])(a["translate"])("AIProviders_EndpointUrlPlaceholder"),autocomplete:"off","full-width":"",uicontrol:"text","onUpdate:modelValue":i[0]||(i[0]=e=>t("update:endpointUrl",""+e))},null,8,["model-value","name","title","placeholder"])):Object(n["createCommentVNode"])("",!0),Object(n["withDirectives"])(Object(n["createVNode"])(Object(n["unref"])(c["Field"]),{"model-value":null===(A=e.configuration)||void 0===A?void 0:A.apiKey,name:"apiKey-"+e.provider.id,placeholder:e.provider.configuration.hasApiKey?Object(n["unref"])(a["translate"])("AIProviders_ApiKeyAlreadyConfiguredPlaceholder"):Object(n["unref"])(a["translate"])("AIProviders_ApiKeyPlaceholder"),title:Object(n["unref"])(a["translate"])("AIProviders_ApiKey"),autocomplete:"new-password","full-width":"",uicontrol:"password","onUpdate:modelValue":i[1]||(i[1]=e=>t("update:apiKey",""+e))},null,8,["model-value","name","placeholder","title"]),[[Object(n["unref"])(a["AutoClearPassword"])]]),e.provider.supportsCustomEndpoint?(Object(n["openBlock"])(),Object(n["createElementBlock"])("div",v,[e.availableModels.length?(Object(n["openBlock"])(),Object(n["createBlock"])(Object(n["unref"])(c["Field"]),{key:0,"model-value":null===(C=e.configuration)||void 0===C?void 0:C.model,name:"model-"+e.provider.id,title:Object(n["unref"])(a["translate"])("AIProviders_Model"),options:Object(n["unref"])(P),"full-width":"",uicontrol:"select","onUpdate:modelValue":i[2]||(i[2]=e=>t("update:model",""+e))},null,8,["model-value","name","title","options"])):(Object(n["openBlock"])(),Object(n["createElementBlock"])("p",f,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_ClickTestConnectionToShowAvailableModels")),1)),e.availableModels.length?(Object(n["openBlock"])(),Object(n["createElementBlock"])("button",{key:2,class:"btn-flat ai-providers-refresh-models",type:"button",disabled:e.isTesting||!Object(n["unref"])(h),title:Object(n["unref"])(a["translate"])("AIProviders_RefreshModels"),onClick:i[3]||(i[3]=Object(n["withModifiers"])(e=>t("test"),["prevent","stop"]))},[O,Object(n["createTextVNode"])(" "+Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_RefreshModels")),1)],8,j)):Object(n["createCommentVNode"])("",!0)])):Object(n["createCommentVNode"])("",!0),Object(n["createElementVNode"])("div",{class:Object(n["normalizeClass"])([{"is-connected":e.provider.configuration.isUsable},"ai-providers-card-status"])},[Object(n["createElementVNode"])("span",{"aria-hidden":"true",class:Object(n["normalizeClass"])(["icon ai-providers-status-icon",e.provider.configuration.isUsable?"icon-ok":"icon-minus"])},null,2),Object(n["createTextVNode"])(" "+Object(n["toDisplayString"])(e.provider.configuration.isUsable?Object(n["unref"])(a["translate"])("AIProviders_StatusConnected"):Object(n["unref"])(a["translate"])("AIProviders_StatusNotConnected")),1)],2),Object(n["createElementVNode"])("div",m,[Object(n["createElementVNode"])("button",{class:"btn btn-small",type:"button",disabled:e.isTesting||!Object(n["unref"])(h),onClick:i[4]||(i[4]=Object(n["withModifiers"])(e=>t("test"),["prevent","stop"]))},Object(n["toDisplayString"])(e.isTesting?Object(n["unref"])(a["translate"])("AIProviders_TestingConnection"):Object(n["unref"])(a["translate"])("AIProviders_TestConnection")),9,g),Object(n["createElementVNode"])("button",{class:"btn-flat",type:"button",disabled:e.isDisconnecting||!e.provider.configuration.hasApiKey,onClick:i[5]||(i[5]=Object(n["withModifiers"])(e=>t("disconnect"),["prevent","stop"]))},Object(n["toDisplayString"])(e.isDisconnecting?Object(n["unref"])(a["translate"])("AIProviders_Disconnecting"):Object(n["unref"])(a["translate"])("AIProviders_Disconnect")),9,y)])],64)):Object(n["createCommentVNode"])("",!0)])],42,l)}}}),P=(r("a112"),h);const k={class:"ai-providers-page"},A={class:"ai-providers-page-header"},C={class:"ai-providers-page-title"},E={class:"ai-providers-page-subtitle"},N={class:"ai-providers"},S={class:"ai-providers-defaults-title"},I={class:"ai-providers-section"},B={class:"ai-providers-subsection-title"},V={class:"ai-providers-section-help"},_=["aria-label"],D={key:1,class:"ai-providers-section"},w={class:"ai-providers-subsection-title"},U={class:"ai-providers-section-help"},x=["aria-label"],T={class:"ai-providers-capability-header"},M=["value"],K={class:"ai-providers-capability-label"},H={key:0,class:"ai-providers-capability-description"},L={key:2,class:"ai-providers-footer"},F=["disabled"];var q=Object(n["defineComponent"])({__name:"ManageAIProviders",setup(e){const t=Object(n["ref"])(null),r=Object(n["ref"])(!1),i=Object(n["ref"])(!1),o=Object(n["ref"])(""),l=Object(n["ref"])(""),s=Object(n["ref"])({}),d=Object(n["ref"])({}),u=Object(n["ref"])({}),b=Object(n["ref"])({}),p=Object(n["computed"])(()=>{var e;return(null===(e=t.value)||void 0===e?void 0:e.providers)||[]}),v=Object(n["computed"])(()=>p.value.some(e=>e.configuration.isUsable)),f=Object(n["computed"])(()=>{var e;return!(null===(e=t.value)||void 0===e||!e.canEditCapabilityLevel)}),j=Object(n["computed"])(()=>{var e;return!(null===(e=t.value)||void 0===e||!e.canEditProviderConfiguration)}),O=Object(n["ref"])(""),m=Object(n["computed"])(()=>{var e;const r=(null===(e=t.value)||void 0===e?void 0:e.capabilityLevels)||{};return Object.entries(r).map(([e,t])=>({id:e,label:Object(a["translate"])(t.label),description:t.description?Object(a["translate"])(t.description):""}))});function g(){return JSON.stringify({defaultProviderId:o.value,defaultCapabilityLevel:l.value,providerConfigurations:s.value})}const y=Object(n["computed"])(()=>!!t.value&&g()!==O.value);function h(e){t.value=e,o.value=e.defaultProviderId,l.value=e.defaultCapabilityLevel;const r={};e.providers.forEach(e=>{const t=e.configuration.model||"";r[e.id]={apiKey:"",endpointUrl:e.configuration.endpointUrl||"",model:t}}),s.value=r,d.value={},O.value=g()}function q(e){if(!t.value)return;const r=t.value.providers.find(t=>t.id===e);r&&(r.configuration=Object.assign(Object.assign({},r.configuration),{},{hasApiKey:!0,isUsable:!0})),o.value||(o.value=e)}function z(e){let t="";return t=e&&"object"===typeof e&&"message"in e?""+e.message:""+e,t.replace(/\s*#\d+\s+[\s\S]*$/,"").replace(/\s+/g," ").trim()}function R(e){return e.replace(/[^\w]/g,"_")}function J(e,t){const r=z(e),i=r&&"Something went wrong"!==r,o=i?Object(a["translate"])("AIProviders_RequestFailed",r):Object(a["translate"])("AIProviders_UnexpectedError");return a["NotificationsStore"].show({message:o,type:"transient",id:t,context:"error"})}function $(e,t){s.value[e]=Object.assign(Object.assign({},s.value[e]),{},{model:t})}async function G(e,t){u.value[e]=!0;try{const i=await a["AjaxHelper"].post({method:"AIProviders.testConnection"},{providerId:e,providerConfiguration:JSON.stringify(s.value[e]||{})},{withTokenInUrl:!0,createErrorNotification:!1});var r;if(q(e),i.models&&i.models.length)d.value[e]=i.models,null!==(r=s.value[e])&&void 0!==r&&r.model||$(e,i.models[0]);t&&a["NotificationsStore"].show({message:Object(a["translate"])("AIProviders_TestConnectionSuccess",i.providerName),type:"transient",id:R("aiProvidersTest-"+e),context:"success"})}catch(i){t&&J(i,R("aiProvidersTestError-"+e))}finally{u.value[e]=!1}}async function W(){r.value=!0;try{const e=await a["AjaxHelper"].fetch({method:"AIProviders.getSettings"},{createErrorNotification:!1});h(e),e.providers.filter(e=>e.supportsCustomEndpoint&&e.configuration.isUsable).forEach(e=>{G(e.id,!1)})}catch(e){J(e,"aiProvidersLoadError")}finally{r.value=!1}}function Q(e,t){s.value[e]=Object.assign(Object.assign({},s.value[e]),{},{apiKey:t})}function X(e,t){s.value[e]=Object.assign(Object.assign({},s.value[e]),{},{endpointUrl:t}),d.value[e]=[]}async function Y(e){b.value[e]=!0;try{const t=await a["AjaxHelper"].post({method:"AIProviders.disconnectProvider"},{providerId:e},{withTokenInUrl:!0,createErrorNotification:!1});h(t),a["NotificationsStore"].show({message:Object(a["translate"])("AIProviders_DisconnectSuccess"),type:"transient",id:R("aiProvidersDisconnect-"+e),context:"success"})}catch(t){J(t,R("aiProvidersDisconnectError-"+e))}finally{b.value[e]=!1}}async function Z(e){await G(e,!0)}function ee(){t.value&&h(t.value)}async function te(){i.value=!0;try{const e=await a["AjaxHelper"].post({method:"AIProviders.saveSettings"},{defaultProviderId:o.value,defaultCapabilityLevel:l.value,providerConfigurations:JSON.stringify(s.value)},{withTokenInUrl:!0,createErrorNotification:!1});h(e);const t=a["NotificationsStore"].show({message:Object(a["translate"])("AIProviders_SettingsSaveSuccess"),type:"transient",id:"aiProvidersSettings",context:"success"});a["NotificationsStore"].scrollToNotification(t)}catch(e){const t=J(e,"aiProvidersSettingsError");a["NotificationsStore"].scrollToNotification(t)}finally{i.value=!1}}return Object(n["onMounted"])(W),(e,O)=>(Object(n["openBlock"])(),Object(n["createElementBlock"])("div",k,[Object(n["createElementVNode"])("header",A,[Object(n["createElementVNode"])("h2",C,[Object(n["createVNode"])(Object(n["unref"])(a["EnrichedHeadline"]),null,{default:Object(n["withCtx"])(()=>[Object(n["createTextVNode"])(Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_MenuTitle")),1)]),_:1})]),Object(n["createElementVNode"])("p",E,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_ConfigurationIntro")),1)]),r.value?(Object(n["openBlock"])(),Object(n["createBlock"])(Object(n["unref"])(a["ActivityIndicator"]),{key:0,loading:r.value},null,8,["loading"])):t.value?(Object(n["openBlock"])(),Object(n["createBlock"])(Object(n["unref"])(a["ContentBlock"]),{key:1,class:"ai-providers-content"},{default:Object(n["withCtx"])(()=>[Object(n["createElementVNode"])("span",{class:Object(n["normalizeClass"])(["ai-providers-unsaved-changes",{"is-visible":Object(n["unref"])(y)}])},Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_UnsavedChanges")),3),Object(n["withDirectives"])((Object(n["openBlock"])(),Object(n["createElementBlock"])("div",N,[Object(n["unref"])(j)?Object(n["createCommentVNode"])("",!0):(Object(n["openBlock"])(),Object(n["createBlock"])(Object(n["unref"])(a["Alert"]),{key:0,severity:"info"},{default:Object(n["withCtx"])(()=>[Object(n["createTextVNode"])(Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_ManagedConfigurationHelp")),1)]),_:1})),Object(n["createElementVNode"])("h3",S,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_DefaultsTitle")),1),Object(n["createElementVNode"])("section",I,[Object(n["createElementVNode"])("h4",B,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_DefaultProvider")),1),Object(n["createElementVNode"])("p",V,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_DefaultProviderHelp")),1),Object(n["createElementVNode"])("div",{"aria-label":Object(n["unref"])(a["translate"])("AIProviders_DefaultProvider"),class:"ai-providers-cards",role:"radiogroup"},[(Object(n["openBlock"])(!0),Object(n["createElementBlock"])(n["Fragment"],null,Object(n["renderList"])(Object(n["unref"])(p),e=>(Object(n["openBlock"])(),Object(n["createBlock"])(P,{key:e.id,"available-models":d.value[e.id]||[],"can-edit":Object(n["unref"])(j),configuration:s.value[e.id],"is-disconnecting":!!b.value[e.id],"is-testing":!!u.value[e.id],provider:e,selected:o.value===e.id,"usable-as-default":e.configuration.isUsable,onDisconnect:t=>Y(e.id),onSelect:t=>e.configuration.isUsable?o.value=e.id:null,onTest:t=>Z(e.id),"onUpdate:apiKey":t=>Q(e.id,t),"onUpdate:endpointUrl":t=>X(e.id,t),"onUpdate:model":t=>$(e.id,t)},null,8,["available-models","can-edit","configuration","is-disconnecting","is-testing","provider","selected","usable-as-default","onDisconnect","onSelect","onTest","onUpdate:apiKey","onUpdate:endpointUrl","onUpdate:model"]))),128))],8,_),Object(n["unref"])(v)?Object(n["createCommentVNode"])("",!0):(Object(n["openBlock"])(),Object(n["createBlock"])(Object(n["unref"])(a["Alert"]),{key:0,class:"ai-providers-default-warning",severity:"warning"},{default:Object(n["withCtx"])(()=>[Object(n["createTextVNode"])(Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_NoDefaultProviderWarning")),1)]),_:1}))]),Object(n["unref"])(f)?(Object(n["openBlock"])(),Object(n["createElementBlock"])("section",D,[Object(n["createElementVNode"])("h4",w,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_DefaultCapabilityLevel")),1),Object(n["createElementVNode"])("p",U,Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("AIProviders_DefaultCapabilityLevelHelp")),1),Object(n["createElementVNode"])("div",{"aria-label":Object(n["unref"])(a["translate"])("AIProviders_DefaultCapabilityLevel"),class:"ai-providers-capability-cards",role:"radiogroup"},[(Object(n["openBlock"])(!0),Object(n["createElementBlock"])(n["Fragment"],null,Object(n["renderList"])(Object(n["unref"])(m),e=>(Object(n["openBlock"])(),Object(n["createElementBlock"])("label",{key:e.id,class:Object(n["normalizeClass"])([{"is-selected":l.value===e.id},"ai-providers-capability-card"])},[Object(n["createElementVNode"])("div",T,[Object(n["withDirectives"])(Object(n["createElementVNode"])("input",{"onUpdate:modelValue":O[0]||(O[0]=e=>l.value=e),value:e.id,name:"defaultCapabilityLevel",type:"radio"},null,8,M),[[n["vModelRadio"],l.value]]),Object(n["createElementVNode"])("span",K,Object(n["toDisplayString"])(e.label),1)]),e.description?(Object(n["openBlock"])(),Object(n["createElementBlock"])("div",H,Object(n["toDisplayString"])(e.description),1)):Object(n["createCommentVNode"])("",!0)],2))),128))],8,x)])):Object(n["createCommentVNode"])("",!0)])),[[Object(n["unref"])(c["Form"])]])]),_:1})):Object(n["createCommentVNode"])("",!0),t.value?(Object(n["openBlock"])(),Object(n["createElementBlock"])("div",L,[Object(n["createElementVNode"])("button",{disabled:i.value||!Object(n["unref"])(y),class:"btn ai-providers-cancel",type:"button",onClick:O[1]||(O[1]=e=>ee())},Object(n["toDisplayString"])(Object(n["unref"])(a["translate"])("General_Cancel")),9,F),Object(n["createVNode"])(Object(n["unref"])(c["SaveButton"]),{disabled:!Object(n["unref"])(y),saving:i.value,onConfirm:O[2]||(O[2]=e=>te())},null,8,["disabled","saving"])])):Object(n["createCommentVNode"])("",!0)]))}}),z=(r("20f9"),q)}})}));
+//# sourceMappingURL=AIProviders.umd.min.js.map
\ No newline at end of file
diff --git a/vue/dist/umd.metadata.json b/vue/dist/umd.metadata.json
new file mode 100644
index 0000000..dce4477
--- /dev/null
+++ b/vue/dist/umd.metadata.json
@@ -0,0 +1,6 @@
+{
+  "dependsOn": [
+    "CoreHome",
+    "CorePluginsAdmin"
+  ]
+}
\ No newline at end of file
diff --git a/vue/src/ManageAIProviders.vue b/vue/src/ManageAIProviders.vue
new file mode 100644
index 0000000..7c86e4d
--- /dev/null
+++ b/vue/src/ManageAIProviders.vue
@@ -0,0 +1,644 @@
+<!--
+  Matomo - free/libre analytics platform
+
+  @link    https://matomo.org
+  @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+-->
+
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue';
+import {
+  ActivityIndicator,
+  AjaxHelper,
+  Alert,
+  ContentBlock,
+  EnrichedHeadline,
+  NotificationsStore,
+  translate,
+} from 'CoreHome';
+import { Form as vForm, SaveButton } from 'CorePluginsAdmin';
+import ProviderCard from './components/ProviderCard.vue';
+import type {
+  CapabilityLevelOption,
+  ProviderConfiguration,
+  Settings,
+  TestConnectionResponse,
+} from './types';
+
+const settings = ref<Settings | null>(null);
+const isLoading = ref(false);
+const isSaving = ref(false);
+const defaultProviderId = ref('');
+const defaultCapabilityLevel = ref('');
+const providerConfigurations = ref<Record<string, ProviderConfiguration>>({});
+// Models discovered per provider from the last "test connection"/refresh, used
+// to populate the model picker.
+const availableModels = ref<Record<string, string[]>>({});
+const testingProviders = ref<Record<string, boolean>>({});
+const disconnectingProviders = ref<Record<string, boolean>>({});
+
+const providers = computed(() => settings.value?.providers || []);
+const hasUsableProvider = computed(() => providers.value.some(
+  (provider) => provider.configuration.isUsable,
+));
+const canEditCapabilityLevel = computed(() => !!settings.value?.canEditCapabilityLevel);
+const canEditProviderConfiguration = computed(() => !!settings.value?.canEditProviderConfiguration);
+
+// Snapshot of the saved state, used to detect unsaved changes.
+const savedSnapshot = ref('');
+
+const capabilityLevelOptions = computed<CapabilityLevelOption[]>(() => {
+  const capabilityLevels = settings.value?.capabilityLevels || {};
+
+  return Object.entries(capabilityLevels).map(([id, keys]) => ({
+    id,
+    label: translate(keys.label),
+    description: keys.description ? translate(keys.description) : '',
+  }));
+});
+
+// Serializes everything the user can edit, so it can be compared to the saved snapshot.
+function serializeEditableState() {
+  return JSON.stringify({
+    defaultProviderId: defaultProviderId.value,
+    defaultCapabilityLevel: defaultCapabilityLevel.value,
+    providerConfigurations: providerConfigurations.value,
+  });
+}
+
+const hasUnsavedChanges = computed(() => (
+  !!settings.value && serializeEditableState() !== savedSnapshot.value
+));
+
+/**
+ * Applies the given settings to the component state.
+ * @param nextSettings
+ */
+function applySettings(nextSettings: Settings) {
+  settings.value = nextSettings;
+  defaultProviderId.value = nextSettings.defaultProviderId;
+  defaultCapabilityLevel.value = nextSettings.defaultCapabilityLevel;
+
+  const nextProviderConfigurations: Record<string, ProviderConfiguration> = {};
+  nextSettings.providers.forEach((provider) => {
+    const savedModel = provider.configuration.model || '';
+    nextProviderConfigurations[provider.id] = {
+      apiKey: '',
+      endpointUrl: provider.configuration.endpointUrl || '',
+      model: savedModel,
+    };
+  });
+  providerConfigurations.value = nextProviderConfigurations;
+  availableModels.value = {};
+
+  // Capture the freshly applied state as the baseline for unsaved-change detection.
+  savedSnapshot.value = serializeEditableState();
+}
+
+function markProviderUsable(providerId: string) {
+  if (!settings.value) {
+    return;
+  }
+
+  const provider = settings.value.providers.find((p) => p.id === providerId);
+  if (provider) {
+    provider.configuration = {
+      ...provider.configuration,
+      hasApiKey: true,
+      isUsable: true,
+    };
+  }
+
+  if (!defaultProviderId.value) {
+    defaultProviderId.value = providerId;
+  }
+}
+
+function getCleanErrorMessage(error: unknown) {
+  let message = '';
+
+  if (error && typeof error === 'object' && 'message' in error) {
+    message = `${(error as { message: string }).message}`;
+  } else {
+    message = `${error}`;
+  }
+
+  return message
+    .replace(/\s*#\d+\s+[\s\S]*$/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// Notification IDs may only contain word characters (alphanumerics + underscore),
+// see core/Notification/Manager.php::checkId(). Provider IDs can contain other
+// characters (e.g. hyphens), so sanitize before using them in a notification ID.
+function notificationId(id: string) {
+  return id.replace(/[^\w]/g, '_');
+}
+
+function showErrorNotification(error: unknown, id: string) {
+  const cleaned = getCleanErrorMessage(error);
+  const isUseful = cleaned && cleaned !== 'Something went wrong';
+  const message = isUseful
+    ? translate('AIProviders_RequestFailed', cleaned)
+    : translate('AIProviders_UnexpectedError');
+
+  return NotificationsStore.show({
+    message,
+    type: 'transient',
+    id,
+    context: 'error',
+  });
+}
+
+function updateModel(providerId: string, model: string) {
+  providerConfigurations.value[providerId] = {
+    ...providerConfigurations.value[providerId],
+    model,
+  };
+}
+
+async function fetchAvailableModels(providerId: string, showNotifications: boolean) {
+  testingProviders.value[providerId] = true;
+
+  try {
+    const response = await AjaxHelper.post<TestConnectionResponse>(
+      {
+        method: 'AIProviders.testConnection',
+      },
+      {
+        providerId,
+        providerConfiguration: JSON.stringify(providerConfigurations.value[providerId] || {}),
+      },
+      {
+        withTokenInUrl: true,
+        createErrorNotification: false,
+      },
+    );
+
+    markProviderUsable(providerId);
+
+    if (response.models && response.models.length) {
+      availableModels.value[providerId] = response.models;
+
+      // Default to the first discovered model when none is selected yet.
+      if (!providerConfigurations.value[providerId]?.model) {
+        updateModel(providerId, response.models[0]);
+      }
+    }
+
+    if (showNotifications) {
+      NotificationsStore.show({
+        message: translate(
+          'AIProviders_TestConnectionSuccess',
+          response.providerName,
+        ),
+        type: 'transient',
+        id: notificationId(`aiProvidersTest-${providerId}`),
+        context: 'success',
+      });
+    }
+  } catch (error) {
+    if (showNotifications) {
+      showErrorNotification(error, notificationId(`aiProvidersTestError-${providerId}`));
+    }
+  } finally {
+    testingProviders.value[providerId] = false;
+  }
+}
+
+async function loadSettings() {
+  isLoading.value = true;
+
+  try {
+    const response = await AjaxHelper.fetch<Settings>({
+      method: 'AIProviders.getSettings',
+    }, {
+      createErrorNotification: false,
+    });
+    applySettings(response);
+    response.providers
+      .filter((provider) => provider.supportsCustomEndpoint && provider.configuration.isUsable)
+      .forEach((provider) => {
+        fetchAvailableModels(provider.id, false);
+      });
+  } catch (error) {
+    showErrorNotification(error, 'aiProvidersLoadError');
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+function updateApiKey(providerId: string, apiKey: string) {
+  providerConfigurations.value[providerId] = {
+    ...providerConfigurations.value[providerId],
+    apiKey,
+  };
+}
+
+function updateEndpointUrl(providerId: string, endpointUrl: string) {
+  providerConfigurations.value[providerId] = {
+    ...providerConfigurations.value[providerId],
+    endpointUrl,
+  };
+  availableModels.value[providerId] = [];
+}
+
+async function disconnectProvider(providerId: string) {
+  disconnectingProviders.value[providerId] = true;
+
+  try {
+    const response = await AjaxHelper.post<Settings>(
+      {
+        method: 'AIProviders.disconnectProvider',
+      },
+      {
+        providerId,
+      },
+      {
+        withTokenInUrl: true,
+        createErrorNotification: false,
+      },
+    );
+    applySettings(response);
+
+    NotificationsStore.show({
+      message: translate('AIProviders_DisconnectSuccess'),
+      type: 'transient',
+      id: notificationId(`aiProvidersDisconnect-${providerId}`),
+      context: 'success',
+    });
+  } catch (error) {
+    showErrorNotification(error, notificationId(`aiProvidersDisconnectError-${providerId}`));
+  } finally {
+    disconnectingProviders.value[providerId] = false;
+  }
+}
+
+async function testConnection(providerId: string) {
+  await fetchAvailableModels(providerId, true);
+}
+
+function cancelChanges() {
+  if (settings.value) {
+    applySettings(settings.value);
+  }
+}
+
+/**
+ * Saves the current settings to the server.
+ */
+async function saveSettings() {
+  isSaving.value = true;
+
+  try {
+    const response = await AjaxHelper.post<Settings>(
+      {
+        method: 'AIProviders.saveSettings',
+      },
+      {
+        defaultProviderId: defaultProviderId.value,
+        defaultCapabilityLevel: defaultCapabilityLevel.value,
+        providerConfigurations: JSON.stringify(providerConfigurations.value),
+      },
+      {
+        withTokenInUrl: true,
+        createErrorNotification: false,
+      },
+    );
+    applySettings(response);
+
+    const notificationInstanceId = NotificationsStore.show({
+      message: translate('AIProviders_SettingsSaveSuccess'),
+      type: 'transient',
+      id: 'aiProvidersSettings',
+      context: 'success',
+    });
+    NotificationsStore.scrollToNotification(notificationInstanceId);
+  } catch (error) {
+    const notificationInstanceId = showErrorNotification(error, 'aiProvidersSettingsError');
+    NotificationsStore.scrollToNotification(notificationInstanceId);
+  } finally {
+    isSaving.value = false;
+  }
+}
+
+onMounted(loadSettings);
+</script>
+
+<template>
+  <div class="ai-providers-page">
+    <header class="ai-providers-page-header">
+      <h2 class="ai-providers-page-title">
+        <EnrichedHeadline>
+          {{ translate('AIProviders_MenuTitle') }}
+        </EnrichedHeadline>
+      </h2>
+      <p class="ai-providers-page-subtitle">
+        {{ translate('AIProviders_ConfigurationIntro') }}
+      </p>
+    </header>
+
+    <ActivityIndicator
+      v-if="isLoading"
+      :loading="isLoading"
+    />
+
+    <template v-else-if="settings">
+      <ContentBlock class="ai-providers-content">
+      <span
+        class="ai-providers-unsaved-changes"
+        :class="{ 'is-visible': hasUnsavedChanges }"
+      >
+        {{ translate('AIProviders_UnsavedChanges') }}
+      </span>
+      <div v-form class="ai-providers">
+        <Alert
+          v-if="!canEditProviderConfiguration"
+          severity="info"
+        >
+          {{ translate('AIProviders_ManagedConfigurationHelp') }}
+        </Alert>
+
+        <h3 class="ai-providers-defaults-title">
+          {{ translate('AIProviders_DefaultsTitle') }}
+        </h3>
+
+        <section class="ai-providers-section">
+          <h4 class="ai-providers-subsection-title">
+            {{ translate('AIProviders_DefaultProvider') }}
+          </h4>
+          <p class="ai-providers-section-help">
+            {{ translate('AIProviders_DefaultProviderHelp') }}
+          </p>
+
+          <div
+            :aria-label="translate('AIProviders_DefaultProvider')"
+            class="ai-providers-cards"
+            role="radiogroup"
+          >
+            <ProviderCard
+              v-for="provider in providers"
+              :key="provider.id"
+              :available-models="availableModels[provider.id] || []"
+              :can-edit="canEditProviderConfiguration"
+              :configuration="providerConfigurations[provider.id]"
+              :is-disconnecting="!!disconnectingProviders[provider.id]"
+              :is-testing="!!testingProviders[provider.id]"
+              :provider="provider"
+              :selected="defaultProviderId === provider.id"
+              :usable-as-default="provider.configuration.isUsable"
+              @disconnect="disconnectProvider(provider.id)"
+              @select="provider.configuration.isUsable ? defaultProviderId = provider.id : null"
+              @test="testConnection(provider.id)"
+              @update:api-key="updateApiKey(provider.id, $event)"
+              @update:endpoint-url="updateEndpointUrl(provider.id, $event)"
+              @update:model="updateModel(provider.id, $event)"
+            />
+          </div>
+
+          <Alert
+            v-if="!hasUsableProvider"
+            class="ai-providers-default-warning"
+            severity="warning"
+          >
+            {{ translate('AIProviders_NoDefaultProviderWarning') }}
+          </Alert>
+        </section>
+
+        <section
+          v-if="canEditCapabilityLevel"
+          class="ai-providers-section"
+        >
+          <h4 class="ai-providers-subsection-title">
+            {{ translate('AIProviders_DefaultCapabilityLevel') }}
+          </h4>
+          <p class="ai-providers-section-help">
+            {{ translate('AIProviders_DefaultCapabilityLevelHelp') }}
+          </p>
+
+          <div
+            :aria-label="translate('AIProviders_DefaultCapabilityLevel')"
+            class="ai-providers-capability-cards"
+            role="radiogroup"
+          >
+            <label
+              v-for="capability in capabilityLevelOptions"
+              :key="capability.id"
+              :class="{ 'is-selected': defaultCapabilityLevel === capability.id }"
+              class="ai-providers-capability-card"
+            >
+              <div class="ai-providers-capability-header">
+                <input
+                  v-model="defaultCapabilityLevel"
+                  :value="capability.id"
+                  name="defaultCapabilityLevel"
+                  type="radio"
+                />
+                <span class="ai-providers-capability-label">{{ capability.label }}</span>
+              </div>
+              <div
+                v-if="capability.description"
+                class="ai-providers-capability-description"
+              >
+                {{ capability.description }}
+              </div>
+            </label>
+          </div>
+        </section>
+      </div>
+      </ContentBlock>
+    </template>
+
+    <div
+      v-if="settings"
+      class="ai-providers-footer"
+    >
+      <button
+        :disabled="isSaving || !hasUnsavedChanges"
+        class="btn ai-providers-cancel"
+        type="button"
+        @click="cancelChanges()"
+      >
+        {{ translate('General_Cancel') }}
+      </button>
+      <SaveButton
+        :disabled="!hasUnsavedChanges"
+        :saving="isSaving"
+        @confirm="saveSettings()"
+      />
+    </div>
+  </div>
+</template>
+
+<style lang="less">
+.ai-providers-page {
+  position: relative;
+  --ai-providers-border: var(--theme-color-border-light);
+  --ai-providers-border-strong: var(--theme-color-border);
+  --ai-providers-accent: var(--theme-color-brand);
+  --ai-providers-text-muted: var(--theme-color-text-light);
+  --ai-providers-heading: var(--theme-color-headline-alternative);
+
+  h2, h3, h4 {
+    color: var(--ai-providers-heading);
+    margin: 0;
+    padding: 0;
+  }
+}
+
+.ai-providers-page-header {
+  margin-bottom: 24px;
+}
+
+.ai-providers-page-title {
+  font-size: 22px;
+  line-height: 1.3;
+}
+
+.ai-providers-page-subtitle {
+  color: var(--ai-providers-text-muted);
+  font-size: 14px;
+  line-height: 1.5;
+  margin: 4px 0 0;
+}
+
+.ai-providers-defaults-title {
+  font-size: 18px;
+  line-height: 1.4;
+  margin-bottom: 24px!important;
+}
+
+.ai-providers-subsection-title {
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.4;
+}
+
+.ai-providers-section + .ai-providers-section {
+  margin-top: 24px;
+  padding-top: 24px;
+  border-top: 1px solid var(--ai-providers-border);
+}
+
+.ai-providers-section-help {
+  color: var(--ai-providers-text-muted);
+  margin: 4px 0 16px;
+}
+
+.ai-providers-cards,
+.ai-providers-capability-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  gap: 16px;
+}
+
+.ai-providers-cards {
+  padding-top: 24px;
+  margin-top: 32px;
+}
+
+.ai-providers-default-warning {
+  margin-top: 16px;
+}
+
+.ai-providers-capability-card {
+  display: flex;
+  flex-direction: column;
+  padding: 16px;
+  background: var(--theme-color-background-contrast);
+  border: 1px solid var(--ai-providers-border);
+  border-radius: 6px;
+  cursor: pointer;
+  transition: border-color 120ms ease, box-shadow 120ms ease, background-color 120ms ease;
+
+  &:hover {
+    border-color: var(--ai-providers-border-strong);
+  }
+
+  &.is-selected {
+    border-color: var(--ai-providers-accent);
+    box-shadow: 0 0 0 1px var(--ai-providers-accent) inset;
+    background: var(--theme-color-background-tinyContrast);
+  }
+}
+
+.ai-providers-capability-header {
+  margin-bottom: 8px;
+}
+
+.ai-providers-capability-label {
+  color: var(--ai-providers-heading);
+  font-weight: 600;
+  font-size: 15px;
+}
+
+.ai-providers-capability-description {
+  color: var(--ai-providers-text-muted);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.ai-providers-content {
+  position: relative;
+}
+
+.ai-providers-unsaved-changes {
+  position: absolute;
+  top: 16px;
+  right: 16px;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--ai-providers-text-muted);
+  font-size: 12px;
+  font-style: italic;
+  visibility: hidden;
+  opacity: 0;
+  transition: opacity 150ms ease;
+
+  &::before {
+    content: '';
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: var(--ai-providers-accent);
+  }
+
+  &.is-visible {
+    visibility: visible;
+    opacity: 1;
+  }
+}
+
+.ai-providers-footer {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  align-items: center;
+  gap: 12px;
+  margin-top: 24px;
+}
+
+.ai-providers-cancel {
+  background: transparent;
+  color: var(--theme-color-text);
+  border: 1px solid var(--ai-providers-border-strong);
+  box-shadow: none;
+  transition: background-color 0.15s ease, border-color 0.15s ease;
+
+  &:hover,
+  &:focus {
+    background: var(--theme-color-background-tinyContrast);
+    border-color: var(--theme-color-text-light);
+    color: var(--theme-color-text);
+  }
+
+  &:disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+    background: transparent;
+    border-color: var(--ai-providers-border);
+  }
+}
+</style>
diff --git a/vue/src/components/ProviderCard.vue b/vue/src/components/ProviderCard.vue
new file mode 100644
index 0000000..8f769b1
--- /dev/null
+++ b/vue/src/components/ProviderCard.vue
@@ -0,0 +1,388 @@
+<!--
+  Matomo - free/libre analytics platform
+
+  @link    https://matomo.org
+  @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+-->
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { AutoClearPassword as vAutoClearPassword, translate } from 'CoreHome';
+import { Field } from 'CorePluginsAdmin';
+import type { Provider, ProviderConfiguration } from '../types';
+
+const props = defineProps<{
+  provider: Provider;
+  configuration: ProviderConfiguration | undefined;
+  availableModels: string[];
+  selected: boolean;
+  usableAsDefault: boolean;
+  canEdit: boolean;
+  isTesting: boolean;
+  isDisconnecting: boolean;
+}>();
+
+/* eslint-disable func-call-spacing, no-spaced-func */
+const emit = defineEmits<{
+  (e: 'select'): void;
+  (e: 'update:apiKey', value: string): void;
+  (e: 'update:endpointUrl', value: string): void;
+  (e: 'update:model', value: string): void;
+  (e: 'test'): void;
+  (e: 'disconnect'): void;
+}>();
+/* eslint-enable func-call-spacing, no-spaced-func */
+
+const hasPendingKey = computed(() => (props.configuration?.apiKey ?? '') !== '');
+const hasEndpointUrl = computed(() => (props.configuration?.endpointUrl ?? '') !== '');
+
+// Custom endpoints may run without a key, so reaching the server only needs the
+// URL; fixed hosted providers need a key (pending or already stored).
+const canTest = computed(() => (props.provider.supportsCustomEndpoint
+  ? hasEndpointUrl.value
+  : hasPendingKey.value || props.provider.configuration.hasApiKey));
+
+const modelOptions = computed(() => {
+  const options: Record<string, string> = {};
+  props.availableModels.forEach((model) => { options[model] = model; });
+  return options;
+});
+
+function selectProvider() {
+  if (props.usableAsDefault) {
+    emit('select');
+  }
+}
+</script>
+
+<template>
+  <div
+    :aria-checked="selected"
+    :aria-disabled="!usableAsDefault"
+    :class="{ 'is-selected': selected, 'is-not-usable': !usableAsDefault }"
+    class="ai-providers-card"
+    role="radio"
+    :tabindex="usableAsDefault ? 0 : -1"
+    @click="selectProvider()"
+    @keydown.enter.prevent="selectProvider()"
+    @keydown.space.prevent="selectProvider()"
+  >
+    <div
+      v-if="selected"
+      class="ai-providers-card-default"
+    >
+      {{ translate('AIProviders_DefaultBadge') }}
+    </div>
+
+    <div class="ai-providers-card-inner">
+      <div class="ai-providers-card-header">
+        <span class="ai-providers-card-name">{{ provider.name }}</span>
+      </div>
+
+      <p class="ai-providers-card-description">
+        {{ translate(provider.description) }}
+      </p>
+
+      <template v-if="canEdit">
+        <Field
+          v-if="provider.supportsCustomEndpoint"
+          :model-value="configuration?.endpointUrl"
+          :name="`endpointUrl-${provider.id}`"
+          :title="translate('AIProviders_EndpointUrl')"
+          :placeholder="translate('AIProviders_EndpointUrlPlaceholder')"
+          autocomplete="off"
+          full-width
+          uicontrol="text"
+          @update:model-value="emit('update:endpointUrl', `${$event}`)"
+        />
+
+        <Field
+          v-auto-clear-password
+          :model-value="configuration?.apiKey"
+          :name="`apiKey-${provider.id}`"
+          :placeholder="provider.configuration.hasApiKey
+            ? translate('AIProviders_ApiKeyAlreadyConfiguredPlaceholder')
+            : translate('AIProviders_ApiKeyPlaceholder')"
+          :title="translate('AIProviders_ApiKey')"
+          autocomplete="new-password"
+          full-width
+          uicontrol="password"
+          @update:model-value="emit('update:apiKey', `${$event}`)"
+        />
+
+        <div
+          v-if="provider.supportsCustomEndpoint"
+          class="ai-providers-card-model"
+        >
+          <Field
+            v-if="availableModels.length"
+            :model-value="configuration?.model"
+            :name="`model-${provider.id}`"
+            :title="translate('AIProviders_Model')"
+            :options="modelOptions"
+            full-width
+            uicontrol="select"
+            @update:model-value="emit('update:model', `${$event}`)"
+          />
+          <p
+            v-else
+            class="ai-providers-card-model-help"
+          >
+            {{ translate('AIProviders_ClickTestConnectionToShowAvailableModels') }}
+          </p>
+          <button
+            v-if="availableModels.length"
+            class="btn-flat ai-providers-refresh-models"
+            type="button"
+            :disabled="isTesting || !canTest"
+            :title="translate('AIProviders_RefreshModels')"
+            @click.prevent.stop="emit('test')"
+          >
+            <span
+              aria-hidden="true"
+              class="icon icon-reload"
+            ></span>
+            {{ translate('AIProviders_RefreshModels') }}
+          </button>
+        </div>
+
+        <div
+          :class="{ 'is-connected': provider.configuration.isUsable }"
+          class="ai-providers-card-status"
+        >
+          <span
+            aria-hidden="true"
+            class="icon ai-providers-status-icon"
+            :class="provider.configuration.isUsable ? 'icon-ok' : 'icon-minus'"
+          ></span>
+          {{
+            provider.configuration.isUsable
+              ? translate('AIProviders_StatusConnected')
+              : translate('AIProviders_StatusNotConnected')
+          }}
+        </div>
+
+        <div class="ai-providers-card-actions">
+          <button
+            class="btn btn-small"
+            type="button"
+            :disabled="isTesting || !canTest"
+            @click.prevent.stop="emit('test')"
+          >
+            {{
+              isTesting
+                ? translate('AIProviders_TestingConnection')
+                : translate('AIProviders_TestConnection')
+            }}
+          </button>
+          <button
+            class="btn-flat"
+            type="button"
+            :disabled="isDisconnecting || !provider.configuration.hasApiKey"
+            @click.prevent.stop="emit('disconnect')"
+          >
+            {{
+              isDisconnecting
+                ? translate('AIProviders_Disconnecting')
+                : translate('AIProviders_Disconnect')
+            }}
+          </button>
+        </div>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style lang="less">
+.ai-providers-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--theme-color-background-contrast);
+  border: 1px solid var(--ai-providers-border);
+  border-radius: 6px;
+  cursor: pointer;
+  transition: border-color 120ms ease;
+
+  &:hover:not(.is-not-usable):not(.is-selected) {
+    border-color: var(--ai-providers-border-strong);
+  }
+
+  &.is-selected {
+    background: var(--ai-providers-accent);
+    border-color: var(--ai-providers-accent);
+    margin-top: -24px;
+  }
+
+  &.is-not-usable {
+    cursor: default;
+  }
+
+  &:focus,
+  &:focus-visible,
+  &:active {
+    outline: none;
+    box-shadow: none;
+  }
+
+  // Reset Materialize wrapper margins that would otherwise double-stack with
+  // our own form-group / card-description spacing.
+  .form-group {
+    margin-bottom: 12px;
+    border: 0;
+  }
+
+  .input-field {
+    margin-top: 0;
+    margin-bottom: 0;
+  }
+
+  .matomo-form-field {
+    border: 0;
+    margin-left: 0;
+    margin-right: 0;
+    margin-top: 32px;
+
+    > .col {
+      padding-left: 0 !important;
+      padding-right: 0 !important;
+    }
+  }
+
+  .input-field > label,
+  .input-field.col > label {
+    left: 0 !important;
+  }
+
+  .matomo-field-select > label,
+  .matomo-field-select > .select-wrapper + label {
+    left: 0 !important;
+  }
+
+  .input-field > input {
+    padding-left: 0;
+    margin-left: 0;
+    width: 100%;
+    box-sizing: border-box;
+  }
+}
+
+.ai-providers-card-inner {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  padding: 16px;
+}
+
+.ai-providers-card.is-selected .ai-providers-card-inner {
+  background: var(--theme-color-background-contrast);
+  // Matches the card's 6px radius at the top; bottom corners are 1px tighter
+  // to sit cleanly inside the 1px accent frame (margin: 0 1px 1px).
+  border-radius: 6px 6px 5px 5px;
+  margin: 0 1px 1px;
+}
+
+.ai-providers-card-default {
+  min-height: 24px;
+  padding: 5px 12px;
+  background-color: var(--ai-providers-accent);
+  color: var(--theme-color-brand-contrast);
+  font-size: 10px;
+  font-weight: 700;
+  line-height: 1.5;
+  text-transform: uppercase;
+}
+
+.ai-providers-card-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 8px;
+}
+
+.ai-providers-card-name {
+  color: var(--ai-providers-heading);
+  font-weight: 600;
+  font-size: 15px;
+}
+
+.ai-providers-card-description {
+  color: var(--ai-providers-text-muted);
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 0 0 16px;
+}
+
+.ai-providers-refresh-models {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 4px;
+  padding: 0;
+  font-size: 12px;
+
+  &[disabled] {
+    pointer-events: none;
+    cursor: not-allowed;
+    color: var(--theme-color-text-on-disabled);
+  }
+
+  .icon-reload {
+    font-size: 12px;
+  }
+}
+
+.ai-providers-card-model-help {
+  color: var(--ai-providers-text-muted);
+  font-size: 12px;
+  line-height: 1.5;
+  margin: 0;
+}
+
+.ai-providers-card-status {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 4px 0 0;
+  color: var(--ai-providers-text-muted);
+  font-size: 13px;
+  line-height: 1.5;
+
+  &.is-connected {
+    color: var(--ai-providers-accent);
+
+    .ai-providers-status-icon {
+      color: var(--ai-providers-accent);
+    }
+  }
+}
+
+.ai-providers-status-icon {
+  font-size: 14px;
+  line-height: 1;
+  color: var(--ai-providers-border-strong);
+  flex: none;
+}
+
+.ai-providers-card-actions {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  justify-content: flex-start;
+  gap: 12px;
+  margin-top: auto;
+  padding-top: 16px;
+
+  .btn,
+  .btn-flat {
+    white-space: nowrap;
+  }
+
+  .btn-flat[disabled] {
+    pointer-events: none;
+    cursor: not-allowed;
+    color: var(--theme-color-text-on-disabled);
+  }
+}
+</style>
diff --git a/vue/src/index.ts b/vue/src/index.ts
new file mode 100644
index 0000000..41fbd81
--- /dev/null
+++ b/vue/src/index.ts
@@ -0,0 +1,8 @@
+/*!
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+export { default as ManageAIProviders } from './ManageAIProviders.vue';
diff --git a/vue/src/types.ts b/vue/src/types.ts
new file mode 100644
index 0000000..0f40bac
--- /dev/null
+++ b/vue/src/types.ts
@@ -0,0 +1,52 @@
+/*!
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+export interface ProviderConfiguration {
+  apiKey: string;
+  endpointUrl: string;
+  model: string;
+}
+
+export interface Provider {
+  id: string;
+  name: string;
+  description: string;
+  supportsCustomEndpoint: boolean;
+  defaultModel: string;
+  configuration: {
+    hasApiKey: boolean;
+    endpointUrl: string;
+    model: string;
+    isUsable: boolean;
+  };
+}
+
+export interface CapabilityLevel {
+  label: string;
+  description: string;
+}
+
+export interface Settings {
+  defaultProviderId: string;
+  defaultCapabilityLevel: string;
+  canEditProviderConfiguration: boolean;
+  canEditCapabilityLevel: boolean;
+  capabilityLevels: Record<string, CapabilityLevel>;
+  providers: Provider[];
+}
+
+export interface CapabilityLevelOption {
+  id: string;
+  label: string;
+  description: string;
+}
+
+export interface TestConnectionResponse {
+  providerId: string;
+  providerName: string;
+  models: string[];
+}