flowchart TB
    subgraph User["用户层"]
        APP[应用代码]
    end

    subgraph PromptsModule["Prompts模块"]
        subgraph Creation["模板创建"]
            FROM_TEMPLATE[from_template<br/>from_messages]
            CONSTRUCTOR[构造函数]
        end

        subgraph Templates["模板层"]
            PROMPT_TPL[PromptTemplate<br/>字符串模板]
            CHAT_TPL[ChatPromptTemplate<br/>聊天模板]
            FEW_SHOT[FewShotPromptTemplate<br/>Few-Shot模板]
        end

        subgraph Components["组件层"]
            MSG_PLACEHOLDER[MessagesPlaceholder<br/>消息占位符]
            MSG_TPL[MessagePromptTemplate<br/>消息模板]
            IMAGE_TPL[ImagePromptTemplate<br/>图片模板]
        end

        subgraph Processing["处理层"]
            VARIABLE_EXTRACT[变量提取<br/>get_template_variables]
            FORMATTER[格式化器<br/>f-string/jinja2/mustache]
            VALIDATOR[验证器<br/>check_valid_template]
        end

        subgraph Output["输出层"]
            PROMPT_VALUE[PromptValue<br/>抽象基类]
            STRING_VALUE[StringPromptValue<br/>文本输出]
            CHAT_VALUE[ChatPromptValue<br/>消息列表输出]
        end
    end

    subgraph Downstream["下游组件"]
        LLM[LLM<br/>文本生成模型]
        CHAT_MODEL[ChatModel<br/>对话模型]
        CHAIN[Chain<br/>链式调用]
    end

    subgraph Core["核心基础设施"]
        RUNNABLE[Runnable<br/>可运行接口]
        CALLBACKS[Callbacks<br/>回调系统]
        MESSAGES[Messages<br/>消息类型]
    end

    APP --> FROM_TEMPLATE
    APP --> CONSTRUCTOR
    FROM_TEMPLATE --> PROMPT_TPL
    FROM_TEMPLATE --> CHAT_TPL
    CONSTRUCTOR --> FEW_SHOT

    PROMPT_TPL --> VARIABLE_EXTRACT
    CHAT_TPL --> MSG_TPL
    CHAT_TPL --> MSG_PLACEHOLDER
    MSG_TPL --> IMAGE_TPL

    VARIABLE_EXTRACT --> FORMATTER
    FORMATTER --> VALIDATOR
    VALIDATOR --> PROMPT_VALUE

    PROMPT_TPL --> STRING_VALUE
    CHAT_TPL --> CHAT_VALUE
    STRING_VALUE --> PROMPT_VALUE
    CHAT_VALUE --> PROMPT_VALUE

    PROMPT_VALUE --> LLM
    PROMPT_VALUE --> CHAT_MODEL
    PROMPT_VALUE --> CHAIN

    PROMPT_TPL -.继承.-> RUNNABLE
    CHAT_TPL -.继承.-> RUNNABLE
    PROMPT_TPL -.使用.-> CALLBACKS
    CHAT_TPL -.使用.-> MESSAGES

    style PromptsModule fill:#e1f5ff
    style Templates fill:#fff4e1
    style Output fill:#e8f5e9
    style Downstream fill:#ffe1f5

flowchart TB
    subgraph Base["基类层"]
        RUNNABLE[RunnableSerializable<br/>可运行基类]
        BASE_PROMPT[BasePromptTemplate<br/>提示词模板基类]
        STRING_PROMPT[StringPromptTemplate<br/>字符串模板基类]
        BASE_CHAT[BaseChatPromptTemplate<br/>聊天模板基类]
        BASE_MSG[BaseMessagePromptTemplate<br/>消息模板基类]
    end

    subgraph SimpleTemplates["简单模板"]
        PROMPT_TEMPLATE[PromptTemplate<br/>基础字符串模板]
    end

    subgraph ChatTemplates["聊天模板"]
        CHAT_PROMPT[ChatPromptTemplate<br/>聊天提示模板]
        MSG_PLACEHOLDER[MessagesPlaceholder<br/>消息占位符]
        HUMAN_TPL[HumanMessagePromptTemplate<br/>用户消息模板]
        AI_TPL[AIMessagePromptTemplate<br/>AI消息模板]
        SYSTEM_TPL[SystemMessagePromptTemplate<br/>系统消息模板]
    end

    subgraph FewShot["Few-Shot模板"]
        FEW_SHOT[FewShotPromptTemplate<br/>示例提示模板]
        FEW_SHOT_CHAT[FewShotChatMessagePromptTemplate<br/>聊天示例模板]
    end

    subgraph Specialized["特殊模板"]
        IMAGE_TPL[ImagePromptTemplate<br/>图片模板]
        DICT_TPL[DictPromptTemplate<br/>字典模板]
    end

    RUNNABLE <|-- BASE_PROMPT
    BASE_PROMPT <|-- STRING_PROMPT
    BASE_PROMPT <|-- BASE_CHAT
    BASE_PROMPT <|-- IMAGE_TPL
    BASE_PROMPT <|-- DICT_TPL

    STRING_PROMPT <|-- PROMPT_TEMPLATE
    STRING_PROMPT <|-- FEW_SHOT

    BASE_CHAT <|-- CHAT_PROMPT

    BASE_MSG <|-- MSG_PLACEHOLDER
    BASE_MSG <|-- HUMAN_TPL
    BASE_MSG <|-- AI_TPL
    BASE_MSG <|-- SYSTEM_TPL

    CHAT_PROMPT --> MSG_PLACEHOLDER
    CHAT_PROMPT --> HUMAN_TPL
    CHAT_PROMPT --> AI_TPL
    CHAT_PROMPT --> SYSTEM_TPL
    CHAT_PROMPT --> FEW_SHOT_CHAT

    style BASE_PROMPT fill:#e1f5ff
    style CHAT_PROMPT fill:#fff4e1
    style PROMPT_TEMPLATE fill:#e8f5e9

sequenceDiagram
    autonumber
    participant User as 用户代码
    participant PT as PromptTemplate
    participant Extractor as get_template_variables
    participant Validator as check_valid_template
    participant Base as BasePromptTemplate
    participant Formatter as DEFAULT_FORMATTER
    participant PV as StringPromptValue
    participant Model as ChatModel

    Note over User,Model: 阶段1: 模板创建

    User->>PT: from_template("Tell me a {adjective} joke")
    activate PT
    PT->>Extractor: 提取模板变量
    activate Extractor
    Extractor->>Extractor: 使用Formatter().parse()解析
    Extractor-->>PT: ["adjective"]
    deactivate Extractor

    alt validate_template=True
        PT->>Validator: 验证模板
        activate Validator
        Validator->>Validator: 检查变量一致性
        Validator-->>PT: 验证通过
        deactivate Validator
    end

    PT->>PT: 构造实例<br/>template="Tell me a {adjective} joke"<br/>input_variables=["adjective"]
    PT-->>User: PromptTemplate实例
    deactivate PT

    Note over User,Model: 阶段2: 模板调用(invoke)

    User->>PT: invoke({"adjective": "funny"})
    activate PT
    PT->>Base: invoke(input, config)
    activate Base
    Base->>Base: ensure_config(config)
    Base->>Base: 注入metadata和tags
    Base->>Base: _call_with_config(<br/>  _format_prompt_with_error_handling,<br/>  input, config, run_type="prompt"<br/>)

    Note over Base: 回调系统启动
    Base->>Base: _validate_input({"adjective": "funny"})
    Base->>Base: 检查input_variables是否满足

    Base->>PT: format_prompt(adjective="funny")
    PT->>PT: format(adjective="funny")
    activate PT
    PT->>PT: _merge_partial_and_user_variables
    PT->>PT: 合并partial_variables和kwargs
    PT->>Formatter: DEFAULT_FORMATTER_MAPPING["f-string"]
    activate Formatter
    Formatter->>Formatter: template.format(adjective="funny")
    Formatter-->>PT: "Tell me a funny joke"
    deactivate Formatter
    PT-->>Base: "Tell me a funny joke"
    deactivate PT

    Base->>PV: StringPromptValue(text="Tell me a funny joke")
    activate PV
    PV-->>Base: StringPromptValue实例
    deactivate PV
    Base-->>PT: PromptValue
    deactivate Base
    PT-->>User: PromptValue
    deactivate PT

    Note over User,Model: 阶段3: 传递给模型

    User->>Model: prompt | model
    activate Model
    Model->>PV: to_messages()
    activate PV
    PV->>PV: 转换为[HumanMessage(content=text)]
    PV-->>Model: [HumanMessage("Tell me a funny joke")]
    deactivate PV
    Model->>Model: _generate(messages)
    Model-->>User: AIMessage(...)
    deactivate Model

@classmethod
def from_template(
    cls,
    template: str,
    *,
    template_format: str = "f-string",
    partial_variables: dict[str, Any] | None = None,
    **kwargs: Any,
) -> PromptTemplate:
    # 1) 提取变量
    input_variables = get_template_variables(template, template_format)
    # get_template_variables内部:
    #   if template_format == "f-string":
    #       return {v for _, v, _, _ in Formatter().parse(template) if v is not None}

    # 2) 移除partial_variables
    if partial_variables:
        input_variables = [
            var for var in input_variables
            if var not in partial_variables
        ]

    # 3) 构造实例
    return cls(
        template=template,
        input_variables=input_variables,
        template_format=template_format,
        partial_variables=partial_variables or {},
        **kwargs,
    )

def invoke(
    self, input: dict, config: RunnableConfig | None = None, **kwargs: Any
) -> PromptValue:
    config = ensure_config(config)
    # 注入元数据
    if self.metadata:
        config["metadata"] = {**config["metadata"], **self.metadata}
    if self.tags:
        config["tags"] += self.tags

    # _call_with_config会:
    # 1) 启动回调系统(on_prompt_start)
    # 2) 调用_format_prompt_with_error_handling
    # 3) 触发回调(on_prompt_end)
    return self._call_with_config(
        self._format_prompt_with_error_handling,
        input,
        config,
        run_type="prompt",
        serialized=self._serialized,
    )

def _format_prompt_with_error_handling(self, inner_input: dict) -> PromptValue:
    # 验证输入
    inner_input_ = self._validate_input(inner_input)
    # 调用format_prompt
    return self.format_prompt(**inner_input_)

def format(self, **kwargs: Any) -> str:
    # 合并变量
    kwargs = self._merge_partial_and_user_variables(**kwargs)
    # _merge_partial_and_user_variables内部:
    #   partial_kwargs = {
    #       k: v if not callable(v) else v()
    #       for k, v in self.partial_variables.items()
    #   }
    #   return {**partial_kwargs, **kwargs}

    # 格式化
    return DEFAULT_FORMATTER_MAPPING[self.template_format](self.template, **kwargs)
    # 对于f-string: template.format(**kwargs)

# 管道操作符
class RunnableSerializable:
    def __or__(self, other: Runnable) -> RunnableSequence:
        # prompt | model 创建一个RunnableSequence
        return RunnableSequence(first=self, last=other)

# StringPromptValue转换
class StringPromptValue(PromptValue):
    def to_messages(self) -> list[BaseMessage]:
        # 将文本包装为HumanMessage
        return [HumanMessage(content=self.text)]

sequenceDiagram
    autonumber
    participant User as 用户代码
    participant CPT as ChatPromptTemplate
    participant Conv as _convert_to_message_template
    participant Validator as validate_input_variables
    participant Base as BasePromptTemplate
    participant Msg_TPL as MessagePromptTemplate
    participant Placeholder as MessagesPlaceholder
    participant Convert as convert_to_messages
    participant PV as ChatPromptValue
    participant Model as ChatModel

    Note over User,Model: 阶段1: 模板创建

    User->>CPT: from_messages([<br/>  ("system", "You are {role}"),<br/>  MessagesPlaceholder("history"),<br/>  ("human", "{input}")<br/>])
    activate CPT

    loop 每个消息
        CPT->>Conv: _convert_to_message_template(message)
        activate Conv

        alt message是tuple("system", "You are {role}")
            Conv->>Conv: _create_template_from_message_type("system", template)
            Conv->>Msg_TPL: SystemMessagePromptTemplate.from_template
            activate Msg_TPL
            Msg_TPL->>Msg_TPL: PromptTemplate.from_template("You are {role}")
            Msg_TPL-->>Conv: SystemMessagePromptTemplate
            deactivate Msg_TPL
        else message是MessagesPlaceholder
            Conv-->>CPT: MessagesPlaceholder(variable_name="history")
        else message是tuple("human", "{input}")
            Conv->>Msg_TPL: HumanMessagePromptTemplate.from_template
            activate Msg_TPL
            Msg_TPL->>Msg_TPL: PromptTemplate.from_template("{input}")
            Msg_TPL-->>Conv: HumanMessagePromptTemplate
            deactivate Msg_TPL
        end

        Conv-->>CPT: MessagePromptTemplate
        deactivate Conv
    end

    CPT->>CPT: 收集所有input_variables:<br/>["role", "history", "input"]
    CPT->>CPT: 识别optional_variables:<br/>如果MessagesPlaceholder.optional=True
    CPT->>Validator: validate_input_variables
    activate Validator
    Validator->>Validator: 检查变量一致性
    Validator-->>CPT: 验证通过
    deactivate Validator

    CPT->>CPT: 构造实例<br/>messages=[SystemMsgTpl, Placeholder, HumanMsgTpl]<br/>input_variables=["role", "history", "input"]
    CPT-->>User: ChatPromptTemplate实例
    deactivate CPT

    Note over User,Model: 阶段2: 模板调用(invoke)

    User->>CPT: invoke({<br/>  "role": "assistant",<br/>  "history": [("human", "Hi"), ("ai", "Hello!")],<br/>  "input": "How are you?"<br/>})
    activate CPT
    CPT->>Base: invoke(input, config)
    activate Base
    Base->>Base: ensure_config(config)
    Base->>Base: 注入metadata和tags
    Base->>Base: _call_with_config(<br/>  _format_prompt_with_error_handling,<br/>  input, config, run_type="prompt"<br/>)

    Note over Base: 回调系统启动
    Base->>Base: _validate_input({<br/>  "role": "assistant",<br/>  "history": [...],<br/>  "input": "How are you?"<br/>})
    Base->>Base: 检查所有input_variables

    Base->>CPT: format_prompt(**kwargs)
    CPT->>CPT: format_messages(**kwargs)
    activate CPT
    CPT->>CPT: _merge_partial_and_user_variables

    Note over CPT: 遍历messages列表

    CPT->>Msg_TPL: SystemMessagePromptTemplate.format_messages(role="assistant")
    activate Msg_TPL
    Msg_TPL->>Msg_TPL: format(role="assistant")
    Msg_TPL->>Msg_TPL: prompt.format(role="assistant")
    Msg_TPL->>Msg_TPL: "You are assistant"
    Msg_TPL-->>CPT: [SystemMessage("You are assistant")]
    deactivate Msg_TPL

    CPT->>Placeholder: MessagesPlaceholder.format_messages(history=[...])
    activate Placeholder
    Placeholder->>Placeholder: 获取kwargs["history"]
    Placeholder->>Convert: convert_to_messages([("human", "Hi"), ("ai", "Hello!")])
    activate Convert
    Convert->>Convert: 转换tuple为BaseMessage
    Convert-->>Placeholder: [HumanMessage("Hi"), AIMessage("Hello!")]
    deactivate Convert

    alt n_messages设置
        Placeholder->>Placeholder: messages[-n_messages:]<br/>只保留最近N条
    end

    Placeholder-->>CPT: [HumanMessage("Hi"), AIMessage("Hello!")]
    deactivate Placeholder

    CPT->>Msg_TPL: HumanMessagePromptTemplate.format_messages(input="How are you?")
    activate Msg_TPL
    Msg_TPL->>Msg_TPL: format(input="How are you?")
    Msg_TPL->>Msg_TPL: prompt.format(input="How are you?")
    Msg_TPL->>Msg_TPL: "How are you?"
    Msg_TPL-->>CPT: [HumanMessage("How are you?")]
    deactivate Msg_TPL

    CPT->>CPT: result.extend(messages)<br/>合并所有消息:<br/>[SystemMessage, HumanMessage, AIMessage, HumanMessage]
    CPT-->>Base: messages列表
    deactivate CPT

    Base->>PV: ChatPromptValue(messages=[...])
    activate PV
    PV-->>Base: ChatPromptValue实例
    deactivate PV
    Base-->>CPT: PromptValue
    deactivate Base
    CPT-->>User: ChatPromptValue
    deactivate CPT

    Note over User,Model: 阶段3: 传递给模型

    User->>Model: prompt | model
    activate Model
    Model->>PV: to_messages()
    activate PV
    PV->>PV: 直接返回messages列表
    PV-->>Model: [SystemMessage, HumanMessage, AIMessage, HumanMessage]
    deactivate PV
    Model->>Model: _generate(messages)
    Model-->>User: AIMessage(...)
    deactivate Model

def __init__(
    self,
    messages: Sequence[MessageLikeRepresentation],
    *,
    template_format: PromptTemplateFormat = "f-string",
    **kwargs: Any,
) -> None:
    # 1) 转换所有消息
    messages_ = [
        _convert_to_message_template(message, template_format)
        for message in messages
    ]

    # 2) 收集变量
    input_vars: set[str] = set()
    optional_variables: set[str] = set()
    partial_vars: dict[str, Any] = {}

    for _message in messages_:
        # 可选占位符自动添加到partial_variables
        if isinstance(_message, MessagesPlaceholder) and _message.optional:
            partial_vars[_message.variable_name] = []
            optional_variables.add(_message.variable_name)
        elif isinstance(_message, (BaseChatPromptTemplate, BaseMessagePromptTemplate)):
            input_vars.update(_message.input_variables)

    # 3) 构造
    kwargs = {
        "input_variables": sorted(input_vars),
        "optional_variables": sorted(optional_variables),
        "partial_variables": partial_vars,
        **kwargs,
    }
    super().__init__(messages=messages_, **kwargs)

def _convert_to_message_template(
    message: MessageLikeRepresentation,
    template_format: PromptTemplateFormat = "f-string",
) -> BaseMessage | BaseMessagePromptTemplate | BaseChatPromptTemplate:
    # 支持的格式:
    # 1. BaseMessagePromptTemplate: 直接使用
    # 2. BaseMessage: 固定消息
    # 3. tuple: ("role", "template")
    # 4. str: 默认为human消息
    # 5. dict: {"role": "...", "content": "..."}

    if isinstance(message, (BaseMessagePromptTemplate, BaseChatPromptTemplate)):
        return message
    elif isinstance(message, BaseMessage):
        return message
    elif isinstance(message, str):
        # 默认为HumanMessagePromptTemplate
        return _create_template_from_message_type("human", message, template_format)
    elif isinstance(message, (tuple, dict)):
        if isinstance(message, dict):
            message = (message["role"], message["content"])
        message_type_str, template = message
        return _create_template_from_message_type(
            message_type_str, template, template_format
        )
    else:
        raise NotImplementedError(f"Unsupported message type: {type(message)}")

def _create_template_from_message_type(
    message_type: str,
    template: str | list,
    template_format: PromptTemplateFormat = "f-string",
) -> BaseMessagePromptTemplate:
    # 根据消息类型创建对应模板
    if message_type in {"human", "user"}:
        return HumanMessagePromptTemplate.from_template(template, template_format)
    elif message_type in {"ai", "assistant"}:
        return AIMessagePromptTemplate.from_template(template, template_format)
    elif message_type == "system":
        return SystemMessagePromptTemplate.from_template(template, template_format)
    elif message_type == "placeholder":
        # 特殊处理: ("placeholder", "{variable_name}")
        var_name = template[1:-1]  # 去除{}
        return MessagesPlaceholder(variable_name=var_name, optional=True)
    else:
        raise ValueError(f"Unexpected message type: {message_type}")

def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
    # 1) 合并变量
    kwargs = self._merge_partial_and_user_variables(**kwargs)

    # 2) 遍历消息模板
    result = []
    for message_template in self.messages:
        if isinstance(message_template, BaseMessage):
            # 固定消息,直接添加
            result.extend([message_template])
        elif isinstance(message_template, (BaseMessagePromptTemplate, BaseChatPromptTemplate)):
            # 模板消息,格式化后添加
            message = message_template.format_messages(**kwargs)
            result.extend(message)
        else:
            raise ValueError(f"Unexpected input: {message_template}")

    return result

# MessagesPlaceholder实现
class MessagesPlaceholder(BaseMessagePromptTemplate):
    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
        # 1) 获取变量值
        if self.variable_name in kwargs:
            value = kwargs[self.variable_name]
        elif self.optional:
            # 可选占位符,返回空列表
            return []
        else:
            raise KeyError(f"Missing required variable: {self.variable_name}")

        # 2) 转换为消息列表
        messages = convert_to_messages(value)
        # convert_to_messages支持:
        # - list[BaseMessage]: 直接返回
        # - list[tuple]: [("human", "Hi"), ("ai", "Hello")]
        # - list[dict]: [{"role": "human", "content": "Hi"}]

        # 3) 限制消息数量
        if self.n_messages is not None:
            messages = messages[-self.n_messages:]

        return messages

class ChatPromptValue(PromptValue):
    messages: Sequence[BaseMessage]

    def to_messages(self) -> list[BaseMessage]:
        # 直接返回消息列表,无需转换
        return list(self.messages)

    def to_string(self) -> str:
        # 转换为字符串(用于LLM)
        return get_buffer_string(self.messages)
        # get_buffer_string格式:
        # "System: You are assistant\nHuman: Hi\nAI: Hello!\nHuman: How are you?"

classDiagram
    class BasePromptTemplate {
        <<abstract>>
        +input_variables: list[str]
        +partial_variables: dict
        +metadata: dict|None
        +tags: list[str]|None
        +format(**kwargs) str
        +format_prompt(**kwargs) PromptValue
        +invoke(input) PromptValue
    }

    class PromptTemplate {
        +template: str
        +template_format: str
        +validate_template: bool
        +from_template(template: str) PromptTemplate
    }

    class ChatPromptTemplate {
        +messages: list[MessageLike]
        +from_messages(messages: list) ChatPromptTemplate
        +from_template(template: str) ChatPromptTemplate
        +format_messages(**kwargs) list[BaseMessage]
    }

    class MessagesPlaceholder {
        +variable_name: str
        +optional: bool
        +n_messages: int|None
    }

    class FewShotPromptTemplate {
        +examples: list[dict]
        +example_prompt: PromptTemplate
        +example_separator: str
        +prefix: str
        +suffix: str
    }

    BasePromptTemplate <|-- PromptTemplate
    BasePromptTemplate <|-- ChatPromptTemplate
    ChatPromptTemplate --> MessagesPlaceholder
    BasePromptTemplate <|-- FewShotPromptTemplate

template: str  # 模板字符串
template_format: str  # 模板格式
partial_variables: dict | None  # 部分变量

PromptTemplate  # 提示词模板实例

class PromptTemplate(StringPromptTemplate):
    @classmethod
    def from_template(
        cls,
        template: str,
        *,
        template_format: str = "f-string",
        partial_variables: dict | None = None,
        **kwargs: Any,
    ) -> PromptTemplate:
        """从模板字符串创建提示词模板

        Args:
            template: 模板字符串,如"Tell me a {adjective} joke about {content}"
            template_format: 模板格式,"f-string"或"jinja2"
            partial_variables: 部分变量字典

        Returns:
            PromptTemplate实例
        """
        # 1) 提取模板中的变量
        if template_format == "f-string":
            input_variables = get_template_variables(template, template_format)
        elif template_format == "jinja2":
            input_variables = get_template_variables(template, template_format)
        else:
            msg = f"Unsupported template format: {template_format}"
            raise ValueError(msg)

        # 2) 从input_variables中移除partial_variables
        if partial_variables:
            input_variables = [
                var for var in input_variables
                if var not in partial_variables
            ]

        # 3) 构造PromptTemplate实例
        return cls(
            template=template,
            input_variables=input_variables,
            template_format=template_format,
            partial_variables=partial_variables or {},
            **kwargs,
        )

    def format(self, **kwargs: Any) -> str:
        """格式化模板

        Args:
            **kwargs: 变量值

        Returns:
            格式化后的字符串
        """
        # 1) 合并partial_variables和kwargs
        all_kwargs = {**self.partial_variables, **kwargs}

        # 2) 根据template_format格式化
        if self.template_format == "f-string":
            return self.template.format(**all_kwargs)
        elif self.template_format == "jinja2":
            return self._render_jinja2(self.template, all_kwargs)

# 基础使用
prompt = PromptTemplate.from_template(
    "Tell me a {adjective} joke about {content}"
)

result = prompt.format(adjective="funny", content="chickens")
# "Tell me a funny joke about chickens"

# 使用partial变量
prompt = PromptTemplate.from_template(
    "Tell me a {adjective} joke about {content}",
    partial_variables={"adjective": "funny"}
)

result = prompt.format(content="chickens")
# "Tell me a funny joke about chickens"

# Jinja2模板
prompt = PromptTemplate.from_template(
    "Tell me a {{ adjective }} joke about {{ content }}",
    template_format="jinja2"
)

# 在链中使用
chain = prompt | model | parser
result = chain.invoke({"adjective": "funny", "content": "chickens"})

sequenceDiagram
    autonumber
    participant User
    participant PromptTemplate
    participant Parser as get_template_variables

    User->>PromptTemplate: from_template("Tell me a {adjective} joke")
    PromptTemplate->>Parser: 提取变量
    Parser-->>PromptTemplate: ["adjective"]
    PromptTemplate->>PromptTemplate: 构造实例
    PromptTemplate-->>User: PromptTemplate实例

    User->>PromptTemplate: format(adjective="funny")
    PromptTemplate->>PromptTemplate: 合并partial_variables
    PromptTemplate->>PromptTemplate: template.format(**kwargs)
    PromptTemplate-->>User: "Tell me a funny joke"

messages: Sequence[MessageLikeRepresentation]
# MessageLikeRepresentation = tuple | str | BaseMessage | MessagePromptTemplate

ChatPromptTemplate  # 聊天提示模板实例

class ChatPromptTemplate(BaseChatPromptTemplate):
    @classmethod
    def from_messages(
        cls,
        messages: Sequence[MessageLikeRepresentation],
    ) -> ChatPromptTemplate:
        """从消息列表创建聊天提示模板

        Args:
            messages: 消息列表,支持多种格式

        Returns:
            ChatPromptTemplate实例
        """
        # 1) 转换每个消息为MessagePromptTemplate
        message_templates = []
        for message in messages:
            message_template = _convert_to_message_template(message)
            message_templates.append(message_template)

        # 2) 提取所有输入变量
        input_variables = set()
        for template in message_templates:
            input_variables.update(template.input_variables)

        # 3) 构造实例
        return cls(
            messages=message_templates,
            input_variables=list(input_variables),
        )

    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
        """格式化为消息列表

        Args:
            **kwargs: 变量值

        Returns:
            BaseMessage列表
        """
        # 1) 合并partial_variables和kwargs
        all_kwargs = {**self.partial_variables, **kwargs}

        # 2) 格式化每个消息模板
        result = []
        for message_template in self.messages:
            messages = message_template.format_messages(**all_kwargs)
            result.extend(messages)

        return result

def _convert_to_message_template(message: MessageLikeRepresentation):
    """转换为MessagePromptTemplate"""
    if isinstance(message, BaseMessagePromptTemplate):
        return message
    elif isinstance(message, BaseMessage):
        # 固定消息,无变量
        return FixedMessagePromptTemplate(message=message)
    elif isinstance(message, tuple) and len(message) == 2:
        # ("system", "You are {role}") → SystemMessagePromptTemplate
        role, content = message
        return _role_to_template(role, content)
    elif isinstance(message, str):
        # "What is {topic}?" → HumanMessagePromptTemplate
        return HumanMessagePromptTemplate.from_template(message)
    else:
        msg = f"Unsupported message type: {type(message)}"
        raise ValueError(msg)

def _role_to_template(role: str, content: str):
    """根据角色创建对应模板"""
    role = role.lower()
    if role in ("system",):
        return SystemMessagePromptTemplate.from_template(content)
    elif role in ("human", "user"):
        return HumanMessagePromptTemplate.from_template(content)
    elif role in ("ai", "assistant"):
        return AIMessagePromptTemplate.from_template(content)
    elif role == "placeholder":
        return MessagesPlaceholder(variable_name=content)
    else:
        return ChatMessagePromptTemplate.from_template(content, role=role)

# 基础使用
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    ("human", "Hello, my name is {name}"),
    ("ai", "Hello {name}, nice to meet you!"),
    ("human", "{question}"),
])

messages = prompt.format_messages(name="Alice", question="What is AI?")
# [
#   SystemMessage("You are a helpful assistant"),
#   HumanMessage("Hello, my name is Alice"),
#   AIMessage("Hello Alice, nice to meet you!"),
#   HumanMessage("What is AI?"),
# ]

# 使用MessagesPlaceholder
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    MessagesPlaceholder("history"),
    ("human", "{input}"),
])

messages = prompt.format_messages(
    history=[
        ("human", "Hi"),
        ("ai", "Hello!"),
    ],
    input="What is 2+2?"
)

# 在链中使用
chain = prompt | model | parser
result = chain.invoke({"name": "Bob", "question": "Explain quantum computing"})

sequenceDiagram
    autonumber
    participant User
    participant ChatPrompt as ChatPromptTemplate
    participant Convert as _convert_to_message_template
    participant Model as ChatModel

    User->>ChatPrompt: from_messages([<br/>  ("system", "You are {role}"),<br/>  ("human", "{input}")<br/>])

    loop 每个消息
        ChatPrompt->>Convert: 转换消息格式
        Convert-->>ChatPrompt: MessagePromptTemplate
    end

    ChatPrompt-->>User: ChatPromptTemplate实例

    User->>ChatPrompt: format_messages(role="assistant", input="Hi")

    loop 每个模板
        ChatPrompt->>ChatPrompt: 格式化模板
    end

    ChatPrompt-->>User: [SystemMessage(...), HumanMessage(...)]

    User->>Model: invoke(messages)
    Model-->>User: AIMessage(...)

variable_name: str  # 占位符变量名
optional: bool  # 是否可选
n_messages: int | None  # 保留最近N条消息

MessagesPlaceholder  # 消息占位符实例

class MessagesPlaceholder(BaseMessagePromptTemplate):
    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
        """格式化占位符为消息列表

        Args:
            **kwargs: 必须包含variable_name对应的消息列表

        Returns:
            消息列表
        """
        # 1) 获取变量值
        if self.variable_name in kwargs:
            value = kwargs[self.variable_name]
        elif self.optional:
            # 可选占位符,返回空列表
            return []
        else:
            msg = f"Missing required variable: {self.variable_name}"
            raise KeyError(msg)

        # 2) 转换为消息列表
        messages = convert_to_messages(value)

        # 3) 限制消息数量
        if self.n_messages is not None:
            messages = messages[-self.n_messages:]

        return messages

# 基础使用
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    MessagesPlaceholder("chat_history"),
    ("human", "{input}"),
])

# 传入对话历史
messages = prompt.format_messages(
    chat_history=[
        ("human", "What's 2+2?"),
        ("ai", "2+2 equals 4"),
        ("human", "What's 3+3?"),
        ("ai", "3+3 equals 6"),
    ],
    input="Now what's 5+5?"
)

# 可选占位符
optional_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    MessagesPlaceholder("chat_history", optional=True),
    ("human", "{input}"),
])

# 不传chat_history也不会报错
messages = optional_prompt.format_messages(input="Hello")

# 限制历史长度
limited_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    MessagesPlaceholder("chat_history", n_messages=2),  # 只保留最近2条
    ("human", "{input}"),
])

examples: list[dict]  # 示例列表
example_prompt: PromptTemplate  # 单个示例的格式模板
example_separator: str  # 示例之间的分隔符
prefix: str  # 前缀
suffix: str  # 后缀
input_variables: list[str]  # 输入变量

FewShotPromptTemplate  # Few-Shot模板实例

class FewShotPromptTemplate(StringPromptTemplate):
    examples: list[dict]
    example_prompt: PromptTemplate
    example_separator: str = "\n\n"
    prefix: str = ""
    suffix: str = ""

    def format(self, **kwargs: Any) -> str:
        """格式化Few-Shot模板

        Args:
            **kwargs: 变量值

        Returns:
            格式化后的字符串
        """
        # 1) 格式化前缀
        result = [self.prefix.format(**kwargs) if self.prefix else ""]

        # 2) 格式化每个示例
        for example in self.examples:
            example_str = self.example_prompt.format(**example)
            result.append(example_str)

        # 3) 格式化后缀
        if self.suffix:
            result.append(self.suffix.format(**kwargs))

        # 4) 用分隔符连接
        return self.example_separator.join([r for r in result if r])

# 定义示例
examples = [
    {"input": "What's 2+2?", "output": "4"},
    {"input": "What's 3+3?", "output": "6"},
    {"input": "What's 4+4?", "output": "8"},
]

# 定义示例格式
example_prompt = PromptTemplate.from_template(
    "Input: {input}\nOutput: {output}"
)

# 创建Few-Shot模板
prompt = FewShotPromptTemplate(
    examples=examples,
    example_prompt=example_prompt,
    prefix="Answer the following questions:",
    suffix="Input: {input}\nOutput:",
    input_variables=["input"],
)

# 使用
result = prompt.format(input="What's 5+5?")
# Answer the following questions:
#
# Input: What's 2+2?
# Output: 4
#
# Input: What's 3+3?
# Output: 6
#
# Input: What's 4+4?
# Output: 8
#
# Input: What's 5+5?
# Output:

prompt = ChatPromptTemplate.from_messages([
    ("system", """你是一个专业的{domain}专家。

你的特点:
- 知识渊博,经验丰富
- 表达清晰,逻辑严谨
- 善于举例说明

请用专业但通俗易懂的方式回答问题。"""),
    MessagesPlaceholder("examples", optional=True),
    ("human", "{question}"),
])

# 使用
response = (prompt | model).invoke({
    "domain": "机器学习",
    "question": "什么是梯度下降?"
})

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    MessagesPlaceholder("chat_history"),
    ("human", "{input}"),
])

# 维护对话历史
chat_history = []

def chat(user_input: str):
    messages = prompt.format_messages(
        chat_history=chat_history,
        input=user_input
    )

    response = model.invoke(messages)

    # 更新历史
    chat_history.append(HumanMessage(user_input))
    chat_history.append(response)

    return response.content

# 对话
chat("Hi, I'm Alice")
chat("What's my name?")  # 记住前面的对话

from langchain_core.prompts import FewShotChatMessagePromptTemplate

# 动态选择示例
example_selector = SemanticSimilarityExampleSelector.from_examples(
    examples,
    OpenAIEmbeddings(),
    Chroma,
    k=2  # 选择最相关的2个示例
)

few_shot_prompt = FewShotChatMessagePromptTemplate(
    example_selector=example_selector,
    example_prompt=ChatPromptTemplate.from_messages([
        ("human", "{input}"),
        ("ai", "{output}"),
    ]),
)

final_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    few_shot_prompt,
    ("human", "{input}"),
])

# 推荐: 将模板定义为常量
SYSTEM_PROMPT = "You are a {role} expert"
USER_PROMPT = "Answer this question: {question}"

prompt = ChatPromptTemplate.from_messages([
    ("system", SYSTEM_PROMPT),
    ("human", USER_PROMPT),
])

# 推荐: 模板复用
base_system = "You are a helpful assistant"

qa_prompt = ChatPromptTemplate.from_messages([
    ("system", base_system),
    ("human", "Question: {question}"),
])

chat_prompt = ChatPromptTemplate.from_messages([
    ("system", base_system),
    MessagesPlaceholder("history"),
    ("human", "{input}"),
])

# 使用partial固定某些变量
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a {role} expert. Today is {date}"),
    ("human", "{question}"),
])

# 固定date
from datetime import datetime
prompt_with_date = prompt.partial(date=datetime.now().strftime("%Y-%m-%d"))

# 只需传role和question
prompt_with_date.invoke({"role": "AI", "question": "..."})

# 清晰的指令
prompt = ChatPromptTemplate.from_template("""
根据以下文本回答问题。

文本:
{context}

要求:
1. 只使用文本中的信息
2. 如果文本中没有答案,说"我不知道"
3. 引用原文支持你的答案

问题: {question}
答案:""")

# Few-Shot增强
few_shot_examples = [...]  # 高质量示例
prompt = FewShotPromptTemplate(
    examples=few_shot_examples,
    example_prompt=example_template,
    suffix="Now answer: {question}",
    input_variables=["question"],
)

flowchart LR
    subgraph Upstream["上游模块(调用方)"]
        APP[应用代码]
        CHAINS[Chains模块]
        AGENTS[Agents模块]
    end

    subgraph PromptsCore["Prompts模块核心"]
        PT[PromptTemplate]
        CPT[ChatPromptTemplate]
        FST[FewShotPromptTemplate]
    end

    subgraph Downstream["下游模块(被调用方)"]
        LLM[LLM模型]
        CHAT[ChatModel]
        EMBEDDINGS[Embeddings]
    end

    subgraph Infrastructure["基础设施模块"]
        RUNNABLE[Runnables]
        MESSAGES[Messages]
        CALLBACKS[Callbacks]
        PV[PromptValues]
    end

    APP -->|创建模板| PT
    APP -->|创建模板| CPT
    CHAINS -->|链式调用| PT
    CHAINS -->|链式调用| CPT
    AGENTS -->|构造提示| CPT
    AGENTS -->|格式化指令| FST

    PT -->|继承| RUNNABLE
    CPT -->|继承| RUNNABLE
    FST -->|继承| RUNNABLE

    PT -->|生成| PV
    CPT -->|生成| PV
    CPT -->|使用| MESSAGES

    PT -->|通过Runnable| LLM
    CPT -->|通过Runnable| CHAT
    PT -->|格式化文档| EMBEDDINGS

    PT -.触发.-> CALLBACKS
    CPT -.触发.-> CALLBACKS

    style PromptsCore fill:#e1f5ff
    style Infrastructure fill:#fff4e1

# PromptTemplate
app_code → PromptTemplate.from_template()
  → get_template_variables()  # 提取变量
  → __init__()  # 构造实例

# ChatPromptTemplate
app_code → ChatPromptTemplate.from_messages()
  → _convert_to_message_template()  # 转换消息
  → __init__()  # 构造实例

chain/agent → prompt.invoke(input_dict)
  → BasePromptTemplate.invoke()
  → _call_with_config()  # 启动回调
    → _format_prompt_with_error_handling()
      → _validate_input()  # 验证输入
      → format_prompt()  # 格式化
        → format()  # 子类实现
  → 返回PromptValue