"""
# LangChain / LangGraph 短期记忆(Short-Term Memory)

一、核心概念

LangChain 1.x 的 create_agent 基于 LangGraph 构建。

Agent 的短期记忆主要通过 State + Checkpointer + thread_id 实现。

1. State(状态)
    - 保存 Agent 当前执行过程中的状态数据。
    - 默认 AgentState 包含 messages 字段,用来保存对话消息。
    - 除了 messages,还可以通过自定义 State 保存其他业务状态。
    - State 是运行时的逻辑状态,不等于数据库,也不负责持久化。

2. Checkpointer(检查点持久化器)
    - 负责保存和读取 State 的检查点。
    - LangGraph 通常在每个 super-step(超级步骤)边界生成检查点。
    - 保存的不只是对话消息,还可能包括其他 State 字段及执行元数据。
    - 可以用于多轮对话、断点恢复、人工审核和历史状态查看。
    - 它是一套持久化接口,底层可以使用内存、Redis、PostgreSQL 等。

3. thread_id(会话标识)
    - 用于标识一条独立的会话线程。
    - 同一个 thread_id:读取该会话此前保存的状态,继续进行新的对话。
    - 不同的 thread_id:使用不同的会话状态。
    - thread_id 不是用户 ID,而是会话 ID;一个用户可以有多条会话。

整个执行过程:

用户输入
    ↓
config 中传入 thread_id
    ↓
Agent 通过 Checkpointer 查询当前会话的历史 State
    ↓
加载已有 State,并合并本次输入的 messages
    ↓
LLM 基于当前 State 执行推理
    ↓
Agent / Tool 等节点更新 State
    ↓
Checkpointer 保存新的检查点
    ↓
返回 Agent 执行结果

注意:
    - 一般不需要手动查询 Redis 并拼接历史消息。
    - Checkpointer 会在 LangGraph 执行过程中自动读取和保存状态。
    - 再次调用时,只需要传入相同的 thread_id 和本轮新增消息。
    - Checkpointer 保存历史状态,不代表会自动压缩模型上下文。
    - 短期记忆主要作用于同一个 thread;跨会话的长期记忆通常使用 Store。
"""


# ============================================================
# 二、方式一:使用内存保存短期记忆
# ============================================================

"""
InMemorySaver:
    - LangGraph 提供的内存型 Checkpointer。
    - 数据保存于当前 Python 进程的内存中。
    - 不需要数据库,适合本地开发、测试和简单 Demo。
    - Python 进程退出后,保存的状态就会丢失。
    - 多个独立进程之间不能共享其状态。
    - 不建议用于需要可靠持久化的生产环境。
"""

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver

# llm 为提前实例化好的 LangChain ChatModel
checkpointer = InMemorySaver()

agent = create_agent(
    model=llm,
    tools=[],
    checkpointer=checkpointer,
)

# 定义会话 ID
config = {
    "configurable": {
        "thread_id": "user_001:session_001"
    }
}

# 第一轮对话
result1 = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "我叫小王"}]},
    config=config,
)

# 第二轮对话
# 不需要手动重新传入第一轮历史消息
# 因为 Checkpointer 会自动加载相同 thread_id 的 State
result2 = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "我叫什么名字?"}]},
    config=config,
)

print(result2["messages"][-1].content)


# ============================================================
# 三、方式二:Redis 持久化短期记忆(推荐用于生产项目)
# ============================================================

"""
为什么使用 Redis?

1. InMemorySaver 的数据仅存在当前 Python 进程中。
2. Redis 是独立运行的内存数据库,支持多个服务进程共享数据。
3. Agent 服务重启后,只要 Redis 数据仍存在,就可以恢复会话状态。
4. 支持设置 TTL,控制检查点的保存时间。
5. 可以结合 Redis 的 RDB / AOF 等机制实现数据持久化。

注意:
    - Redis 本身也是以内存为主要存储介质,并不是无限容量。
    - Redis 不会自动解决所有内存问题,需要合理配置 TTL 和容量。
    - Redis 并非唯一的生产方案,PostgreSQL 也是常见选择。
    - 生产环境需要考虑 Redis 数据持久化、备份、故障恢复等问题。
"""


# ------------------------------------------------------------
# 1. 安装依赖与准备 Redis 服务
# ------------------------------------------------------------

"""
安装 Python 依赖:

uv add langchain langgraph langgraph-checkpoint-redis redis

如果使用 FastAPI:
uv add fastapi uvicorn

如果使用 OpenAI 模型:
uv add langchain-openai


Redis 服务要求:

langgraph-checkpoint-redis 需要:
    - RedisJSON:保存 JSON 格式的检查点文档。
    - RediSearch:建立索引并检索检查点。

推荐 Redis 8.0+,相关功能已内置。

本地 Docker 启动:

docker run -d \
    --name langgraph-redis \
    -p 127.0.0.1:6379:6379 \
    redis:8

对于 Redis 8.0 以下版本:
    需要使用具备 RedisJSON 和 RediSearch 功能的 Redis Stack,
    或使用其他已安装对应模块的 Redis 服务。

注意:
    普通的旧版 Redis 不一定可以直接使用 AsyncRedisSaver。
"""


# ------------------------------------------------------------
# 2. 创建 Redis 异步连接池
# ------------------------------------------------------------

import redis.asyncio as redis

"""
为什么使用连接池?

如果每次请求都独立创建和关闭 Redis TCP 连接:
    - 增加连接建立和释放的开销。
    - 高并发下产生大量短生命周期连接。
    - 增加 Redis 服务端和应用程序的资源消耗。

ConnectionPool:
    - 负责管理和复用 Redis TCP 连接。
    - 多个并发任务可以通过同一个 Redis 客户端使用连接池。
    - 可以配置最大连接数量。
    - 不负责保存会话状态。
    - 不负责区分不同用户的对话。

需要区分:
    ConnectionPool:负责连接管理。
    Redis Client:负责向 Redis 发送命令。
    AsyncRedisSaver:负责 LangGraph Checkpoint 的读写。
    thread_id:负责区分不同会话。
"""

pool = redis.ConnectionPool(
    host="localhost",
    port=6379,
    db=0,
    password=None,

    # Redis Checkpointer 推荐使用 bytes 响应。
    # 避免启用 Redis 客户端的自动字符串解码。
    decode_responses=False,

    # 最大连接数,不等于最大并发请求数。
    max_connections=50,

    # TCP 建立连接的超时时间(秒)
    socket_connect_timeout=5,

    # Redis Socket 操作的超时时间(秒)
    socket_timeout=15,

    # 定期检查连接健康状态(秒)
    health_check_interval=30,
)


# ------------------------------------------------------------
# 3. 使用连接池创建 Redis 客户端
# ------------------------------------------------------------

redis_client = redis.Redis(
    connection_pool=pool
)

"""
redis_client:
    - 是异步 Redis 客户端。
    - 它会自动从 pool 获取连接执行 Redis 命令。
    - 支持多个异步任务复用。
    - Redis(...) 本身通常不会立即建立网络连接。
    - 第一次执行 Redis 命令时才实际获取连接。

通过已有 ConnectionPool 创建的客户端,
通常由应用程序自行管理连接池生命周期。
"""

# 可选:测试连接是否可用
await redis_client.ping()


# ------------------------------------------------------------
# 4. 创建 AsyncRedisSaver
# ------------------------------------------------------------

from langgraph.checkpoint.redis.aio import AsyncRedisSaver

"""
AsyncRedisSaver:
    - 是 LangGraph Checkpointer 的 Redis 异步实现。
    - 接收 redis.asyncio.Redis 客户端。
    - 负责序列化与反序列化检查点中的 State 数据。
    - 通过 RedisJSON 保存检查点及中间写入数据。
    - 通过 RediSearch 索引查询对应的检查点。
    - 在 Agent 执行过程中自动完成相关读写。

需要修正的理解:

    AsyncRedisSaver 不是简单的 Redis JSON 读写器。

    更准确地说:
    它是 LangGraph Checkpointer 接口的一种 Redis 存储实现,
    负责按照 LangGraph 的检查点协议管理状态及其历史记录。

    也不需要开发者自己将 State 转成 JSON 再调用 Redis.set()。
"""

checkpointer = AsyncRedisSaver(
    redis_client=redis_client,

    # 可选:设置检查点 TTL
    ttl={
        # 单位是分钟
        # 这里设置为 7 天
        "default_ttl": 60 * 24 * 7,

        # 读取已有检查点时刷新其 TTL
        "refresh_on_read": True,
    }
)

# 重要:初始化 Redis Checkpointer 所需的索引
# 必须在首次使用 Checkpointer 之前完成。
await checkpointer.asetup()

"""
补充:

1. 当前 AsyncRedisSaver 还提供异步 setup() 兼容接口:
       await checkpointer.setup()

2. 官方文档中也广泛使用:
       await checkpointer.asetup()

3. 如果采用:
       async with AsyncRedisSaver.from_conn_string(...) as checkpointer:
   其异步上下文管理器会自动执行初始化。
   因此一般不需要再次调用 asetup()。

4. 上面的示例采用外部 Redis 客户端,
   因此由应用程序统一负责关闭 Redis Client 和 ConnectionPool。
"""


# ------------------------------------------------------------
# 5. 将 Checkpointer 传给 Agent
# ------------------------------------------------------------

from langchain.agents import create_agent

agent = create_agent(
    model=llm,
    tools=[],

    # 指定持久化实现
    # Agent 内部会通过它保存和恢复运行状态
    checkpointer=checkpointer,
)

"""
Agent 与 Checkpointer 的关系:

    Agent:
        负责模型推理、工具调用、State 更新和执行流程。

    Checkpointer:
        负责持久化 State 的检查点。

    Redis:
        负责实际存储数据。

这里不需要给每个用户分别实例化一个 Agent。

通常一个应用进程可以复用一个 Agent 实例,
使用不同的 thread_id 来管理不同会话。
"""


# ------------------------------------------------------------
# 6. 配置 thread_id,区分不同用户和会话
# ------------------------------------------------------------

user_id = "user_001"
session_id = "session_001"

config = {
    "configurable": {
        "thread_id": f"{user_id}:{session_id}"
    }
}

"""
config 必须注意:

正确:
    "configurable"

错误:
    "configuable"

thread_id 的设计:

    user_001:session_001
    user_001:session_002
    user_002:session_001

效果:
    - 同一用户的不同会话具有不同的 State。
    - 不同用户的会话也相互隔离。

注意:
    thread_id 只是存储层面的会话标识,不是权限校验机制。
    生产环境应从已认证的用户身份生成或校验 thread_id,
    不能直接信任前端传入的任意 user_id。
"""


# ------------------------------------------------------------
# 7. 调用 Agent,自动读取和保存短期记忆
# ------------------------------------------------------------

message = "你好,我叫小王"

result = await agent.ainvoke(
    {
        "messages": [
            {
                "role": "user",
                "content": message
            }
        ]
    },
    config=config,
)

# 获取最后一条消息
answer = result["messages"][-1].content

print(answer)

"""
这里的执行过程:

1. LangGraph 根据 config 中的 thread_id 查找已有检查点。
2. 如果当前会话已有 State,则加载最近的状态。
3. 将本轮用户消息加入 State.messages。
4. Agent 根据当前 State 进行推理。
5. LangGraph 在执行过程中自动保存 Checkpoint。
6. 最后返回包含最新状态的 result。

再次调用相同的 thread_id:

    不需要手动添加历史对话。
    不需要自己查询 Redis。
    只需要传入当前新增的用户消息。

补充:
    result["messages"][-1].content 通常是文本字符串,
    但多模态模型或结构化内容场景也可能返回内容块列表。
    因此生产接口应按实际模型输出类型进行处理。
"""


# ------------------------------------------------------------
# 8. 查看某个会话当前保存的 State
# ------------------------------------------------------------

snapshot = await agent.aget_state(config)

# 获取当前会话的 State
state = snapshot.values

# 获取历史消息
messages = state.get("messages", [])

for msg in messages:
    print(msg.type, msg.content)

"""
aget_state(config):
    - 获取指定 thread_id 的最新状态快照。
    - snapshot.values 是该检查点中的 State 字段。
    - snapshot.metadata 是相关执行元数据。
    - snapshot.config 包含检查点配置信息。

注意:
    aget_state() 是查看状态的接口。
    普通聊天请求无需提前调用它;
    agent.ainvoke() 本身就会通过 Checkpointer 恢复状态。
"""


# ------------------------------------------------------------
# 9. 程序退出时释放 Redis 资源
# ------------------------------------------------------------

await redis_client.aclose()
await pool.aclose()

"""
为什么需要显式关闭?

redis.asyncio 使用异步网络连接。
程序退出时,应主动释放客户端及连接池资源。

    redis_client.aclose()
        关闭 Redis 客户端所持有的资源。

    pool.aclose()
        关闭连接池中维护的连接。

如果 pool 在多个客户端之间共享,
应在所有使用它的任务和客户端结束后,再关闭整个连接池。

生产环境不要每次请求结束都关闭共享连接池。
应将其生命周期交给应用程序统一管理。
"""


# ============================================================
# 四、生产环境推荐:结合 FastAPI Lifespan
# ============================================================

"""
上面的代码主要用于理解各组件之间的关系。

实际 FastAPI 项目中,更推荐:

    服务启动:
        创建 Redis 连接池
            ↓
        创建 Redis Client
            ↓
        创建 AsyncRedisSaver
            ↓
        初始化 Checkpointer
            ↓
        创建 Agent
            ↓
        将 Agent 注册到 app.state

    服务运行:
        不同请求复用 Agent 和 Redis Client,
        使用各自的 thread_id 区分会话。

    服务关闭:
        停止提供服务
            ↓
        释放 Redis Client
            ↓
        关闭 Redis 连接池

下面是一份独立的 FastAPI 示例。
"""

# ===== main.py =====

import os
from contextlib import asynccontextmanager

import redis.asyncio as redis

from fastapi import FastAPI
from pydantic import BaseModel

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.redis.aio import AsyncRedisSaver


@asynccontextmanager
async def lifespan(app: FastAPI):

    # 1. 服务启动:创建共享 Redis 连接池
    pool = redis.ConnectionPool(
        host=os.getenv("REDIS_HOST", "localhost"),
        port=int(os.getenv("REDIS_PORT", "6379")),
        db=int(os.getenv("REDIS_DB", "0")),
        password=os.getenv("REDIS_PASSWORD") or None,
        decode_responses=False,
        max_connections=50,
        socket_connect_timeout=5,
        socket_timeout=15,
        health_check_interval=30,
    )

    # 2. 创建共享 Redis Client
    redis_client = redis.Redis(connection_pool=pool)

    try:
        # 3. 检查连接
        await redis_client.ping()

        # 4. 创建 Checkpointer
        checkpointer = AsyncRedisSaver(
            redis_client=redis_client,
            ttl={
                "default_ttl": 60 * 24 * 7,
                "refresh_on_read": True,
            },
        )

        # 5. 初始化检查点索引
        await checkpointer.asetup()

        # 6. 初始化 LLM
        # MODEL_ID 例如:openai:gpt-5.5
        # 对应模型的 API Key 等配置需提前设置。
        llm = init_chat_model(os.environ["MODEL_ID"])

        # 7. 创建 Agent
        agent = create_agent(
            model=llm,
            tools=[],
            checkpointer=checkpointer,
        )

        # 8. 保存为应用级共享对象
        app.state.agent = agent

        # yield 之后,FastAPI 开始正常处理请求
        yield

    finally:
        # 9. 服务关闭:释放共享资源
        app.state.agent = None

        # 先关闭客户端,再关闭共享连接池
        await redis_client.aclose()
        await pool.aclose()


app = FastAPI(lifespan=lifespan)


# 定义请求体
class ChatRequest(BaseModel):
    user_id: str
    session_id: str
    message: str


@app.post("/chat")
async def chat(request: ChatRequest):

    """
    接口执行逻辑:

    1. 从请求中获取用户信息和会话信息。
    2. 生成对应的 thread_id。
    3. 调用 Agent。
    4. Agent 自动加载和保存当前会话的 State。
    5. 返回本次回答。

    注意:
    此处接收 user_id 仅用于演示。
    生产项目应从登录认证信息中获取 user_id,
    并检查用户对 session_id 的访问权限。
    """

    thread_id = f"{request.user_id}:{request.session_id}"

    config = {
        "configurable": {
            "thread_id": thread_id
        }
    }

    result = await app.state.agent.ainvoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": request.message
                }
            ]
        },
        config=config,
    )

    return {
        "session_id": request.session_id,
        "answer": result["messages"][-1].content,
    }


# 启动命令:
# uv run uvicorn main:app --host 0.0.0.0 --port 8000


# ============================================================
# 五、需要掌握的其他注意事项
# ============================================================

"""
1. State 和 Checkpointer 不要混淆

    State:
        定义和承载 Agent 的运行状态。

    Checkpointer:
        负责保存、读取和恢复 State 的检查点。

    Redis:
        是 Checkpointer 的具体存储后端之一。


2. Checkpointer 和 Redis ConnectionPool 不要混淆

    ConnectionPool:
        复用 Redis 网络连接,提高连接管理效率。

    AsyncRedisSaver:
        实现 LangGraph 的检查点存储协议。

    二者关注的层次不同。


3. Redis 持久化不等于模型上下文无限增长

    Checkpointer 可以保存很多轮历史对话,
    但是 LLM 的上下文窗口是有限的。

    随着 messages 不断增加:
        - Token 消耗增加。
        - 推理成本增加。
        - 响应速度可能下降。
        - 可能超过模型上下文长度限制。

    因此实际项目可能还需要:
        - 保留最近 N 轮对话。
        - 历史消息裁剪(Trimming)。
        - 历史对话摘要(Summarization)。
        - 将长期知识提取到 Store 或其他存储系统。

    注意:
        上述消息管理需要额外实现或配置相应 Middleware。
        仅使用 Checkpointer 不会自动执行这些策略。


4. Redis 的 TTL 不等于模型消息裁剪

    TTL:
        控制 Redis 中检查点数据的生存时间。

    消息裁剪:
        控制进入 LLM 上下文的历史消息数量。

    这两个机制解决的是不同的问题。


5. Agent 实例通常不需要按请求创建

    推荐:
        每个应用进程初始化一次 Agent。
        多个请求复用该 Agent。
        不同会话使用不同的 thread_id。

    避免:
        每次请求重新初始化模型、连接池和 Checkpointer。

    注意:
        多个 Worker 进程可能分别创建自己的 Agent 实例和连接池,
        但可以连接同一个 Redis,访问共享的会话状态。


6. 并发请求与同一 thread_id

    不同 thread_id:
        一般可以并发调用 Agent。

    相同 thread_id:
        应避免多个请求同时修改同一个会话状态。
        否则可能出现检查点分支、状态竞争或消息顺序问题。

    生产项目可使用:
        - 会话级队列。
        - 分布式锁。
        - 同一会话请求串行化。

    注意:
        asyncio.Lock 只在当前进程内生效,
        多 Worker / 多实例部署时需要跨进程的并发控制。


7. 短期记忆和长期记忆的区别

    短期记忆:
        以 thread_id 为核心。
        保存某个会话中的消息和执行状态。
        通常通过 Checkpointer 实现。

    长期记忆:
        可以跨多个 thread_id 使用。
        保存用户偏好、用户画像或提取出的知识。
        可以通过 LangGraph Store 等机制实现。

    同一个用户创建一个新会话时:
        不会仅因为 user_id 相同,就自动继承之前会话的消息历史。


8. 整套机制的最终总结

    Agent + State + Checkpointer + thread_id

    Agent:
        执行 LLM 推理及工具调用。

    State:
        保存执行状态和消息数据。

    Checkpointer:
        负责状态检查点的持久化和恢复。

    thread_id:
        区分独立会话,定位对应的状态历史。

    Redis Client:
        提供 Redis 操作能力。

    ConnectionPool:
        管理并复用 Redis 连接。

    AsyncRedisSaver:
        将 LangGraph Checkpointer 协议适配到 Redis。

    FastAPI Lifespan:
        统一管理这些共享资源的生命周期。


最终可以理解为:

用户请求
    ↓
FastAPI
    ↓
获取共享 Agent
    ↓
传入 thread_id + 本轮消息
    ↓
Checkpointer 从 Redis 恢复 State
    ↓
Agent 执行推理 / 工具调用
    ↓
State 更新
    ↓
Checkpointer 将检查点保存到 Redis
    ↓
返回回答

这是使用 LangChain / LangGraph 构建多用户、多会话 Agent
短期记忆系统的一种常见工程实现。
"""