Extension System

Extensions add entity types and storage behavior without changing the workspace API.

1. What Extensions Do

HeavenBase extensions register additional entity types or developer hooks into a workspace. The workspace API stays the same: you still call register, upsert, query, and get. Two layers matter in 0.1.1.5:

Entity extensions add optional entity types through ExtensionSpec and ws.enable_extension(...).
Developer extensions register backends, handlers, storage strategies, and query ops through hb.ext.

2. Built-In System and Prompt Extensions

Every workspace enables the required system extension automatically during construction. You do not call enable_extension("system") in application code. The system and default-loaded prompt extensions register built-in persistent entities:

Entity id	Role
`sys-catalog`	Concrete object discovery
`sys-metaschema`	Workspace structure, capabilities, and enabled extensions
`sys-prompt`	Callable prompt rows from `prompt`
`sys-translation`	Prompt-bound translations from `prompt`
`sys-capsule`	Executable Capsule manifests
`sys-toolkit`	Toolkit manifests and Capsule references

Capsule and Toolkit are part of system; Prompt and Translation are part of the default-loaded prompt extension.

import heavenbase as hb

ws = hb.HeavenBase("ext-demo", preset="debug")

print("system" in ws.extensions())
print("prompt" in ws.extensions())
print("sys-capsule" in ws.entities)

When you register a prompt in a workspace, HeavenBase ensures the prompt extension is enabled. Use hb.Prompt(...).register(ws=ws) through the root package API.

3. Inspect Enabled Extensions

Use ws.extensions() for enabled extension metadata, or query MetaSchema for published extension rows:

print(list(ws.extensions()))

ext_rows = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "extension")
    .select("subject_id", "name", "desc")
    .execute()
    .rows()
)

print([row["subject_id"] for row in ext_rows])

The system and prompt rows include meta.entities with their built-in entity ids.

4. Register a Custom Entity Extension

Package authors register entity extensions in the process registry before workspaces load them:

import heavenbase as hb
from heavenbase.ext import Extension, ExtensionSpec, register_extension


class AuditLog(hb.Entity):
    identifier = "audit-log"

    event = hb.field(hb.ShortText)
    payload = hb.field(hb.Json).default({})


register_extension(
    Extension(
        ExtensionSpec(
            identifier="audit",
            name="Audit Log",
            desc="Optional audit rows for demo extensions.",
            entities=(AuditLog,),
            tags=("audit",),
        )
    )
)

ws = hb.HeavenBase("ext-custom", preset="debug")
ws.enable_extension("audit")
ws.register(AuditLog)
ws.upsert(
    AuditLog,
    {"object_id": "a1", "name": "startup", "event": "startup", "payload": {"ok": True}},
)

To enable custom extensions on every new workspace, set heavenbase.extensions.default in config to a comma-separated list or array of extension ids.

5. Extend Backends and Handlers

Lower-level extension authors use heavenbase.ext (also hb.ext) to register backends, handler plugins, logical types, storage strategies, and query operations. Workspace routing picks them up through registries instead of central edits.

from heavenbase.ext import registered_backend_identifiers, registered_ops

print("sqlite" in registered_backend_identifiers())
print("eq" in registered_ops())

Discover supported combinations through the public capability index:

import heavenbase as hb

hb.capabilities.logical_types()
hb.capabilities.backends(hb.Vector, hb.VectorIndex, op="near")

Use this surface when you ship a new storage provider or compiler, not for everyday workspace application code. See demos/04_extension_backend_template.py for a custom operation example.

Further Exploration

Related resources:

Extensions - Entity and developer extension reference
Architecture - Where extensions sit in the core path
Catalog - System entities from the system extension
Prompt - Callable prompts backed by sys-prompt
Capsules - Executable manifests under sys-capsule
Backends - Backend families extensions can register

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. What Extensions Do

2. Built-In System and Prompt Extensions

3. Inspect Enabled Extensions

4. Register a Custom Entity Extension

5. Extend Backends and Handlers

Further Exploration

​1. What Extensions Do

​2. Built-In System and Prompt Extensions

​3. Inspect Enabled Extensions

​4. Register a Custom Entity Extension

​5. Extend Backends and Handlers

​Further Exploration

1. What Extensions Do

2. Built-In System and Prompt Extensions

3. Inspect Enabled Extensions

4. Register a Custom Entity Extension

5. Extend Backends and Handlers

Further Exploration