Capsules

A Capsule is a function with luggage, fingerprints, and a very strict border agent.

1. Motivation

Pickling a function can preserve bytes without preserving an inspectable public identity, input schema, docstring, restore policy, or trust decision. Importing a module path is readable but fails when the consumer does not share the original checkout. A Capsule records callable identity, signature, schemas, docstring, dependencies, restore layers, capabilities, trust flags, and integrity fingerprints. It can behave like the original function now and restore it later under an explicit policy. Restoring a Capsule executes Python code. The metadata makes that boundary reviewable; it does not make untrusted code safe.

2. Capture and Call a Function

import heavenbase as hb


def add(left: int, right: int) -> int:
    """Add two integers."""
    return left + right


capsule = hb.Capsule(
    add,
    name="add",
    namespace="demo",
    version="1",
)

assert capsule(left=2, right=3) == 5

Capsule accepts a callable directly and preserves function-like metadata. Capsule.from_func(...) is the equivalent explicit constructor. It also works as a decorator:

@hb.Capsule(name="multiply", namespace="demo", version="1")
def multiply(left: int, right: int) -> int:
    return left * right

Versions are authored contract values, not automatic content-hash counters. Publish a new version when the public executable contract changes.

3. Understand Restore Layers

The default capture considers source and import-path layers. A trusted-local cloudpickle layer is optional and disabled by default.

source_only = hb.Capsule(
    add,
    name="source-add",
    include_cloudpickle=False,
)

print(source_only.to_str("source"))
print(source_only.to_str("json"))

Source can restore without the original file path. Import targets are compact when the same stable package is installed. Binary payloads can represent harder callables but expand the trust boundary. Use source-only capture unless reviewed local code genuinely needs a binary fallback.

4. Inspect and Verify Before Running

manifest = capsule.to_dict()
capsule.verify()

print(manifest["identity"])
print(manifest["input_schema"])
print(manifest["fingerprints"])

verify() checks stored source and binary payloads against the fingerprints in the same manifest without executing the callable. That is a record-integrity check, not a comparison with today’s live source and not a code-safety proof. to_str("json"), to_str("yaml"), to_str("source"), and to_str("docstring") expose reviewable forms. Capsule.from_str(...) restores JSON or YAML manifests.

5. Let an Application Workspace Own Toolkit Capsules

Concrete Toolkit persistence stores the sys-toolkit row and every referenced sys-capsule row in one explicit application workspace:

ws = hb.HeavenBase("math-app", preset="debug")
toolkit = hb.Toolkit("math", {"add": add}, namespace="demo")

toolkit_id = toolkit.register(ws=ws)
stored = ws.get(toolkit_id, entity=hb.Toolkit)

print(stored["name"])

This is the normal application path. The workspace owns identity, Context, Extension activation, rows, and cleanup. Loading the Toolkit restores its Capsule references lazily through the same workspace authority. Standalone Capsule.register() and Capsule.load() remain advanced Context-private administration over the configured Capsule registry. Use them when a Capsule genuinely exists outside an application Toolkit, and pass matching resolver/config authority when isolation matters.

6. Load and Run a Standalone Capsule

capsule_id = capsule.register(reason="publish demo add")

loaded = hb.Capsule.load(
    capsule_id,
    resolver=ws.context.modules(),
    config=ws.context.config,
)

assert loaded.run(left=2, right=3) == 5

register() defaults to overwrite=False. load() verifies stored checksums and restores lazily. Capsule.list(...) inspects stored rows; Capsule.delete(...) tombstones by default. For ordinary Toolkit code, prefer toolkit.register(ws=...) so Capsule and Toolkit rows share the explicit application workspace.

7. Use Capsules Behind Tools

@hb.Tool
def subtract(left: int, right: int) -> int:
    return left - right


wrapped = hb.Tool(capsule, name="plus")

assert subtract(left=5, right=2) == 3
assert wrapped(left=2, right=3) == 5

A Tool is a function-like view over one execution Capsule plus an optional serializer Capsule. Toolkit.add(...) accepts a Tool, Capsule, or plain callable and normalizes all three to the same contract. Agent and MCP calls remain keyword-oriented even though local Tools and Capsules can behave like their wrapped functions.

8. Keep the Trust Boundary Explicit

Only capture, store, restore, or serve code you own or have reviewed. A valid fingerprint proves integrity of the stored payload, not safety of its behavior.

Treat installed module artifacts and Capsule rows like source repositories.
Keep include_cloudpickle=False unless a reviewed local callable requires it.
Review input schemas before exposing a Tool to an agent.
Scope MCP profiles to the minimum tools and entities required.
Use explicit workspaces and Contexts so executable state does not drift into ambient authority.
Use tombstones or new versions for intentional lifecycle changes; immutable revision history is not a universal application migration system.

Summary

Capsules capture callable behavior with inspectable restore layers and fingerprints.
Application workspaces own Capsules referenced by persisted Toolkits.
Integrity is not safety; executable payloads remain trusted code.

Further Exploration

Related resources:

Toolkits - Group Capsules into callable tool collections
MCP Toolkit - Review persistence and serving methods
First MCP - Serve a small Toolkit
Extensions - Understand the required Capsule Extension root

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Capture and Call a Function

3. Understand Restore Layers

4. Inspect and Verify Before Running

5. Let an Application Workspace Own Toolkit Capsules

6. Load and Run a Standalone Capsule

7. Use Capsules Behind Tools

8. Keep the Trust Boundary Explicit

Summary

Further Exploration

​1. Motivation

​2. Capture and Call a Function

​3. Understand Restore Layers

​4. Inspect and Verify Before Running

​5. Let an Application Workspace Own Toolkit Capsules

​6. Load and Run a Standalone Capsule

​7. Use Capsules Behind Tools

​8. Keep the Trust Boundary Explicit

​Summary

​Further Exploration

1. Motivation

2. Capture and Call a Function

3. Understand Restore Layers

4. Inspect and Verify Before Running

5. Let an Application Workspace Own Toolkit Capsules

6. Load and Run a Standalone Capsule

7. Use Capsules Behind Tools

8. Keep the Trust Boundary Explicit

Summary

Further Exploration