001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bean.mcp.v20260728;
018
019import static org.apache.juneau.commons.utils.CollectionUtils.*;
020import static org.apache.juneau.commons.utils.Shorts.*;
021
022import java.util.*;
023
024import org.apache.juneau.marshall.*;
025
026/**
027 * Parameters for {@value McpMethods#SAMPLING_CREATE_MESSAGE}, a server-to-client duplex request (MCP sampling).
028 * Never dispatched through {@code McpRevision} — this is a plain POJO decoded/encoded by
029 * hand (or via the client's typed duplex flow) inside an {@code McpServerRequestHandler} implementation.
030 */
031@Marshalled
032public class CreateMessageRequest {
033
034   private List<SamplingMessage> messages;
035   private ModelPreferences modelPreferences;
036   private String systemPrompt;
037   private String includeContext;
038   private Double temperature;
039   private Integer maxTokens;
040   private List<String> stopSequences;
041   private Map<String,Object> metadata;
042
043   /**
044    * The conversation history to sample from.
045    *
046    * @return The messages list, or {@code null} if not set.
047    */
048   public List<SamplingMessage> getMessages() {
049      return u(messages);
050   }
051
052   /**
053    * Sets the messages.
054    *
055    * @param value The new value.  Can be <jk>null</jk> to unset the property.
056    * @return This object (for method chaining).
057    */
058   public CreateMessageRequest setMessages(List<SamplingMessage> value) {
059      messages = value;
060      return this;
061   }
062
063   /**
064    * Sets the messages.
065    *
066    * @param value The new value.  Can be <jk>null</jk> to unset the property.
067    * @return This object (for method chaining).
068    */
069   public CreateMessageRequest setMessages(SamplingMessage...value) {
070      messages = list(value);
071      return this;
072   }
073
074   /**
075    * Appends to the messages.
076    *
077    * @param value The values to append.
078    * @return This object (for method chaining).
079    */
080   public CreateMessageRequest addMessages(SamplingMessage...value) {
081      if (messages == null)
082         messages = list();
083      Collections.addAll(messages, value);
084      return this;
085   }
086
087   /**
088    * Appends to the messages.
089    *
090    * @param value The values to append.
091    * @return This object (for method chaining).
092    */
093   public CreateMessageRequest addMessages(Collection<SamplingMessage> value) {
094      if (messages == null)
095         messages = list();
096      messages.addAll(value);
097      return this;
098   }
099
100   /**
101    * Model-selection preferences.
102    *
103    * @return The preferences, or {@code null} if not set.
104    */
105   public ModelPreferences getModelPreferences() {
106      return modelPreferences;
107   }
108
109   /**
110    * Sets the model preferences.
111    *
112    * @param value The new value.  Can be <jk>null</jk> to unset the property.
113    * @return This object (for method chaining).
114    */
115   public CreateMessageRequest setModelPreferences(ModelPreferences value) {
116      modelPreferences = value;
117      return this;
118   }
119
120   /**
121    * An optional system prompt.
122    *
123    * @return The system prompt, or {@code null} if not set.
124    */
125   public String getSystemPrompt() {
126      return systemPrompt;
127   }
128
129   /**
130    * Sets the system prompt.
131    *
132    * @param value The new value.  Can be <jk>null</jk> to unset the property.
133    * @return This object (for method chaining).
134    */
135   public CreateMessageRequest setSystemPrompt(String value) {
136      systemPrompt = value;
137      return this;
138   }
139
140   /**
141    * Which MCP context to include ({@code none}/{@code thisServer}/{@code allServers} per the pinned schema).
142    * Kept as a plain {@code String}, matching this module's existing precedent of not over-modeling
143    * schema string-enums that do not gate real branching logic in this codebase.
144    *
145    * @return The include-context value, or {@code null} if not set.
146    */
147   public String getIncludeContext() {
148      return includeContext;
149   }
150
151   /**
152    * Sets the include-context value.
153    *
154    * @param value The new value.  Can be <jk>null</jk> to unset the property.
155    * @return This object (for method chaining).
156    */
157   public CreateMessageRequest setIncludeContext(String value) {
158      includeContext = value;
159      return this;
160   }
161
162   /**
163    * Sampling temperature.
164    *
165    * @return The temperature, or {@code null} if not set.
166    */
167   public Double getTemperature() {
168      return temperature;
169   }
170
171   /**
172    * Sets the temperature.
173    *
174    * @param value The new value.  Can be <jk>null</jk> to unset the property.
175    * @return This object (for method chaining).
176    */
177   public CreateMessageRequest setTemperature(Double value) {
178      temperature = value;
179      return this;
180   }
181
182   /**
183    * Maximum tokens to sample.
184    *
185    * @return The max tokens, or {@code null} if not set.
186    */
187   public Integer getMaxTokens() {
188      return maxTokens;
189   }
190
191   /**
192    * Sets the max tokens.
193    *
194    * @param value The new value.  Can be <jk>null</jk> to unset the property.
195    * @return This object (for method chaining).
196    */
197   public CreateMessageRequest setMaxTokens(Integer value) {
198      maxTokens = value;
199      return this;
200   }
201
202   /**
203    * Sequences that stop sampling when generated.
204    *
205    * @return The stop sequences, or {@code null} if not set.
206    */
207   public List<String> getStopSequences() {
208      return u(stopSequences);
209   }
210
211   /**
212    * Sets the stop sequences.
213    *
214    * @param value The new value.  Can be <jk>null</jk> to unset the property.
215    * @return This object (for method chaining).
216    */
217   public CreateMessageRequest setStopSequences(List<String> value) {
218      stopSequences = value;
219      return this;
220   }
221
222   /**
223    * Sets the stop sequences.
224    *
225    * @param value The new value.  Can be <jk>null</jk> to unset the property.
226    * @return This object (for method chaining).
227    */
228   public CreateMessageRequest setStopSequences(String...value) {
229      stopSequences = list(value);
230      return this;
231   }
232
233   /**
234    * Appends to the stop sequences.
235    *
236    * @param value The values to append.
237    * @return This object (for method chaining).
238    */
239   public CreateMessageRequest addStopSequences(String...value) {
240      if (stopSequences == null)
241         stopSequences = list();
242      Collections.addAll(stopSequences, value);
243      return this;
244   }
245
246   /**
247    * Appends to the stop sequences.
248    *
249    * @param value The values to append.
250    * @return This object (for method chaining).
251    */
252   public CreateMessageRequest addStopSequences(Collection<String> value) {
253      if (stopSequences == null)
254         stopSequences = list();
255      stopSequences.addAll(value);
256      return this;
257   }
258
259   /**
260    * Free-form server-defined metadata.
261    *
262    * @return The metadata map, or {@code null} if not set.
263    */
264   public Map<String,Object> getMetadata() {
265      return u(metadata);
266   }
267
268   /**
269    * Sets the metadata.
270    *
271    * @param value The new value.  Can be <jk>null</jk> to unset the property.
272    * @return This object (for method chaining).
273    */
274   public CreateMessageRequest setMetadata(Map<String,Object> value) {
275      metadata = value;
276      return this;
277   }
278
279   /**
280    * Convenience method to add a single metadata entry.
281    *
282    * @param name The entry name.  Can be <jk>null</jk> ({@link LinkedHashMap} tolerates a <jk>null</jk> key).
283    * @param value The entry value.  Can be <jk>null</jk> (stored as <jk>null</jk>).
284    * @return This object (for method chaining).
285    */
286   public CreateMessageRequest putMetadata(String name, Object value) {
287      if (metadata == null)
288         metadata = map();
289      metadata.put(name, value);
290      return this;
291   }
292}