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.

hb.Prompt turns a prompt into a callable Python object and a HeavenBase entity. Function prompts are captured through Capsule manifests and stored as sys-prompt rows. Translation entries live as queryable sys-translation rows in the same workspace, and most code should reach them through prompt.tr.
Prompt rows can restore executable Capsule manifests. Load prompts only from workspaces you trust.

​
Function prompts

import heavenbase as hb


@hb.Prompt(name="demo.greet")
def greet(name: str, *, tr=str) -> str:
    return f"{tr('Hello')}, {name}!"


greet.register()
greet.tr.set("Hello", "zz", "HEY")

assert greet("Ada", lang="zz") == "HEY, Ada!"
assert hb.Prompt.load("demo.greet", lang="zz")("Bob") == "HEY, Bob!"
Construction does not write to a workspace. Call prompt.register(...) explicitly, or pass register=True when you intentionally want decorator-time registration. For agent workflows, pass ws=... on register/load so prompt versions and translations stay scoped to the task workspace.

​
Template prompts

Passing a string to hb.Prompt(...) creates a format-string prompt that is compiled into the same Capsule-backed callable form as function prompts. The whole template can be translated, and selected placeholder values can be translated before formatting. 
welcome = hb.Prompt(
    "Hello, {name}! Welcome to {place}",
    name="demo.welcome",
    tr_keys=["place"],
)
welcome.register()
welcome.tr.set("Hello, {name}! Welcome to {place}", "zz", "HEY, {name}! GO {place}")
welcome.tr.set("Tokyo", "zz", "TOKIO")

assert welcome(name="Ada", place="Tokyo", lang="zz") == "HEY, Ada! GO TOKIO"

​
Loading and versions

Prompts are loaded by dotted name, compact version ref, or row id: 
hb.Prompt.load("demo.greet")
hb.Prompt.load("demo.greet:2")
hb.Prompt.list(prefix="demo.")
hb.Prompt.versions("demo.greet")
hb.Prompt.delete("demo.greet:2")
Latest-version selection considers active rows only. Tombstoned rows are hidden from default loads and lists.

​
Translation lookup

Each prompt binds its own translation dictionary by default. Additional dictionaries can be bound in fallback order. 
prompt.tr.bind("shared.agent-ui")
prompt.tr.set("Hello", "zz", "HEY", dict_name="shared.agent-ui")
prompt.tr.unbind("shared.agent-ui")
prompt.tr is the translation helper bound to the prompt, while stored rows remain regular sys-translation rows and can be queried like other HeavenBase entities. Translation is exported from heavenbase.prompt for lower-level code, but the root import heavenbase as hb surface keeps translation under Prompt.tr. Lookup checks exact rows first, then source patterns with {placeholder} captures. If no translation is found, HeavenBase returns the source text for elicit="none". elicit="llm" is reserved and raises NotImplementedError in this release. Prompt calls resolve language in this order: explicit lang=..., the prompt object’s bound lang, the current CM_HVNB config scope at heavenbase.prompt.lang, then main_lang. 
hb.CM_HVNB.set("heavenbase.prompt.lang", "zz", scope="heavenbase.demo-zz")

with hb.CM_HVNB.scoped("demo-zz"):
    assert greet("Ada") == "HEY, Ada!"

​
Agent prompt assembly

Use hb.fast_prompt_section(...) to assemble multi-section agent prompts without importing AgentHeaven: 
import heavenbase as hb

ws = hb.HeavenBase("agent-prompts", preset="debug")


def agent_bootstrap(task_dir: str, workspace_id: str, *, tr=str) -> str:
    messages = hb.fast_prompt_section(
        system=tr("You are a task agent using HeavenBase as memory."),
        descriptions={"Context": [f"Workspace: {workspace_id}", f"Task directory: {task_dir}"]},
        instructions=[
            "Inspect files before running commands.",
            "Write structured results to the workspace.",
            "Return one plain final line.",
        ],
        tr=tr,
    )
    return messages[-1]["content"]


hb.Prompt(agent_bootstrap, name="agent.bootstrap", ws=ws).register(ws=ws)
system = hb.Prompt.load("agent.bootstrap", ws=ws)(task_dir="./task", workspace_id=ws.id)
Pass separate_system=True when the target LLM path should receive a dedicated system message instead of one user message containing all sections.

​
CLI

hb prompt list --prefix demo. --json
hb prompt show demo.greet --json
hb prompt create demo.hello --template "Hello, {name}" --tr-key name
hb prompt render demo.hello --args '{"name":"Ada"}' --lang zz
hb prompt tr-set demo.hello "Hello, {name}" zz "HEY, {name}"
hb prompt tr-list demo.hello --lang zz --json
hb prompt remove demo.hello
Function prompt creation is Python-only. The CLI create command creates template prompts.