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.

Common utilities are the small imports that many HeavenBase modules share: typing names, dataclasses, dict-path helpers, hashing, debug helpers, logs, proxy contexts, and color formatting.

​
1. Typing and dataclasses

HeavenBase exposes common typing and dataclass names from heavenbase.utils for package code, demos, and small extensions that benefit from a compact import surface. 
from heavenbase.utils import Any, Dict, List, Optional, dataclass, field

@dataclass
class Stage:
    name: str
    notes: List[str] = field(default_factory=list)
This is a convenience layer, not a replacement for Python’s type system. Public APIs should still use clear annotations that readers can understand without chasing aliases.

​
2. Dict paths

Use dget, dset, dunset, dsetdef, dmerge, dflat, and dunflat when you are working with nested config-like dictionaries. 
from heavenbase.utils import dget, dset

state = {}
dset(state, "metadata.step", 2)
assert dget(state, "metadata.step") == 2
These helpers are especially useful in config and agent state code where dotted paths are easier to scan than repeated nested dict.setdefault calls.

​
3. Hashing and debug output

Use md5hash and sha256hash for deterministic local identifiers and integrity checks. md5hash(...) returns a zero-padded decimal string so it can be used directly with string identifier fields. Use md5int(...) or sha256int(...) when numeric modulo or ordering logic needs an integer digest. 
from heavenbase.utils import capture_error, error_str, md5hash, md5int, raise_mismatch, safe_error, sha256int

row_key = md5hash(["bench-item", "p0001"])
bucket = md5int(row_key) % 16
wide_bucket = sha256int(row_key) % 1024

try:
    raise_mismatch(["json", "yaml"], "jsno", name="format")
except ValueError as exc:
    message = error_str(exc, tb=False)
    record = capture_error(exc)

message = safe_error(RuntimeError("Connection failed: password=secret-token"))
capture_error(...) returns an ErrorRecord that keeps the original exception object and formatted text. Call record.reraise() when a diagnostic path needs to preserve the original exception rather than flatten it to a string.

​
4. Identifiers, names, and operation tokens

Use identifier helpers before user-provided names cross a backend boundary. They validate public names and convert workspace/entity IDs into backend-safe table and index names. 
from heavenbase.utils import check_entity_id, entity_table_name, workspace_index_name

entity_id = check_entity_id("person-001")
table = entity_table_name(entity_id)
index = workspace_index_name("workspace-main")
Use class_name, field_name, kebab, snake, and clean_doc when generated names or documentation snippets need stable formatting. Use normalize_op, registered_ops, ops_for, and the OP_* constants when handler code needs to reason about query operation families.

​
5. Logging

Use get_logger for a colored HeavenBase logger. configure_logs(...) changes the global output behavior for all HeavenBase loggers that use this helper. 
from heavenbase.utils import configure_logs, get_logger, restore_logs, suppress_logs

logger = get_logger("heavenbase.demo")
logger.success("ready")

configure_logs(file="logs/heavenbase.log", level="INFO")
logger.warning("written to the configured log file")

suppress_logs()
logger.warning("suppressed")
restore_logs()
Use redirect_logs(path, loggers=[...]) to write selected loggers to a file, then call restore_logs(...) when the redirect should end. Passing a stream object to redirect_logs(...) routes all configured HeavenBase logger output to that stream.

​
6. Network proxy contexts

Use NetworkProxy when one operation needs temporary HTTP_PROXY, HTTPS_PROXY, or NO_PROXY environment variables. Existing values are restored when the context exits. Passing an empty string disables that proxy variable inside the context. 
from heavenbase.utils import NetworkProxy

with NetworkProxy(http_proxy="http://localhost:7890", no_proxy="localhost,127.0.0.1"):
    ...

​
7. Color output

Color helpers use ANSI codes and respect NO_COLOR. 
from heavenbase.utils import color_success, strip_color

text = color_success("ready")
plain = strip_color(text)
Use colors for terminal diagnostics only. Do not store colored strings in JSON, database rows, or benchmark artifacts.

​
Further Exploration

Related resources:
  • Configuration - where dict-path helpers are most common.
  • Function utilities - command execution, parallel helpers, and StableRNG.