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

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

370 lines 11.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\Client\Tasks\DTO\TaskMetadata;
8	use WP\McpSchema\Common\JsonRpc\DTO\RequestParamsMeta;
9	use WP\McpSchema\Common\Tasks\DTO\TaskAugmentedRequestParams;
10	use WP\McpSchema\Common\Traits\ValidatesRequiredFields;
11	use WP\McpSchema\Server\Tools\DTO\Tool;
12
13	/**
14	* Parameters for a `sampling/createMessage` request.
15	*
16	* @since 2025-11-25
17	*
18	* @mcp-domain Client
19	* @mcp-subdomain Sampling
20	* @mcp-version 2025-11-25
21	*/
22	class CreateMessageRequestParams extends TaskAugmentedRequestParams
23	{
24	use ValidatesRequiredFields;
25
26	/**
27	* @since 2025-11-25
28	*
29	* @var array<\WP\McpSchema\Client\Sampling\DTO\SamplingMessage>
30	*/
31	protected array $messages;
32
33	/**
34	* The server's preferences for which model to select. The client MAY ignore these preferences.
35	*
36	* @since 2025-11-25
37	*
38	* @var \WP\McpSchema\Client\Sampling\DTO\ModelPreferences\|null
39	*/
40	protected ?ModelPreferences $modelPreferences;
41
42	/**
43	* An optional system prompt the server wants to use for sampling. The client MAY modify or omit this prompt.
44	*
45	* @since 2025-11-25
46	*
47	* @var string\|null
48	*/
49	protected ?string $systemPrompt;
50
51	/**
52	* A request to include context from one or more MCP servers (including the caller), to be attached to the prompt.
53	* The client MAY ignore this request.
54	*
55	* Default is "none". Values "thisServer" and "allServers" are soft-deprecated. Servers SHOULD only use these values if the client
56	* declares ClientCapabilities.sampling.context. These values may be removed in future spec releases.
57	*
58	* @since 2025-11-25
59	*
60	* @var 'none'\|'thisServer'\|'allServers'\|null
61	*/
62	protected ?string $includeContext;
63
64	/**
65	* @since 2025-11-25
66	*
67	* @var float\|null
68	*/
69	protected ?float $temperature;
70
71	/**
72	* The requested maximum number of tokens to sample (to prevent runaway completions).
73	*
74	* The client MAY choose to sample fewer tokens than the requested maximum.
75	*
76	* @since 2025-11-25
77	*
78	* @var float
79	*/
80	protected float $maxTokens;
81
82	/**
83	* @since 2025-11-25
84	*
85	* @var array<string>\|null
86	*/
87	protected ?array $stopSequences;
88
89	/**
90	* Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.
91	*
92	* @since 2025-11-25
93	*
94	* @var object\|null
95	*/
96	protected ?object $metadata;
97
98	/**
99	* Tools that the model may use during generation.
100	* The client MUST return an error if this field is provided but ClientCapabilities.sampling.tools is not declared.
101	*
102	* @since 2025-11-25
103	*
104	* @var array<\WP\McpSchema\Server\Tools\DTO\Tool>\|null
105	*/
106	protected ?array $tools;
107
108	/**
109	* Controls how the model uses tools.
110	* The client MUST return an error if this field is provided but ClientCapabilities.sampling.tools is not declared.
111	* Default is `{ mode: "auto" }`.
112	*
113	* @since 2025-11-25
114	*
115	* @var \WP\McpSchema\Client\Sampling\DTO\ToolChoice\|null
116	*/
117	protected ?ToolChoice $toolChoice;
118
119	/**
120	* @param array<\WP\McpSchema\Client\Sampling\DTO\SamplingMessage> $messages @since 2025-11-25
121	* @param float $maxTokens @since 2025-11-25
122	* @param \WP\McpSchema\Client\Tasks\DTO\TaskMetadata\|null $task @since 2025-11-25
123	* @param \WP\McpSchema\Common\JsonRpc\DTO\RequestParamsMeta\|null $_meta @since 2025-11-25
124	* @param \WP\McpSchema\Client\Sampling\DTO\ModelPreferences\|null $modelPreferences @since 2025-11-25
125	* @param string\|null $systemPrompt @since 2025-11-25
126	* @param 'none'\|'thisServer'\|'allServers'\|null $includeContext @since 2025-11-25
127	* @param float\|null $temperature @since 2025-11-25
128	* @param array<string>\|null $stopSequences @since 2025-11-25
129	* @param object\|null $metadata @since 2025-11-25
130	* @param array<\WP\McpSchema\Server\Tools\DTO\Tool>\|null $tools @since 2025-11-25
131	* @param \WP\McpSchema\Client\Sampling\DTO\ToolChoice\|null $toolChoice @since 2025-11-25
132	*/
133	public function __construct(
134	array $messages,
135	float $maxTokens,
136	?TaskMetadata $task = null,
137	?RequestParamsMeta $_meta = null,
138	?ModelPreferences $modelPreferences = null,
139	?string $systemPrompt = null,
140	?string $includeContext = null,
141	?float $temperature = null,
142	?array $stopSequences = null,
143	?object $metadata = null,
144	?array $tools = null,
145	?ToolChoice $toolChoice = null
146	) {
147	parent::__construct($_meta, $task);
148	$this->messages = $messages;
149	$this->maxTokens = $maxTokens;
150	$this->modelPreferences = $modelPreferences;
151	$this->systemPrompt = $systemPrompt;
152	$this->includeContext = $includeContext;
153	$this->temperature = $temperature;
154	$this->stopSequences = $stopSequences;
155	$this->metadata = $metadata;
156	$this->tools = $tools;
157	$this->toolChoice = $toolChoice;
158	}
159
160	/**
161	* Creates an instance from an array.
162	*
163	* @param array{
164	* task?: array<string, mixed>\|\WP\McpSchema\Client\Tasks\DTO\TaskMetadata\|null,
165	* _meta?: array<string, mixed>\|\WP\McpSchema\Common\JsonRpc\DTO\RequestParamsMeta\|null,
166	* messages: array<array<string, mixed>\|\WP\McpSchema\Client\Sampling\DTO\SamplingMessage>,
167	* modelPreferences?: array<string, mixed>\|\WP\McpSchema\Client\Sampling\DTO\ModelPreferences\|null,
168	* systemPrompt?: string\|null,
169	* includeContext?: 'none'\|'thisServer'\|'allServers'\|null,
170	* temperature?: float\|null,
171	* maxTokens: float,
172	* stopSequences?: array<string>\|null,
173	* metadata?: object\|null,
174	* tools?: array<array<string, mixed>\|\WP\McpSchema\Server\Tools\DTO\Tool>\|null,
175	* toolChoice?: array<string, mixed>\|\WP\McpSchema\Client\Sampling\DTO\ToolChoice\|null
176	* } $data
177	* @phpstan-param array<string, mixed> $data
178	* @return self
179	*/
180	public static function fromArray(array $data): self
181	{
182	self::assertRequired($data, ['messages', 'maxTokens']);
183
184	/** @var array<\WP\McpSchema\Client\Sampling\DTO\SamplingMessage> $messages */
185	$messages = array_map(
186	static fn($item) => is_array($item)
187	? SamplingMessage::fromArray($item)
188	: $item,
189	self::asArray($data['messages'])
190	);
191
192	/** @var \WP\McpSchema\Client\Tasks\DTO\TaskMetadata\|null $task */
193	$task = isset($data['task'])
194	? (is_array($data['task'])
195	? TaskMetadata::fromArray(self::asArray($data['task']))
196	: $data['task'])
197	: null;
198
199	/** @var \WP\McpSchema\Common\JsonRpc\DTO\RequestParamsMeta\|null $_meta */
200	$_meta = isset($data['_meta'])
201	? (is_array($data['_meta'])
202	? RequestParamsMeta::fromArray(self::asArray($data['_meta']))
203	: $data['_meta'])
204	: null;
205
206	/** @var \WP\McpSchema\Client\Sampling\DTO\ModelPreferences\|null $modelPreferences */
207	$modelPreferences = isset($data['modelPreferences'])
208	? (is_array($data['modelPreferences'])
209	? ModelPreferences::fromArray(self::asArray($data['modelPreferences']))
210	: $data['modelPreferences'])
211	: null;
212
213	/** @var 'none'\|'thisServer'\|'allServers'\|null $includeContext */
214	$includeContext = isset($data['includeContext'])
215	? self::asStringOrNull($data['includeContext'])
216	: null;
217
218	/** @var array<\WP\McpSchema\Server\Tools\DTO\Tool>\|null $tools */
219	$tools = isset($data['tools'])
220	? array_map(
221	static fn($item) => is_array($item)
222	? Tool::fromArray($item)
223	: $item,
224	self::asArray($data['tools'])
225	)
226	: null;
227
228	/** @var \WP\McpSchema\Client\Sampling\DTO\ToolChoice\|null $toolChoice */
229	$toolChoice = isset($data['toolChoice'])
230	? (is_array($data['toolChoice'])
231	? ToolChoice::fromArray(self::asArray($data['toolChoice']))
232	: $data['toolChoice'])
233	: null;
234
235	return new self(
236	$messages,
237	self::asFloat($data['maxTokens']),
238	$task,
239	$_meta,
240	$modelPreferences,
241	self::asStringOrNull($data['systemPrompt'] ?? null),
242	$includeContext,
243	self::asFloatOrNull($data['temperature'] ?? null),
244	self::asStringArrayOrNull($data['stopSequences'] ?? null),
245	self::asObjectOrNull($data['metadata'] ?? null),
246	$tools,
247	$toolChoice
248	);
249	}
250
251	/**
252	* Converts the instance to an array.
253	*
254	* @return array<string, mixed>
255	*/
256	public function toArray(): array
257	{
258	$result = parent::toArray();
259
260	$result['messages'] = array_map(static fn($item) => $item->toArray(), $this->messages);
261	if ($this->modelPreferences !== null) {
262	$result['modelPreferences'] = $this->modelPreferences->toArray();
263	}
264	if ($this->systemPrompt !== null) {
265	$result['systemPrompt'] = $this->systemPrompt;
266	}
267	if ($this->includeContext !== null) {
268	$result['includeContext'] = $this->includeContext;
269	}
270	if ($this->temperature !== null) {
271	$result['temperature'] = $this->temperature;
272	}
273	$result['maxTokens'] = $this->maxTokens;
274	if ($this->stopSequences !== null) {
275	$result['stopSequences'] = $this->stopSequences;
276	}
277	if ($this->metadata !== null) {
278	$result['metadata'] = $this->metadata;
279	}
280	if ($this->tools !== null) {
281	$result['tools'] = array_map(static fn($item) => $item->toArray(), $this->tools);
282	}
283	if ($this->toolChoice !== null) {
284	$result['toolChoice'] = $this->toolChoice->toArray();
285	}
286
287	return $result;
288	}
289
290	/**
291	* @return array<\WP\McpSchema\Client\Sampling\DTO\SamplingMessage>
292	*/
293	public function getMessages(): array
294	{
295	return $this->messages;
296	}
297
298	/**
299	* @return \WP\McpSchema\Client\Sampling\DTO\ModelPreferences\|null
300	*/
301	public function getModelPreferences(): ?ModelPreferences
302	{
303	return $this->modelPreferences;
304	}
305
306	/**
307	* @return string\|null
308	*/
309	public function getSystemPrompt(): ?string
310	{
311	return $this->systemPrompt;
312	}
313
314	/**
315	* @return 'none'\|'thisServer'\|'allServers'\|null
316	*/
317	public function getIncludeContext(): ?string
318	{
319	return $this->includeContext;
320	}
321
322	/**
323	* @return float\|null
324	*/
325	public function getTemperature(): ?float
326	{
327	return $this->temperature;
328	}
329
330	/**
331	* @return float
332	*/
333	public function getMaxTokens(): float
334	{
335	return $this->maxTokens;
336	}
337
338	/**
339	* @return array<string>\|null
340	*/
341	public function getStopSequences(): ?array
342	{
343	return $this->stopSequences;
344	}
345
346	/**
347	* @return object\|null
348	*/
349	public function getMetadata(): ?object
350	{
351	return $this->metadata;
352	}
353
354	/**
355	* @return array<\WP\McpSchema\Server\Tools\DTO\Tool>\|null
356	*/
357	public function getTools(): ?array
358	{
359	return $this->tools;
360	}
361
362	/**
363	* @return \WP\McpSchema\Client\Sampling\DTO\ToolChoice\|null
364	*/
365	public function getToolChoice(): ?ToolChoice
366	{
367	return $this->toolChoice;
368	}
369	}
370