jaspersoft-agent-learn/step_02_state/exercise.py

"""
Step 02 练习题：设计你的第一个 Agent State

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 练习目标：
    1. 巩固 State 的基本结构
    2. 设计一个业务相关的 State
    3. 理解状态在多步骤任务中的作用

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
"""

from typing import TypedDict, List, Dict, Any


# ═══════════════════════════════════════════════════════════════════════════════
# 练习 1：完善一个简单的聊天机器人状态
# ═══════════════════════════════════════════════════════════════════════════════

"""
任务：
    设计一个客服聊天机器人的状态

要求：
    1. 记录用户信息（用户名、ID）
    2. 记录对话历史
    3. 记录当前正在处理的问题
    4. 记录问题解决状态
    5. 记录用户满意度评分

提示：
    - 使用 TypedDict 定义状态
    - 考虑哪些字段是必须的，哪些是可选的
"""

class CustomerServiceState(TypedDict, total=False):
    """
    客服聊天机器人的状态

    请补全以下字段的定义：
    """
    # 用户信息
    user_id: str
    user_name: str

    # TODO: 添加更多字段...
    pass


# ═══════════════════════════════════════════════════════════════════════════════
# 练习 2：设计一个数据分析 Agent 的状态
# ═══════════════════════════════════════════════════════════════════════════════

"""
任务：
    设计一个数据分析 Agent 的状态

功能：
    1. 用户提出数据分析需求
    2. Agent 连接数据源
    3. Agent 执行查询
    4. Agent 生成报告

请设计状态来支持这个流程，包括：
    - 用户需求
    - 数据源配置
    - 查询结果
    - 生成的报告
    - 中间状态
"""

class DataAnalysisState(TypedDict, total=False):
    """
    数据分析 Agent 的状态

    请补全状态定义...
    """
    pass


# ═══════════════════════════════════════════════════════════════════════════════
# 练习 3：实现状态快照和恢复
# ═══════════════════════════════════════════════════════════════════════════════

"""
任务：
    给以下状态实现快照和恢复功能

提示：
    - 快照应该保存足够的信息来恢复状态
    - 恢复后状态应该是完整的
    - 考虑哪些字段需要保存，哪些不需要
"""

def create_snapshot(state: dict) -> dict:
    """
    创建状态快照

    应该保存：
        - 关键业务数据
        - 不包括临时计算的中间结果

    返回格式：
        {
            "data": {...},  # 快照数据
            "timestamp": "..."  # 时间戳
        }
    """
    # TODO: 实现这个函数
    pass


def restore_from_snapshot(state: dict, snapshot: dict) -> dict:
    """
    从快照恢复状态

    参数：
        state: 当前状态（会被更新）
        snapshot: 之前保存的快照

    返回：
        恢复后的状态
    """
    # TODO: 实现这个函数
    pass


# ═══════════════════════════════════════════════════════════════════════════════
# 练习 4：状态验证
# ═══════════════════════════════════════════════════════════════════════════════

"""
任务：
    实现状态验证函数

验证规则：
    1. 必填字段不能为空
    2. 字段类型要正确
    3. 某些字段有取值范围限制

返回：
    {
        "valid": True/False,
        "errors": ["错误1", "错误2", ...]
    }
"""

def validate_state(state: dict, rules: dict) -> dict:
    """
    验证状态

    参数：
        state: 要验证的状态
        rules: 验证规则，格式：
            {
                "field_name": {
                    "type": int/str/list/dict,
                    "required": True/False,
                    "min": 0,  # 可选，数字最小值
                    "max": 100,  # 可选，数字最大值
                    "choices": ["a", "b"]  # 可选，枚举值
                }
            }

    示例：
        rules = {
            "user_id": {"type": str, "required": True},
            "age": {"type": int, "min": 0, "max": 150},
            "status": {"type": str, "choices": ["active", "inactive"]}
        }
    """
    # TODO: 实现这个函数
    pass


# ═══════════════════════════════════════════════════════════════════════════════
# 测试
# ═══════════════════════════════════════════════════════════════════════════════

def test_exercises():
    """测试所有练习"""
    print("\n" + "=" * 60)
    print("测试练习答案")
    print("=" * 60)

    # 测试练习 3
    print("\n📝 练习 3: 快照和恢复")
    # 示例状态
    sample_state = {
        "user_id": "123",
        "current_task": "数据分析",
        "progress": 50,
        "temp_data": ["计算中...", "处理中..."],  # 临时数据
    }

    print(f"原始状态: {sample_state}")

    # 创建快照
    snapshot = create_snapshot(sample_state)
    print(f"快照: {snapshot}")

    # 修改状态
    sample_state["progress"] = 100
    print(f"修改后状态: {sample_state}")

    # 恢复
    restored = restore_from_snapshot(sample_state, snapshot)
    print(f"恢复后状态: {restored}")

    # 测试练习 4
    print("\n📝 练习 4: 状态验证")
    rules = {
        "user_id": {"type": str, "required": True},
        "age": {"type": int, "min": 0, "max": 150},
        "status": {"type": str, "choices": ["active", "inactive"]}
    }

    # 有效状态
    valid_state = {"user_id": "123", "age": 25, "status": "active"}
    print(f"验证有效状态: {validate_state(valid_state, rules)}")

    # 无效状态
    invalid_state = {"user_id": "123", "age": 200, "status": "unknown"}
    print(f"验证无效状态: {validate_state(invalid_state, rules)}")


if __name__ == "__main__":
    test_exercises()