Metadata-Version: 2.4
Name: lzm-space
Version: 0.3.0
Summary: 以空间为概念的统一存储、检索、编排引擎 - 像管理文件夹一样管理数据
Author: Lzm
License-Expression: MIT
Project-URL: Homepage, https://github.com/lzm/lzm-space
Project-URL: Issues, https://github.com/lzm/lzm-space/issues
Keywords: space,storage,s3,minio,oss,elasticsearch,rag,knowledge-base,ledger,lzm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: lzm-edsm>=0.2
Provides-Extra: s3
Requires-Dist: minio>=7.0; extra == "s3"
Provides-Extra: es
Requires-Dist: elasticsearch>=8.0; extra == "es"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: sql
Requires-Dist: asyncpg>=0.29; extra == "sql"
Provides-Extra: cabinet
Requires-Dist: sqlalchemy>=2.0; extra == "cabinet"
Provides-Extra: all
Requires-Dist: lzm-space[s3]; extra == "all"
Requires-Dist: lzm-space[es]; extra == "all"
Requires-Dist: lzm-space[redis]; extra == "all"
Requires-Dist: lzm-space[sql]; extra == "all"
Requires-Dist: lzm-space[cabinet]; extra == "all"

# lzm-space — Agent System 空间引擎基座

> 编码：utf8 | 作者：Lzm | 日期：2026-07-17

**以"空间"为概念的统一数据编排基座——像管理文件夹一样管理数据，像仓库台账一样追踪出入库。**

lzm-space 定位为 **Agent System 开发基座库**，不替代 ORM，而是提供一个比 ORM 更上层的抽象：**空间（Space）**。

一个 `create_space()` 即可获得：
- **信息柜（Cabinet）** — 结构化数据，自动 Schema 演进
- **仓库（Warehouse）** — 文件/对象存储（S3/MinIO/OSS）
- **知识库（Knowledge Base）** — 文档切片 + 向量化 + 多策略搜索（RAG）
- **台账（Ledger）** — 操作审计流水，不可篡改
- **权限（Permissions）** — 空间级访问控制
- **清单（Inventory）** — 空间资产实时盘点

---

## 核心理念

```
传统开发：为每个模块 建表 → CRUD → 配权限 → 接文件 → 加审计 → 搞缓存
          → 模块多了 → 每个都来一遍 → 管理爆炸

lzm-space：定义一个 Space → 自动获得 Cabinet + 仓库 + 知识库 + 台账 + 权限
           → 业务代码只需关心 put/get/search
           → 其他都是基建自动化的
```

| 概念 | 类比 | 后端 | 用途 |
|------|------|------|------|
| **空间（Space）** | Linux 目录 / K8s Namespace | — | 数据归属 + 权限边界 |
| **信息柜（Cabinet）** | Excel 工作表 | PostgreSQL（SQLAlchemy） | 结构化 CRUD，自动 DDL |
| **仓库（Warehouse）** | S3 存储桶 | MinIO / S3 / OSS | 文件/大块数据存取 |
| **知识库（KB / RAG）** | 搜索引擎 | Elasticsearch | 语义搜索 / 向量检索 |
| **台账（Ledger）** | 银行流水 | PostgreSQL（SQLAlchemy） | 审计追踪 / 事件溯源 |
| **清单（Inventory）** | 库存盘点 | Cabinet 数据实时聚合 | 空间资产统计 |
| **关联图（Graph）** | 知识图谱 | 远期规划 | 跨数据关联查询 |

---

## 技术架构

```
┌─ SpaceClient ──────────────────────────────────────────┐
│                                                        │
│   create_space() → 获得 Space 实例                      │
│     ├─ space.cabinet("users")  → 信息柜（自动 DDL）     │
│     ├─ space.upload("doc.pdf") → 仓库（S3/MinIO）       │
│     ├─ space.archive("文档")   → 知识库（ES + RAG）     │
│     ├─ space.search("查询")    → 多策略搜索             │
│     ├─ space.get_ledger()      → 台账审计               │
│     └─ space.inventory()       → 清单盘点（v0.3.0+）   │
│                                                        │
│   复杂查询走穿透：space.raw_sql("SELECT ... JOIN ...")  │
│                                                        │
├────────────────────────────────────────────────────────┤
│   SQLAlchemy 底座 (v0.3.0+)                            │
│   ├─ SQLAlchemy Core — 统一连接池/事务/方言             │
│   ├─ SchemaManager — 自动 DDL（lzm-space 独有）        │
│   ├─ CabinetBackend — 信息柜包装器                      │
│   └─ raw_sql() — 复杂查询穿透通道                      │
├────────────────────────────────────────────────────────┤
│   多后端适配器                                          │
│   ├─ PostgreSQL (asyncpg) — 信息柜 + 台账               │
│   ├─ Elasticsearch — 知识库/向量检索                    │
│   ├─ MinIO / S3 / OSS — 文件/对象存储                  │
│   ├─ Redis — 缓存/热数据                                │
│   └─ lzm-edsm — 事件驱动台账编排                       │
└────────────────────────────────────────────────────────┘
```

---

## 快速开始

### 安装

```bash
# 核心（零外部依赖）
pip install lzm-space

# 全部后端
pip install lzm-space[all]

# 指定后端
pip install lzm-space[s3,es,sql]

# + 插件系统（切片/向量化/提取/重排）
pip install lzm-space[all] lzm-plugin[all]
```

### 基础用法

```python
import asyncio
from lzm.space import SpaceClient

client = SpaceClient()

async def main():
    # 1. 创建空间 = 创建一个完整的数据资源组
    space = await client.create_space("my-project")
    print(f"空间创建成功: {space.space_id}")

    # 2. 信息柜 — 结构化数据存取
    users = await space.register_cabinet("users", sql_backend)
    await users.put({"name": "Alice", "role": "admin", "dept": "eng"})
    # → 自动建列，无需预定义表结构

    result = await users.query() \
        .filter("role = 'admin'") \
        .group_by("dept") \
        .agg(cnt="count(*)") \
        .to_list()
    print(f"管理员分布: {result}")

    # 3. 仓库 — 文件存储
    await space.upload("设计稿.zip", file_data)

    # 4. 知识库 — RAG（需要 lzm-plugin）
    result = await space.archive_knowledge("文档内容...", extract_events=True)
    hits = await space.search("关于XX", strategy="hybrid")

    # 5. 台账 — 审计查询
    ledger = await space.get_ledger(limit=10)
    for entry in ledger:
        print(f"  [{entry.operation}] by {entry.actor}")

    # 6. 清单 — 资产盘点（v0.3.0+）
    inv = await space.inventory()
    print(f"信息柜分布: {inv}")

    # 7. 复杂查询 — 穿透到 SQLAlchemy
    results = await space.raw_sql(
        "SELECT * FROM cabinet_data WHERE _c_role = 'admin'"
    )

asyncio.run(main())
```

### 权限外套 — 快速集成到已有业务

如果已有 SQLAlchemy Model，直接用 Cabinet 包装即可获得权限管理 + 台账审计：

```python
from lzm.space.cabinet import Cabinet, CabinetPermissionManager

# 已有业务模型
class Task(Base):
    __tablename__ = "tasks"
    id = Column(Integer, primary_key=True)
    space_id = Column(String(36))  # 只需添加 space_id 列
    title = Column(String(256))
    status = Column(String(32))

perm_mgr = CabinetPermissionManager()

# 1. 定义角色
await perm_mgr.define_role(session, "project-alpha", "manager", {
    "tasks": "lrwxdmau",   # 全部权限
})
await perm_mgr.define_role(session, "project-alpha", "viewer", {
    "tasks": "lr------",   # 只读
})

# 2. 分配角色
await perm_mgr.assign_role(session, "project-alpha", "alice", "manager")
await perm_mgr.assign_role(session, "project-alpha", "bob", "viewer")

# 3. 使用 Cabinet 查询（自动鉴权 + 空间过滤 + 台账）
cab = Cabinet(Task)

# alice（manager）— 正常读取
tasks = await cab.query(session, "alice", "project-alpha") \
    .where(Task.status == "active") \
    .to_list()

# bob（viewer）— 尝试写入 → CabinetPermissionDenied
# await cab.insert(session, "bob", {"title": "hack"}, "project-alpha")


---

## 项目状态

- **版本**：0.3.0
- **当前阶段**：v0.3.0 已完成（Cabinet 权限外套）
- **测试**：246+ 用例 ✅
- **v0.3.0 变更**：
  - **Cabinet 权限外套** — Cabinet 从存储适配器重构为权限包装器，对已有 SQLAlchemy Model 进行权限管理
  - **双层权限模型** — `space_roles`（角色权限模板）+ `space_members`（用户角色赋值），细粒度表级别控制
  - **自动台账** — 每次 Cabinet 操作自动记录 `cabinet_ledger`，支持审计追踪
  - **权限字系统** — 8 位权限字（l/r/w/x/d/m/a/u），灵活配置
  - **自动空间过滤** — query/update/delete 操作自动追加 `WHERE space_id = ?`
  - **链式查询** — `where()`/`order_by()`/`limit()`/`offset()`/`to_list()`/`first()`/`count()`
  - 新增 `cabinet/` 子模块，含 models/cabinet/permission/__init__

---

## 技术栈

| 层 | 技术 | 版本 |
|----|------|------|
| 语言 | Python | >=3.11 |
| 底座 ORM | SQLAlchemy (v0.3.0+) | >=2.0 |
| 编排引擎 | lzm-edsm | >=0.2 |
| S3 存储 | minio | >=7.0（可选） |
| ES 存储 | elasticsearch | >=8.0（可选） |
| Redis | redis-py | >=5.0（可选） |
| PG 驱动 | asyncpg | >=0.29（可选） |
| 插件系统 | lzm-plugin | >=0.2（可选） |

---

## 目录结构

```
lzm-space/
├── README.md                         # 总纲
├── pyproject.toml                    # 包配置
├── src/lzm/space/
│   ├── __init__.py                   # 包入口
│   ├── core/
│   │   ├── node.py                   # SpaceNode, SpaceType
│   │   ├── permissions.py            # SpacePermissions, AllowEntry
│   │   ├── path.py                   # 路径解析
│   │   ├── models.py                 # 数据模型
│   │   └── client.py                 # SpaceClient 统一入口
│   ├── cabinet/                      # 权限外套（v0.3.0+）
│   │   ├── __init__.py               # 模块导出
│   │   ├── models.py                 # space_roles / space_members / cabinet_ledger
│   │   ├── cabinet.py                # Cabinet + CabinetQuery
│   │   └── permission.py             # CabinetPermissionManager + 鉴权逻辑
│   ├── manager/
│   │   ├── __init__.py
│   │   └── space_manager.py          # 空间 CRUD + 后端路由
│   ├── backends/
│   │   ├── __init__.py
│   │   ├── base.py                   # StorageBackend ABC + DataDescriptor
│   │   ├── es_backend.py             # Elasticsearch 后端
│   │   ├── schema_manager.py         # 列注册与动态列管理
│   │   ├── sql_backend.py            # SQL 结构后端 — 列优先+JSONB
│   │   ├── sql_dialect.py            # PostgreSQL 方言封装
│   │   ├── sql_query.py              # QueryBuilder + CrossSpaceQuery
│   │   ├── redis_backend.py          # Redis 后端
│   │   └── s3.py                     # MinIO/S3 后端
│   └── ledger/
│       ├── __init__.py
│       ├── engine.py                 # LedgerEngine 双层台账引擎
│       ├── models.py                 # LedgerEntry 数据模型
│       ├── pg_store.py               # PostgreSQL 台账持久化
│       ├── store.py                  # SQLite 台账 + 全局空间注册表
│       └── hooks.py                  # 外部回调注册表
├── docs/
│   ├── timeline.md                   # 开发进度时间线
│   ├── common-errors.md              # 常见错误归档
│   ├── coding-standards.md           # 编码规范
│   ├── todo.md                       # TODO 管理
│   ├── plugin-integration-guide.md   # 插件集成指南
│   └── logic-records/                # 设计文档
└── tests/                            # 测试用例
```

---

## 相关文档

- [开发进度时间线](docs/timeline.md)
- [常见错误归档](docs/common-errors.md)
- [编码规范](docs/coding-standards.md)
- [TODO 管理](docs/todo.md)
- [Cabinet 权限外套设计文档](docs/logic-records/20260717-cabinet-permission-wrapper.md)
- [核心概念定义](docs/logic-records/20260717-space-concepts-definition.md)
- [插件集成指南](docs/plugin-integration-guide.md)
- [逻辑记录](docs/logic-records/)
