Prompt

Language is not text, but a mapping from information to expression.

A prompt in HeavenBase is not a string you paste into an LLM call. It is a callable that turns arbitrary input into the text or messages the model actually sees. This page explains that encoder model, the Markdown helpers that format prompt text, the one-shot layout convention, and how hb.Prompt persists prompts as Capsule-backed workspace rows with first-class translation.

1. Why Prompt Utilities Exist

Without a prompt system, every LLM call site assembles its own prompt text from raw f-strings. The result is prompt drift: one endpoint formats instructions one way, another endpoint uses different phrasing, and there is no single source of truth for what the prompt should say.

# Anti-pattern: prompt text scattered as ad-hoc f-strings
system_prompt = f"You are a helpful assistant. Task: {task}. Use these tools: {tools}"
user_prompt = f"Context: {context}\n\nQuestion: {question}"

# Another file, different style:
instructions = "## Task\n" + task + "\n## Tools\n" + tools

This approach treats language as finished text. In practice, a prompt is an encoder: it maps structured information — task context, examples, the current instance — into an expression the model can act on. When prompts live as strings, they are hard to test, hard to version, and impossible to localize without duplicating entire templates. HeavenBase models a prompt as a function that returns rendered text or messages:

import heavenbase as hb

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

greet.register()
assert greet("Ada") == "Hello, Ada!"

The callable is the prompt. Arguments are the payload. The return value is what the LLM reads. That separation keeps logic in code, data in arguments, and the rendered surface stable enough to test and translate. A callable encoder is also more flexible than a format-string template. The function body can branch on payload shape, assemble instance-specific sections, call workspace helpers, or even invoke a meta-prompter LLM that drafts the system text from the actual inputs. String templates cover the simple fill-in-the-blanks case; function prompts cover everything else.

2. Prompt as an Encoder

Think of hb.Prompt as a named encoder — a callable you register, version, and reload. Format-string prompts are one encoding strategy; Python functions are another. Both compile into Capsule-backed callables and share one runtime path.

import heavenbase as hb

# Function encoder — arbitrary logic in the body
@hb.Prompt(name="demo.greet")
def greet(name: str, *, tr=str) -> str:
    return f"{tr('Hello')}, {name}!"

# Format-string encoder — same Capsule-backed callable underneath
welcome = hb.Prompt("Hello, {name}!", name="demo.welcome")

Prompt is a special case of Capsule. The prompt definition — source code or compiled format string — is captured as a manifest and can be stored as a sys-prompt workspace row. At call time, prompt + payload produces the serialized text the LLM sees:

payload = {"name": "Ada", "place": "Tokyo"}
text = welcome(**payload)  # "Hello, Ada!" — the model's input, not the stored encoder

That split gives you maximum flexibility. The encoder can assemble Markdown sections, pull workspace context, apply translations, branch on input shape, or chain other prompts — whatever the task needs — while the stored definition stays a versioned, loadable object. Because the underlay is Capsule, prompts are persistable, restorable, and auditable like any other HeavenBase entity.

Construction does not write to a workspace. Call prompt.register(...) explicitly, or pass register=True when you want decorator-time registration. Scope register and load with ws=... when prompts belong to a task workspace.

3. Markdown Helpers

Before you reach for hb.Prompt, you often need stable Markdown blocks: headings, lists, code fences, structured examples. HeavenBase keeps these in heavenbase.utils so generated prompt text stays deterministic across runs, reports, and tests.

from heavenbase.utils import (
    bullet_dict,
    bullet_list,
    code_block,
    example_block,
    file_block,
    json_block,
    md_block,
    md_section,
    numbered_list,
    omission_list,
)

content = md_section(
    title="Task",
    content="Inspect the workspace and report the next action.",
    sections=[
        {"title": "Rules", "content": bullet_list(["Read files first", "Use HeavenBase utilities"])},
        {"title": "Example", "content": code_block("result = hb.HeavenBase.load('demo')", lang="python")},
    ],
)

Helper	Use when
`md_section(...)`	Nested headings with optional body text
`md_block(...)` / `code_block(...)`	Fenced blocks with optional language tag
`bullet_list(...)` / `numbered_list(...)`	Plain or ordered lists
`bullet_dict(...)`	Key-value pairs as a bullet list
`json_block(...)` / `file_block(...)`	Structured or file-attributed payloads
`example_block(...)`	One few-shot example with inputs, output, hints, and notes
`omission_list(...)`	Long lists truncated with head/tail ellipsis

Use these helpers inside function prompts when you want full control over layout. They are composable building blocks, not tied to any single task shape.

4. One-Shot Prompt Layout

For the common case — a single-turn task with system context, a few examples, and a new instance to solve — HeavenBase provides fast_prompt_section(...). It is a convenience wrapper that turns a conventional section layout into OpenAI-style messages using the Markdown helpers above. The layout follows one principle: system + descriptions + examples + instructions + instance Each example carries inputs, hints, output, expected, and notes. The new instance reuses the same shape but marks its output as TODO, signaling the model what to produce.

import heavenbase as hb

messages = hb.fast_prompt_section(
    system="You are a concise worker.",
    descriptions={"Task": ["Read the files.", "Write the result."]},
    examples=[{"inputs": {"numbers": [1, 2]}, "output": 3, "hints": "Sum the list."}],
    instructions=["Use tools for filesystem access.", "Return one line."],
    instance={"inputs": {"numbers": [5, 8]}},
)

user_message = messages[-1]["content"]

This layout works well for one-shot tasks: classification, extraction, structured generation, and similar patterns where you show a few solved examples and hand the model a fresh input. It is less suited to multi-turn dialogue or open-ended agents that assemble context dynamically across turns — those flows are better served by a custom function prompt. Pass separate_system=True when the target LLM path should receive a dedicated system message instead of one user message containing all sections.

5. Function Prompts

Decorate a Python function when the encoder logic should stay in code and persist as a Capsule-backed callable. The function body is your encoder; call arguments are the payload.

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!"

Accept *, tr=str in the signature when the prompt contains user-facing phrases. HeavenBase injects a bound translation function at call time so localized text flows through the same encoder without forking the function.

5.1. Compose Encoders

Function prompts can call other prompts, layout helpers, and LLMs in one encoder. A toy meta-prompter pattern: a one-line format-string prompt drafts the system section; fast_prompt_section(...) assembles the one-shot body from examples and the new instance.

import heavenbase as hb

meta_system = hb.Prompt(
    "Write one concise system paragraph for this one-shot task: {task}",
    name="demo.meta_system",
)


@hb.Prompt(name="demo.adaptive_extraction")
def adaptive_extraction(task: str, examples: list, instance: dict, *, tr=str) -> str:
    system = meta_system(task=tr(task))
    messages = hb.fast_prompt_section(
        system=system,
        descriptions={"Task": [tr(f"Extract fields from: {task}")]},
        examples=examples,
        instructions=[tr("Match the example format exactly.")],
        instance=instance,
        tr=tr,
    )
    return messages[-1]["content"]


def adaptive_extraction_with_llm_meta(task: str, examples: list, instance: dict, *, tr=str) -> str:
    meta_llm = hb.LLM(preset="chat")
    system = meta_llm.chat(
        tr(f"Task={task}; instance={instance}"),
        system=tr("Write one system paragraph for the one-shot task in the user message."),
    )
    messages = hb.fast_prompt_section(
        system=system,
        descriptions={"Task": [tr(task)]},
        examples=examples,
        instance=instance,
        tr=tr,
    )
    return messages[-1]["content"]

The first variant keeps meta-generation inside HeavenBase prompts. The second delegates system drafting to another LLM while the outer encoder still owns the final layout. Both return the user message content that the downstream task LLM should see.

6. Format-String Prompts

Passing a string to hb.Prompt(...) creates the simplest encoder: a compiled format string with placeholder substitution. It uses the same Capsule-backed callable path as function prompts, but the body cannot run arbitrary logic. Use it for short, stable patterns; reach for a function prompt when the encoder needs branching, composition, or meta-generation.

import heavenbase as hb

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"

Use a short format string without tr_keys when only the full string needs translation:

import heavenbase as hb

welcome = hb.Prompt("Hello, {name}", name="demo.welcome")
text = welcome(name="Ada")

7. Load, List, and Version Prompts

Prompts are loaded by dotted name, compact version ref, or row id:

import heavenbase as hb

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. Register in a workspace when you want the prompt stored as a sys-prompt row:

import heavenbase as hb

ws = hb.HeavenBase("prompt-docs", preset="debug")
welcome = hb.Prompt("Hello, {name}", name="demo.welcome", ws=ws)
welcome.register(ws=ws)
loaded = hb.Prompt.load("demo.welcome", ws=ws)

Prompt rows can restore executable Capsule manifests. Load persisted prompts only from workspaces you trust.

8. Translation as a First-Class Concern

Localization should not require maintaining parallel prompt files. HeavenBase makes translation a first-class part of the prompt surface through the tr argument and prompt.tr. Every prompt call resolves 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. The bound tr function applies that language to source phrases inside the encoder:

import heavenbase as hb

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

Pass tr=... to fast_prompt_section(...) to translate section titles and list items the same way. Function prompts receive tr automatically when the signature declares it. Translation rows live as queryable sys-translation entities in the same workspace. Reach them through prompt.tr:

prompt.tr.bind("shared.agent-ui")
prompt.tr.set("Hello", "zz", "HEY", dict_name="shared.agent-ui")
prompt.tr.unbind("shared.agent-ui")

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.

import heavenbase as hb

ws = hb.HeavenBase("prompt-tr-docs", preset="debug")
prompt = hb.Prompt("Hello, {name}", name="demo.hello", ws=ws)
prompt.tr.set("Hello, {name}", "zz", "HEY, {name}")

assert prompt(name="Ada", lang="zz") == "HEY, Ada"

hb.CM_HVNB.set("heavenbase.prompt.lang", "zz", scope="heavenbase.demo-zz")

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

Translation is available from heavenbase.extensions.prompt for lower-level code, but the root import heavenbase as hb surface keeps translation under Prompt.tr.

9. Persist Agent Instructions

Combine fast_prompt_section(...) with hb.Prompt when agent instructions should persist with the task workspace. The function encoder wraps the one-shot layout; registration stores the callable as a versioned row.

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)

10. 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 format-string prompts.

Summary

Model prompts as encoders — callable functions that map input data to LLM-facing text, not as static strings.
hb.Prompt is a Capsule special case: prompt + payload produces the final serialized output, and the encoder itself is persistable.
Prefer function prompts when the encoder needs logic, composition, or meta-generation; use format-string prompts for simple substitution.
Use Markdown helpers for stable text blocks; use fast_prompt_section(...) for the standard one-shot layout when it fits.
Pass tr through encoders and fast_prompt_section(...) so localization stays in the same code path as rendering.

Further Exploration

Related resources:

Agents - how prompts fit agent memory and MCP tools.
Capsules - how function prompts are captured and restored.
LLM Overview - how prompts flow into hb.LLM.
Configuration - prompt language defaults under heavenbase.prompt.lang in CM_HVNB

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Why Prompt Utilities Exist

2. Prompt as an Encoder

3. Markdown Helpers

4. One-Shot Prompt Layout

5. Function Prompts

5.1. Compose Encoders

6. Format-String Prompts

7. Load, List, and Version Prompts

8. Translation as a First-Class Concern

9. Persist Agent Instructions

10. CLI

Summary

Further Exploration

​1. Why Prompt Utilities Exist

​2. Prompt as an Encoder

​3. Markdown Helpers

​4. One-Shot Prompt Layout

​5. Function Prompts

​5.1. Compose Encoders

​6. Format-String Prompts

​7. Load, List, and Version Prompts

​8. Translation as a First-Class Concern

​9. Persist Agent Instructions

​10. CLI

​Summary

​Further Exploration

1. Why Prompt Utilities Exist

2. Prompt as an Encoder

3. Markdown Helpers

4. One-Shot Prompt Layout

5. Function Prompts

5.1. Compose Encoders

6. Format-String Prompts

7. Load, List, and Version Prompts

8. Translation as a First-Class Concern

9. Persist Agent Instructions

10. CLI

Summary

Further Exploration