video_decode/src/states/what_deconstruction_state.py

"""
What Deconstruction State Definitions.

Defines the state structure for the What Deconstruction workflow.
"""

from typing import TypedDict, List, Dict, Any, Optional


class WhatDeconstructionState(TypedDict, total=False):
    """What解构工作流状态（仅支持视频输入）"""

    # ========== 输入数据 ==========
    video: Optional[str]  # 视频URL
    channel_content_id: Optional[str]  # 视频内容ID
    title: Optional[str]  # 视频标题
    body_text: Optional[str]  # 视频正文
    text: Optional[Dict[str, Any]]  # {title, body, hashtags}（兼容格式）
    historical_posts: Optional[List[Dict[str, Any]]]  # 历史帖子（可选）
    history_baseline: Optional[Dict[str, Any]]  # 历史基准（可选）

    # ========== 中间结果 ==========
    video_file: Optional[Any]  # 视频文件对象（Gemini File对象，优先使用）
    video_uploaded_uri: Optional[str]  # 视频上传后的URI（兼容旧版本）
    video_file_name: Optional[str]  # 视频上传后的文件名称（用于获取文件对象）
    video_upload_error: Optional[str]  # 视频上传错误信息
    inspiration_points: Optional[Dict[str, Any]]  # 灵感点解构结果
    purpose_point: Optional[Dict[str, Any]]  # 目的点解构结果
    key_points: Optional[Dict[str, Any]]  # 关键点解构结果
    topic_selection_understanding: Optional[Dict[str, Any]]  # 选题理解结果

    # ========== 最终输出 ==========
    final_result: Optional[Dict[str, Any]]  # 最终的树状JSON结果


class ElementNode(TypedDict, total=False):
    """元素节点结构（树状结构的节点）

    根据 PRD 1.4 - 2.2.2.2 节点字段定义：

    **中间元素节点包含6个字段**：
    - id: 节点编号
    - what: 元素概述
    - 描述: 动态描述维度
    - 子节点元素关系: 子节点间关系描述
    - 元素重要性权重: 权重值
    - 子节点元素: 子节点列表

    **叶子节点包含4个字段**（不含子节点元素、子节点元素关系）：
    - id: 节点编号
    - what: 元素概述
    - 描述: 动态描述维度
    - 元素重要性权重: 权重值
    """

    id: str
    """节点编号：由数字与下划线动态组合

    - 第一层元素编号：1、2、3...
    - 第二层元素编号：1_1、2_1、3_2...
    - 第N层元素编号：以此类推
    - 示例："1", "1_1", "1_1_2"
    """

    what: str
    """元素概述

    根据节点元素类型：
    - **文本元素**（标题、正文、话题标签）：what字段的值是节点文本的原文，不要对其做任何改造、总结、概括
    - **视觉元素**（图片、图片的局部）：what字段的值是一句针对该视觉元素的文本描述，要涵盖该视觉元素的核心元素和核心要点特征
    """

    描述: Dict[str, Any]
    """动态描述维度（由知识库决定）

    约束条件：
    1. 描述维度一定要包含待解构元素最关键/最吸引人的亮点维度
    2. 描述维度的数量不得少于3个，要尽可能多而全的覆盖这个元素的所有可描述角度
    3. 描述维度有哪些、有多少个，需要根据待解构元素向知识库动态请求询问

    Query句式：
    刻画描述"{元素的what字段值}"核心特征的角度和维度有哪些？请尽可能不重不漏列举全。
    """

    子节点元素关系: List[str]
    """子节点元素关系：string数组

    数组中每个元素表示一条该节点所属子节点间的关联关系的文字描述。

    **注意**：叶子节点不包含此字段。
    """

    元素重要性权重: float
    """元素重要性权重：大于0且小于等于1的数值

    衡量该节点的内容对读者观众的吸引力大小。帖子中越是亮点、越是吸引观众关注的元素节点，权重值越大。

    **约束条件**：
    同一父节点下的各个子节点的权重值之和应固定为1。

    示例：
    - 元素1_1下包含3个子节点1_1_1、1_1_2、1_1_3
    - 不论这3个节点的权重值如何设定分配，3者之和应为1
    - 如：0.2 + 0.3 + 0.5 = 1.0
    """

    权重理由: str
    """权重理由：解释为什么给出该权重分数

    说明该元素为什么具有这样的吸引力权重，基于什么维度和特征进行评估。
    """

    子节点元素: List['ElementNode']
    """子节点元素：JSON数组

    表示该视觉元素包含的子节点视觉元素，也就是树状结构的子节点元素。
    - 子节点元素的数量是动态不固定的

    **注意**：叶子节点不包含此字段。
    """

    图片链接: Optional[str]
    """图片链接（可选）：用于关联原始多媒体素材

    - 对于视觉元素节点，存储图片分割后的独立图片路径
    - 用于直接关联原始多媒体素材（PRD 2.2.1要求）
    """

    完整描述: Optional[str]
    """完整描述（可选）：图片的整体描述（仅根节点）

    - 仅用于图片元素的根节点（第一层元素）
    - 从消费者视角描述图片的核心元素
    - 描述粒度聚焦于消费者关注的内容，避免无关细节
    - 例如：如果帖子主题是事物处理前后对比，就不应关注托举食物的手指甲等细节
    """


class FinalOutput(TypedDict):
    """最终输出的JSON结构

    根据 PRD 1.4 - 2.2 系统输出定义：

    输出一个JSON对象，以层级递归地、自上而下地、从宏观到微观、从整体到局部的解构一篇笔记的全部"What"元素，
    解构形成一棵"what元素树"。输出结果为key-value组织的层级化要素集合，每个要素包含结构化的核心属性、
    关键特征、消费者亮点和素材关联，直接关联原始多媒体素材。

    输出格式：
    {
        "帖子整体": {
            "描述维度1": "值1",
            "描述维度2": "值2",
            ...  # 动态描述维度（由知识库决定）
        },
        "评论分析": {
            "亮点列表": [...],  # 消费者关注的亮点
            "整体情感": "正面/中性/负面",
            "关键话题": ["话题1", "话题2", ...]
        },
        "帖子包含元素": [...]  # 元素树的根节点列表
    }
    """

    帖子整体: Dict[str, Any]
    """帖子整体的各种描述维度

    根据 PRD 1.4 - 2.2.2.2 要求：
    1. 帖子总体的各种描述、总结、归纳等维度或角度，每一个维度都是一个字段项
    2. 包括但不限于：品类、主题、脚本等维度
    3. **一定要包含本帖子最关键/最吸引内容消费者的亮点维度**，包括但不限于：内容亮点/情绪共鸣点/创作手法等维度
    4. 描述维度的数量不得少于3个，要尽可能多而全的覆盖这个帖子的所有可描述角度
    5. 描述维度有哪些、有多少个，需要根据本帖子的品类、主题、关键词等信息来向知识库动态请求询问

    Query句式（参见 PRD 1.4 - 3.2 环节）：
    对于一篇主题为"{帖子主题}"，品类为"{帖子品类}"，关键词包含"{帖子关键词列表}"的多模态社交媒体帖子，
    从内容创作者视角进行What要素的初步识别和分类，需要使用哪些通用工具？
    """

    评论分析: Dict[str, Any]
    """评论分析的完整信息

    包含从评论区提取的消费者关注点的完整分析结果，完全保留 CommentAnalysisAgent 的输出。

    结构：
    {
        "亮点列表": [
            {
                "element": "具体的帖子元素标识，格式为'位置标识（具体内容）'",
                "reason": "为什么这个元素是亮点（基于评论的客观分析）",
                "original_comments": ["评论原文1", "评论原文2", "评论原文3"],
                "emotion": "情感类型（兴趣/共鸣/惊喜/认同/幽默等）",
                "frequency": "提及频率（高/中/低）"
            }
        ],
        "整体情感": "评论区的整体情感倾向（正面/中性/负面）",
        "关键话题": ["高频话题1", "高频话题2", "高频话题3"]
    }

    说明：
    - 亮点列表：包含消费者关注的每个亮点的完整信息（元素标识、理由、原始评论、情感类型、提及频率）
    - 整体情感：评论区的整体情感倾向
    - 关键话题：从评论中提取的高频话题
    """

    帖子包含元素: List[ElementNode]
    """帖子包含的顶层元素列表（元素树的根节点列表）

    包含所有一级元素节点（如封面图、其他图片、标题、正文、话题标签等），每个元素节点可递归包含子节点。
    """