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.

A Tool is a runtime view over a Capsule. The Capsule is the durable executable payload.

​
What a Toolkit is

A Toolkit groups Capsules under tool names and serving metadata. Use it when you want a set of functions to behave like a local API, an MCP server, or an export target for model tool calling. The durable model is intentionally small:
  • Capsule: stores the executable function manifest
  • Tool: names one Capsule and exposes a runtime run(...) surface
  • Toolkit: orders tools, saves references, and exports servers
  • ToolkitRecord: stores Toolkit manifests and Capsule references in the registry

​
Build and register a Toolkit

import heavenbase as hb

def add(left: int, right: int) -> int:
    return left + right

def fibonacci(number: int) -> int:
    previous = 0
    current = 1
    for _ in range(number):
        previous, current = current, previous + current
    return previous

toolkit = hb.Toolkit("math-tools", namespace="demo", version="1")

@toolkit.tool(name="add")
def add_tool(left: int, right: int) -> int:
    return add(left, right)

toolkit.add(fibonacci, name="fibonacci", namespace="demo", version="1")

toolkit_id = toolkit.register()
toolkit.register(...) saves each Capsule first, then stores the Toolkit manifest as Capsule references. Loading a Toolkit restores the referenced Capsules lazily. For compact construction, pass a list, pairs, or a mapping: 
toolkit = hb.Toolkit("math-tools", {"add": add, "fibonacci": fibonacci}, namespace="demo")

​
Load from another path

loaded = hb.Toolkit.load(name="math-tools", namespace="demo", version="1")
assert loaded.run("add", left=2, right=3) == 5
assert loaded.run("fibonacci", number=10) == 55
The consumer does not need to import the file that created the Toolkit. It loads the Toolkit manifest from the registry, then restores each Capsule from its manifest. Tests and applications can pass registry_config=... to isolate registry storage while keeping the same public API.

​
Architecture data flow

Toolkit execution is a thin layer over Capsules:
  1. Toolkit.add(callable) captures the callable as a Capsule.
  2. toolkit.register() persists each Capsule and then stores a Toolkit manifest containing ordered Capsule references.
  3. Toolkit.load(...) resolves the manifest and restores each referenced Capsule into a Tool.
  4. Toolkit.run(name, **kwargs) calls the selected Capsule locally.
  5. Toolkit.to_fastmcp() wraps each Tool with a signature-compatible FastMCP function.
  6. Toolkit.to_anthropic_tools(...) exports a separate Anthropic programmatic tool schema with allowed_callers.

​
Serve through MCP

from fastmcp import Client

server = loaded.to_fastmcp()

async with Client(server) as client:
    tools = await client.list_tools()
    result = await client.call_tool("add", {"left": 2, "right": 3})
    assert result.structured_content["result"] == 5
You can also print client configuration: 
print(loaded.to_mcp_json(transport="http", host="127.0.0.1", port=7011))

​
Import an MCP server

client_toolkit = hb.Toolkit.from_fastmcp(server, name="math-client")
assert client_toolkit.run("add", left=2, right=3)["result"] == 5

​
Workspace Toolkits

Every workspace can still become a Toolkit: 
workspace = hb.HeavenBase("notes", backends={"main": {"type": "inmem"}})
toolkit = workspace.to_mcp(name="notes")

print(toolkit.list_tools())
Workspace Toolkits expose entity definition, Catalog discovery, CRUD, count, query, and explain tools. They use the same native Toolkit runtime as Capsule Toolkits.

​
Demo

python demos/20_capsule_math_toolkit_demo.py
The demo creates a persisted math Toolkit, loads it back through Toolkit.load(...), shows Capsule docstring/format conversion, and checks that FastMCP can list and call the tools.