Merge pull request #99 from tarosky/feature/configurable-ai-model-temperature

AI Overview: モデル選択UIとtemperature設定を追加（複数コネクタ対応・temperature 400修正）

Author: fumikito

.wp-env.json

@@ -2,7 +2,9 @@
 	"phpVersion": "7.4",
 	"plugins": [
 		".",
-		"https://downloads.wordpress.org/plugin/query-monitor.latest-stable.zip"
+		"https://downloads.wordpress.org/plugin/query-monitor.latest-stable.zip",
+		"https://downloads.wordpress.org/plugin/ai-provider-for-google.latest-stable.zip",
+		"https://downloads.wordpress.org/plugin/ai-provider-for-anthropic.latest-stable.zip"
 	],
 	"themes": [
 		"https://downloads.wordpress.org/theme/twentytwentyone.latest-stable.zip"

README.md

@@ -3,7 +3,7 @@
 Contributors: tarosky, hametuha, Takahashi_Fumiki    
 Tags: faq,help  
 Tested up to: 7.0  
-Stable Tag: 2.3.1  
+Stable Tag: 2.4.0  
 License: GPL 3.0 or later  
 License URI: https://www.gnu.org/licenses/gpl-3.0.html
 
@@ -111,6 +111,14 @@ You can contribute to our github repo. Any [issues](https://github.com/tarosky/h
 
 ## Changelog
 
+For full release notes of each version, see [GitHub Releases](https://github.com/tarosky/hamelp/releases).
+
+### 2.4.0
+
+- Add an **AI Model** setting to pin the provider/model used for AI Overview. Only configured connectors (WordPress 7.0 Settings → Connectors) are listed, and if the chosen model later becomes unavailable it falls back to auto-selection instead of failing.
+- Change the default **temperature** to omitted. Some models (e.g. Claude Opus/Sonnet) reject a temperature and returned a 400 error when auto-selected; omitting is safe for every model. Set a value on the settings page only if you need it.
+- Add `hamelp_ai_model` and `hamelp_ai_temperature` filters to override the model and temperature from code.
+
 ### 2.3.1
 
 - User can change the reference prefix (Ref. 1).

app/Hametuha/Hamelp/Hooks/Settings.php

@@ -8,6 +8,7 @@
 namespace Hametuha\Hamelp\Hooks;
 
 use Hametuha\Hamelp\Pattern\Singleton;
+use Hametuha\Hamelp\Services\AiModelResolver;
 use Hametuha\Hamelp\Services\FaqCatalogBuilder;
 
 /**
@@ -223,6 +224,52 @@ public function register_settings() {
 			]
 		);
 
+		// Preferred AI model (auto-select by default; validated against the live registry).
+		register_setting(
+			self::OPTION_GROUP,
+			AiModelResolver::OPTION_MODEL,
+			[
+				'type'              => 'string',
+				'sanitize_callback' => [ $this, 'sanitize_model' ],
+				'default'           => '',
+			]
+		);
+
+		add_settings_field(
+			AiModelResolver::OPTION_MODEL,
+			__( 'AI Model', 'hamelp' ),
+			[ $this, 'render_model_select' ],
+			self::PAGE_SLUG,
+			'hamelp_ai_section',
+			[
+				'option_name' => AiModelResolver::OPTION_MODEL,
+			]
+		);
+
+		// Sampling temperature (blank = omit, which is the default and safe for all models).
+		register_setting(
+			self::OPTION_GROUP,
+			AiModelResolver::OPTION_TEMPERATURE,
+			[
+				'type'              => 'string',
+				'sanitize_callback' => [ $this, 'sanitize_temperature' ],
+				'default'           => '',
+			]
+		);
+
+		add_settings_field(
+			AiModelResolver::OPTION_TEMPERATURE,
+			__( 'Temperature', 'hamelp' ),
+			[ $this, 'render_text' ],
+			self::PAGE_SLUG,
+			'hamelp_ai_section',
+			[
+				'option_name' => AiModelResolver::OPTION_TEMPERATURE,
+				'default'     => '',
+				'description' => __( 'Sampling temperature between 0 and 2 (e.g. 0.3). Leave blank (the default) to omit it entirely — omitting is safe for every model, whereas some models (e.g. Claude Opus) return an error if a temperature is supplied.', 'hamelp' ),
+			]
+		);
+
 		// Citation reference label (customizable, translatable).
 		register_setting(
 			self::OPTION_GROUP,
@@ -555,6 +602,91 @@ public function sanitize_mode( $value ) {
 		return in_array( $value, $allowed, true ) ? $value : 'conversation';
 	}
 
+	/**
+	 * Render the AI model select field.
+	 *
+	 * Choices are built from the live registry so only currently configured
+	 * providers/models appear. Warns when a previously saved model is no longer
+	 * available (e.g. its connector was disabled outside Hamelp).
+	 *
+	 * @param array $args Field arguments (option_name).
+	 */
+	public function render_model_select( array $args ) {
+		if ( ! AiModelResolver::is_ai_available() ) {
+			printf(
+				'<p class="description">%s</p>',
+				esc_html__( 'No AI provider is available. Connect one in Settings → Connectors, then reload this page.', 'hamelp' )
+			);
+			return;
+		}
+
+		$value   = (string) get_option( $args['option_name'], '' );
+		$choices = [ '' => __( 'Auto (recommended)', 'hamelp' ) ] + AiModelResolver::get_available_models();
+
+		printf( '<select name="%1$s" id="%1$s">', esc_attr( $args['option_name'] ) );
+		foreach ( $choices as $key => $label ) {
+			printf(
+				'<option value="%s" %s>%s</option>',
+				esc_attr( $key ),
+				selected( $value, $key, false ),
+				esc_html( $label )
+			);
+		}
+		echo '</select>';
+
+		if ( AiModelResolver::is_stored_model_stale() ) {
+			printf(
+				'<p class="description" style="color:#b32d2e;">%s</p>',
+				esc_html__( 'The previously selected model is no longer available (its connector may have been disabled). Auto-selection is being used until you choose an available model.', 'hamelp' )
+			);
+		}
+
+		printf(
+			'<p class="description">%s</p>',
+			esc_html__( 'Pin the provider/model used for AI Overview. Only configured connectors are listed. If the chosen model becomes unavailable, Hamelp falls back to auto-selection instead of failing.', 'hamelp' )
+		);
+	}
+
+	/**
+	 * Sanitize the AI model option.
+	 *
+	 * Accepts only the empty string (auto) or a currently available
+	 * `provider_id|model_id` value; anything else resets to auto.
+	 *
+	 * @param string $value Submitted value.
+	 * @return string A valid model key, or empty string for auto-select.
+	 */
+	public function sanitize_model( $value ) {
+		$value = (string) $value;
+		if ( '' === $value ) {
+			return '';
+		}
+		$available = AiModelResolver::get_available_models();
+		return isset( $available[ $value ] ) ? $value : '';
+	}
+
+	/**
+	 * Sanitize the temperature option.
+	 *
+	 * Empty string is preserved (omit the parameter). A numeric value is clamped
+	 * to the 0–2 range. Any other input falls back to the default.
+	 *
+	 * @param string $value Submitted value.
+	 * @return string Sanitized temperature, or empty string to omit it.
+	 */
+	public function sanitize_temperature( $value ) {
+		$value = trim( (string) $value );
+		if ( '' === $value ) {
+			return '';
+		}
+		if ( ! is_numeric( $value ) ) {
+			return '0.3';
+		}
+		$float = (float) $value;
+		$float = max( 0.0, min( 2.0, $float ) );
+		return (string) $float;
+	}
+
 	/**
 	 * Render a checkbox field.
 	 *

app/Hametuha/Hamelp/Services/AiModelResolver.php

@@ -0,0 +1,156 @@
+<?php
+/**
+ * AI model resolution and enumeration.
+ *
+ * @package hamelp
+ */
+
+namespace Hametuha\Hamelp\Services;
+
+use WordPress\AiClient\AiClient;
+use WordPress\AiClient\Providers\Models\DTO\ModelRequirements;
+use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
+
+/**
+ * Bridges the WordPress 7.0 AI client registry with Hamelp settings.
+ *
+ * Everything here reads the *live* registry so that connectors toggled on or
+ * off outside Hamelp (Settings → Connectors) are always reflected. A stored
+ * model selection is never trusted blindly: it is validated against the
+ * currently configured providers on every request, and a selection that no
+ * longer exists silently falls back to auto-selection rather than pinning a
+ * dead model endpoint.
+ */
+class AiModelResolver {
+
+	/**
+	 * Option holding the preferred model, formatted `provider_id|model_id`.
+	 *
+	 * Empty string means "auto-select".
+	 *
+	 * @var string
+	 */
+	const OPTION_MODEL = 'hamelp_ai_model';
+
+	/**
+	 * Option holding the sampling temperature.
+	 *
+	 * Empty string means "omit the parameter" and is the default, since omitting
+	 * is safe for every model while some (e.g. Claude Opus) reject a temperature.
+	 *
+	 * @var string
+	 */
+	const OPTION_TEMPERATURE = 'hamelp_ai_temperature';
+
+	/**
+	 * Separator between provider id and model id in the stored option value.
+	 *
+	 * @var string
+	 */
+	const SEPARATOR = '|';
+
+	/**
+	 * Whether the WordPress AI client is available in this environment.
+	 *
+	 * @return bool
+	 */
+	public static function is_ai_available(): bool {
+		return function_exists( 'wp_ai_client_prompt' )
+			&& function_exists( 'wp_supports_ai' )
+			&& wp_supports_ai()
+			&& class_exists( '\WordPress\AiClient\AiClient' );
+	}
+
+	/**
+	 * Enumerate configured providers/models capable of text generation.
+	 *
+	 * Only providers that are currently configured (connector enabled and
+	 * authenticated) are returned, so the list mirrors the live registry.
+	 *
+	 * @return array<string, string> Map of `provider_id|model_id` => `Provider / Model` label.
+	 */
+	public static function get_available_models(): array {
+		if ( ! self::is_ai_available() ) {
+			return [];
+		}
+
+		$models = [];
+		try {
+			$registry     = AiClient::defaultRegistry();
+			$requirements = new ModelRequirements( [ CapabilityEnum::textGeneration() ], [] );
+			foreach ( $registry->findModelsMetadataForSupport( $requirements ) as $provider_models ) {
+				$provider      = $provider_models->getProvider();
+				$provider_id   = $provider->getId();
+				$provider_name = $provider->getName();
+				foreach ( $provider_models->getModels() as $model ) {
+					$key            = $provider_id . self::SEPARATOR . $model->getId();
+					$models[ $key ] = sprintf( '%s / %s', $provider_name, $model->getName() );
+				}
+			}
+		} catch ( \Throwable $e ) {
+			// Registry not ready or provider misbehaving: degrade to auto-select.
+			return [];
+		}
+
+		return $models;
+	}
+
+	/**
+	 * Resolve the effective model preference for a generation request.
+	 *
+	 * Returns a `[ provider_id, model_id ]` pair suitable for the AI client's
+	 * model preference API, or null to let the client auto-select. A stored
+	 * selection that is no longer available resolves to null.
+	 *
+	 * @return array{0: string, 1: string}|null
+	 */
+	public static function get_effective_model_preference(): ?array {
+		$stored = (string) get_option( self::OPTION_MODEL, '' );
+		if ( '' === $stored ) {
+			return null;
+		}
+
+		// Validate against the live registry so a removed/disabled model is dropped.
+		$available = self::get_available_models();
+		if ( ! isset( $available[ $stored ] ) ) {
+			return null;
+		}
+
+		$parts = explode( self::SEPARATOR, $stored, 2 );
+		if ( 2 !== count( $parts ) || '' === $parts[0] || '' === $parts[1] ) {
+			return null;
+		}
+
+		return [ $parts[0], $parts[1] ];
+	}
+
+	/**
+	 * Resolve the effective temperature for a generation request.
+	 *
+	 * @return float|null Temperature, or null to omit the parameter entirely.
+	 */
+	public static function get_effective_temperature(): ?float {
+		$stored = get_option( self::OPTION_TEMPERATURE, '' );
+		if ( '' === $stored || null === $stored ) {
+			return null;
+		}
+		return (float) $stored;
+	}
+
+	/**
+	 * Whether a stored model selection has become unavailable.
+	 *
+	 * Used by the settings screen to warn that a previously chosen model is no
+	 * longer offered (e.g. its connector was disabled outside Hamelp).
+	 *
+	 * @return bool
+	 */
+	public static function is_stored_model_stale(): bool {
+		$stored = (string) get_option( self::OPTION_MODEL, '' );
+		if ( '' === $stored ) {
+			return false;
+		}
+		$available = self::get_available_models();
+		return ! isset( $available[ $stored ] );
+	}
+}

app/Hametuha/Hamelp/Services/FaqSearchService.php

@@ -74,9 +74,43 @@ public function generate_overview( string $query, array $history = [] ) {
 		}
 		$messages[] = new UserMessage( [ new MessagePart( $query ) ] );
 
-		$response = wp_ai_client_prompt( $messages )
-			->using_system_instruction( $system_prompt )
-			->using_temperature( 0.3 )
+		$prompt = wp_ai_client_prompt( $messages )
+			->using_system_instruction( $system_prompt );
+
+		/**
+		 * Filter the preferred AI model for FAQ overview generation.
+		 *
+		 * The default is resolved from the Hamelp settings screen and validated
+		 * against the live provider registry, so a selection whose connector was
+		 * disabled outside Hamelp falls back to auto-selection. Return a value to
+		 * override. Accepted forms mirror the AI client's model preference API:
+		 *
+		 * - a model ID string, e.g. `'gemini-2.5-flash'`
+		 * - a `[ provider_id, model_id ]` pair, e.g. `[ 'anthropic', 'claude-opus-4-1' ]`
+		 *
+		 * @param string|array|null $model Preferred model. Null auto-selects.
+		 */
+		$model = apply_filters( 'hamelp_ai_model', AiModelResolver::get_effective_model_preference() );
+		if ( ! empty( $model ) ) {
+			$prompt = $prompt->using_model_preference( $model );
+		}
+
+		/**
+		 * Filter the sampling temperature for FAQ overview generation.
+		 *
+		 * The default is resolved from the Hamelp settings screen. Return `null`
+		 * to omit the temperature entirely. This is required for models that
+		 * reject the parameter (e.g. Claude Opus responds with a 400 error when a
+		 * temperature is supplied).
+		 *
+		 * @param float|null $temperature Sampling temperature. Null omits it.
+		 */
+		$temperature = apply_filters( 'hamelp_ai_temperature', AiModelResolver::get_effective_temperature() );
+		if ( null !== $temperature ) {
+			$prompt = $prompt->using_temperature( (float) $temperature );
+		}
+
+		$response = $prompt
 			->as_json_response()
 			->generate_text();