stampmem 0.4.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
stampmem/__init__.py ADDED
@@ -0,0 +1,22 @@
1
+ # -*- coding: utf-8 -*-
2
+ """stampmem:带时间戳的 Agent 长期记忆库"""
3
+
4
+ from .memory import Memory, DefaultEmbedder
5
+ from .llm import LLMProvider, OpenAICompatProvider, LLMJudge, load_api_key
6
+ from .timestamps import stamp_documents, parse_period, to_memory_payload
7
+ from .context import render_context, render_context_with_sources
8
+
9
+ __all__ = [
10
+ "Memory",
11
+ "DefaultEmbedder",
12
+ "LLMProvider",
13
+ "OpenAICompatProvider",
14
+ "LLMJudge",
15
+ "load_api_key",
16
+ "stamp_documents",
17
+ "parse_period",
18
+ "to_memory_payload",
19
+ "render_context",
20
+ "render_context_with_sources",
21
+ ]
22
+ __version__ = "0.4.4"
stampmem/context.py ADDED
@@ -0,0 +1,72 @@
1
+ """Render retrieved evidence without internal identifiers or arbitrary metadata.
2
+
3
+ This adapter supports metadata availability comparisons; it does not implement or
4
+ claim to reproduce the paper's frozen benchmark pipeline.
5
+ """
6
+ import hashlib
7
+ import json
8
+ import secrets
9
+
10
+
11
+ def render_context(hits, *, include_time=True, include_estimated_day=False):
12
+ """Return JSON evidence in input order, preserving all text and candidates.
13
+
14
+ No truncation, retrieval, sorting or automatic event-time inference occurs here.
15
+ Hiding time removes structured fields only; dates in the text remain intact.
16
+ Inferred observation days are hidden by default. Known archive bounds and
17
+ observed dates from non-inferred sources remain visible.
18
+ Opt in to the inferred point with include_estimated_day=True.
19
+ Never forwards raw ids, distances, embeddings, line_id or answer-status labels.
20
+ Text is evidence data and can itself contain untrusted instructions.
21
+ """
22
+ evidence = []
23
+ for hit in hits:
24
+ item = {"text": hit["text"]}
25
+ meta = hit.get("metadata") or {}
26
+ if include_time:
27
+ source = meta.get("time_source", "unverified_legacy")
28
+ temporal = {"source": source}
29
+ observed = meta.get("observed_at") or meta.get("created_at")
30
+ exact_bound = (observed == meta.get("ts_period_start") == meta.get("ts_period_end"))
31
+ if (observed and source != "synthetic_unanchored"
32
+ and (source != "inferred" or include_estimated_day or exact_bound)):
33
+ temporal["observed_at"] = observed
34
+ if meta.get("event_time"):
35
+ temporal["event_time"] = meta["event_time"]
36
+ for key in ("ts_confidence", "ts_method", "ts_period_start", "ts_period_end"):
37
+ if key in meta:
38
+ temporal[key] = meta[key]
39
+ item["time"] = temporal
40
+ evidence.append(item)
41
+ return json.dumps(evidence, ensure_ascii=False)
42
+
43
+
44
+ def _text_digest(text):
45
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
46
+
47
+
48
+ def render_context_with_sources(hits, *, excerpts=None, include_time=True, include_estimated_day=False):
49
+ """Return (context JSON, private source map) for a single retrieval pass.
50
+
51
+ Pass original hits. Optional excerpts is a server-side {hit id: text}
52
+ mapping; each excerpt must describe only its own source hit. This function
53
+ does not generate or verify summaries. Never pass the private map to a model.
54
+ """
55
+ hits = list(hits)
56
+ ids = [hit.get("id") for hit in hits]
57
+ if any(not isinstance(i, str) or not i for i in ids) or len(set(ids)) != len(ids):
58
+ raise ValueError("出处视图需要每条原文都有唯一的记忆 ID")
59
+ excerpts = {} if excerpts is None else excerpts
60
+ if not set(excerpts) <= set(ids) or any(not isinstance(value, str) or not value.strip()
61
+ for value in excerpts.values()):
62
+ raise ValueError("摘录必须对应本轮命中的原文,且不能为空")
63
+ out = json.loads(render_context(hits, include_time=include_time, include_estimated_day=include_estimated_day))
64
+ mapping = {}
65
+ for row,hit,mid in zip(out,hits,ids,strict=True):
66
+ ref = "src_" + secrets.token_urlsafe(12)
67
+ while ref in mapping:
68
+ ref = "src_" + secrets.token_urlsafe(12)
69
+ mapping[ref] = (mid, _text_digest(hit["text"]))
70
+ row["source_ref"] = ref
71
+ row["text"] = excerpts.get(mid, hit["text"])
72
+ return json.dumps(out, ensure_ascii=False), mapping
stampmem/llm.py ADDED
@@ -0,0 +1,188 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ LLM 抽象层:让记忆库不绑死任何一家大模型。
4
+
5
+ 设计思想(可插拔、能适配未来):
6
+ 1. 定义抽象接口 LLMProvider(只声明 chat 方法)
7
+ 2. 各家模型实现这个接口(OpenAI 兼容的都能用)
8
+ 3. 核心逻辑(LLMJudge)只依赖接口,不依赖具体实现
9
+ 4. API Key 获取优先级:显式传参 > 环境变量 > .env 文件
10
+
11
+ 这样未来出现新模型,只需写一个新的 Provider 类,核心代码无需改动。
12
+ """
13
+
14
+ import os
15
+ import json
16
+ from abc import ABC, abstractmethod
17
+
18
+ try:
19
+ from openai import OpenAI
20
+ except ImportError:
21
+ OpenAI = None
22
+
23
+ # ============================================================
24
+ # 1. 抽象接口
25
+ # ============================================================
26
+ class LLMProvider(ABC):
27
+ """所有大模型 Provider 必须实现的接口"""
28
+
29
+ @abstractmethod
30
+ def chat(self, messages: list, temperature: float = 0.3) -> str:
31
+ """输入 messages,返回模型的文本回复"""
32
+ raise NotImplementedError
33
+
34
+
35
+ # ============================================================
36
+ # 2. OpenAI 兼容 Provider(适配 DeepSeek / OpenAI / 通义 / 智谱 ...)
37
+ # ============================================================
38
+ class OpenAICompatProvider(LLMProvider):
39
+ """
40
+ 适配所有 OpenAI 兼容接口的通用 Provider。
41
+ 换模型只需改 base_url + model 即可。
42
+
43
+ 设计原则(库不碰 env):
44
+ - api_key 必须由【调用方】显式传入,库自己不去读环境变量/.env
45
+ - 读 .env 是【应用层】的职责,不是库的职责
46
+ """
47
+
48
+ def __init__(self, api_key: str, base_url: str = None,
49
+ model: str = "deepseek-chat"):
50
+ if OpenAI is None:
51
+ raise ImportError("请先安装 openai:pip install openai")
52
+
53
+ if not api_key:
54
+ raise ValueError(
55
+ "必须显式传入 api_key。库不会自动读环境变量/.env,"
56
+ "请由应用层读取后传入。"
57
+ )
58
+
59
+ self.api_key = api_key
60
+ self.base_url = base_url or "https://api.deepseek.com"
61
+ self.model = model
62
+ self.client = OpenAI(api_key=self.api_key, base_url=self.base_url)
63
+
64
+ def chat(self, messages: list, temperature: float = 0.3) -> str:
65
+ """发一次对话请求,返回模型回复的纯文本(已 strip)。
66
+
67
+ messages 采用 OpenAI 格式:[{"role": "user", "content": "..."}]。
68
+ 网络异常与限流会原样抛出,由调用方决定重试策略 —— 库不替你做重试。
69
+ """
70
+ resp = self.client.chat.completions.create(
71
+ model=self.model,
72
+ messages=messages,
73
+ temperature=temperature,
74
+ )
75
+ return resp.choices[0].message.content.strip()
76
+
77
+
78
+ # ============================================================
79
+ # 3. 应用层辅助函数:从 .env / 环境变量读 key(给用户用,不是库内部用)
80
+ # ============================================================
81
+ def load_api_key(env_key_name: str = "DEEPSEEK_API_KEY", env_file: str = None) -> str:
82
+ """
83
+ 供【应用层】使用的辅助函数:从环境变量或 .env 文件读 API Key。
84
+ 注意:这是给"调用库的人"用的,库内部不会自动调用它。
85
+ """
86
+ # 1. 环境变量
87
+ key = os.environ.get(env_key_name)
88
+ if key:
89
+ return key
90
+
91
+ # 2. 尝试读取 .env 文件
92
+ try:
93
+ from dotenv import load_dotenv
94
+ load_dotenv(env_file) # 加载 .env
95
+ key = os.environ.get(env_key_name)
96
+ if key:
97
+ return key
98
+ except ImportError:
99
+ pass
100
+
101
+ return ""
102
+
103
+
104
+ # ============================================================
105
+ # 4. 记忆状态判断(只依赖抽象接口,不绑死具体模型)
106
+ # ============================================================
107
+ class LLMJudge:
108
+ """用 LLM 判断记忆状态,并生成自然的确认问句"""
109
+
110
+ def __init__(self, provider: LLMProvider):
111
+ # 必须显式传入一个已配置好的 Provider(库不自动创建、不读 env)
112
+ self.provider = provider
113
+
114
+ def judge(self, memory_text: str, created_at: str, current_text: str) -> dict:
115
+ """
116
+ 输入:一条记忆 + 它的记录时间 + 用户当前说的话
117
+ 输出:dict { 'status': 'done'/'ongoing'/'uncertain',
118
+ 'reply': '自然语言确认问句' }
119
+ 核心要求:回复里【不要】出现具体时间戳,用"之前/上次"等模糊词。
120
+ """
121
+ prompt = f"""你是 AI 的长期记忆管理助手。
122
+
123
+ 背景信息:
124
+ - 用户曾说过/做过这样一件事(记忆):"{memory_text}"
125
+ - 这条记忆被记录的时间是:{created_at}
126
+
127
+ 现在用户说:"{current_text}"
128
+ 请判断这条记忆现在的状态,并生成一句自然的回复:
129
+ 1. 状态 status 只能是:done(已完成/已过时)、ongoing(仍在进行)、uncertain(不确定)
130
+ 2. 回复 reply 要自然、口语化,像人一样,不要提具体时间戳、不要提"某年某月某日"
131
+ 3. 只有当你认为这条记忆和用户当前说的话可能相关时,才在 reply 里向用户确认;否则 reply 可以为空
132
+
133
+ 只输出 JSON,格式:{{"status":"...", "reply":"..."}}"""
134
+
135
+ content = self.provider.chat(
136
+ messages=[{"role": "user", "content": prompt}],
137
+ temperature=0.3,
138
+ )
139
+
140
+ # 去掉可能的 ```json ... ``` 包裹
141
+ if content.startswith("```"):
142
+ content = content.strip("`")
143
+ if content.startswith("json"):
144
+ content = content[4:]
145
+ try:
146
+ return json.loads(content)
147
+ except json.JSONDecodeError:
148
+ return {"status": "uncertain", "reply": content}
149
+
150
+ def detect_conflict(self, old_memory: str, new_memory: str) -> dict:
151
+ """
152
+ 判断新旧两条记忆是否冲突,以及如何处理。
153
+
154
+ 输入:旧记忆、新记忆
155
+ 输出:dict {
156
+ 'is_conflict': true/false, # 是否冲突
157
+ 'action': 'update'/'keep'/'ask', # update=新替旧, keep=保留旧, ask=需确认
158
+ 'reason': '一句话解释'
159
+ }
160
+ """
161
+ prompt = f"""你是 AI 的长期记忆冲突检测器。
162
+
163
+ 有两条关于同一用户的记忆:
164
+ - 旧记忆:"{old_memory}"
165
+ - 新记忆:"{new_memory}"
166
+
167
+ 请判断这两条记忆是否矛盾/冲突,并决定如何处理:
168
+ 1. is_conflict:true 表示矛盾,false 表示不矛盾
169
+ 2. action 只能是:
170
+ - update:新记忆是真实改变,应更新旧记忆
171
+ - keep:新记忆只是一时情绪/气话,应保留旧记忆
172
+ - ask:无法确定,需要向用户确认
173
+ 3. reason:用一句话解释你的判断
174
+
175
+ 只输出 JSON,格式:{{"is_conflict":true/false,"action":"...","reason":"..."}}"""
176
+
177
+ content = self.provider.chat(
178
+ messages=[{"role": "user", "content": prompt}],
179
+ temperature=0.3,
180
+ )
181
+ if content.startswith("```"):
182
+ content = content.strip("`")
183
+ if content.startswith("json"):
184
+ content = content[4:]
185
+ try:
186
+ return json.loads(content)
187
+ except json.JSONDecodeError:
188
+ return {"is_conflict": True, "action": "ask", "reason": content}