ahvn.utils.basic.config_utils module¶

ahvn.utils.basic.config_utils.dmerge(iterable, start=None)[source]¶

Merge multiple dictionaries into a single dictionary, with later dictionaries overwriting earlier ones. Nested dictionaries are merged recursively while all other non-dictionary values are overwritten.

Warning

The merging of dictionaries is not order-preserving. The order of keys in the resulting dictionary may not match the order of keys in the input dictionaries.

Parameters:

iterable (Iterable[Dict[str, Any]]) – An iterable of dictionaries to merge.
start (Optional[Dict[str, Any]]) – An optional starting dictionary to merge into.

Returns:

The merged dictionary.

Return type:

Dict[str, Any]

Examples

>>> d1 = {'a': 1, 'b': {'c': 2, 'f': 5}}
>>> d2 = {'b': {'d': 3, 'f': 0}, 'e': 4}
>>> dmerge([d1, d2])
{'a': 1, 'b': {'c': 2, 'f': 0, 'd': 3}, 'e': 4}
>>> dmerge([d2, d1])
{'b': {'d': 3, 'f': 5, 'c': 2}, 'e': 4, 'a': 1}
>>> dmerge([d1, d2], start={'a': 0, 'g': 6})
{'a': 1, 'g': 6, 'b': {'c': 2, 'f': 0, 'd': 3}, 'e': 4}

ahvn.utils.basic.config_utils.dget(d, key_path=None, default=None)[source]¶

Get a value from a dictionary using a dot-separated key path. If the key path does not exist, return the default value.

Parameters:

d (Dict[str, Any]) – The dictionary to search.
key_path (Optional[str]) – The dot-separated key path to the value.
default (Optional[Any]) – The default value to return if the key path does not exist.

Returns:

The value at the specified key path or the default value if not found.

Return type:

Any

Examples

>>> dget({'a': {'b': {'c': 42}}}, 'a.b.c')
42
>>> dget({'a': {'b': {'c': 42}}}, 'a.b.d', default='not found')
'not found'
>>> dget({'a': {'b': {'c': [1, 2, 3]}}}, 'a.b.c[1]')
2

ahvn.utils.basic.config_utils.dset(d, key_path, value=None)[source]¶

Set a value in a dictionary using a dot-separated key path. If the key path does not exist, it will be created.

Parameters:

d (Dict[str, Any]) – The dictionary to modify.
key_path (str) – The dot-separated key path to the value.
value (Optional[Any]) – The value to set at the specified key path.

Returns:

True if the value was set successfully, False if the key path is invalid.

Return type:

bool

Examples

>>> d = {}
>>> dset(d, 'a.b.c', 42)
True
>>> d
{'a': {'b': {'c': 42}}}

ahvn.utils.basic.config_utils.dunset(d, key_path)[source]¶

Unset a value in a dictionary using a dot-separated key path. If the key path does not exist, it will be ignored.

Parameters:

d (Dict[str, Any]) – The dictionary to modify.
key_path (str) – The dot-separated key path to the value to unset.

Returns:

True if the value was unset successfully, False if the key path is invalid.

Return type:

bool

Examples

>>> d = {'a': {'b': {'c': 42}}}
>>> dunset(d, 'a.b.c')
True
>>> d
{'a': {'b': {}}}

ahvn.utils.basic.config_utils.dsetdef(d, key_path, default=None)[source]¶

Set a default value in a dictionary using a dot-separated key path if the key path does not exist.

Notice that if key_path exists but its value is None, the default value will also be set.

Parameters:

d (Dict[str, Any]) – The dictionary to modify.
key_path (str) – The dot-separated key path to the value.
default (Optional[Any]) – The default value to set at the specified key path if it does not exist.

Returns:

True if the default value was set successfully, False if the key path is invalid or already exists.

Return type:

bool

Examples

>>> d = {}
>>> dsetdef(d, 'a.b.c', 42)
True
>>> d
{'a': {'b': {'c': 42}}}
>>> dsetdef(d, 'a.b.c', 100)
False
>>> d
{'a': {'b': {'c': 42}}}

ahvn.utils.basic.config_utils.dflat(d, prefix='', enum=False)[source]¶

Flatten a nested dictionary into a flat dictionary with dot-separated keys.

Parameters:

d (Dict[str, Any]) – The dictionary to flatten.
prefix (str) – The prefix to prepend to the keys. Defaults to an empty string.
enum (bool) – If True, apart from leaf nodes, also include intermediate nodes in the flattened output. Defaults to False.

Yields:

Generator[str, None, None] – A generator yielding key-value pairs in the flattened format.

Return type:

Generator[str, None, None]

Examples

>>> dict(dflat({'a': {'b': {'c': 42, 'd': [1, 2, 3]}}, 'e': 5}))
{'a.b.c': 42, 'a.b.d[0]': 1, 'a.b.d[1]': 2, 'a.b.d[2]': 3, 'e': 5}
>>> dict(dflat({'a': {'b': {'c': 42, 'd': [1, 2, 3]}}, 'e': 5}, enum=True))
{'a': {'b': {'c': 42, 'd': [1, 2, 3]}}, 'a.b': {'c': 42, 'd': [1, 2, 3]}, 'a.b.c': 42, 'a.b.d': [1, 2, 3], 'a.b.d[0]': 1, 'a.b.d[1]': 2, 'a.b.d[2]': 3, 'e': 5}

ahvn.utils.basic.config_utils.dunflat(d)[source]¶

Unflatten a flat dictionary with dot-separated keys into a nested dictionary.

Parameters:: d (Dict[str, Any]) – The flat dictionary to unflatten.
Returns:: The nested dictionary.
Return type:: Dict[str, Any]

Examples

>>> d = {'a.b.c': 42}
>>> dunflat(d)
{'a': {'b': {'c': 42}}}

class ahvn.utils.basic.config_utils.ConfigManager(name=None, package=None, cwd=None)[source]¶

Bases: object

Parameters:

name (str)
package (str)
cwd (str | None)

__init__(name=None, package=None, cwd=None)[source]¶

Parameters:

name (str | None)
package (str | None)
cwd (str | None)

name: str = 'ahvn'¶

package: str = 'ahvn'¶

set_cwd(cwd=None)[source]¶

Set the current working directory for the configuration manager.

Parameters:: cwd (str) – The new current working directory.

property local_dir: str¶

Get the local configuration directory.

Returns:: The path to the local configuration directory.
Return type:: str

property local_config_path: str¶

Get the path to the local configuration file.

Returns:: The path to the local configuration file.
Return type:: str

property global_config_path: str¶

Get the path to the global configuration file.

Returns:: The path to the global configuration file.
Return type:: str

property system_config_path: str¶

Get the path to the system configuration file.

Returns:: The path to the system configuration file.
Return type:: str

config_path(level=None)[source]¶

Get the path to the configuration file for a specific level.

Parameters:: level (Literal[None, 'local', 'global', 'system']) – The configuration level to get the path for. If None, returns the local configuration path.
Returns:: The path to the configuration file for the specified level.
Return type:: str

resource(*args)[source]¶

Get the path to a resource file in the package resources directory.

Parameters:: *args (List[str]) – The path components to the resource file.
Returns:: The absolute path to the resource file.
Return type:: str

property config: Dict[str, Any]¶

property system_config: Dict[str, Any]¶

property global_config: Dict[str, Any]¶

property local_config: Dict[str, Any]¶

load()[source]¶

save(level=None)[source]¶

Parameters:: level (Literal[None, 'local', 'global'])

init(reset=False)[source]¶

Initialize the local configuration manager by loading the default configuration and creating the necessary directories.

Parameters:: reset (bool) – If True, reset the local configuration to the default values.
Return type:: bool

setup(reset=False)[source]¶

Setup the global configuration manager by initializing it and loading the configuration and creating the necessary directories.

Parameters:: reset (bool) – If True, reset the global configuration to the default values.
Return type:: bool

get(key_path=None, default=None, level=None)[source]¶

Get a value from the configuration using a dot-separated key path.

Parameters:

key_path (str) – The dot-separated key path to the value.
default (Any) – The default value to return if the key path does not exist.
level (Literal[None,'local','global']) – The configuration level to use. If None, uses local configuration.

Returns:

The value at the specified key path or the default value if not found.

Return type:

Any

set(key_path, value=None, level=None)[source]¶

Set a value in the configuration using a dot-separated key path.

Parameters:

key_path (str) – The dot-separated key path to the value.
value (Any) – The value to set at the specified key path.
level (Literal['local','global']) – The configuration level to use. If None, uses local configuration.

Returns:

True if the value was set successfully, False if the key path is invalid.

Return type:

bool

unset(key_path, level=None)[source]¶

Unset a value in the configuration using a dot-separated key path.

Parameters:

key_path (str) – The dot-separated key path to the value to unset.
level (Literal['local','global']) – The configuration level to use. If None, uses local configuration.

Returns:

True if the value was unset successfully, False if the key path is invalid.

Return type:

bool

ahvn.utils.basic.config_utils.hpj(*args, abs=False, cm=None)[source]¶

Join a list of strings into a path. Platform-agnostic. Spaces and trailing slashes are stripped from each argument. The following characters will be expanded: - ‘~’ to the user’s home directory. - ‘&’ the resources directory of AgentHeaven. It is only recommended to use it at the beginning of the path. - ‘>’ the local root folder (without .ahvn/) of the current AgentHeaven repository. It is only recommended to use it at the beginning of the path.

Parameters:

*args (List[str]) – Components of the path to join. Each argument should be a string.
abs (bool, optional) – If True, returns the absolute path. Defaults to False.
cm (Optional[ConfigManager]) – The configuration manager to use for resource and local directory resolution. Defaults to HEAVEN_CM.

Returns:

The joined, normalized path. Expands ‘~’ to the user’s home directory.

Return type:

str

Examples

>>> hpj("A", "B/C", " D/ ")
'A/B/C/D'
>>> hpj("A", "B/C", " D/ ", abs=True)
'<path_to_cwd>/A/B/C'
>>> hpj("~", "A", "B/C", " D/ ", abs=True)
'<path_to_user_dir>/A/B/C'
>>> hpj("&", "B", "C")
'<path_to_ahvn>/resources/B/C'
>>> hpj("& B", "C")
'<path_to_ahvn>/resources/B/C'
>>> hpj("&/B", "C")
'<path_to_ahvn>/resources/B/C'
>>> hpj("& /B", "C") # Not recommended
'/B/C'
>>> hpj("> B/C", " D/ ")
'<path_to_repo>/B/C/D'

ahvn.utils.basic.config_utils.encrypt_config(config, encrypt_keys=None)[source]¶

Encrypt sensitive information in the LLM configuration dictionary.

Parameters:

config (Dict[str, Any]) – The LLM configuration dictionary to encrypt.
encrypt_keys (Optional[List[str]]) – List of keys to encrypt. If None, uses the keys specified in the global config under “core.encrypt_keys”.

Returns:

The encrypted LLM configuration dictionary.

Return type:

Dict[str, Any]