> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> A guided map to the HeavenBase Utilities Toolbox.

<Note>
  *"Give me six hours to chop down a tree and I will spend the first four sharpening the axe." — Abraham Lincoln*
</Note>

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.

<br />

## 1. Choose a Utility

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/features/configuration">
    Keep active defaults out of wrapper signatures, then override them by application scope.
  </Card>

  <Card title="File System" icon="folder-open" href="/features/utilities/file-system">
    Normalize paths, resolve aliases, and read or write files with config-driven encoding defaults.
  </Card>

  <Card title="Hash" icon="fingerprint" href="/features/utilities/hash">
    Bridge string IDs, deterministic hashes, and integer-like sortable identifiers.
  </Card>

  <Card title="Random" icon="dice" href="/features/utilities/random">
    Generate data that stays reproducible by seed and stable under sampling changes.
  </Card>

  <Card title="Prompt" icon="message" href="/features/utilities/prompt">
    Turn structured context into prompt text, messages, templates, and stored prompt rows.
  </Card>

  <Card title="Miscs" icon="toolbox" href="/features/utilities/miscs">
    Browse support helpers and development-time utilities: commands, parallel work, diagnostics, and migration bridges.
  </Card>
</CardGroup>

<br />

## 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`.

<Info>
  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.
</Info>

<br />

## 3. Import Pattern

Most demos can import from the top-level utility surface:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils.files import pj, touch_dir
from heavenbase.utils.serialize import load_json
```

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Configuration](/features/configuration) - scoped active defaults and overrides.
  * [File System](/features/utilities/file-system) - paths, files, and serialization.
  * [Miscs](/features/utilities/miscs) - support helpers and development-time utilities.
</Tip>

<br />