artl-memory 0.2.0__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.
@@ -0,0 +1,33 @@
1
+ # -*- coding: utf-8 -*-
2
+ """artl-memory — ARTL 家族的记忆层。
3
+
4
+ 逐句原话 · 按人隔离 · 证据链 · 把握度。
5
+ It remembers everyone in the room — separately.
6
+
7
+ from artl_memory import SqliteMemoryStore, InMemoryStore, MemoryService, MemView
8
+
9
+ store = SqliteMemoryStore("memory.db")
10
+ mem = MemoryService(store, designer="heima")
11
+ mem.remember("fact", "预算", "三十万", source="utterance:123", confidence=0.9)
12
+ mem.recall("客厅预算多少")
13
+ """
14
+
15
+ from .memview import MemView
16
+ from .memory_store import InMemoryStore
17
+ from .port import MemoryStore
18
+ from .service import MemoryItem, MemoryService
19
+ from .sqlite import SqliteMemoryStore
20
+ from .types import Op
21
+
22
+ __version__ = "0.2.0"
23
+
24
+ __all__ = [
25
+ "InMemoryStore",
26
+ "MemoryItem",
27
+ "MemoryService",
28
+ "MemoryStore",
29
+ "MemView",
30
+ "Op",
31
+ "SqliteMemoryStore",
32
+ "__version__",
33
+ ]
@@ -0,0 +1,255 @@
1
+ # -*- coding: utf-8 -*-
2
+ """内存实现:零依赖,行为与 SQLite 版一致。
3
+
4
+ 用于测试、试用、以及"先把逻辑跑起来再决定用什么后端"。
5
+
6
+ 注意:本实现不是线程安全的,只适合单线程与测试场景;
7
+ 要并发请用 SqliteMemoryStore(自带可重入锁)。
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import copy
13
+ import json
14
+ import time
15
+ from contextlib import contextmanager
16
+ from typing import Any
17
+
18
+ from .types import Op
19
+
20
+
21
+ def _json_roundtrip(value: Any) -> Any:
22
+ """与 SQLite 后端同口径:值按 JSON 序列化存储。
23
+
24
+ tuple 读出变 list、datetime 变 str——边界写在 README,两个后端
25
+ 必须长一样,否则同一段代码换个后端行为就变了。
26
+ """
27
+ return json.loads(json.dumps(value, ensure_ascii=False, default=str))
28
+
29
+
30
+ class InMemoryStore:
31
+ def __init__(self):
32
+ self._ops: list[Op] = []
33
+ self._mem: dict[tuple, dict] = {}
34
+ self._utt: list[dict] = []
35
+ self._trace: list[dict] = []
36
+ self._items: dict[str, dict] = {}
37
+
38
+ # ---- 决策轨迹(append-only) -------------------------------------------
39
+ def append_trace(self, designer: str, row: dict) -> None:
40
+ row = dict(row)
41
+ row["designer"] = designer
42
+ self._trace.append(row)
43
+
44
+ def traces(self, designer: str, limit: int = 50, before: float = 0.0) -> list:
45
+ rows = [r for r in self._trace if r.get("designer") == designer]
46
+ if before:
47
+ rows = [r for r in rows if float(r.get("ts") or 0) < before]
48
+ out = rows[-limit:]
49
+ out.reverse() # 最新在前,跟排查的视角一致
50
+ return copy.deepcopy(out) # 给副本:外部改嵌套值不许污染库
51
+
52
+ # ---- op 链 -------------------------------------------------------------
53
+ def append_op(self, op: Op) -> None:
54
+ if op.parent is None and self._ops:
55
+ prev = self._last_of(op.designer)
56
+ if prev is not None:
57
+ op.parent = prev.id
58
+ self._ops.append(op)
59
+
60
+ def _last_of(self, designer: str) -> Op | None:
61
+ for op in reversed(self._ops):
62
+ if op.designer == designer:
63
+ return op
64
+ return None
65
+
66
+ def last_op(self, designer: str) -> Op | None:
67
+ return self._last_of(designer)
68
+
69
+ def recent_ops(self, designer: str, limit: int = 20, before: float = 0.0) -> list[Op]:
70
+ rows = [o for o in self._ops if o.designer == designer]
71
+ if before:
72
+ rows = [o for o in rows if float(o.ts) < before]
73
+ # 按 ts 排序,与 SQLite 后端口径一致(乱序写入不该有两种结果)
74
+ rows.sort(key=lambda o: float(o.ts or 0))
75
+ return rows[-limit:]
76
+
77
+ def count_ops(self, designer: str) -> int:
78
+ return sum(1 for o in self._ops if o.designer == designer)
79
+
80
+ def clear_ops(self, designer: str) -> int:
81
+ before = len(self._ops)
82
+ self._ops = [o for o in self._ops if o.designer != designer]
83
+ return before - len(self._ops)
84
+
85
+ def clear_mem(self, owner: str, designer: str) -> int:
86
+ n = 0
87
+ for key in list(self._mem):
88
+ if key[0] == owner and key[1] == designer:
89
+ n += len(self._mem.pop(key))
90
+ return n
91
+
92
+ def clear_all_mem(self, designer: str) -> int:
93
+ """这个人的所有记忆,不分 owner。"""
94
+ n = 0
95
+ for key in list(self._mem):
96
+ if key[1] == designer:
97
+ n += len(self._mem.pop(key))
98
+ return n
99
+
100
+ # ---- 逐句(留 N 天后降级) ----------------------------------------------
101
+ def add_utterance(self, designer: str, row: dict) -> None:
102
+ row = dict(row)
103
+ row["designer"] = designer
104
+ self._utt.append(row)
105
+
106
+ def utterances(self, designer: str, days: int = 7, limit: int = 200) -> list:
107
+ cutoff = time.time() - days * 86400
108
+ rows = [r for r in self._utt
109
+ if r.get("designer") == designer and float(r.get("ts") or 0) >= cutoff]
110
+ # 按 ts 排序,与 SQLite 后端口径一致(乱序写入不该有两种结果)
111
+ rows.sort(key=lambda r: float(r.get("ts") or 0))
112
+ return copy.deepcopy(rows[-limit:]) # 给副本:外部改不许污染库
113
+
114
+ def count_utterances(self, designer: str, days: int | None = None) -> int:
115
+ if days is None:
116
+ return sum(1 for r in self._utt if r.get("designer") == designer)
117
+ cutoff = time.time() - days * 86400
118
+ return sum(1 for r in self._utt
119
+ if r.get("designer") == designer and float(r.get("ts") or 0) >= cutoff)
120
+
121
+ def prune_utterances(self, designer: str, days: int = 7) -> int:
122
+ """超过 N 天:没引用过的整行删,有引用的正文清空(snippet 留着)。
123
+
124
+ "有引用"的判定:snippet 非空(写入时标记),或被
125
+ memory_items.source_event 点名(证据链)。被引用的行先用正文
126
+ 兜底 snippet 再清正文——证据链不能悬空。
127
+ 返回值 = 删除条数 + 清正文条数(与 SQLite 后端口径一致)。
128
+ """
129
+ cutoff = time.time() - days * 86400
130
+ referenced = [str(it.get("source_event") or "")
131
+ for it in self._items.values()
132
+ if it.get("designer") == designer and it.get("source_event")]
133
+
134
+ def _is_referenced(rid) -> bool:
135
+ rid = str(rid or "")
136
+ # 子串匹配是刻意保守的:误判的代价是多留一条证据,方向安全
137
+ return bool(rid) and any(rid in ref for ref in referenced)
138
+
139
+ n = 0
140
+ keep = []
141
+ for r in self._utt:
142
+ if r.get("designer") == designer and float(r.get("ts") or 0) < cutoff:
143
+ if r.get("snippet") or _is_referenced(r.get("id")):
144
+ if r.get("text"):
145
+ if not r.get("snippet"):
146
+ r["snippet"] = str(r.get("text") or "")[:40]
147
+ r["text"] = "" # 有引用的留 snippet,正文清掉
148
+ n += 1
149
+ # 正文已清过的不再计数:prune 幂等
150
+ else:
151
+ n += 1
152
+ continue # 没引用的整行删掉
153
+ keep.append(r)
154
+ self._utt = keep
155
+ return n
156
+
157
+ # ---- 记忆(按 owner/designer/project 隔离) ------------------------------
158
+ @staticmethod
159
+ def _norm_project(project) -> str:
160
+ # None 与 "" 归一为同一个槽,与 SQLite 后端的 _key() 口径一致
161
+ return "" if project is None else str(project)
162
+
163
+ def set_mem(self, owner, designer, project, key, value, confidence: float = 1.0) -> None:
164
+ slot = (owner, designer, self._norm_project(project))
165
+ self._mem[slot] = self._mem.get(slot, {})
166
+ self._mem[slot][key] = {"value": _json_roundtrip(value),
167
+ "confidence": confidence, "ts": time.time()}
168
+
169
+ def get_mem(self, owner, designer, project, key, default: Any = None) -> Any:
170
+ row = self._mem.get((owner, designer, self._norm_project(project)), {}).get(key)
171
+ return default if row is None else row["value"]
172
+
173
+ def all_mem(self, owner, designer, project=None) -> dict:
174
+ rows = self._mem.get((owner, designer, self._norm_project(project)), {})
175
+ return {k: v["value"] for k, v in rows.items()}
176
+
177
+ def snapshot_mem(self, owner, designer, project=None) -> dict:
178
+ # 深拷贝:快照是给人看的,改动快照不许污染库(SQLite 版天然是新对象)
179
+ return copy.deepcopy(
180
+ self._mem.get((owner, designer, self._norm_project(project)), {}))
181
+
182
+ # ---- 统一记忆条目(证据链) ----------------------------------------------
183
+ def add_memory_item(self, item: dict) -> None:
184
+ item = dict(item)
185
+ item["value"] = _json_roundtrip(item.get("value"))
186
+ self._items[str(item.get("id"))] = item
187
+
188
+ def memory_items(self, designer: str, project: str = "", scope: str = "",
189
+ kind: str = "", key: str = "", active_only: bool = True,
190
+ limit: int = 1000) -> list:
191
+ out = []
192
+ for row in self._items.values():
193
+ if row.get("designer") != designer or str(row.get("project") or "") != project:
194
+ continue
195
+ if scope and row.get("scope") != scope:
196
+ continue
197
+ if kind and row.get("kind") != kind:
198
+ continue
199
+ if key and row.get("key") != key:
200
+ continue
201
+ if active_only and row.get("valid_to"):
202
+ continue
203
+ out.append(copy.deepcopy(row)) # 深拷贝:外部改嵌套值不许污染库
204
+ out.sort(key=lambda r: -float(r.get("valid_from") or 0))
205
+ # 调用方给多少就是多少,不在这里偷偷设天花板
206
+ return out[:max(1, int(limit))]
207
+
208
+ def expire_memory_item(self, item_id: str, ts: float, designer: str) -> None:
209
+ ts = float(ts)
210
+ if ts <= 0:
211
+ # truthy 判断下 valid_to=0 等于"恢复有效",这是撤销失效的后门
212
+ raise ValueError("expire 的时间戳必须 > 0")
213
+ if not designer:
214
+ raise ValueError("expire 必须指明 designer(属主校验)")
215
+ row = self._items.get(item_id)
216
+ if row is None:
217
+ return
218
+ # 属主校验:拿到 id 不许作废别人的条目
219
+ if row.get("designer") != designer:
220
+ return
221
+ row["valid_to"] = ts
222
+
223
+ # ---- 隐私:把一个人整个抹掉 ----------------------------------------------
224
+ def purge_designer(self, designer: str) -> dict:
225
+ """删除这个人的全部数据(ops/utterances/memory/memory_items/trace)。
226
+
227
+ 返回各部分删掉的条数。这是"被遗忘权"的硬实现:不是标记,是真删。
228
+ """
229
+ n_ops = len(self._ops)
230
+ self._ops = [o for o in self._ops if o.designer != designer]
231
+ n_utt = len(self._utt)
232
+ self._utt = [r for r in self._utt if r.get("designer") != designer]
233
+ n_trace = len(self._trace)
234
+ self._trace = [r for r in self._trace if r.get("designer") != designer]
235
+ n_mem = 0
236
+ for key in list(self._mem):
237
+ if key[1] == designer:
238
+ n_mem += len(self._mem.pop(key))
239
+ n_items = len(self._items)
240
+ self._items = {k: v for k, v in self._items.items()
241
+ if v.get("designer") != designer}
242
+ return {"ops": n_ops - len(self._ops),
243
+ "utterances": n_utt - len(self._utt),
244
+ "memory": n_mem,
245
+ "memory_items": n_items - len(self._items),
246
+ "trace": n_trace - len(self._trace)}
247
+
248
+ # ---- 生命周期 -------------------------------------------------------------
249
+ @contextmanager
250
+ def batch(self):
251
+ """内存版没有 fsync 问题,batch 只是保持两后端接口同构的空操作。"""
252
+ yield
253
+
254
+ def close(self) -> None:
255
+ pass
artl_memory/memview.py ADDED
@@ -0,0 +1,64 @@
1
+ # -*- coding: utf-8 -*-
2
+ """MemView:一个被限定的记忆视图。
3
+
4
+ 技能/插件拿到的是 `MemView(owner="skill:xxx")`——它**看不到**基础记忆,
5
+ 也看不到别的技能。这不是靠约定,是靠它手里没有那个入口:
6
+
7
+ - 不保存 store 本体,只留四个绑定好的方法(get/set/all/snapshot),
8
+ 参数里的 owner/designer/project 在构造时就焊死了;
9
+ - owner / designer / project 是只读属性,配上 __slots__,
10
+ 想改道去读别人的记忆,连赋值这一步都过不去。
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from typing import Any
16
+
17
+
18
+ class MemView:
19
+ __slots__ = ("_owner", "_designer", "_project", "_fns")
20
+
21
+ def __init__(self, store, owner: str, designer: str, project=None):
22
+ self._owner = str(owner)
23
+ self._designer = str(designer)
24
+ self._project = project
25
+ # 只留包了一层闭包的方法引用,不挂 store 本体、不挂绑定方法
26
+ # (绑定方法的 __self__ 一跳就能摸回 store)。身份在构造时焊死。
27
+ g, st, al, sn = store.get_mem, store.set_mem, store.all_mem, store.snapshot_mem
28
+ o, d, p = self._owner, self._designer, self._project
29
+ self._fns = {
30
+ "get": lambda key, default=None: g(o, d, p, key, default),
31
+ "set": lambda key, value, confidence=1.0: st(o, d, p, key, value, confidence),
32
+ "all": lambda: al(o, d, p),
33
+ "snapshot": lambda: sn(o, d, p),
34
+ }
35
+ # 诚实声明:这堵墙是 API 面的——正常使用拿不到别人的入口;
36
+ # 但同进程内没有密码学意义的隔离(闭包细胞/gc 总能挖回去)。
37
+ # 要防恶意代码,请上进程边界。
38
+
39
+ @property
40
+ def owner(self) -> str:
41
+ return self._owner
42
+
43
+ @property
44
+ def designer(self) -> str:
45
+ return self._designer
46
+
47
+ @property
48
+ def project(self):
49
+ return self._project
50
+
51
+ def get(self, key: str, default: Any = None) -> Any:
52
+ return self._fns["get"](key, default)
53
+
54
+ def put(self, key: str, value: Any, confidence: float = 1.0) -> None:
55
+ self._fns["set"](key, value, confidence)
56
+
57
+ def all(self) -> dict:
58
+ return self._fns["all"]()
59
+
60
+ def snapshot(self) -> dict:
61
+ return self._fns["snapshot"]()
62
+
63
+ def __repr__(self) -> str: # pragma: no cover
64
+ return f"<MemView {self._owner} designer={self._designer}>"
artl_memory/port.py ADDED
@@ -0,0 +1,84 @@
1
+ # -*- coding: utf-8 -*-
2
+ """存储协议。记忆层只依赖这个形状;实现可以是内存、SQLite,或你自己的后端。
3
+
4
+ 协议分四组,实现一个后端就是实现这四组方法:
5
+ op 链 —— 交互历史,append-only
6
+ mem —— 按 (owner, designer, project) 隔离的键值记忆
7
+ utterances —— 逐句原话,带说话人,留 N 天后降级
8
+ memory_items / trace —— 统一记忆条目(证据链)与决策轨迹
9
+
10
+ 实现者必读(两个内置后端共同遵守的约定):
11
+ - 值经 JSON 序列化存储:tuple 读出时会变 list,自定义对象需可自行序列化
12
+ - prune_utterances 的返回值 = 删除条数 + 清正文条数
13
+ - purge_designer 是真删不是标记——这是"被遗忘权"的硬实现
14
+
15
+ 规模与并发的边界(写在明处,不藏着):
16
+ - InMemoryStore 非线程安全,只适合单线程与测试
17
+ - MemoryService.recall 是 O(n) 全量打分,为可解释性刻意不做索引,
18
+ 适用万级以下条目;更大规模请在自己的后端里建索引
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ from typing import Any, Protocol, runtime_checkable
24
+
25
+ from .types import Op
26
+
27
+
28
+ @runtime_checkable
29
+ class MemoryStore(Protocol):
30
+ """记忆后端的协议。所有方法按 designer(主人)隔离,这是硬约束。"""
31
+
32
+ # ---- op 链 -----------------------------------------------------------
33
+ def append_op(self, op: Op) -> None: ...
34
+
35
+ def last_op(self, designer: str) -> Op | None: ...
36
+
37
+ def recent_ops(self, designer: str, limit: int = 20, before: float = 0.0) -> list[Op]: ...
38
+
39
+ def count_ops(self, designer: str) -> int: ...
40
+
41
+ def clear_ops(self, designer: str) -> int: ...
42
+
43
+ # ---- mem:按 owner 隔离的键值 ----------------------------------------
44
+ def get_mem(self, owner: str, designer: str, project, key: str, default: Any = None) -> Any: ...
45
+
46
+ def set_mem(self, owner: str, designer: str, project, key: str, value: Any,
47
+ confidence: float = 1.0) -> None: ...
48
+
49
+ def all_mem(self, owner: str, designer: str, project=None) -> dict: ...
50
+
51
+ def snapshot_mem(self, owner: str, designer: str, project=None) -> dict: ...
52
+
53
+ def clear_mem(self, owner: str, designer: str) -> int: ...
54
+
55
+ def clear_all_mem(self, designer: str) -> int: ...
56
+
57
+ # ---- utterances:逐句原话 ---------------------------------------------
58
+ def add_utterance(self, designer: str, row: dict) -> None: ...
59
+
60
+ def utterances(self, designer: str, days: int = 7, limit: int = 200) -> list: ...
61
+
62
+ def count_utterances(self, designer: str, days: int | None = None) -> int: ...
63
+
64
+ def prune_utterances(self, designer: str, days: int = 7) -> int: ...
65
+
66
+ # ---- memory_items:统一记忆条目(证据链) -------------------------------
67
+ def add_memory_item(self, item: dict) -> None: ...
68
+
69
+ def memory_items(self, designer: str, project: str = "", scope: str = "",
70
+ kind: str = "", key: str = "", active_only: bool = True,
71
+ limit: int = 1000) -> list: ...
72
+
73
+ def expire_memory_item(self, item_id: str, ts: float, designer: str) -> None: ...
74
+
75
+ # ---- trace:决策轨迹 ---------------------------------------------------
76
+ def append_trace(self, designer: str, row: dict) -> None: ...
77
+
78
+ def traces(self, designer: str, limit: int = 50, before: float = 0.0) -> list: ...
79
+
80
+ # ---- 隐私:把一个人整个抹掉 ---------------------------------------------
81
+ def purge_designer(self, designer: str) -> dict: ...
82
+
83
+ # ---- 生命周期 ----------------------------------------------------------
84
+ def close(self) -> None: ...
artl_memory/py.typed ADDED
@@ -0,0 +1 @@
1
+