Prompts for language models (Effect's Prompt).
A Prompt is a sequence of messages: a SystemMessage, UserMessage
(text and files), AssistantMessage (text, files, reasoning, tool calls,
results and approval requests) and ToolMessage (tool results and
approval responses). Each part and message carries provider options.
make accepts a string (one user message), messages, encoded messages
({"role": "user", "content": "hi"}, Effect's wire form) or a prompt::
prompt = make([
{"role": "system", "content": "Be brief."},
{"role": "user", "content": "Hello"},
]).append_system(" Answer in French.")Every class is a schema of its wire form (camelCase keys, as Effect's), so
S.encode_sync(Prompt)(prompt) exports a conversation.
Values#
| Attribute | Type | Description |
|---|---|---|
PROVIDER_OPTIONS | RecordSchema[str, bool | int | float | str | Sequence[JsonValue] | Mapping[str, JsonValue] | None, str, bool | int | float | str | Sequence[JsonValue] | Mapping[str, JsonValue] | None, Never, Never] | |
TOOL_MODEL_OUTPUT_PART | S.Bottom[ToolModelOutputPart, Mapping[str, object]] | |
PART | S.Bottom[Part, Mapping[str, object]] | |
USER_MESSAGE_PART | S.Bottom[UserMessagePart, Mapping[str, object]] | |
ASSISTANT_MESSAGE_PART | S.Bottom[AssistantMessagePart, Mapping[str, object]] | |
TOOL_MESSAGE_PART | S.Bottom[ToolMessagePart, Mapping[str, object]] | |
MESSAGE | S.Bottom[Message, Mapping[str, object]] | |
empty | Prompt | The prompt with no messages. |
Types#
| Type | Definition | Description |
|---|---|---|
ProviderOptions | type ProviderOptions = dict[str, JsonValue] | Options for each provider, by provider name. |
FileData | type FileData = str | bytes | Url | A file's data: base64 text, bytes or a URL (a |
ToolModelOutputPart | type ToolModelOutputPart = TextPart | FilePart | A part a tool's |
Part | type Part = TextPart | ReasoningPart | FilePart | ToolCallPart | ToolResultPart | ToolApprovalResponsePart | ToolApprovalRequestPart | |
UserMessagePart | type UserMessagePart = TextPart | FilePart | |
AssistantMessagePart | type AssistantMessagePart = TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart | ToolApprovalRequestPart | |
ToolMessagePart | type ToolMessagePart = ToolResultPart | ToolApprovalResponsePart | |
Message | type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage | |
RawInput | type RawInput = str | Iterable[Message | Mapping[str, object]] | Prompt | What |
Classes#
Functions#
tool_model_output_to_text#
tool_model_output_to_text(parts) -> strModel output as text, for providers whose tool results are text only: text parts joined by newlines, each file replaced by a placeholder naming its media type and file name.
| Parameter | Type | Description |
|---|---|---|
parts | Sequence[ToolModelOutputPart] |
Returns str
def tool_model_output_to_text(parts: Sequence[ToolModelOutputPart]) -> str:
"""Model output as text, for providers whose tool results are text
only: text parts joined by newlines, each file replaced by a placeholder
naming its media type and file name."""
return "\n".join(
part.text
if isinstance(part, TextPart)
else f"[{part.media_type}{'' if part.file_name is None else f' {part.file_name}'} omitted]"
for part in parts
)make#
make(input) -> PromptA prompt from text (one user message), messages or their wire form
(decoded; a bad one raises SchemaError), or a prompt itself.
| Parameter | Type | Description |
|---|---|---|
input | RawInput |
Returns Prompt
def make(input: RawInput) -> Prompt:
"""A prompt from text (one user message), messages or their wire form
(decoded; a bad one raises ``SchemaError``), or a prompt itself."""
if isinstance(input, str):
return Prompt((UserMessage(content=(TextPart(text=input),)),))
if isinstance(input, Prompt):
return input
items = list(input)
if all(
isinstance(m, (SystemMessage, UserMessage, AssistantMessage, ToolMessage)) for m in items
):
return Prompt(tuple(cast("list[Message]", items)))
encoded = [
S.encode_sync(MESSAGE)(m)
if isinstance(m, (SystemMessage, UserMessage, AssistantMessage, ToolMessage))
else m
for m in items
]
return Prompt(_decode_messages(encoded, errors="all"))from_messages#
from_messages(messages) -> Prompt| Parameter | Type | Description |
|---|---|---|
messages | Iterable[Message] |
Returns Prompt
def from_messages(messages: Iterable[Message]) -> Prompt:
return Prompt(tuple(messages))from_response_parts#
from_response_parts(parts) -> PromptThe prompt continuing a conversation with a response: an assistant message of its text, reasoning (streamed deltas folded), files, tool calls and provider-executed results, then a tool message of the other final tool results.
| Parameter | Type | Description |
|---|---|---|
parts | Sequence[Response.AnyPart] |
Returns Prompt
def from_response_parts(parts: Sequence[Response.AnyPart]) -> Prompt:
"""The prompt continuing a conversation with a response: an assistant
message of its text, reasoning (streamed deltas folded), files, tool
calls and provider-executed results, then a tool message of the other
final tool results."""
builder = _Builder()
for part in parts:
_fold(builder, part)
return builder.finish()