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.

HeavenBase runtime defaults are read through the native CM_HVNB config manager: 
from heavenbase.utils import CM_HVNB

CM_HVNB.get("heavenbase.query.near.default_top_k", default=50)
CM_HVNB keeps config values scoped, persistent, and fast to read. The hot path uses immutable in-memory snapshots, so repeated get(...) calls do not run SQL or rebuild merged dictionaries on every access.
Import configuration APIs from heavenbase.utils when you need the shared runtime config manager or dict-path helpers.

​
Scopes

Configuration is resolved from broad scopes to narrow scopes. A scope such as heavenbase.workspace.demo reads layers in this order:
  1. heavenbase
  2. heavenbase.workspace
  3. heavenbase.workspace.demo
Use scoped(...) as a context manager or decorator: 
with CM_HVNB.scoped("workspace.demo"):
    metric = CM_HVNB.get("heavenbase.query.near.default_metric")

​
Snapshots

For high-volume read paths, keep a snapshot and reuse it: 
snap = CM_HVNB.snapshot()
top_k = snap.get("heavenbase.query.near.default_top_k")
metric = snap.get("heavenbase.query.near.default_metric")
A snapshot is immutable. Hot config edits do not mutate existing snapshots. The next snapshot refresh observes the latest generation according to the manager’s refresh policy.

​
Editing and maintenance

Config writes are persisted immediately. Use set(...), setdef(...), and unset(...) for ordinary edits: 
CM_HVNB.set("heavenbase.query.near.default_top_k", 25)
CM_HVNB.setdef("heavenbase.query.near.default_metric", "cosine")
CM_HVNB.unset("heavenbase.backends.vec")
List edits use path syntax:
  • items[0] replaces an item.
  • items[] appends.
  • items[2+] inserts before index 2.
unset(...) writes a tombstone so a child scope can hide a value inherited from its parent scope. Dicts can use __HB_OVERWRITE__ to replace a parent dict instead of recursively merging it. Use load() for a mutable merged dictionary and layer(scope, version=None) for the raw layer stored in one scope. history(...), version, version_chain, scopes(), compact(...), and remove(...) expose the retained store state for diagnostics and maintenance. save() is a no-op success method because writes are persisted immediately. resource(...) resolves files under the package resources/ directory when that package can be located. load_default() returns the in-memory default config template used to initialize scopes.

​
Persistence

Config layers are stored in a local SQLite database through a bootstrap store. By default, each scope keeps the latest 10 versions, so ordinary edits do not accumulate hundreds of historical rows. The bootstrap store exposes ConfigLayer and ConfigCompat as system entity projections for future CLI and workspace management views, but config boot does not require creating a normal HeavenBase workspace.

​
Interpolation

OmegaConf interpolation resolves when a snapshot is compiled:
  • ${env:VAR} is allowed by default.
  • ${oc.env:VAR,default} works through OmegaConf.
  • ${cmd:...} is disabled by default and requires an explicit policy override.