Repository navigation
Description
Motivation
The current event management provides string-based event IDs and allows handlers to be registered for individual events. For higher-level adaptive applications, event generation should become configurable in a generic and reusable way.
A concrete use case is an adaptive model such as CellStream, which may expose both low-frequency state transitions (for example, creation/removal of clusters or saturation) and high-frequency events (for example, a cluster being fed or drained). These events should be configurable independently from the generic adaptation mechanism.
In particular, an event may either be disabled, emitted as an event only, or emitted and additionally count as a model adaptation.
Since events may occur in hot paths and potentially at instance frequency, event handling must also be lightweight. Routine logging inside the event manager is therefore undesirable, and event-object creation / dispatch should avoid unnecessary overhead.
Proposed design
mlpro.bf.events
Introduce a generic event configuration layer:
EventModeOFF = 0ON = 1
EventConfig- generic base class for implementation-specific event configurations
- may define arbitrary event switches/parameters
EventManager- receives a generic
p_events: EventConfig - keeps the existing string-based event-ID / handler-registration mechanism
- receives a generic
The concrete EventConfig subclasses define which events an implementation exposes.
As a convention, the name of an event switch in an EventConfig subclass should be identical to the corresponding event ID. Example:
@dataclass
class MyEvents(EventConfig):
model_changed: EventMode = EventMode.OFFcorresponds to event ID:
"model_changed"This is deliberately a convention, not something enforced or inferred by MLPro. The concrete implementation is responsible for using matching event IDs.
mlpro.bf.ml
Introduce an ML-specific extension:
EventModeMLOFF = 0ON = 1ADAPTATION = 2
Semantics:
OFF: do not emit the eventON: emit the event onlyADAPTATION: emit the event and additionally report a model adaptation
This allows individual events to participate in the generic adaptation mechanism without forcing every state transition to trigger an adaptation event.
The existing adaptation/event flow should be reviewed accordingly, especially the interaction between model-specific events, adapt() / _adapted(), the generic adapted event, and downstream adapt_on_event() handlers.
Performance / event dispatch
Event dispatch is a fundamental hot-path operation. High-frequency events must not cause avoidable framework overhead.
The following principles apply:
EventManagershall not inherit fromLogmerely for event-dispatch logging.- Routine messages such as "event fired", "calling handler", or "no handlers registered" shall not be emitted.
- Classes that require logging shall inherit / compose logging explicitly instead of receiving it transitively through
EventManager. _raise_event()should use a minimal dispatch path: direct lookup of registered handlers, immediate return if no handler exists, and direct handler invocation.- Event-object creation should be tuned so that disabled or otherwise unused events do not cause unnecessary object creation or preparation work.
- Event processing must remain efficient enough for events that may occur once per processed instance.
Event object redesign
Refactor Event into a lightweight, extensible dataclass.
Proposed base model:
@dataclass(kw_only=True)
class Event:
p_raising_object: object
p_tstamp: datetime = field(default_factory=datetime.now)Design principles:
p_raising_objectidentifies the event source.p_tstampis optional and defaults to the creation time viadefault_factory=datetime.now.kw_only=Truekeeps inheritance extensible and avoids argument-order conflicts when subclasses introduce additional mandatory payload fields.- Specialized event classes shall extend
Eventwith explicit typed dataclass fields. - Arbitrary payload should not be modeled as a magic
**p_kwargsfield inside the dataclass. Where truly required, use an explicit mapping field such asp_kwargs: dict = field(default_factory=dict). - Event creation should stay cheap enough for hot-path usage.
Documentation
Because these classes form fundamental building blocks, both the generic event configuration and the ML-specific adaptation mode need clear documentation and examples.
Each concrete EventConfig subclass should document:
- the available event switches,
- the corresponding event IDs,
- the exact event semantics / trigger condition,
- the event payload,
- and the supported event modes.
Todos
- Refactor
Eventto@dataclass(kw_only=True)- Replace eager timestamp defaults with
field(default_factory=datetime.now) - Review existing event constructor calls for compatibility
- Review subclasses and migrate payload to explicit typed dataclass fields where practical
- Decide whether a generic payload mapping is still required for backward compatibility
- Add tests for default/custom timestamps, inheritance, and event payload handling
- Replace eager timestamp defaults with
- Remove logging dependency from
EventManagerand refactor affected MLPro classes accordingly - Tune
_raise_event()for minimal handler lookup and dispatch overhead - Introduce
EventModeinmlpro.bf.eventswithOFFandON - Introduce generic base class
EventConfiginmlpro.bf.events - Add
p_events: EventConfigtoEventManager - Define/document the convention
EventConfig attribute name == event ID - Ensure that this convention remains implementation responsibility and is not enforced by MLPro
- Introduce
EventModeMLinmlpro.bf.mlwithOFF,ON, andADAPTATION - Define the exact semantics of
EventModeML.ADAPTATION - Review the interaction between model-specific events and
adapt() / _adapted() - Review the generic
adaptedevent and downstreamadapt_on_event()handling - Ensure high-frequency model events can be emitted without necessarily triggering generic adaptation
- Add API documentation for
EventMode,EventConfig, andEventModeML - Add a minimal generic example for configurable event handling
- Add an ML example showing the difference between
ONandADAPTATION - Update relevant tests for event configuration, handler registration, adaptation behavior, and high-frequency dispatch
Activity
Redesign event management
Redesign event management
Redesign event management
Redesign event management
Redesign event management