Event hooks¶
consortium.framework.event_hooks
¶
The event hooks framework provides the building blocks for reacting to framework events.
An event hook is implemented by subclassing
BaseEventHook and declaring the
EventType values it subscribes to. When
one of those events fires anywhere in the framework (server lifecycle changes, listener
and agent generator state changes, agent activity, user sessions, or resource CRUD
operations), the hook's handler is invoked with the event so it can run custom logic.
BaseEventHook()
¶
Bases: ComponentMetadata
Base class for implementing custom event hooks in the Consortium framework.
Event hooks allow components to react to specific framework events by executing user-defined logic. All custom event hooks must inherit from this class and implement the required event hook methods.
Attributes:
| Name | Type | Description |
|---|---|---|
event_hook_id |
UUID
|
Unique framework-wide identifier for this event hook instance, generated as a UUID4. |
name |
str | None
|
Human-readable name for identifying this event hook. |
description |
str
|
Brief description of the event hook's purpose and functionality. |
authors |
set[str] | None
|
Set of authors associated with this event hook. |
version |
str | None
|
Version of the event hook, specified using a valid PEP 440 version string. |
compatible_framework_version |
str | None
|
Framework version specifier defining which versions of Consortium this event hook is compatible with. |
event_types |
set[EventType] | None
|
Set of event types declared in the hook's class body, subscribed
to when the hook is loaded. This is the declaration only: read
|
subscribed_event_types |
frozenset[EventType]
|
Read-only, live view of the event types the events
service currently holds a registration for on this hook, reflecting any
change made at runtime through |
component_dependencies |
set[str] | None
|
Version-pinned dependencies on other framework components, defined using PEP 440 specifiers. |
third_party_dependencies |
set[str] | None
|
Third-party library dependencies required for this event hook to function. |
root_directory |
set[str] | None
|
Filesystem path to the project directory containing this event hook's source code. |
environment |
SimpleNamespace
|
Namespace for storing hook-specific state shared across event invocations without naming conflicts. |
services |
SimpleNamespace
|
Namespace providing programmatic access to server-level framework services. |
logger |
Event-hook-specific logger instance, automatically tagged with the hook's name and ID for traceability in logs. |
|
event_logger |
EventLogger
|
Event-hook-specific event logger used to record structured, client-facing events (successes, failures, informational messages). Entries are optionally mirrored to the hook's system logger. |
event_types = None
class-attribute
instance-attribute
¶
event_hook_id = uuid.uuid4()
instance-attribute
¶
logger = logger.bind(logger_name=f'Event Hook - {self}')
instance-attribute
¶
event_logger = EventLogger(event_log=(EventLog(subject_id=(self.event_hook_id))), system_logger=(self.logger))
instance-attribute
¶
environment = types.SimpleNamespace()
instance-attribute
¶
subscribed_event_types
property
¶
The event types this hook is currently subscribed to.
This is the live registration state held by the events service, not the
declaration: it is empty for a hook that is not currently loaded, and reflects
every subscribe_to_event_type and unsubscribe_from_event_type call made
while the hook is loaded.
Returns:
| Type | Description |
|---|---|
frozenset[EventType]
|
A read-only view of the currently subscribed event types. |
on_setup()
async
¶
Called once when the event hook is initialized.
Override to perform any setup or resource allocation required before the hook begins handling events.
on_triggered(event)
async
¶
Called whenever one of the subscribed event types fires.
Override to implement custom logic for processing the event and performing any related actions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
Event
|
The event object carrying details about what occurred, including the event type and any associated payload data. |
required |
on_teardown()
async
¶
Called when the event hook is being shut down.
Override to release resources or perform cleanup operations before the hook stops receiving events.
subscribe_to_event_type(event_type)
¶
Subscribes the hook to an additional event type.
The event type appears in subscribed_event_types immediately and the hook
starts receiving it as soon as it is running. Safe to call at any point in the
hook's lifecycle, including from on_setup and from on_triggered. Subscribing
to an event type the hook already handles is a no-op.
This is the only supported way to change subscriptions.
subscribed_event_types is read-only, since a set that dispatch does not read
back would silently disagree with what the hook actually receives.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type
|
EventType
|
The event type to start receiving. |
required |
Raises:
| Type | Description |
|---|---|
InvalidEventTypeError
|
If the provided event type does not correspond to a
valid |
unsubscribe_from_event_type(event_type)
¶
Unsubscribes the hook from an event type.
The event type is removed from subscribed_event_types and the hook stops
receiving it immediately. Safe to call at any point in the hook's lifecycle.
Unsubscribing from an event type the hook does not handle is a no-op.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type
|
EventType
|
The event type to stop receiving. |
required |
to_json(limit=10, offset=None)
¶
Serialize the event hook's metadata to a JSON-compatible dictionary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit
|
int
|
Maximum number of event log entries to include. |
10
|
offset
|
int | None
|
Sequence offset to start the event log window from. If None, the tail (most recent entries up to limit) is returned. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, JsonValue]
|
A dictionary containing the event hook ID, label, name, description, |
dict[str, JsonValue]
|
authors, version, framework compatibility, component dependencies, declared |
dict[str, JsonValue]
|
event types, live subscribed event types, third-party dependencies, and |
dict[str, JsonValue]
|
event log. |
EventType
¶
Bases: StrEnum
Framework-wide event identifiers used to subscribe event hooks to specific occurrences.
Use these values in BaseEventHook.event_types to declare which events the hook should be triggered by. Events cover server lifecycle, listener and agent generator state changes, agent activity, user sessions, and resource (payload, asset, artifact) CRUD operations.
Attributes:
| Name | Type | Description |
|---|---|---|
START_SERVER |
The server is starting. |
|
STOP_SERVER |
The server is stopping. |
|
LISTENER_CREATED |
A listener instance is created. |
|
LISTENER_ADDED |
A listener is added to the server. |
|
LISTENER_UPDATED |
A listener's configuration is updated. |
|
LISTENER_REMOVED |
A listener is removed from the server. |
|
LISTENER_STARTED |
A listener starts. |
|
LISTENER_STOPPED |
A listener stops. |
|
LISTENER_CANCELLED |
A listener is cancelled. |
|
AGENT_GENERATOR_CREATED |
An agent generator instance is created. |
|
AGENT_GENERATOR_ADDED |
An agent generator is added to the server. |
|
AGENT_GENERATOR_UPDATED |
An agent generator's configuration is updated. |
|
AGENT_GENERATOR_REMOVED |
An agent generator is removed from the server. |
|
AGENT_GENERATOR_STARTED |
An agent generator starts. |
|
AGENT_GENERATOR_STOPPED |
An agent generator stops. |
|
AGENT_GENERATOR_CANCELLED |
An agent generator is cancelled. |
|
AGENT_REGISTERED |
An agent registers with the server. |
|
AGENT_CHECKED_IN |
An agent checks in with the server. |
|
AGENT_UPDATED |
An agent's metadata is updated. |
|
AGENT_DEREGISTERED |
An agent deregisters from the server. |
|
AGENT_DELETED |
An agent is deleted. |
|
AGENT_TASKED |
A task is assigned to an agent. |
|
AGENT_TASK_COMPLETED |
An agent completes a task. |
|
TASK_DELETED |
A retained task record is deleted. |
|
USER_LOGGED_IN |
A user signs in. |
|
USER_LOGGED_OUT |
A user signs out. |
|
PAYLOAD_CREATED |
A payload is created. |
|
PAYLOAD_UPDATED |
A payload is updated. |
|
PAYLOAD_DELETED |
A payload is deleted. |
|
ASSET_CREATED |
An asset is created. |
|
ASSET_UPDATED |
An asset is updated. |
|
ASSET_DELETED |
An asset is deleted. |
|
ARTIFACT_CREATED |
An artifact is created. |
|
ARTIFACT_UPDATED |
An artifact is updated. |
|
ARTIFACT_DELETED |
An artifact is deleted. |
|
LISTENER_RUNTIME_ERRORED |
A listener runtime error occurs. |
|
AGENT_GENERATOR_RUNTIME_ERRORED |
An agent-generator runtime error occurs. |