causal-slicing 0.1.0__py3-none-any.whl

causal_slicing-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: causal-slicing
+Version: 0.1.0
+Summary: 元龙因果 Agent 的切片器（BotSlicer）：把对话流切分为事件粒子，贞入因果星空并按 source_id 组成因果链
+Keywords: causal,因果,memory,记忆,agent,llm,slicer,切片器
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+Provides-Extra: redis
+Requires-Dist: redis>=4.2; extra == "redis"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+
+# causal-slicing
+
+元龙因果 Agent 的**切片器**（`BotSlicer`）：把对话流切分为事件粒子（「瓶子」），按 `source_id`（场景会话）隔离，
+以物理时间先后组织成因果链，贞入（写入）因果星空；并以 `bot_id` 为主键跨 `source_id` 全局共享可见。
+
+单文件、自包含实现，`import causal_slicing` 不会发起任何网络连接（连接是懒加载的）。
+
+## 安装
+
+```bash
+pip install causal-slicing
+# 需要 Redis 作为跨进程状态库时（Redis 5.x 仅支持 RESP2，请传 redis_protocol=2）
+pip install "causal-slicing[redis]"
+```
+
+## 快速开始
+
+```python
+from causal_slicing import BotSlicer
+
+slicer = BotSlicer(**SLICER_KWARGS)
+
+# 贞入一条事件（必答消息：写入后 click 拉取事件视界作为 AI 历史上下文）
+for r in slicer.zhenru(
+    event_tuple="你好，今天是一个晴天。",
+    node_id=slicer.make_node_id("你好，今天是一个晴天。"),
+    user_name="廉颇",
+    user_id="415135222",
+    is_must_answer="yes",
+):
+    print(r.get("action"), r.get("serial_id"), r.get("error"))
+
+# 当下视界（Agent Memory）
+horizon = slicer.present()
+print(horizon["data"]["serial_id"], len(horizon.get("event_horizon") or []))
+```
+
+配合坍塌器（另一个发行版 `causal-collapse`）：
+
+```python
+from causal_slicing import BotSlicer
+from causal_collapse import Collapser
+
+slicer = BotSlicer(**SLICER_KWARGS)
+collapser = Collapser(**COLLAPSER_KWARGS)     # redis_key_prefix 必须与切片器一致（同一焦点键）
+slicer.set_collapse_callback(collapser.collapse)   # 整链超阈值时自动坍塌
+```
+
+## 构造参数（`BotSlicer.__init__`）
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `base_url` | **必填** | 因果星空服务地址，如 `http://192.168.66.39:8094` |
+| `bot_id` | **必填** | 机器人 ID，跨场共享主键 |
+| `owner_id` | `"default"` | 事件拥有者 ID（当前视角场）；真实运行按 `field_owner_id(source_id, bot_id)` 现算 |
+| `actor_id` | `""` | 用户/观测者 ID，用于个性化权重与定位大股东 |
+| `token` | `None` | 私密场钥匙 token |
+| `source_id` | `None` | 当前场景会话 ID，也可在 `zhenru()` 逐条传入 |
+| `max_tuple_size` | `2000` | 瓶子大小：单个事件节点 `event_tuple` 大小上限（字符） |
+| `collapse_threshold` | `10000` | 整链大小上限：所有瓶子之和超过 `collapse_threshold × collapse_trigger_ratio` 触发坍塌 |
+| `collapse_trigger_ratio` | `1.5` | 坍塌触发倍率（迟滞用，避免坍完立刻再触发） |
+| `max_eyes` | `30` | 望远镜功率 / 事件视界半径 |
+| `timeout` | `120` | HTTP 超时（秒）；大文本语义向量化较慢，需放宽 |
+| `redis_url` | `redis://127.0.0.1:6379/0` | Redis 状态库地址（不可用时自动退化为进程内字典） |
+| `redis_protocol` | `2` | Redis 协议版本，Redis 5.x 需 2（RESP2） |
+| `redis_key_prefix` | `"causal_slicing"` | Redis 键前缀，须与坍塌器保持一致 |
+
+`SLICER_KWARGS` 就是一个普通 dict，按上表拼即可：
+
+```python
+SLICER_KWARGS = {
+    "base_url": "http://192.168.66.39:8094",
+    "owner_id": "415135222_3787687088",
+    "actor_id": "415135222",
+    "token": "123456|<你的 token>",
+    "bot_id": "3787687088",
+    "source_id": "415135222",
+    "max_tuple_size": 2000,
+    "collapse_threshold": 8000,
+    "collapse_trigger_ratio": 2,
+    "max_eyes": 30,
+    "timeout": 300,
+    "redis_url": "redis://192.168.66.24:6379/2",
+    "redis_protocol": 2,
+    "redis_key_prefix": "causal_slicing",
+}
+```
+
+## 主要接口
+
+| 成员 | 说明 |
+|---|---|
+| `zhenru(event_tuple, node_id=None, user_name="", user_id="", source_id=None, is_must_answer="no")` | 贞入：装得下就 `update` 累加，满则「又贞」接龙到链尾；返回本次操作结果列表 |
+| `present(max_eyes=None)` | 当下视界（带 `bot_id` 即 Agent Memory） |
+| `past(serial_id, max_eyes=None)` | 点击某节点（提升权重）并返回视界 |
+| `set_collapse_callback(callback)` | 注册坍塌器回调（独立线程调用，签名 `callback(bot_id=..., chain_size=..., source_id=...)`） |
+| `collapse_future()` / `collapse_is_running()` / `collapse_done()` / `collapse_result(timeout=None)` | 监听最近一次坍塌任务 |
+| `get_chain_size(source_id=None)` | 读整链 `event_tuple` 累计大小 |
+| `reset_state(source_id=None)` | 清空 redis 中的焦点与整链计数（不删星空节点） |
+| `make_node_id(text)` | 由文本生成稳定的节点 ID |
+| `field_owner_id(source_id, bot_id)` | 模块级函数：`{source_id}_{bot_id}` 场名（一 source 一场一链） |
+| `CausalClient` | 因果星空 HTTP 客户端（`genesis` / `update` / `delete` / `horizon` / `click` / `history`） |
+
+## 注意事项
+
+- 本包按原样发布：`import causal_slicing` 时会执行一次 `logging.basicConfig(level=INFO, ...)`，
+  即设置宿主项目的 root logger 级别与格式。若你的项目需要自定义日志，请在 import 之前完成 `basicConfig` 配置。
+- 未安装 `redis` 库或连接失败时，焦点与整链计数退化为**进程内字典**（重启即失），并打印一次告警。
+- 文件末尾的命令行演示（`if __name__ == "__main__"`）依赖同仓库的 `causal_config.py`，仅在直接运行该文件时才会触发，
+  `import causal_slicing` 不受影响。
+
+## 许可证
+
+未声明许可证。如需分发/商用请先与作者确认。

causal_slicing-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+causal_slicing.py,sha256=hpfdweYmuwYzyk1Drgr_08Os-kLV1rnl3paeLlOvGxk,62130
+causal_slicing-0.1.0.dist-info/METADATA,sha256=BXjsV0fFhk5d2Q87zDTzfB5Ty8e2GoiD7VL2C78-_Cs,6423
+causal_slicing-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+causal_slicing-0.1.0.dist-info/top_level.txt,sha256=G8dSshfWN_IXW1t6TJYrQYqKQlx6-FNHspJFOrph47E,15
+causal_slicing-0.1.0.dist-info/RECORD,,

causal_slicing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

causal_slicing-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+causal_slicing