POML Python Core API 参考

POML Python Core API 参考

导语

本文基于 POML 官方文档的 Python Core APIs 参考页面，梳理核心接口的用途与用法。POML（Prompt Orchestration Markup Language）用于创建结构化的提示与对话；核心 API 提供对 POML 标记的处理能力，并支持可选的追踪与多种后端集成。

概览与功能说明

• poml()：处理 POML 标记，按指定格式返回结果，可选择聊天模式或单次提示，并支持将输出保存到文件。
• set_trace()：启用/关闭追踪，并按需接入后端（local、weave、agentops、mlflow）。
• clear_trace() / get_trace()：清理或获取追踪日志副本。
• trace_artifact()：为最近一次 poml 调用写入额外的工件文件（实验性）。
• 说明要点：
  • 在启用 set_trace() 时，会自动记录调用详情。
  • 支持多种输出格式（如 raw、message_dict、dict、openai_chat、langchain、pydantic）。
  • 在聊天格式下支持多模态内容（例如图片）。

核心 API 与参数

set_trace(enabled=True, /, *, trace_dir=None)

• 作用：启用或禁用 poml 调用的追踪，并可选择后端集成。
• 参数：
  • enabled: bool | List[str] | str
    • True：仅启用本地追踪（等价于 ["local"]）
    • False：关闭所有追踪（等价于 []）
    • "local" | "weave" | "agentops" | "mlflow"：启用单个后端
    • List[str]：启用多个后端（指定任一后端时会自动启用本地追踪）
  • trace_dir: Optional[str | Path]：为本地追踪指定目录；开启本地追踪时会在其中创建以时间戳命名的子目录。
• 返回：Optional[Path]，若启用本地追踪则返回追踪目录路径，否则为 None。
• 其他：可通过环境变量 POML_TRACE 与 Node.js 共享目录。可用后端：
  • local：将追踪文件保存到磁盘
  • weave：上报到 Weights & Biases Weave（需要本地追踪）
  • agentops：上报到 AgentOps（需要本地追踪）
  • mlflow：上报到 MLflow（需要本地追踪）

poml(markup, context=None, stylesheet=None, chat=True, output_file=None, format='message_dict', extra_args=None)

• 作用：处理 POML 标记并按指定格式返回结果。
• 参数（节选）：
  • markup: str | Path：POML 源文本，或指向 .poml 文件的路径；若字符串看起来像路径但文件不存在，会发出警告并按源文本处理。
  • context: dict | str | Path | None：注入模板的上下文，可为字典、JSON 字符串或 JSON 文件路径。
  • stylesheet: dict | str | Path | None：渲染样式，支持字典、JSON 字符串或 JSON 文件路径。
  • chat: bool：是否按"聊天"处理（默认 True；False 时按单条提示处理）。
  • output_file: str | Path | None：可选的输出保存路径；未提供则直接返回结果而不落盘。
  • format：输出格式，支持：
    • "raw"：返回原始字符串
    • "message_dict"：仅返回消息数组（兼容旧格式）
    • "dict"：包含 messages、schema、tools、runtime 的完整结构
    • "openai_chat"：OpenAI Chat Completion 兼容格式（含工具/模式）
    • "langchain"：LangChain 消息与元数据
    • "pydantic"：返回强类型 PomlFrame
  • extra_args: Optional[List[str]]：额外传给 POML 处理器的命令行参数。
• 返回：list | dict | str | PomlFrame，与 format 对应。
• 说明：
  • openai_chat：在有工具/模式时包含 tools 与 response_format；运行时参数转换为 snake_case。
  • langchain：保留全部元数据并返回 LangChain 格式的 messages。
  • pydantic：返回 PomlFrame，其中 messages 为 PomlMessage 对象，并带 output_schema、tools、runtime。
• 异常：
  • FileNotFoundError：指定的文件路径不存在时
  • RuntimeError：处理器失败或后端追踪要求未满足时
  • ValueError：输出格式非法时

clear_trace()

• 作用：清空已收集的追踪日志。

get_trace()

• 作用：返回追踪日志的副本。

trace_artifact(file_suffix, contents)

• 作用：为最近一次 poml 调用写入额外工件文件（实验性）。
• 返回：Optional[Path]，若没有可用前缀则返回 None。

示例（来自文档）

>>> result = poml("<p>Hello {{name}}!</p>", context={"name": "World"})

>>> result = poml("template.poml", context="context.json")

>>> messages = poml("chat.poml", format="openai_chat")

>>> result = poml(
...     markup="template.poml",
...     context={"user": "Alice"},
...     stylesheet={"role": {"captionStyle": "bold"}},
...     format="pydantic"
... )

>>> poml("template.poml", output_file="output.json", format="raw")

参考链接

• 文档：microsoft.github.io/poml/stable...

总结

Core API 提供了对 POML 标记的处理、结果格式化、追踪与工件写入等能力。根据需求选择合适的 format 与追踪后端，并参考文档中的示例与参数说明进行集成与调用。