ahvn.utils.basic package

Basic utilities for AgentHeaven.

This subpackage groups helpers for logging, colors, paths, files, configs, serialization, hashing, templating, and small conveniences used across the project.

ahvn.utils.basic.lazy_getattr(name, export_map, package)[source]

Helper function to implement __getattr__ for lazy loading modules.

Parameters:

  • name (str) – The attribute name being accessed.

  • export_map (Dict[str, str]) – A dictionary mapping attribute names to relative module paths (e.g., { “MyClass”: “.my_module” }).

  • package (str) – The package name (usually __name__ of the calling module).

Returns:

The requested attribute from the imported module.

Raises:

AttributeError – If the name is not in the export_map.

ahvn.utils.basic.collect_exports(package_names, parent_package)[source]

Collects exported names from a list of subpackages to build a master lazy map.

Parameters:

  • package_names (List[str]) – List of relative package names (e.g., [“klstore”, “klengine”]).

  • parent_package (str) – The parent package name (usually __name__).

Returns:

“.klstore” }).

Return type:

A dictionary mapping exported names to their relative package path (e.g., { “DatabaseKLStore”

ahvn.utils.basic.deepcopy(x, memo=None, _nil=[])[source]

Deep copy operation on arbitrary Python objects.

See the module’s __doc__ string for more info.

ahvn.utils.basic.dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

ahvn.utils.basic.field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

class ahvn.utils.basic.ABC[source]

Bases: object

Helper class that provides a standard way to create an ABC using inheritance.

ahvn.utils.basic.abstractmethod(funcobj)[source]

A decorator indicating abstract methods.

Requires that the metaclass is ABCMeta or derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods are overridden. The abstract methods can be called using any of the normal ‘super’ call mechanisms. abstractmethod() may be used to declare abstract methods for properties and descriptors.

Usage:

class C(metaclass=ABCMeta):

@abstractmethod def my_abstract_method(self, arg1, arg2, argN):

…

class ahvn.utils.basic.defaultdict

Bases: dict

defaultdict(default_factory=None, /, […]) –> dict with default factory

The default factory is called without arguments to produce a new value when a key is not present, in __getitem__ only. A defaultdict compares equal to a dict with the same items. All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.

__init__(*args, **kwargs)
copy() → a shallow copy of D.
default_factory

Factory for default value called by __missing__().

class ahvn.utils.basic.Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

  • Any is compatible with every type.

  • Any assumed to have all methods.

  • All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

Submodules