Skip to main content
“Give me six hours to chop down a tree and I will spend the first four sharpening the axe.” — Abraham Lincoln
Use this section when you want to configure HeavenBase or choose a helper before writing feature code. The pages are ordered by the workflow most readers hit first.

​
1. Choose a Utility

Configuration

Keep active defaults out of wrapper signatures, then override them by application scope.

File System

Normalize paths, resolve aliases, and read or write files with config-driven encoding defaults.

Hash

Bridge string IDs, deterministic hashes, and integer-like sortable identifiers.

Random

Generate data that stays reproducible by seed and stable under sampling changes.

Prompt

Turn structured context into prompt text, messages, templates, and stored prompt rows.

Miscs

Browse support helpers and development-time utilities: commands, parallel work, diagnostics, and migration bridges.

​
2. Core Idea

heavenbase.utils is not meant to become a giant public framework. It is a local toolbox for concerns that show up everywhere in HeavenBase: configuration, paths, serialization, deterministic IDs, deterministic data generation, prompt text, command execution, diagnostics, and a few migration bridges. The rule of thumb is simple:
  • Use the focused utility pages for app-facing helpers.
  • Use feature docs for feature surfaces such as workspaces, backends, query, LLM, capsules, and toolkits.
  • Treat system-only support modules as implementation details even if they are temporarily importable from heavenbase.utils.
Some current utility exports exist because HeavenBase is still finishing its migration away from legacy AgentHeaven utility modules. Internal helpers such as operation tokens, registry identity helpers, and some naming helpers are expected to move out of the general utility surface over time.

​
3. Import Pattern

Most demos can import from the top-level utility surface: 
from heavenbase.utils import StableRNG, dump_json, pj, touch_dir

root = touch_dir(pj("demos", ".temp", "trial"))
dump_json({"seed": StableRNG(seed=42).rnd_int()}, pj(root, "meta.json"))
When you are writing implementation code and want a clearer dependency boundary, import from the focused module: 
from heavenbase.utils.files import pj, touch_dir
from heavenbase.utils.serialize import load_json

​
Further Exploration

Related resources:
  • Configuration - scoped active defaults and overrides.
  • File System - paths, files, and serialization.
  • Miscs - support helpers and development-time utilities.