tessl/maven-org-springframework-ai--spring-ai-model
Core model interfaces and abstractions for Spring AI framework providing portable API for chat, embeddings, images, audio, and tool calling across multiple AI providers
prompts.mddocs/reference/
Prompt Management
Comprehensive prompt construction including message composition, template-based prompt creation with variable substitution, prompt augmentation, and builder patterns for flexible prompt creation.
Capabilities
Prompt
Represents a prompt containing messages and options for a chat model call.
public class Prompt implements ModelRequest<List<Message>> {
/**
* Construct a Prompt from a simple string.
*
* @param contents the message content
*/
public Prompt(String contents);
/**
* Construct a Prompt from a single message.
*
* @param message the message
*/
public Prompt(Message message);
/**
* Construct a Prompt from a list of messages.
*
* @param messages the list of messages
*/
public Prompt(List<Message> messages);
/**
* Construct a Prompt from message array.
*
* @param messages the messages
*/
public Prompt(Message... messages);
/**
* Construct a Prompt from a string with options.
*
* @param contents the message content
* @param chatOptions the chat options
*/
public Prompt(String contents, ChatOptions chatOptions);
/**
* Construct a Prompt from a single message with options.
*
* @param message the message
* @param chatOptions the chat options
*/
public Prompt(Message message, ChatOptions chatOptions);
/**
* Construct a Prompt with messages and options.
*
* @param messages the list of messages
* @param chatOptions the chat options
*/
public Prompt(List<Message> messages, ChatOptions chatOptions);
/**
* Get the concatenated contents of all messages.
*
* @return concatenated message text
*/
String getContents();
/**
* Get the chat options for this prompt.
*
* @return the chat options
*/
ChatOptions getOptions();
/**
* Get all messages in this prompt.
*
* @return list of messages
*/
List<Message> getInstructions();
/**
* Get the first system message in this prompt.
*
* @return the first system message, or null
*/
SystemMessage getSystemMessage();
/**
* Get the first user message in this prompt.
*
* @return the first user message, or null
*/
UserMessage getUserMessage();
/**
* Get all user messages in this prompt.
*
* @return list of user messages
*/
List<UserMessage> getUserMessages();
/**
* Create a copy of this prompt.
*
* @return a new prompt copy
*/
Prompt copy();
/**
* Augment the system message with a transformation function.
*
* @param augmentor function to transform system message
* @return new prompt with augmented system message
*/
Prompt augmentSystemMessage(Function<SystemMessage, SystemMessage> augmentor);
/**
* Augment the system message by appending text.
*
* @param newSystemText text to append to system message
* @return new prompt with augmented system message
*/
Prompt augmentSystemMessage(String newSystemText);
/**
* Augment the user message with a transformation function.
*
* @param augmentor function to transform user message
* @return new prompt with augmented user message
*/
Prompt augmentUserMessage(Function<UserMessage, UserMessage> augmentor);
/**
* Augment the user message by appending text.
*
* @param newUserText text to append to user message
* @return new prompt with augmented user message
*/
Prompt augmentUserMessage(String newUserText);
/**
* Create a builder from this prompt for mutation.
*
* @return a builder initialized with this prompt's data
*/
Builder mutate();
/**
* Create a new prompt builder.
*
* @return a new builder
*/
static Builder builder();
/**
* Builder class for constructing Prompt instances.
*/
static class Builder {
/**
* Set the prompt content as a string.
*
* @param content the content text
* @return this builder
*/
Builder content(String content);
/**
* Set the messages array.
*
* @param messages the messages
* @return this builder
*/
Builder messages(Message... messages);
/**
* Set the messages list.
*
* @param messages the list of messages
* @return this builder
*/
Builder messages(List<Message> messages);
/**
* Set the chat options.
*
* @param chatOptions the chat options
* @return this builder
*/
Builder chatOptions(ChatOptions chatOptions);
/**
* Build the Prompt instance.
*
* @return the constructed Prompt
*/
Prompt build();
}
}PromptTemplateStringActions Interface
Base interface for prompt templates that can render strings.
public interface PromptTemplateStringActions {
/**
* Render the template to a string with no model variables.
*
* @return the rendered string
*/
String render();
/**
* Render the template to a string with the given model variables.
*
* @param model map of variable names to values
* @return the rendered string
*/
String render(Map<String, Object> model);
}PromptTemplateActions Interface
Interface for prompt templates that can create Prompt objects.
public interface PromptTemplateActions extends PromptTemplateStringActions {
/**
* Create a Prompt with no model variables or options.
*
* @return the created Prompt
*/
Prompt create();
/**
* Create a Prompt with chat options but no model variables.
*
* @param modelOptions the chat options
* @return the created Prompt
*/
Prompt create(ChatOptions modelOptions);
/**
* Create a Prompt with model variables but no options.
*
* @param model map of variable names to values
* @return the created Prompt
*/
Prompt create(Map<String, Object> model);
/**
* Create a Prompt with both model variables and chat options.
*
* @param model map of variable names to values
* @param modelOptions the chat options
* @return the created Prompt
*/
Prompt create(Map<String, Object> model, ChatOptions modelOptions);
}PromptTemplateMessageActions Interface
Interface for prompt templates that can create Message objects.
public interface PromptTemplateMessageActions {
/**
* Create a Message with no media or model variables.
*
* @return the created Message
*/
Message createMessage();
/**
* Create a Message with media attachments.
*
* @param mediaList list of media to attach
* @return the created Message
*/
Message createMessage(List<Media> mediaList);
/**
* Create a Message with model variables.
*
* @param model map of variable names to values
* @return the created Message
*/
Message createMessage(Map<String, Object> model);
}PromptTemplateChatActions Interface
Interface for prompt templates that can create lists of messages.
public interface PromptTemplateChatActions {
/**
* Create a list of Messages with no model variables.
*
* @return the created list of Messages
*/
List<Message> createMessages();
/**
* Create a list of Messages with model variables.
*
* @param model map of variable names to values
* @return the created list of Messages
*/
List<Message> createMessages(Map<String, Object> model);
}PromptTemplate
Template for creating prompts with variable substitution.
public class PromptTemplate implements PromptTemplateActions, PromptTemplateMessageActions {
/**
* Construct a PromptTemplate from a template string.
*
* @param template the template string with {variable} placeholders
*/
public PromptTemplate(String template);
/**
* Construct a PromptTemplate from a resource file.
*
* @param templateResource the resource containing the template
*/
public PromptTemplate(Resource templateResource);
/**
* Add a template variable.
*
* @param name the variable name
* @param value the variable value
*/
void add(String name, Object value);
/**
* Render the template to a string.
*
* @return the rendered template
*/
String render();
/**
* Render the template with a model map.
*
* @param model the variable map
* @return the rendered template
*/
String render(Map<String, Object> model);
/**
* Create a message from this template.
*
* @return the created message
*/
Message createMessage();
/**
* Create a message from this template with media list.
*
* @param mediaList the list of media attachments
* @return the created message
*/
Message createMessage(List<Media> mediaList);
/**
* Create a message from this template with a model.
*
* @param model the variable map
* @return the created message
*/
Message createMessage(Map<String, Object> model);
/**
* Create a prompt from this template.
*
* @return the created prompt
*/
Prompt create();
/**
* Create a prompt from this template with options.
*
* @param chatOptions the chat options
* @return the created prompt
*/
Prompt create(ChatOptions chatOptions);
/**
* Create a prompt from this template with a model.
*
* @param model the variable map
* @return the created prompt
*/
Prompt create(Map<String, Object> model);
/**
* Create a prompt from this template with model and options.
*
* @param model the variable map
* @param chatOptions the chat options
* @return the created prompt
*/
Prompt create(Map<String, Object> model, ChatOptions chatOptions);
}SystemPromptTemplate
Template specifically for creating system messages.
public class SystemPromptTemplate extends PromptTemplate {
/**
* Construct a SystemPromptTemplate from a template string.
*
* @param template the template string
*/
public SystemPromptTemplate(String template);
/**
* Construct a SystemPromptTemplate from a resource.
*
* @param templateResource the template resource
*/
public SystemPromptTemplate(Resource templateResource);
}AssistantPromptTemplate
Template specifically for creating assistant messages.
public class AssistantPromptTemplate extends PromptTemplate {
/**
* Construct an AssistantPromptTemplate from a template string.
*
* @param template the template string
*/
public AssistantPromptTemplate(String template);
/**
* Construct an AssistantPromptTemplate from a resource.
*
* @param templateResource the template resource
*/
public AssistantPromptTemplate(Resource templateResource);
}FunctionPromptTemplate
Template specifically for creating function/tool messages.
public class FunctionPromptTemplate extends PromptTemplate {
/**
* Construct a FunctionPromptTemplate from a template string.
*
* @param template the template string
*/
public FunctionPromptTemplate(String template);
/**
* Construct a FunctionPromptTemplate from a resource.
*
* @param templateResource the template resource
*/
public FunctionPromptTemplate(Resource templateResource);
}ChatPromptTemplate
Template for creating complete chat prompts with multiple messages.
public class ChatPromptTemplate implements PromptTemplateActions, PromptTemplateChatActions {
/**
* Create a ChatPromptTemplate from message templates.
*
* @param promptTemplates list of message-level prompt templates
*/
public ChatPromptTemplate(List<PromptTemplate> promptTemplates);
/**
* Render all message templates to a single string.
*
* @return concatenated rendered messages
*/
String render();
/**
* Render all message templates with a model map.
*
* @param model the variable map
* @return concatenated rendered messages
*/
String render(Map<String, Object> model);
/**
* Create messages from all templates.
*
* @return list of messages
*/
List<Message> createMessages();
/**
* Create messages from all templates with a model.
*
* @param model the variable map
* @return list of messages
*/
List<Message> createMessages(Map<String, Object> model);
/**
* Create a prompt from this template.
*
* @return the created prompt
*/
Prompt create();
/**
* Create a prompt from this template with options.
*
* @param modelOptions the chat options
* @return the created prompt
*/
Prompt create(ChatOptions modelOptions);
/**
* Create a prompt from this template with a model.
*
* @param model the variable map
* @return the created prompt
*/
Prompt create(Map<String, Object> model);
/**
* Create a prompt from this template with model and options.
*
* @param model the variable map
* @param modelOptions the chat options
* @return the created prompt
*/
Prompt create(Map<String, Object> model, ChatOptions modelOptions);
}ChatOptions Interface
Options for configuring chat model behavior.
public interface ChatOptions extends ModelOptions {
/**
* Get the model name to use.
*
* @return the model name
*/
String getModel();
/**
* Get the frequency penalty (-2.0 to 2.0).
* Penalizes tokens based on frequency in the text so far.
*
* @return the frequency penalty
*/
Double getFrequencyPenalty();
/**
* Get the maximum number of tokens to generate.
*
* @return the max tokens
*/
Integer getMaxTokens();
/**
* Get the presence penalty (-2.0 to 2.0).
* Penalizes tokens that have already appeared.
*
* @return the presence penalty
*/
Double getPresencePenalty();
/**
* Get stop sequences that will halt generation.
*
* @return list of stop sequences
*/
List<String> getStopSequences();
/**
* Get the sampling temperature (0.0 to 2.0).
* Higher values make output more random.
*
* @return the temperature
*/
Double getTemperature();
/**
* Get the top-k sampling parameter.
* Considers only the k most likely tokens.
*
* @return the top-k value
*/
Integer getTopK();
/**
* Get the top-p (nucleus) sampling parameter (0.0 to 1.0).
* Considers tokens with cumulative probability up to p.
*
* @return the top-p value
*/
Double getTopP();
/**
* Create a copy of these options.
*
* @return a copy of the options
*/
<T extends ChatOptions> T copy();
/**
* Create a new options builder.
*
* @return a new builder
*/
static Builder builder();
}DefaultChatOptions
Default implementation of ChatOptions.
public class DefaultChatOptions implements ChatOptions {
// Default implementation with all standard chat options
}ChatOptions.Builder
Builder for constructing ChatOptions fluently.
public interface Builder {
Builder model(String model);
Builder frequencyPenalty(Double frequencyPenalty);
Builder maxTokens(Integer maxTokens);
Builder presencePenalty(Double presencePenalty);
Builder stopSequences(List<String> stopSequences);
Builder temperature(Double temperature);
Builder topK(Integer topK);
Builder topP(Double topP);
ChatOptions build();
}Usage Examples
Basic Prompt Creation
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.messages.SystemMessage;
// From string
Prompt simplePrompt = new Prompt("What is the weather?");
// From messages
SystemMessage system = new SystemMessage("You are a helpful assistant.");
UserMessage user = new UserMessage("Explain machine learning.");
Prompt structuredPrompt = new Prompt(List.of(system, user));
// With options
ChatOptions options = ChatOptions.builder()
.temperature(0.7)
.maxTokens(500)
.build();
Prompt promptWithOptions = new Prompt("Tell me a story", options);Using Prompt Templates
import org.springframework.ai.chat.prompt.PromptTemplate;
// Create template
PromptTemplate template = new PromptTemplate(
"Tell me about {topic} in {style} style."
);
// Add variables
template.add("topic", "quantum physics");
template.add("style", "simple");
// Create prompt
Prompt prompt = template.create();
// Or use a map
Map<String, Object> model = Map.of(
"topic", "quantum physics",
"style", "simple"
);
Prompt promptFromMap = template.create(model);System Prompt Template
import org.springframework.ai.chat.prompt.SystemPromptTemplate;
SystemPromptTemplate systemTemplate = new SystemPromptTemplate(
"You are a {role}. Your specialty is {specialty}."
);
Map<String, Object> variables = Map.of(
"role", "data scientist",
"specialty", "machine learning"
);
Message systemMessage = systemTemplate.createMessage(variables);Chat Prompt Template
import org.springframework.ai.chat.prompt.ChatPromptTemplate;
// Create multi-message template
ChatPromptTemplate chatTemplate = ChatPromptTemplate.create(
"system: You are a {role}",
"user: {user_input}"
);
Map<String, Object> model = Map.of(
"role", "coding assistant",
"user_input", "How do I write a REST API?"
);
Prompt prompt = chatTemplate.create(model);Prompt Augmentation
import org.springframework.ai.chat.prompt.Prompt;
Prompt originalPrompt = new Prompt(List.of(
new SystemMessage("You are a helpful assistant."),
new UserMessage("What is AI?")
));
// Augment system message
Prompt augmented = originalPrompt.augmentSystemMessage(
"Always provide examples in your answers."
);
// Augment with function
Prompt customAugmented = originalPrompt.augmentUserMessage(msg ->
new UserMessage(msg.getText() + " Please be brief.")
);Using Prompt Builder
import org.springframework.ai.chat.prompt.Prompt;
Prompt prompt = Prompt.builder()
.messages(List.of(
new SystemMessage("You are helpful."),
new UserMessage("Hello!")
))
.options(ChatOptions.builder()
.temperature(0.8)
.maxTokens(1000)
.build()
)
.build();Template from File
import org.springframework.core.io.ClassPathResource;
import org.springframework.ai.chat.prompt.PromptTemplate;
// Load template from classpath
Resource templateResource = new ClassPathResource("prompts/analysis.txt");
PromptTemplate template = new PromptTemplate(templateResource);
Map<String, Object> variables = Map.of(
"data", "sales data",
"timeframe", "Q4 2024"
);
Prompt prompt = template.create(variables);Configuring Chat Options
import org.springframework.ai.chat.prompt.ChatOptions;
// Build comprehensive options
ChatOptions options = ChatOptions.builder()
.model("gpt-4o")
.temperature(0.7)
.maxTokens(2000)
.topP(0.9)
.frequencyPenalty(0.5)
.presencePenalty(0.5)
.stopSequences(List.of("\n\n", "END"))
.build();
Prompt prompt = new Prompt("Generate code", options);