agent-context 0.1.1

Multi-backend agent context manager with three-zone memory model
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

//! # agent-context
//!
//! 通用、后端无关的 LLM 对话上下文管理器，基于 [kameo](https://crates.io/crates/kameo) Actor 模型构建。
//!
//! ## 核心概念
//!
//! ### 三区 + Scratch 消息模型
//!
//! 上下文消息按可变性分为三个存储区域，加上一个不存储的 Scratch 层，按序拼接为完整对话：
//!
//! | 区域 | 容器 | 可变性 | 用途 |
//! |------|------|--------|------|
//! | **immutable** | [`ReadOnly`] | 不可变 | 系统提示词、预设上下文等构造后不变的消息 |
//! | **compressed** | `Vec` | 仅压缩时写入 | 历史对话压缩后的摘要 |
//! | **incremental** | `Vec` | 完全可变 | 当前活跃对话，支持增删改查 |
//! | **scratch** | — | 不存储 | 每轮刷新的临时元数据（时间、工作目录等），通过 [`CommonOpts`] 配置 |
//!
//! 拼接顺序：immutable → compressed → incremental → scratch（如有）。
//! Scratch 由调用方在每次 [`SendMsg`]/[`SendStreamMsg`] 时通过 [`CommonOpts`] 传入，
//! 不存入任何区域，不触发变更事件，不参与序列化。
//!
//! ### 后端 trait
//!
//! [`ContextBackend`] 是核心抽象，封装 LLM 后端的：
//!
//! - **消息工厂**：[`user_message`](ContextBackend::user_message)、[`system_message`](ContextBackend::system_message)、[`tool_message`](ContextBackend::tool_message)
//! - **格式转换**：[`to_system_message`](ContextBackend::to_system_message)、[`to_request_messages`](ContextBackend::to_request_messages)
//! - **响应解析**：[`extract_messages`](ContextBackend::extract_messages)
//! - **模型对话**：[`send`](ContextBackend::send)、[`send_stream`](ContextBackend::send_stream)、[`estimate_tokens`](ContextBackend::estimate_tokens)
//!
//! 实现 `ContextBackend` 即可让 AC 支持任意 LLM 后端（DeepSeek、智谱、OpenAI 等）。
//!
//! ### 变更通知
//!
//! 通过 [`with_on_change`](AgentContext::with_on_change) 注册回调，监听 [`ChangeEvent`] 实时追踪消息变化。
//!
//! ### 上下文压缩
//!
//! [`SendMsg`]/[`SendStreamMsg`] 发送前自动检测上下文是否已满。
//! 当 [`CommonOpts::auto_compress`] 为 `true` 时自动压缩；为 `false` 时返回错误。
//! 也可通过 [`CompressMsg`] 手动触发压缩，支持 [`CompressStrategy::Summarize`] 策略。
//!
//! ## 快速开始
//!
//! ```ignore
//! use agent_context::{AgentContext, AppendMsg, SendMsg, SendStreamMsg, MessagesMsg, ContextBackend, CommonOpts};
//! use futures::StreamExt;
//!
//! // 1. 实现 ContextBackend（以你的 LLM SDK 类型）
//! // 2. 创建 Actor
//! let ctx = AgentContext::new(my_backend, vec![backend.system_message("You are a helpful assistant.")]);
//! let actor = AgentContext::spawn(ctx);
//!
//! // 3. 非流式对话
//! actor.ask(AppendMsg { message: user_msg }).await?;
//! actor.ask(SendMsg { opts: my_opts }).await?;
//!
//! // 4. 流式对话
//! let mut stream = actor.ask(SendStreamMsg { opts: my_opts }).await??;
//! while let Some(chunk) = stream.next().await { /* 逐块处理 */ }
//! let chunks = stream.take_chunks(); // 取出原始 chunk 自行处理
//!
//! // 5. 读取全部消息
//! let all: Vec<_> = actor.ask(MessagesMsg).await?;
//! ```

#![forbid(
    unused_must_use,
    clippy::panic,
    clippy::let_underscore_must_use,
    clippy::disallowed_types,
    clippy::disallowed_methods,
    clippy::allow_attributes,
    unfulfilled_lint_expectations
)]
#![deny(clippy::unwrap_used, clippy::expect_used)]

mod context;
mod error;
mod message;
mod readonly;
mod role;

pub use context::{
    AgentContext, AgentSendStream, AppendMsg, ChangeEvent, ClearMsg, CommonOpts, CompressMsg,
    CompressStrategy, CompressedMsg, ContextBackend, ContextBackendResponse, EstimateTokensMsg,
    ExtendMsg, FindByRoleMsg, FromJsonlMsg, Get, ImmutableMsg, IncrementalMsg, InsertMsg, IsEmpty,
    Len, MessagesMsg, PopMsg, RemoveMsg, ResponseType, RetainMsg, SendMsg, SendStreamMsg,
    StreamEvent, ToJsonlMsg, ToolCallInfo, UpdateMsg,
};
pub use error::AgentError;
pub use message::ContextMessage;
pub use readonly::ReadOnly;
pub use role::Role;