peptide-repo/prautoblogger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(models): OpenRouter model registry + interface + cron wiring (model-picker commit 1) (#13)

Browse Source 
Foundation for the smart model picker. Fetches, normalizes, and caches
the OpenRouter model list (/api/v1/models — free, unauthenticated).
Daily refresh via the existing prautoblogger_daily_generation cron with
12h idempotency. 3-retry exponential backoff on transient failures;
serves last-good option payload when stale-and-fetch-fails.

New files:
- interface-model-registry.php — Phase 3-aware contract (94 lines)
- class-openrouter-model-registry.php — fetch + cache + query (226 lines)
- class-openrouter-model-normalizer.php — raw → standardized (114 lines)

Zero-coupling: no PRAUTOBLOGGER_* constants inside the service classes.
Config injected via constructor. Phase 2 lift into a shared Composer
package requires only namespace rename, zero internal edits.

Cost impact: $0/month (free endpoint, no LLM tokens).

Agent-Session: cowork-2026-04-16-model-picker-commit1

Co-authored-by: peptiderepo <peptiderepo@users.noreply.github.com>
This commit is contained in:
peptiderepo
2026-04-16 16:50:12 +07:00
committed by GitHub
parent 33413cf678
commit be5c659999
8 changed files with 741 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
includes/services/class-openrouter-model-normalizer.php Normal file
View File

@@ -0,0 +1,114 @@
<?php
declare(strict_types=1);
/**
* Normalizes raw OpenRouter model data into the standardized record shape.
*
* Extracted from PRAutoBlogger_OpenRouter_Model_Registry so both classes stay
* under the 300-line cap. The registry orchestrates fetch + cache; this helper
* owns the mapping logic.
*
* Triggered by: PRAutoBlogger_OpenRouter_Model_Registry::refresh().
* Dependencies: None — pure data transformation, no I/O.
*
* @see services/class-openrouter-model-registry.php — Sole consumer.
* @see interface-model-registry.php — Defines the normalized record shape.
* @see ARCHITECTURE.md — Capability vocabulary.
*/
class PRAutoBlogger_OpenRouter_Model_Normalizer {
/**
* Standardized capability vocabulary (CTO-locked). Derived from OpenRouter's
* `architecture.input_modalities` + `architecture.output_modalities`.
*
* @var array<string, array{in: string[], out: string[]}>
*/
private const CAPABILITY_MAP = [
'text→text' => [ 'in' => [ 'text' ], 'out' => [ 'text' ] ],
'text+image→text' => [ 'in' => [ 'text', 'image' ], 'out' => [ 'text' ] ],
'text+audio→text' => [ 'in' => [ 'text', 'audio' ], 'out' => [ 'text' ] ],
'text→image' => [ 'in' => [ 'text' ], 'out' => [ 'image' ] ],
'text→audio' => [ 'in' => [ 'text' ], 'out' => [ 'audio' ] ],
'text→video' => [ 'in' => [ 'text' ], 'out' => [ 'video' ] ],
'text→embedding' => [ 'in' => [ 'text' ], 'out' => [ 'embedding' ] ],
];
/**
* Normalize raw OpenRouter model records into the standardized shape.
*
* Unknown architectures degrade to 'text→text' capability — never throws.
* Pricing is converted from per-token (OpenRouter format) to per-million.
*
* @param array $raw_models Raw 'data' array from the OpenRouter API.
*
* @return array<int, array{
* id: string,
* name: string,
* provider: string,
* context_length: int,
* input_price_per_m: float,
* output_price_per_m: float,
* capabilities: string[],
* deprecated: bool,
* updated_at: int,
* }> Normalized records, sorted by name ascending.
*/
public function normalize( array $raw_models ): array {
$normalized = [];
foreach ( $raw_models as $model ) {
if ( ! is_array( $model ) || ! isset( $model['id'] ) ) {
continue;
}
$input_modalities = (array) ( $model['architecture']['input_modalities'] ?? [ 'text' ] );
$output_modalities = (array) ( $model['architecture']['output_modalities'] ?? [ 'text' ] );
$name_parts = explode( '/', (string) $model['id'], 2 );
// OpenRouter prices are per-token; convert to per-million.
$prompt_price = (float) ( $model['pricing']['prompt'] ?? 0 );
$completion_price = (float) ( $model['pricing']['completion'] ?? 0 );
$normalized[] = [
'id' => (string) $model['id'],
'name' => (string) ( $model['name'] ?? $model['id'] ),
'provider' => $name_parts[0] ?? 'unknown',
'context_length' => (int) ( $model['context_length'] ?? 0 ),
'input_price_per_m' => round( $prompt_price * 1_000_000, 4 ),
'output_price_per_m' => round( $completion_price * 1_000_000, 4 ),
'capabilities' => $this->derive_capabilities( $input_modalities, $output_modalities ),
'deprecated' => false,
'updated_at' => (int) ( $model['created'] ?? 0 ),
];
}
usort( $normalized, static function ( array $a, array $b ): int {
return strcasecmp( $a['name'], $b['name'] );
} );
return $normalized;
}
/**
* Derive capability strings from input/output modality arrays.
*
* @param string[] $input_modalities e.g. ['text', 'image']
* @param string[] $output_modalities e.g. ['text']
*
* @return string[] Matched capability labels. Defaults to ['text→text'].
*/
private function derive_capabilities( array $input_modalities, array $output_modalities ): array {
$caps = [];
foreach ( self::CAPABILITY_MAP as $label => $requirements ) {
$input_match = empty( array_diff( $requirements['in'], $input_modalities ) );
$output_match = empty( array_diff( $requirements['out'], $output_modalities ) );
if ( $input_match && $output_match ) {
$caps[] = $label;
}
}
return empty( $caps ) ? [ 'text→text' ] : $caps;
}
}

226
includes/services/class-openrouter-model-registry.php Normal file
View File

@@ -0,0 +1,226 @@
<?php
declare(strict_types=1);
/**
* OpenRouter model registry — fetches, normalizes, and caches the model list.
*
* All config is constructor-injected. No PRAUTOBLOGGER_* constants referenced
* inside this class — Phase 2 lifts it into a shared Composer package with
* zero internal edits.
*
* Storage: WP option (durable) fronted by a transient (fast reads, 24h TTL).
* On stale-and-fetch-fails, the option payload is served and a flag is set.
*
* Triggered by: `prautoblogger_refresh_model_registry` action, manual AJAX
* (commit 3), PRAutoBlogger_Activator::activate().
* Dependencies: wp_remote_get(), PRAutoBlogger_Logger,
* PRAutoBlogger_OpenRouter_Model_Normalizer.
*
* @see interface-model-registry.php — Interface.
* @see class-openrouter-model-normalizer.php — Normalization logic.
* @see class-prautoblogger.php — Hooks the refresh action.
* @see ARCHITECTURE.md — AI Model Registries section.
*/
class PRAutoBlogger_OpenRouter_Model_Registry implements PRAutoBlogger_Model_Registry_Interface {
private const PROVIDER_ID = 'openrouter';
private const LOG_CONTEXT = 'model-registry';
private const HTTP_TIMEOUT = 15;
private const ADMIN_NOTICE_FLAG = 'prautoblogger_model_registry_stale';
private string $option_name;
private string $fetched_at_option;
private string $transient_name;
private string $endpoint;
private int $cache_ttl;
private int $idempotency_window;
private PRAutoBlogger_OpenRouter_Model_Normalizer $normalizer;
/**
* @param string $option_name WP option for the durable payload.
* @param string $transient_name WP transient for fast reads.
* @param string $endpoint OpenRouter models API URL.
* @param int $cache_ttl_seconds Transient TTL (default 86400 = 24h).
* @param int $idempotency_seconds Skip refresh if younger than this (default 43200 = 12h).
*/
public function __construct(
string $option_name,
string $transient_name,
string $endpoint = 'https://openrouter.ai/api/v1/models',
int $cache_ttl_seconds = 86400,
int $idempotency_seconds = 43200
) {
$this->option_name = $option_name;
$this->fetched_at_option = $option_name . '_fetched_at';
$this->transient_name = $transient_name;
$this->endpoint = $endpoint;
$this->cache_ttl = $cache_ttl_seconds;
$this->idempotency_window = $idempotency_seconds;
$this->normalizer = new PRAutoBlogger_OpenRouter_Model_Normalizer();
}
/** {@inheritDoc} */
public function get_models(): array {
return $this->load_payload();
}
/** {@inheritDoc} */
public function get_models_with_capability( string $capability ): array {
return array_values(
array_filter(
$this->load_payload(),
static function ( array $model ) use ( $capability ): bool {
return in_array( $capability, $model['capabilities'] ?? [], true );
}
)
);
}
/** {@inheritDoc} */
public function find_model( string $id ): ?array {
foreach ( $this->load_payload() as $model ) {
if ( ( $model['id'] ?? '' ) === $id ) {
return $model;
}
}
return null;
}
/** {@inheritDoc} */
public function refresh( bool $force = false ): array {
$fetched_at = $this->get_fetched_at();
if ( ! $force && $fetched_at > 0 && ( time() - $fetched_at ) < $this->idempotency_window ) {
$payload = $this->load_payload();
return [ 'count' => count( $payload ), 'fetched_at' => $fetched_at ];
}
$raw_models = $this->fetch_from_api();
if ( null === $raw_models ) {
$this->flag_stale();
$stale = $this->load_from_option();
return [ 'count' => count( $stale ), 'fetched_at' => $fetched_at ];
}
$normalized = $this->normalizer->normalize( $raw_models );
$now = time();
$this->save_payload( $normalized, $now );
$this->clear_stale_flag();
PRAutoBlogger_Logger::instance()->info(
sprintf( 'Model registry refreshed: %d models.', count( $normalized ) ),
self::LOG_CONTEXT
);
return [ 'count' => count( $normalized ), 'fetched_at' => $now ];
}
/** {@inheritDoc} */
public function get_fetched_at(): int {
return (int) get_option( $this->fetched_at_option, 0 );
}
/** {@inheritDoc} */
public function get_provider_name(): string {
return self::PROVIDER_ID;
}
/**
* Load from transient (fast) falling back to option (durable).
*
* @return array<int, array>
*/
private function load_payload(): array {
$cached = get_transient( $this->transient_name );
if ( is_array( $cached ) && ! empty( $cached ) ) {
return $cached;
}
return $this->load_from_option();
}
/** @return array<int, array> */
private function load_from_option(): array {
$data = get_option( $this->option_name, [] );
return is_array( $data ) ? $data : [];
}
private function save_payload( array $payload, int $now ): void {
update_option( $this->option_name, $payload, false );
update_option( $this->fetched_at_option, $now, false );
set_transient( $this->transient_name, $payload, $this->cache_ttl );
}
/**
* Fetch the model list from the OpenRouter API with exponential-backoff retry.
*
* @return ?array Raw 'data' array, or null on failure.
*/
private function fetch_from_api(): ?array {
$max_retries = defined( 'PRAUTOBLOGGER_MAX_RETRIES' ) ? PRAUTOBLOGGER_MAX_RETRIES : 3;
$base_delay = defined( 'PRAUTOBLOGGER_RETRY_BASE_DELAY_SECONDS' ) ? PRAUTOBLOGGER_RETRY_BASE_DELAY_SECONDS : 2;
for ( $attempt = 1; $attempt <= $max_retries; $attempt++ ) {
$response = wp_remote_get( $this->endpoint, [ 'timeout' => self::HTTP_TIMEOUT ] );
if ( is_wp_error( $response ) ) {
PRAutoBlogger_Logger::instance()->warning(
sprintf( 'Model registry fetch attempt %d: %s', $attempt, $response->get_error_message() ),
self::LOG_CONTEXT
);
$this->backoff( $attempt, $base_delay );
continue;
}
$status = (int) wp_remote_retrieve_response_code( $response );
$body = (string) wp_remote_retrieve_body( $response );
if ( $status >= 500 || 429 === $status ) {
PRAutoBlogger_Logger::instance()->warning(
sprintf( 'Model registry fetch attempt %d: HTTP %d', $attempt, $status ),
self::LOG_CONTEXT
);
$this->backoff( $attempt, $base_delay );
continue;
}
if ( $status >= 400 ) {
PRAutoBlogger_Logger::instance()->error(
sprintf( 'Model registry: HTTP %d: %s', $status, substr( $body, 0, 300 ) ),
self::LOG_CONTEXT
);
return null;
}
$decoded = json_decode( $body, true );
if ( ! is_array( $decoded ) || ! isset( $decoded['data'] ) || ! is_array( $decoded['data'] ) ) {
PRAutoBlogger_Logger::instance()->error( 'Model registry: unexpected response shape.', self::LOG_CONTEXT );
return null;
}
return $decoded['data'];
}
PRAutoBlogger_Logger::instance()->error(
sprintf( 'Model registry fetch failed after %d attempts.', $max_retries ),
self::LOG_CONTEXT
);
return null;
}
private function backoff( int $attempt, int $base_delay ): void {
$delay = $base_delay * (int) pow( 2, $attempt - 1 );
if ( $delay > 0 ) {
sleep( $delay );
}
}
private function flag_stale(): void {
update_option( self::ADMIN_NOTICE_FLAG, '1', false );
PRAutoBlogger_Logger::instance()->warning( 'Model registry: serving stale data after refresh failure.', self::LOG_CONTEXT );
}
private function clear_stale_flag(): void {
delete_option( self::ADMIN_NOTICE_FLAG );
}
}

94
includes/services/interface-model-registry.php Normal file
View File

@@ -0,0 +1,94 @@
<?php
declare(strict_types=1);
/**
* Contract for a provider-specific AI model registry.
*
* Phase 1 (v1): single implementation for OpenRouter (`class-openrouter-model-registry.php`).
* Phase 3: a second implementation wraps Cloudflare Workers AI FLUX model data. A
* higher-level dispatcher iterates registered registries, calls each with the same
* capability, and unions the results — the per-registry interface stays unchanged.
*
* Implementations MUST:
* - Store the normalized registry as a WP option + transient cache layer.
* - Degrade gracefully when the source API is unreachable (serve last-good cache).
* - Never throw on public read methods — empty arrays are acceptable fallbacks.
* - Log refresh failures via PRAutoBlogger_Logger.
*
* Triggered by: Settings page field renderer (commit 2), AJAX refresh endpoint
* (commit 3), daily cron via the main plugin loader.
* Dependencies: None at interface level — implementations wrap an HTTP API.
*
* @see services/class-openrouter-model-registry.php — Default implementation.
* @see admin/fields/class-openrouter-model-field.php — Field renderer that queries this interface.
* @see ARCHITECTURE.md — AI Model Registries section.
*/
interface PRAutoBlogger_Model_Registry_Interface {
/**
* Return all models in the registry, normalized.
*
* @return array<int, array{
* id: string,
* name: string,
* provider: string,
* context_length: int,
* input_price_per_m: float,
* output_price_per_m: float,
* capabilities: string[],
* deprecated: bool,
* updated_at: int,
* }> Normalized model records, sorted by name ascending.
*/
public function get_models(): array;
/**
* Return only models matching a given capability string.
*
* @param string $capability One of the standardized capability strings:
* 'text→text', 'text+image→text', 'text+audio→text',
* 'text→image', 'text→audio', 'text→video',
* 'text→embedding'.
*
* @return array<int, array> Same record shape as get_models(), filtered.
*/
public function get_models_with_capability( string $capability ): array;
/**
* Look up one model by its provider-qualified id (e.g. 'anthropic/claude-3.5-haiku').
*
* @param string $id Model identifier.
*
* @return ?array Normalized model record, or null if not in the registry.
*/
public function find_model( string $id ): ?array;
/**
* Fetch fresh data from the upstream source and replace the cached payload.
*
* When `$force` is false, implementations SHOULD skip the HTTP call if the
* payload is younger than a configured idempotency window (default 12h).
*
* Side effects: HTTP GET to the upstream API, wp_options write, transient set,
* log line on failure, admin notice flag on stale-and-failed.
*
* @param bool $force True to bypass the idempotency window (e.g. manual admin refresh).
*
* @return array{count: int, fetched_at: int} Number of models stored and unix timestamp.
*/
public function refresh( bool $force = false ): array;
/**
* Unix timestamp of the last successful refresh. Zero if never refreshed.
*
* @return int
*/
public function get_fetched_at(): int;
/**
* Machine-readable provider identifier (e.g. 'openrouter', 'cloudflare_workers_ai').
*
* @return string
*/
public function get_provider_name(): string;
}