Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

Capsules are trusted-local executable manifests. Store only code you own or have reviewed.

​
What a Capsule is

A Capsule is the durable form of a Python callable. It stores enough metadata to restore and run a function later, including:
  • identity: namespace, name, and explicit version
  • signature: parameters, return annotation, and JSON schema
  • restore layers: source, import path, and optional cloudpickle payload
  • dependencies: Python version and imports found in source
  • capabilities: whether it can be used locally, exported to MCP, or exported for Anthropic programmatic tools
  • trust and fingerprints: local-only execution flags and hashes for review
The default restore order is source first, import path second, and binary payload last when a binary payload was explicitly captured. Source-first restore is what lets a Capsule be loaded from a different folder without importing the file that originally defined the function.

​
Store a function

import heavenbase as hb

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

    Args:
        left: First integer.
        right: Second integer.

    Returns:
        Sum of both integers.
    """
    return left + right

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

capsule_id = capsule.register()
The version is part of the identity. HeavenBase does not auto-increment versions from content hashes; publish a new version when you want a new public executable contract.

​
Load and run it elsewhere

loaded = hb.Capsule.load(name="add", namespace="demo", version="1")
assert loaded.run(left=2, right=3) == 5
The consumer only needs HeavenBase and access to the registry backend. It does not need to import the original builder module when the source restore layer is available. For isolated tests or application-specific registries, pass a config mapping without constructing a registry object in user code: 
loaded = hb.Capsule.load(
    name="add",
    namespace="demo",
    version="1",
    registry_config={"backend": {"main": {"type": "sqlite", "database": "registry.db"}}},
)

​
Docstrings and formats

Capsules parse callable docstrings during capture and can synthesize a callable docstring from the stored signature metadata. 
doc = loaded.manifest.source["doc"]
assert doc["summary"] == "Add two integers."
assert doc["params"]["left"] == "First integer."

print(loaded.to_str("docstring"))
print(loaded.to_str("source"))
print(loaded.to_str("json"))
print(loaded.to_str("yaml"))
Capsule.from_str(...) restores JSON and YAML manifest strings back into a Capsule.

​
Architecture data flow

The Capsule flow is explicit and layered:
  1. Python callable -> CallableSerialization strategy inspects source, import path, docstring, signature, dependencies, and optional binary fallback.
  2. Strategy -> CapsuleManifest records identity, schema, restore layers, capabilities, trust flags, and fingerprints.
  3. capsule.register() -> hidden registry workspace stores the active capsule row and appends a capsule-revision row.
  4. Capsule.load(...) -> manifest is read by id or by namespace/name/version.
  5. Capsule.to_func() -> restore policy tries source, then import path, then trusted-local binary payload.
  6. Tool and Toolkit wrap Capsules for local calls, MCP serving, and programmatic tool exports.
The JSON serializer also routes callables through the same internal heavenbase.capsule.serialize strategy. When a callable cannot be captured as a Capsule, it falls back to a lightweight module.qualname reference instead of failing generic JSON serialization.

​
Registry records

Capsules are stored as normal HeavenBase entities in a hidden registry workspace:
  • capsule: active manifest row
  • capsule-revision: append-only manifest revisions
The default registry config is under heavenbase.capsule.registry. You can pass registry_config=... when a demo, test, or application should keep executable data in a dedicated file. Most application code should prefer capsule.register(...) and Capsule.load(...). CapsuleRegistry remains available for advanced registry administration and inspection.

​
Trust model

Restoring a Capsule executes Python code. Treat Capsule registries like source code repositories, not like inert data files.
Capsules do not verify themselves against the current content of the original Python function. The registry checksum only verifies that a loaded Capsule payload still matches the hashes stored with that same manifest. It is a record-integrity check, not a code-safety proof. HeavenBase caches successful checksum checks in a thread-safe in-memory LRU cache, so a process verifies a Capsule payload once per cache key instead of recalculating hashes every time the Capsule is loaded or restored. If someone edits the registry database after the first cached verification, edits both executable content and stored hashes, registers malicious code, or loads a manual source/binary payload directly, HeavenBase does not make safety guarantees. Use source-only Capsules by default. include_cloudpickle defaults to False; enable binary payloads only for reviewed local code that cannot be represented by source or import path. If source-only restore fails, HeavenBase reports that no trusted-local binary fallback is stored.

​
Demo

Run the math demo from the source checkout: 
python demos/20_capsule_math_toolkit_demo.py
The demo saves add, mul, sub, div, mod, and fibonacci as Capsules, stores a Toolkit, loads it through the public API, and validates the MCP server with a FastMCP client. The cross-directory consumer check is covered by the test suite; the demo itself stays focused on the public API.