<?php
/**
 * Public names for the models CloudScale serves.
 *
 * WHY THIS EXISTS
 * ---------------
 * The managed service routes each job to whichever model does it well for the least money, and
 * which model that is changes: narration moved to a voice model 27× cheaper than the one it
 * started on, and the text path can be served by either of two backends. Printing the raw model
 * id in the UI made a private supply decision into a public promise, every reader learned which
 * vendor we buy from, and every switch looked like a downgrade to anyone who recognised the names.
 *
 * So a managed model is shown by CAPABILITY and TIER: CS-Text-1, CS-Text-Pro, CS-Voice-1,
 * CS-Voice-Pro, CS-Image-1. The reader learns what it does and whether it is the premium option,
 * which is what they actually need in order to choose.
 *
 * TWO RULES THAT ARE NOT NEGOTIABLE
 *
 * 1. A model the CUSTOMER pays for is never masked. If they configured their own API key and
 *    picked claude-sonnet-4-6, the UI says claude-sonnet-4-6, it is their account, their bill and
 *    their choice, and relabelling it would be the same dishonesty as telling them their key was
 *    unused while the dispatcher was failing over to it. Masking applies to OUR supply only.
 *
 * 2. This does not touch disclosure or audit. WordPress.org requires the readme's "External
 *    services" section to name the real third parties and say what is sent to them, and the audit
 *    rows record the real model that served each call (model_used / ai_mode, taken from the
 *    dispatcher). Neither is marketing copy, and a code name in either would be a lie rather than
 *    a brand.
 *
 * @package CloudScale_Shared
 */

// The bare ABSPATH form, deliberately. It used to also accept a CSDT_PROXY constant so the proxy
// could load this file outside WordPress, but nothing in the proxy repo ever defined that constant
// and nothing there ever included this file, so the second condition was unsatisfiable from the day
// it was written. What it did do is make WordPress.org's Plugin Check report the guard as MISSING,
// because that tool matches only this exact shape: an ERROR against code that was already correct.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/*
 * WRAPPED, not guarded by an early return. See class-cloudscale-error-text.php for
 * the full account: an unconditional top-level class is a candidate for OPcache's
 * early binding, so it is declared when the file is INCLUDED, before the guard's
 * `return` ever runs. The second CloudScale plugin to load then fataled with
 * "Cannot declare class ..., because the name is already in use", pointing at the
 * line the guard existed to protect. It does not reproduce under the CLI, which has
 * no opcache, which is why the wrong form survived in four shared classes.
 *
 * A class declared inside a conditional is never early-bound.
 */
if ( ! class_exists( 'CSDT_Model_Names' ) ) {

/**
 * Maps the model ids CloudScale serves to their public names.
 *
 * @since 1.0.0
 */
class CSDT_Model_Names {

	/**
	 * Managed supply: real id => public name.
	 *
	 * Keys are FRAGMENTS, matched case-insensitively, because a map keyed on exact strings starts
	 * returning the generic label the moment a vendor ships a point release: ids carry dates
	 * (claude-sonnet-4-6-20260514) and sometimes a vendor prefix (z-ai/glm-5.2). Longest match wins,
	 * so 'gpt-4o-mini-tts' beats 'gpt-4o-mini' beats 'gpt-4o'. See public_name().
	 */
	const MANAGED = array(
		// Text. Two tiers, because the routed backend is what makes the allowance go far and the
		// premium path is what it falls back to for the hardest work.
		'glm-'             => 'CS-Text-1',
		'claude-haiku'     => 'CS-Text-1',
		'claude-sonnet'    => 'CS-Text-Pro',
		'claude-opus'      => 'CS-Text-Pro',
		'gpt-4o-mini'      => 'CS-Text-1',
		'gpt-4o'           => 'CS-Text-Pro',
		// Voice.
		'kokoro'           => 'CS-Voice-1',
		'zonos'            => 'CS-Voice-1',
		'gpt-4o-mini-tts'  => 'CS-Voice-Pro',
		'tts-1'            => 'CS-Voice-Pro',
		// Images.
		'gpt-image'        => 'CS-Image-1',
		'dall-e'           => 'CS-Image-1',
	);

	/** Shown when a managed model is not in the map: never the raw id. */
	const FALLBACK = 'CloudScale managed model';

	/**
	 * The public name for a model served by CloudScale.
	 *
	 * @param string $model_id Raw provider model id.
	 * @return string Public name, never the raw id.
	 */
	public static function public_name( string $model_id ): string {
		$id = strtolower( trim( $model_id ) );
		if ( '' === $id ) {
			return self::FALLBACK;
		}

		// Ids arrive in two shapes depending on the route: bare (kokoro, gpt-image-2) and
		// vendor-qualified (z-ai/glm-5.2, anthropic/claude-sonnet-4-6). Prefix-matching alone
		// missed every qualified one and quietly returned the generic label, which leaks nothing,
		// but does throw away the tier the reader needed. So the vendor segment is stripped first,
		// and a contains-match is the last resort.
		$bare = strrpos( $id, '/' ) !== false ? substr( $id, strrpos( $id, '/' ) + 1 ) : $id;

		$best  = '';
		$found = self::FALLBACK;
		foreach ( self::MANAGED as $needle => $name ) {
			// Longest match wins, so 'gpt-4o-mini-tts' beats 'gpt-4o-mini' and 'gpt-4o'.
			if ( strlen( $needle ) <= strlen( $best ) ) {
				continue;
			}
			if ( 0 === strpos( $bare, $needle ) || 0 === strpos( $id, $needle ) || false !== strpos( $id, $needle ) ) {
				$best  = $needle;
				$found = $name;
			}
		}
		return $found;
	}

	/**
	 * The name to show for a model, deciding by WHO PAYS rather than by the id.
	 *
	 * @param string $model_id Raw provider model id.
	 * @param bool   $managed  True when CloudScale served it; false when the site's own key did.
	 * @return string
	 */
	public static function display_name( string $model_id, bool $managed ): string {
		if ( ! $managed ) {
			// The customer's own model, on the customer's own key: say what it is.
			return $model_id;
		}
		return self::public_name( $model_id );
	}

	/**
	 * Every public name in use, for glossaries and tests.
	 *
	 * @return array<int,string>
	 */
	public static function public_names(): array {
		$names = array_values( self::MANAGED );
		$names[] = self::FALLBACK;
		return array_values( array_unique( $names ) );
	}

	/**
	 * What a public name means, in one line, for a help page or tooltip.
	 *
	 * Capability and trade-off only. No vendor, no id, that is the point of the scheme, and no
	 * promise about which engine sits underneath, because that is chosen per job and changes.
	 *
	 * @return array<string,string>
	 */
	public static function glossary(): array {
		return array(
			'CS-Text-1'    => 'Everyday text: audits, summaries, metadata. Fast, and the reason a month of requests costs what it does.',
			'CS-Text-Pro'  => 'The premium text tier, used for the hardest reasoning and as the fallback when CS-Text-1 is not a good fit.',
			'CS-Voice-1'   => 'Standard narration. Natural-sounding, and cheap enough to narrate a whole archive.',
			'CS-Voice-Pro' => 'Premium narration, used when a prompt asks for delivery a standard voice cannot follow.',
			'CS-Image-1'   => 'Featured-image generation.',
		);
	}
}

}