unaiverse.custom
What this module does 🟢
Defines the Custom base class for user-extensible agent components and the GenException error type used across the framework.
Global configuration constants and shared sentinel values for the UNaIVERSE framework.
Custom is a namespace-only class (never instantiated) that groups every
tunable constant, environment-variable override, state-machine wildcard, action
argument sentinel, and interaction limit used across the framework. Organising
them here in a single place makes it straightforward to adjust timing parameters
(e.g. SEND_DYNAMIC_PROFILE_EVERY), networking flags (e.g. ENV_USE_TLS),
or reserved argument names without hunting through multiple modules.
The class is divided into sections delimited by comments:
NODE CONFIGURATION- timing intervals governing background tasks such as keep-alive messages, stats persistence, and checkpoint saves.ENVIRONMENT VARIABLES- runtime overrides read from the process environment at import time. Each attribute documents its controlling variable name.STATE MACHINE- wildcard tokens used inside behaviour JSON files to address the world, the agent itself, or its current partner without hard-coding IDs.ACTIONS- sentinel argument-name sets (STREAM_ARG_NAMES,AGENT_ARG_NAMES, etc.) that the@actiondecorator and the HSM engine inspect to inject or strip special arguments before calling action bodies.INTERACTIONS- capacity limits and reserved identifiers for the interaction subsystem.
Attributes:
| Name | Type | Description |
|---|---|---|
SEND_DYNAMIC_PROFILE_EVERY |
Interval in seconds between successive dynamic profile broadcasts. |
|
GET_NEW_TOKEN_EVERY |
Interval in seconds between successive token renewals (set to 23 h 30 min to stay safely below the server-side 24 h limit). |
|
PUBLISH_RENDEZVOUS_EVERY |
Interval in seconds between rendezvous-point publications. |
|
INTERVIEW_TIMEOUT |
Maximum seconds to wait for an interview to complete before considering it timed out. |
|
CONNECT_WITHOUT_ACK_RETRY_TIMEOUT |
Seconds to wait before retrying a connection attempt that did not receive an acknowledgement. |
|
CONNECT_WITHOUT_ACK_TOTAL_TIMEOUT |
Total seconds before abandoning a connection attempt that never received an acknowledgement. |
|
SEND_ALIVE_EVERY |
Interval in seconds between keep-alive messages sent to peers. |
|
SAVE_STATS_EVERY |
Interval in seconds between successive stats persistence operations. |
|
SEND_STATS_EVERY |
Interval in seconds between successive stats transmissions
to the world. Note that the |
|
SAVE_CHECKPOINT_EVERY |
Interval in seconds between checkpoint saves. A
negative value disables checkpointing. Note that the |
|
SLOW_DOWN_CLOCK_AFTER |
Idle seconds (no network exchanges and no interactions) after which the event-loop clock switches to slow mode. |
|
SLOW_CLOCK_DELTA |
Clock delta in seconds used when the loop runs in slow mode. |
|
PRINT_LEVEL |
Verbosity level for console output, read from
|
|
LOG_TO_FILE |
Whether to write log output to a file, read from |
|
PRINT_SCREEN_BASIC_ONLY |
Whether to restrict screen output to basic
messages only, read from |
|
SKIP_WAS_ALIVE_CHECK |
Whether to bypass the alive-check guard on incoming
messages, read from |
|
LIBP2PLOG |
Whether to enable libp2p-level logging, read from
|
|
ENV_IS_ISOLATED |
Whether the node runs in isolated mode (no external
connections), read from |
|
ENV_IS_PUBLIC |
Whether the node advertises itself as publicly reachable,
read from |
|
ENV_IS_PUBLIC_RELAY |
Whether the node acts as a public relay, read from
|
|
ENV_USE_TLS |
Whether TLS is enabled for transport, read from
|
|
ENV_START_PORT |
Starting port number for listener sockets, read from
|
|
ENV_DOMAIN |
Public domain name for the node, read from |
|
ENV_CERT_PATH |
Path to the TLS certificate file, read from
|
|
ENV_KEY_PATH |
Path to the TLS private key file, read from
|
|
PATH_TO_APPEND_ADDRESSES |
File path to which the node appends its running
addresses, read from |
|
ROLE_WILDCARD |
Token used in behaviour JSON to match any role. |
|
WORLD_WILDCARD |
Token used in behaviour JSON to address the world. |
|
AGENT_WILDCARD |
Token used in behaviour JSON to address the agent itself. |
|
PARTNER_WILDCARD |
Token used in behaviour JSON to address the current partner. |
|
DEFAULT_WILDCARDS |
Mapping from each wildcard token to itself, used as the baseline substitution table before real IDs are filled in. |
|
ACTION_TICKS_PER_STATUS |
Three-element list of tick strings printed next to a logged action name to indicate success, in-progress, or failure. |
|
STREAM_ARG_NAMES |
Set of action-body parameter names that the framework treats as stream selectors. |
|
AGENT_ARG_NAMES |
Set of action-body parameter names that the framework treats as agent/partner selectors. |
|
SECONDS_ARG_NAMES |
Ordered list of parameter names that carry the maximum duration for a transition (first entry is the canonical name). |
|
TIMEOUT_ARG_NAMES |
Ordered list of parameter names that carry the retry timeout for a transition (first entry is the canonical name). |
|
DELAY_ARG_NAMES |
Ordered list of parameter names that carry the pre-action delay for a transition (first entry is the canonical name). |
|
TIME_TO_WAIT_BEFORE_ACTING_ARG_NAMES |
Ordered list of parameter names that carry the wait period before a state begins acting (state-level only). |
|
INTERACTION_INJECT_NAMES |
Parameter names for which the framework injects
the live |
|
INTERACTION_FIELD_NAMES |
Parameter names that are promoted from
|
|
HSM_TRANSIT_META_NAMES |
Parameter names consumed by the HSM transition
guessing logic and stripped before the action body is called. Forbidden
in body signatures and wire |
|
WIRE_SENTINEL_NAMES |
Framework-private container name used inside |
|
SPECIAL_ACTION_NAMES |
Names of built-in framework actions that receive
special dispatch treatment (currently only |
|
RESERVED_IN_BODY_SIGNATURE |
Union of name sets that must not appear in a regular action body signature. |
|
RESERVED_IN_ACTION_KWARGS |
Union of name sets that must not appear in wire
|
|
DEFAULT_TIMEOUT |
Default timeout in seconds for an action when none is specified. |
|
ALL_STATES_NAME |
Reserved state name that matches all states in transition tables. |
|
NOT_ALLOWED_STATE_NAMES |
Set of state names that user-defined states must not use. |
|
SYSTEM_INTERACTION_ID |
Short identifier for the implicit system interaction. |
|
SYSTEM_INTERACTION_LABEL |
Human-readable label for the system interaction. |
|
SYSTEM_INTERACTION_UUID |
Composite UUID for the system interaction, formed
as |
|
MAX_INTERACTIONS |
Maximum number of concurrent interactions allowed per agent. |
|
MAX_STREAM_DATA_WITHOUT_INTERACTIONS |
Maximum number of stream data items that may be buffered when no interaction is active. |
|
DEFAULT_INTER_TIMEOUT |
Default interaction timeout in seconds (5 minutes). |
|
DRAIN_TIMEOUT |
Timeout in seconds used when draining interaction queues (0 means non-blocking). |
|
FAKE_INTERACTION_UUID |
UUID string used as a placeholder for synthetic interactions that do not correspond to real network exchanges. |
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
DEFAULT_WILDCARDS = {WORLD_WILDCARD: WORLD_WILDCARD, AGENT_WILDCARD: AGENT_WILDCARD, PARTNER_WILDCARD: PARTNER_WILDCARD, ROLE_WILDCARD: ROLE_WILDCARD}
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
Role Names Semantics¶
INTERACTION_INJECT {'interaction'} Framework injects the Interaction object at call time.
Must be declarable in body sig (that's how injection
opts in). Forbidden in action.args and in wire
action_kwargs.
INTERACTION_FIELD {streams, num_steps, target, timeout, Promoted from Action.args to a field of the Interaction
copy_sys, forced_uuid, id, volatile, object by __build_system_interaction. Allowed in body
data_samples, callback} sig (then stays in action_kwargs).
Allowed in wire action_kwargs iff value equals the
matching Interaction field.
HSM_TRANSIT_META {max_duration, retry_timeout, delay} Per-transit scalars consumed by __guess_* then stripped
from Action.args. Forbidden in body sig and in wire
action_kwargs.
WIRE_SENTINEL {'action_kwargs'} Framework-private container name. Forbidden everywhere
except send's body sig.
REGULAR everything else Validated only against the body sig.
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
INTERACTION_FIELD_NAMES = {'streams', 'num_steps', 'target', 'timeout', 'copy_sys', 'forced_uuid', 'id', 'volatile', 'data_samples', 'callback'}
class-attribute
instance-attribute
¶
HSM_TRANSIT_META_NAMES = {SECONDS_ARG_NAMES[0], TIMEOUT_ARG_NAMES[0], DELAY_ARG_NAMES[0]}
class-attribute
instance-attribute
¶
RESERVED_IN_BODY_SIGNATURE = HSM_TRANSIT_META_NAMES | WIRE_SENTINEL_NAMES
class-attribute
instance-attribute
¶
RESERVED_IN_ACTION_KWARGS = HSM_TRANSIT_META_NAMES | WIRE_SENTINEL_NAMES | INTERACTION_INJECT_NAMES
class-attribute
instance-attribute
¶
NOT_ALLOWED_STATE_NAMES = {ALL_STATES_NAME}
class-attribute
instance-attribute
¶
SYSTEM_INTERACTION_UUID = SYSTEM_INTERACTION_ID + '_' + SYSTEM_INTERACTION_LABEL
class-attribute
instance-attribute
¶
Bases: Exception
Base exception class for the UNaIVERSE framework.
All framework-specific exceptions inherit from GenException so that callers
can catch the entire UNaIVERSE exception hierarchy with a single except
GenException clause while still being able to distinguish individual sub-types
when finer-grained handling is needed.
Because GenException does not override Exception's constructor or add
any attributes, it can be raised with any positional arguments accepted by the
built-in Exception:
raise GenException("Unexpected state reached.")