Python API 概览 - HeavenBase

宽广 API 仍然可以只有一扇正门；消防出口只需贴好标签。

1. 动机

把每个提供商类、Registry helper、查询片段与界面编译器都导入首个用户示例，会让包看起来比应用更难。隐藏所有高级接缝则会产生相反问题：集成开始依赖私有模块。 HeavenBase 保留宽广的惰性根入口，同时推荐一个精简的首读界面。应用示例从 import heavenbase as hb 开始；只有任务真正需要某个边界时，高级作者才进入所属包。

2. 从主要界面开始

区域	主要 API	用途
工作区	`hb.HeavenBase`, `hb.WorkspaceManifest`, `hb.Context`	持久或分离的应用边界
模式	`hb.Entity`, `hb.field`, logical types	类型化 Entity 类与 JSON 兼容模式
放置	`hb.InlineColumn`, `hb.SideTable`, `hb.VectorIndex`, `hb.SparseGramIndex`, `hb.GraphEdge`	字段级存储意图
查询	`hb.Query`, `hb.QuerySpec`, `hb.Aggregate`	不可变查询值与聚合
结果	`hb.ResultFrame`	带显式导出的分离传输结果
元数据	`hb.Catalog`, `hb.MetaSchema`, `hb.capabilities`	对象、结构与已注册选择检查
LLM	`hb.LLM`, `hb.LLMSession`, `hb.Prompt`	预设驱动的生成与提示行
工具	`hb.Capsule`, `hb.Tool`, `hb.Toolkit`	可调用捕获、组合、持久化与 MCP

import heavenbase as hb


class Item(hb.Entity):
    name = hb.field(hb.ShortText)
    score = hb.field(hb.Float)


ws = hb.HeavenBase("api-demo", preset="debug")
ws.register(Item)
ws.upsert(Item, {"name": "Alpha", "score": 0.9})

rows = ws.query(Item).where(Item.score >= 0.5).execute().rows()

这条流程就是默认心智模型：定义、打开、注册、写入、查询，再选择结果导出。

3. 使用正确的工作区入口

ws = hb.HeavenBase("shop", preset="debug")
same = hb.HeavenBase.load("shop")
ws.activate()
active = hb.HeavenBase.load()

调用	缺失行为	注册	激活
`hb.HeavenBase(id, ...)`	创建缺失 id	除非 `detached=True`，否则持久	绝不隐式
`hb.HeavenBase.load(id)`	抛出 `KeyError`	仅已有	不改变
`hb.HeavenBase.load()`	使用活跃项，再使用配置默认项	仅已有	不改变
`hb.HeavenBase(..., detached=True)`	构造调用方自有外观	无	禁止

显式 preset= 或 backends= 值会断言持久构造。冲突会抛出 FileExistsError。release() 移除实时外观并保留 Backend 数据；drop() 销毁所属物理数据。

4. 分离模式与数据行生命周期

ws.register(Item)
item_id = ws.upsert(Item, {"name": "Beta", "score": 0.7})
ws.set(item_id, {"score": 0.8}, entity=Item)
item = ws.get(item_id, entity=Item)

注册建立规范类、放置、物理模式与 MetaSchema 投影。普通数据行操作要求该类已经存在，绝不会把注册模式变成副作用。 hb.Agent 等根动态 Extension Entity 导出通过 hb.DEFAULT_CONTEXT 解析。跨 Context 代码应使用目标工作区中的规范类，而不是把 Python 类身份当作持久身份。

5. 把查询与 Frame 视为值

base = ws.query(Item).where(Item.score >= 0.5)
names = base.select("name")
total = base.count().execute().scalar()

print(names.execute().rows())
print(total)

每个流式变换都返回新的 hb.Query；这里没有可变 builder、copy 或 fork API。execute() 重新计算并返回全新分离的 hb.ResultFrame。使用显式结果出口：

rows() 用于 JSON 风格数据行字典
scalar() 用于单单元格终结结果
to_pandas()、to_pyarrow()、to_numpy()、to_pydantic() 或 to_daft() 用于类型化消费者
ids 与 column(...) 用于聚焦检查

在依赖提供商行为前使用 query.explain() 检查所选 Backend、策略、处理器、原生/回退模式与不支持原因。

6. 使用 Context 绑定的智能体与 LLM API

llm = hb.LLM(preset="mock", context=ws.context)
print(llm.chat("Reply with hb-ok"))

toolkit = ws.to_mcp(profile="agent")
print(toolkit.list_tools())

需要隔离时传递所属 Context。工作区 MCP profile 限定工具、实体、Skill 与序列化器；full 是管理 profile，不是面向不可信智能体的默认项。具体 Toolkit 持久化由工作区拥有。Toolkit.register、load、list、describe 与 delete 接受 ws=；省略时使用仅加载已有项的 hb.HeavenBase.load()，绝不会创建隐藏 Toolkit 存储。

7. 从所属包使用高级 API

边界	公共所有者
Registry 内核	`heavenbase.utils.registry`
模块安装、检查、解析、生命周期	`heavenbase.modules` 与 `context.modules()`
放置值与 profile	`heavenbase.placement`
Frame、片段、处理器、行操作	`heavenbase.execution`
Backend 提供商与类型	`heavenbase.backends`
SQL 方言与数据库行为	`heavenbase.database`
LLM 入口、spec、会话、缓存	`heavenbase.llm`
扩展作者入口	`hb.ext`
解析器中立 CLI 契约	`heavenbase.cli`

使用 hb.ext 编写 Registry 支持的后端、处理器、策略、操作、profile、序列化器与 Extension。普通应用入门应留在根入口。

8. 避免已退役兼容路径

0.1.2.1 架构在以下位置没有兼容包：

heavenbase.registry
heavenbase.storage
heavenbase.handlers
heavenbase.frame
heavenbase.discovery

请改用 heavenbase.utils.registry、heavenbase.placement、heavenbase.execution 与 heavenbase.capabilities。SQL 资源位于 heavenbase.database.resources.sql；Toolkit 提示位于 heavenbase.toolkit.prompts。

9. 保守阅读 API 契约

当实现导入很重时，公共根导出会保持惰性。
已注册标签描述语义声明；它们不证明可执行支持。
独立 Backend 不会形成分布式事务。
工作区清单导出构造、请求的 Extension 根与模式，而不是数据行。
已安装可执行模块与 Capsule 是可信代码边界。
提供商特定原生行为应通过 explain() 与聚焦测试验证。

摘要

主要 API 拥有应用工作流；高级 API 公开狭窄引擎接缝。
Context 与工作区参数保留运行时权威。
已退休兼容包不是扩展点。

进一步探索

相关资源：

工作区 - 学习构造与生命周期
实体 - 定义公共模式
查询 - 组合并解释不可变查询
扩展 - 使用高级 Registry 支持接缝
MCP Toolkit - 持久化并服务工具
CLI 参考 - 使用命令行适配器

​1. 动机

​2. 从主要界面开始

​3. 使用正确的工作区入口

​4. 分离模式与数据行生命周期

​5. 把查询与 Frame 视为值

​6. 使用 Context 绑定的智能体与 LLM API

​7. 从所属包使用高级 API

​8. 避免已退役兼容路径

​9. 保守阅读 API 契约

​摘要

​进一步探索

1. 动机

2. 从主要界面开始

3. 使用正确的工作区入口

4. 分离模式与数据行生命周期

5. 把查询与 Frame 视为值

6. 使用 Context 绑定的智能体与 LLM API

7. 从所属包使用高级 API

8. 避免已退役兼容路径

9. 保守阅读 API 契约

摘要

进一步探索