Skip to main content
Hash utilities are a compatibility compromise: they let HeavenBase use normal string IDs while keeping some hashes integer-like and sortable when an index benefits from that shape.
Use these helpers when two processes should derive the same ID, bucket, or fingerprint from the same logical value.

​
1. Core Idea

HeavenBase often needs identifiers that behave like strings because they move through JSON, database rows, object IDs, and filenames. It also sometimes benefits from values that can be interpreted as integers for ordering, bucket assignment, or index-friendly storage. md5hash(...) currently returns a zero-padded decimal string. That means it can live as a normal string ID, but same-length values also sort like their integer representation.
This is not settled as a universal design. The integer-able string hash is a practical compatibility move for the current pre-release, not a claim that every external API should depend on this exact representation.

​
2. Create a Stable ID

md5hash(...) serializes common Python values with stable JSON ordering and returns a zero-padded decimal string. The default length is 42, which matches HeavenBase’s identifier-friendly hash width. 
from heavenbase.utils import md5hash

row_id = md5hash({"source": "docs", "name": "Ada"})
same_id = md5hash({"name": "Ada", "source": "docs"})

assert row_id == same_id
Use hash_id(...) when an ID should carry a logical namespace: 
from heavenbase.utils import hash_id

prompt_id = hash_id("prompt", "demo.greet", "1")

​
3. Bucket or Order Values

Use integer digests when modulo arithmetic, deterministic sampling, or ordering needs a number. 
from heavenbase.utils import md5int, sha256int

bucket = md5int("workspace-alpha") % 16
wide_bucket = sha256int({"workspace": "alpha", "entity": "person"}) % 1024
md5int(...) is shorter and fast enough for local utility IDs. sha256int(...) is useful when a wider digest makes the intent clearer.

​
4. Fingerprint Larger Payloads

Use sha256hash(...) for hex fingerprints in manifests, config snapshots, and integrity checks. 
from heavenbase.utils import fmt_short_hash, sha256hash

fingerprint = sha256hash({"model": "ds-flash", "temperature": 0})
display = fmt_short_hash(fingerprint, length=10)
These helpers are deterministic utility hashes, not authentication or password-storage primitives.

​
Further Exploration

Related resources:
  • Random - deterministic seed evolution and hash-based sampling.
  • File System - serialization helpers used before hashing structured data.
  • Catalog - object IDs and discoverable names.