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` 不受影响。

## 许可证

未声明许可证。如需分发/商用请先与作者确认。
