agent.commentator
=================

.. py:module:: agent.commentator

.. autoapi-nested-parse::

   规划评语生成器：规则模板 + LLM 润色预留。

   规则注册表 RULES 仅需在列表中添加函数，即可自动参与评语生成。



Attributes
----------

.. autoapisummary::

   agent.commentator.RULES


Functions
---------

.. autoapisummary::

   agent.commentator.check_wait
   agent.commentator.check_late
   agent.commentator.check_density
   agent.commentator.check_distance
   agent.commentator.check_normal
   agent.commentator.polish_with_llm
   agent.commentator.generate_commentary


Module Contents
---------------

.. py:function:: check_wait(solution, spots, cost_mat)

   等待惩罚超过阈值时提醒早到。

   Args:
       solution: 求解结果，含 wait/late/routes 等。
       spots: 景点字典。
       cost_mat: 距离矩阵（km）。

   Returns:
       str | None: 超过 50 分钟等待时返回提醒文本，否则 None。


.. py:function:: check_late(solution, spots, cost_mat)

   迟到惩罚超过阈值时提醒安排太满。

   Args:
       solution: 求解结果。
       spots: 景点字典。
       cost_mat: 距离矩阵。

   Returns:
       str | None: 超过 50 分钟迟到惩罚时返回提醒文本，否则 None。


.. py:function:: check_density(solution, spots, cost_mat)

   单日景点过多时提醒行程紧凑。

   Args:
       solution: 求解结果，含 routes 路径列表。
       spots: 景点字典。
       cost_mat: 距离矩阵。

   Returns:
       str | None: 存在超过 5 个景点的天数时返回提醒，否则 None。


.. py:function:: check_distance(solution, spots, cost_mat)

   单日路程过长时提醒注意交通时间。

   Args:
       solution: 求解结果，含 routes 路径列表。
       spots: 景点字典。
       cost_mat: 距离矩阵（km）。

   Returns:
       str | None: 存在超过 50km 的天数时返回提醒，否则 None。


.. py:function:: check_normal(solution, spots, cost_mat)

   兜底：一切正常时给出正面评语。

   Args:
       solution: 求解结果。
       spots: 景点字典。
       cost_mat: 距离矩阵。

   Returns:
       str: 固定正面评语。


.. py:data:: RULES

.. py:function:: polish_with_llm(text: str, enabled: bool = False) -> str

   LLM 润色评语（预留）。

   Args:
       text: 原始评语文本。
       enabled: 是否启用 LLM 润色，默认关闭。

   Returns:
       str: 原文本（润色功能暂未实现）。


.. py:function:: generate_commentary(solution: dict, spots: dict, cost_mat: numpy.ndarray) -> str

   遍历规则注册表生成评语，取前两条非空结果拼接。

   Args:
       solution: solve_groups 返回的结果，含 routes/total_cost/wait/late 等。
       spots: 景点字典。
       cost_mat: 距离矩阵（km）。

   Returns:
       拼接后的评语文本。