basic use

Basic use

This software is for building, running, and managing software agent. It does not define the models, it uses a model and its layouts to build an agent. That instance can then be run, stopped, and later run again, and will learn as it goes. There is no explicit training mode or inference mode, there is only an up mode where the instance is either single stepping, running between break points, or running continuously.

For a more complete listing of arguments, use hera --help or hera <subcommand> --help.

build – Building an instance

An instance is built from family definitions of a model and a layout, using those to create a local JSON-file, which will then be a quite large. Definition of that file, and thus the instance, can be adjusted through statements in a .herarc file in the users home directory or a hera.json file in the actual work directory. Most of the file consists of initial weights set to zero. Those will slowly adapt during use, contrary to usual artificial neural networks that does not adapt during normal use.

Wiring of an instance is usually quite difficult to change after it is defined. It might be possible to grow some parts of the instance, but to shrink specific parts can be very difficult and often require retraining of those parts. Refer to the documentation of actual models for what they support of growing and shrinking.

Each model should have an example layout, that should be pretty light on the General-purpose computing on graphics processing units (GPGPU), and it should be sufficient for test purposes, although it would not be sufficient for any real work.

Usually, it should be enough to pip-install the repo for a family, or git-clone to the working directory, and then use that to build an instance. Something like

hera --family <family> --layout <layout> build

where hera is the command and build is the subcommand for the actual action. The arguments <family> and <layout> should be replaced with the actual names, for example abraxas and example.

hera --family abraxas --layout example build

This should build a JSON-file in the current working directory, but it will not run the newly created instance. Unless it is given an explicit file name, it will have the identifier as the file name. A newly built instance will be missing parts of the dynamic state. It is not only comatosed, it is dead, as it lacks the dynamic state. Typically, most or all weights will also be set to zero as it lacks proper training.

up – Running an instance

An agent is upped when it is run. The state is loaded into the device, and iterations started. When a newly created instance is upped, it will be copied to a local cache the first time it is stopped or otherwise ordered to make a copy of itself. The copy will be a complete running state, and on next up the iterations will be resumed. Because the agent is continuously evolving when it is running, there is no finite version of the agent. The weights may represent some kind of semistatic state, but the travelling spikes will represent a highly dynamic state. It is possible to copy the file stored in the local cache, but that will only be a copy at a specific time, and on the next up the copy and the original will start to diverge.

It is important to note that a local instance as a JSON-file may be upped, but when it is stopped the agent is represented by the JSON-file in the cache directory. The local JSON-file in the working directory does not evolve, the version in the cache does. The version in the cache directory will also have a dynamic state, which makes it possible to restart it and continue from the previous dynamic state.

An upped agent can be run in normal mode, in --interactive mode, or in --daemon mode. In normal mode some initial output will be made, but otherwise no interactions will be provided. If --silent mode is invoked it should be fairly safe to put the agent in the background. In --interactive mode a prompt for interaction is provided. This can be set to start at once, or the prompt may arrive after some number of iterations. The interactive prompt may be closed, and normal mode will be resumed. If a signal is sent to the agent, possible by the keyboard to an agent running in the terminal, the interactive mode will be resumed. The whole python host interface is available from the prompt, but access to the CUDA device might be limited.

In daemon mode the agent detaches from the terminal, and all communications must go through assigned ports.

Either an instance is upped by providing the filename, which also implicitly install the agent for the current user

hera up <filename>

or an agent is upped by a full or partial UUID if it is previously installed, or on first up

hera --uuid <full-or-partial-uuid> up

To both use an identifier (or a callsign) and a filename is an error.

When the agents resource requirements canʼt be satisfied, it will dump an error report. Usually that happen because the device has some hard limits and the agents resource requirements goes beyond those. This should happen before the inner loop is started. To check if the device has sufficient resources, use the --simulate argument. The agent will then do all the calculations, but not load code and data into the device.

The inner loop for an upped (and thus running) agent can be stopped from the keyboard of a controlling terminal. Typically, this is done by sending a SIGTSTP signal, usually bound to [ctrl]+[z]. The agent will then go into debug mode. An agent that is in the background must be brouht into the foreground before the inner loop can be stopped. If the agent is completely detached from a terminal it can be reattached by the signal subcommand.

down – Stopping an instance

A downed (stopped) agent does not run, it is comatosed. The state is maintained in the JSON-file in the cache, but it is not any longer maintained at the device. When an upped agent is downed (stopped), the present state in the device is offloaded into the JSON-file. The present state is a complete representation of the active state, thus the agent can be restarted at a later moment.

If only a single agent is running, then it is not necessary to provide any identifier

hera down <filename>

or when there are several agents, then a full or partial UUID must be provided

hera --uuid <full-or-partial-uuid> down

Note, the state is preserved by the JSON-file in the cache directory, not by the local file in the working directory. The local JSON-file in the working directory does not evolve, the version in the cache does.

All running agents have a pid-file with the same name as the identifier, and storing the process id. This is used for communicating with the agent.

destroy – Destroying an instance

An agent is destroyed when it is not needed anymore. When an agent is destroyed the managing software tries to verify that it does not run anymore, that is it has no pid-file, and if it can proceed it will uninstall the agent, that is remove the JSON-file from the cache.

When there are several agents, then a full or partial UUID must be provided

hera --uuid <full-or-partial-uuid> destroy

The safe way to stop the instance would be to issue a down to the instance before it is destroyed, or to use the keyboard to signal a kill. In some weird cases a pid-file might be removed before an agent is stopped, but in those cases the running process can be terminated with a normal kill command.

This is an action that can not be undone, as there is no other copy of the running instance outside the cache. Even if the instance is retrained with the same data, it might not converge to the same state. Added noise might give another state, and even round off errors might be sufficient to give variations. Some models might even add noise to counteract specific outcomes.

install – Installing an instance

This will install the named JSON-file to the cache directory with some additional initialization of the agent, but will not up (start) the agent. It is the only proper way to install a system agent, or an agent for another user.

An agent is installed by providing the filename

hera install <filename>

After installing an agent, it can be identified either through --identifier or in some cases by --callsign if it is unique in the context. Identifiers of UUID type should be close to unique, while a callsign could have collisions. An identifier could be partial as long as it uniquely identifies an agent in the given context. The partial identifier is the initial part of the UUID on a recognizable encoding.

uninstall – Uninstalling an instance

This will uninstall the JSON-file for the identified agent from the cache directory with some additional cleanup, and maintain a copy in the current working directory. The agent must already be stopped. It is the only proper way to uninstall a system agent, or an agent for another user.

An agent is uninstalled by providing the identifier

hera --uuid <full-or-partial-uuid> uninstall

Parts of a brain can be extended after the initial configuration. Those parts are typically widths, heights, and depths, and in some cases dendrite and axon lengths, if those can be extended without conflicting offsets or the offsets can be recalculated.

hera --uuid <full-or-partial-uuid> grow

It is in general not possible to safely shrink a brain after initial configuration, without extensive retraining.

signal – Signaling an instance

This will send signals to the identified agent. The signaling is pretty crude, but should be sufficient for basic operations. In particular, it should be sufficient as a basic kill switch and to acquire a terminal for closer control.

An agent is signalled by providing the identifier

hera --uuid <full-or-partial-uuid> signal <named-signal>

The signals used for communicating with the agent are

• SIGCONT – Continue inner loop if stopped, and detach from terminal
• SIGSTOP – Stop inner loop if running, and attach to terminal if in background
• SIGTSTP – Stop inner loop if terminal attached ([ctrl]+[Z])
• SIGHUP – Hangup detected on controlling terminal, detach from terminal
• SIGINT – Go into standby mode ([ctrl]+[C])
• SIGQUIT – Terminate, update cache (i.e. do cleanup), and continue with a core dump
• SIGABRT – Terminate, but don't update cache (i.e. no cleanup), and continue with a core dump
• SIGKILL – Terminate, but don't update cache (i.e. no cleanup)
• SIGTERM – Normal terminate, and update cache (i.e. do cleanup)
• SIGTTIN – Terminal input to background agent, content will be piped line-wise on stdin after a single signal
• SIGTTOU – Terminal output from background process, content will be piped line-wise on stdout after a single signal

The signals SIGTTIN and SIGTTOU pipes in and out from an assigned area in the agents instantiated brain, but through the controlling interface, giving an opportunity for the manager to enforce certain actions.

agents – List installed agents

List installed agents for this user, a named user, or --all available agents.

hera agents
hera agents --user <username>
hera agents --all

This will not list agents residing in individual users own work directories.

devices – List available devices

List all available devices on the host, without regard to whether the devices are usable.

hera agents

There are some limited filtering possibilities.

layouts – List available layouts

List all available layouts for a given device.

hera layouts --device <identifier>

There are some limited filtering possibilities.

families – List installed families

List installed families.

Not sure this is possible

hera families