Build an External Extension

If your extension needs a host patch, it is still a feature request wearing a fake moustache.

1. Motivation

Importing an external class proves only that Python can find it. A real HeavenBase Extension must also survive declarative discovery, inert inspection, Context-local resolution, workspace activation, ordinary CRUD, a fresh process, and exact uninstall targeting. This quickstart builds the smallest useful parity test. You will contribute one Entity and one Extension through the same module protocol used by bundled HeavenBase modules.

2. Create the Module Folder

Create this structure outside the heavenbase package:

acme_notes/
├── __init__.py
├── entities.py
└── meta.yaml

Leave __init__.py empty. Put one public Entity in entities.py:

import heavenbase as hb

class AcmeNote(hb.Entity):
    identifier = "acme-note"

    name = hb.field(hb.ShortText)

The implementation imports the public facade and does not depend on a private host path.

3. Declare the Entity and Extension

Save this as acme_notes/meta.yaml:

manifest_version: 2
coordinate: acme/notes
version: 1.0.0
compatibility: {}
bundle: acme-notes
items:
  - kind: entity
    identifier: acme-note
    name: AcmeNote
    desc: Example external note.
    source: path
    target: {module: entities, qualname: AcmeNote}
    active: true
    meta: {schema_version: 1}
  - kind: extension
    identifier: acme-notes
    name: Acme Notes
    desc: Example external Extension.
    source: inline
    target: definition
    active: true
    meta:
      schema_version: 1
      dependencies: [entity:acme-note]
      definition:
        identifier: acme-notes
        name: Acme Notes
        version: 1.0.0
        desc: Example external Extension.
        required: false
        requires: []
        tags: {external: true}
        entities: [acme-note]
        meta: {}
        setup: null
        api: null
        api_name: null

The Entity record points to code inside the module folder. The Extension definition depends on that record and activates it by identifier.

4. Install and Inspect Without Importing

Run this from the directory that contains acme_notes:

from pathlib import Path

import heavenbase as hb


context = hb.Context.load()
modules = context.modules()
receipt = modules.install(Path("acme_notes"))

records = modules.inspect("extension", "acme-notes")
print(records[0]["record"]["source"])

install() validates the descriptor, captures path-based code as a content-addressed artifact, publishes the records through the Context Registry, and returns an exact receipt. inspect() reads stored metadata without materializing AcmeNote.

5. Enable and Exercise the Extension

Use a detached in-memory workspace so this smoke test does not create a durable workspace identity:

ws = hb.HeavenBase(
    "acme-extension-smoke",
    detached=True,
    backends={"main": {"type": "inmem"}},
    context=context,
)

ws.enable_extension("acme-notes")
Note = ws.entities["acme-note"]

note_id = ws.upsert(Note, {"name": "Installed outside HeavenBase"})
row = ws.get(note_id, entity=Note)

print(row["name"])

The class comes from the installed artifact through the workspace’s Context. CRUD uses the canonical class that activation registered in this workspace.

The script prints inline during inspection and Installed outside HeavenBase after CRUD.

6. Clean Up Deliberately

ws.drop()
modules.uninstall(receipt)
context.close()

drop() is the destructive workspace-data cleanup. uninstall(receipt) removes the exact installed module generation. Module uninstall does not delete rows from other workspaces that enabled the Extension. For a real application, keep the installation and open durable workspaces normally. Reinstall after editing path-based source because installed artifacts are immutable snapshots.

7. Turn the Smoke Test into a Package Gate

Before publishing an external module:

Run install and inert inspection in a clean Context.
Resolve and enable the Extension in a new workspace.
Exercise its Entity, attached API, Toolkit family, or backend behavior.
Close the Context and prove a fresh Context can restore the installed records.
Uninstall by exact receipt and verify the intended generation disappeared.
Test the oldest and newest HeavenBase versions declared by compatibility.

Add Toolkit families and MCP profiles only after the owning workspace API is stable. Keep CLI, MCP, and other interfaces as adapters over that API.

Summary

One module folder declares data, implementation targets, and Extension behavior.
Install and inspect stay import-free until resolution is required.
Lifecycle tests should cover activation, restore, and exact-receipt cleanup.

Further Exploration

Related resources:

Extensions - Understand every Registry-backed extension role
Architecture - See Context and module ownership
Workspace - Choose durable or detached lifecycle
MCP Toolkit - Add tools and scoped profiles
Building GlossWise - See the protocol in a complete external product

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

Build an External Extension

1. Motivation

2. Create the Module Folder

3. Declare the Entity and Extension

4. Install and Inspect Without Importing

5. Enable and Exercise the Extension

6. Clean Up Deliberately

7. Turn the Smoke Test into a Package Gate

Summary

Further Exploration

​1. Motivation

​2. Create the Module Folder

​3. Declare the Entity and Extension

​4. Install and Inspect Without Importing

​5. Enable and Exercise the Extension

​6. Clean Up Deliberately

​7. Turn the Smoke Test into a Package Gate

​Summary

​Further Exploration

1. Motivation

2. Create the Module Folder

3. Declare the Entity and Extension

4. Install and Inspect Without Importing

5. Enable and Exercise the Extension

6. Clean Up Deliberately

7. Turn the Smoke Test into a Package Gate

Summary

Further Exploration