GitHub

API reference for prompt.

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

AttributeTypeDescription
PROVIDER_OPTIONSRecordSchema[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_PARTS.Bottom[ToolModelOutputPart, Mapping[str, object]]
PARTS.Bottom[Part, Mapping[str, object]]
USER_MESSAGE_PARTS.Bottom[UserMessagePart, Mapping[str, object]]
ASSISTANT_MESSAGE_PARTS.Bottom[AssistantMessagePart, Mapping[str, object]]
TOOL_MESSAGE_PARTS.Bottom[ToolMessagePart, Mapping[str, object]]
MESSAGES.Bottom[Message, Mapping[str, object]]
emptyPrompt

The prompt with no messages.

Types

TypeDefinitionDescription
ProviderOptionstype ProviderOptions = dict[str, JsonValue]

Options for each provider, by provider name.

FileDatatype FileData = str | bytes | Url

A file's data: base64 text, bytes or a URL (a Url, from http.url.parse).

ToolModelOutputParttype ToolModelOutputPart = TextPart | FilePart

A part a tool's to_model_output returns, sent to the model in place of the encoded result.

Parttype Part = TextPart | ReasoningPart | FilePart | ToolCallPart | ToolResultPart | ToolApprovalResponsePart | ToolApprovalRequestPart
UserMessageParttype UserMessagePart = TextPart | FilePart
AssistantMessageParttype AssistantMessagePart = TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart | ToolApprovalRequestPart
ToolMessageParttype ToolMessagePart = ToolResultPart | ToolApprovalResponsePart
Messagetype Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
RawInputtype RawInput = str | Iterable[Message | Mapping[str, object]] | Prompt

What make accepts: a user's text, messages (or their wire form), or a prompt.

Classes

Functions

tool_model_output_to_text

tool_model_output_to_text(parts) -> 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.

ParameterTypeDescription
partsSequence[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) -> Prompt

A prompt from text (one user message), messages or their wire form (decoded; a bad one raises SchemaError), or a prompt itself.

ParameterTypeDescription
inputRawInput

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
ParameterTypeDescription
messagesIterable[Message]

Returns Prompt

def from_messages(messages: Iterable[Message]) -> Prompt:
    return Prompt(tuple(messages))

from_response_parts

from_response_parts(parts) -> 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.

ParameterTypeDescription
partsSequence[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()