zip-ai / lib / php-mcp-schema / src / Client / Sampling / DTO / ModelPreferences.php

ModelPreferences.php in ZIP AI – AI Website Builder & AI Agent (Beta) trunk, at lib/php-mcp-schema/src/Client/Sampling/DTO/ModelPreferences.php

189 lines 5.5 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace WP\McpSchema\Client\Sampling\DTO;
6
7	use WP\McpSchema\Common\AbstractDataTransferObject;
8	use WP\McpSchema\Common\Traits\ValidatesRequiredFields;
9
10	/**
11	* The server's preferences for model selection, requested of the client during sampling.
12	*
13	* Because LLMs can vary along multiple dimensions, choosing the "best" model is
14	* rarely straightforward. Different models excel in different areas—some are
15	* faster but less capable, others are more capable but more expensive, and so
16	* on. This interface allows servers to express their priorities across multiple
17	* dimensions to help clients make an appropriate selection for their use case.
18	*
19	* These preferences are always advisory. The client MAY ignore them. It is also
20	* up to the client to decide how to interpret these preferences and how to
21	* balance them against other considerations.
22	*
23	* @since 2024-11-05
24	* @last-updated 2025-11-25 (modified property: hints)
25	*
26	* @mcp-domain Client
27	* @mcp-subdomain Sampling
28	* @mcp-version 2025-11-25
29	*/
30	class ModelPreferences extends AbstractDataTransferObject
31	{
32	use ValidatesRequiredFields;
33
34	/**
35	* Optional hints to use for model selection.
36	*
37	* If multiple hints are specified, the client MUST evaluate them in order
38	* (such that the first match is taken).
39	*
40	* The client SHOULD prioritize these hints over the numeric priorities, but
41	* MAY still use the priorities to select from ambiguous matches.
42	*
43	* @since 2024-11-05
44	*
45	* @var array<\WP\McpSchema\Client\Sampling\DTO\ModelHint>\|null
46	*/
47	protected ?array $hints;
48
49	/**
50	* How much to prioritize cost when selecting a model. A value of 0 means cost
51	* is not important, while a value of 1 means cost is the most important
52	* factor.
53	*
54	* @since 2024-11-05
55	*
56	* @var float\|null
57	*/
58	protected ?float $costPriority;
59
60	/**
61	* How much to prioritize sampling speed (latency) when selecting a model. A
62	* value of 0 means speed is not important, while a value of 1 means speed is
63	* the most important factor.
64	*
65	* @since 2024-11-05
66	*
67	* @var float\|null
68	*/
69	protected ?float $speedPriority;
70
71	/**
72	* How much to prioritize intelligence and capabilities when selecting a
73	* model. A value of 0 means intelligence is not important, while a value of 1
74	* means intelligence is the most important factor.
75	*
76	* @since 2024-11-05
77	*
78	* @var float\|null
79	*/
80	protected ?float $intelligencePriority;
81
82	/**
83	* @param array<\WP\McpSchema\Client\Sampling\DTO\ModelHint>\|null $hints @since 2024-11-05
84	* @param float\|null $costPriority @since 2024-11-05
85	* @param float\|null $speedPriority @since 2024-11-05
86	* @param float\|null $intelligencePriority @since 2024-11-05
87	*/
88	public function __construct(
89	?array $hints = null,
90	?float $costPriority = null,
91	?float $speedPriority = null,
92	?float $intelligencePriority = null
93	) {
94	$this->hints = $hints;
95	$this->costPriority = $costPriority;
96	$this->speedPriority = $speedPriority;
97	$this->intelligencePriority = $intelligencePriority;
98	}
99
100	/**
101	* Creates an instance from an array.
102	*
103	* @param array{
104	* hints?: array<array<string, mixed>\|\WP\McpSchema\Client\Sampling\DTO\ModelHint>\|null,
105	* costPriority?: float\|null,
106	* speedPriority?: float\|null,
107	* intelligencePriority?: float\|null
108	* } $data
109	* @phpstan-param array<string, mixed> $data
110	* @return self
111	*/
112	public static function fromArray(array $data): self
113	{
114	/** @var array<\WP\McpSchema\Client\Sampling\DTO\ModelHint>\|null $hints */
115	$hints = isset($data['hints'])
116	? array_map(
117	static fn($item) => is_array($item)
118	? ModelHint::fromArray($item)
119	: $item,
120	self::asArray($data['hints'])
121	)
122	: null;
123
124	return new self(
125	$hints,
126	self::asFloatOrNull($data['costPriority'] ?? null),
127	self::asFloatOrNull($data['speedPriority'] ?? null),
128	self::asFloatOrNull($data['intelligencePriority'] ?? null)
129	);
130	}
131
132	/**
133	* Converts the instance to an array.
134	*
135	* @return array<string, mixed>
136	*/
137	public function toArray(): array
138	{
139	$result = [];
140
141	if ($this->hints !== null) {
142	$result['hints'] = array_map(static fn($item) => $item->toArray(), $this->hints);
143	}
144	if ($this->costPriority !== null) {
145	$result['costPriority'] = $this->costPriority;
146	}
147	if ($this->speedPriority !== null) {
148	$result['speedPriority'] = $this->speedPriority;
149	}
150	if ($this->intelligencePriority !== null) {
151	$result['intelligencePriority'] = $this->intelligencePriority;
152	}
153
154	return $result;
155	}
156
157	/**
158	* @return array<\WP\McpSchema\Client\Sampling\DTO\ModelHint>\|null
159	*/
160	public function getHints(): ?array
161	{
162	return $this->hints;
163	}
164
165	/**
166	* @return float\|null
167	*/
168	public function getCostPriority(): ?float
169	{
170	return $this->costPriority;
171	}
172
173	/**
174	* @return float\|null
175	*/
176	public function getSpeedPriority(): ?float
177	{
178	return $this->speedPriority;
179	}
180
181	/**
182	* @return float\|null
183	*/
184	public function getIntelligencePriority(): ?float
185	{
186	return $this->intelligencePriority;
187	}
188	}
189