Revised error codes and functional PlaybackEngine
All internal and public errors have been revised (GPT 5.6 Sol) to return more detail without horrendously long error classes, this has reduced the number of error types but each now carries a reason and a code for differentiation if needed PlaybackEngine has been implemented and is functional, core mode changes what signal descriptors are returned to avoid duplicates, the playback engine currently discards the derived signals that would be recorded in the DLPak and derived signals are reprocessed live Future will require the behavior listed above to be selectable so one of two options are possible: A - Derived signals are reprocessed live by the relevant derive units (current behavior B - Derived signals are played back directly from the PlaybackEngine, this requires turning off the routing to the live derive units to avoid duplicate values This will also require the option to perform offline processing with derive units to be able to create derived signals after the fact, this will likely incur a new 'offline' mode in the core to gate things correctly, this will likely be useful for heavier processing that cannot be done live, filters that require a lookahead, or more precise derived signals using interpolated signals for higher acurracy which also brings the ability to offline process on a fixed timebase instead of following either input signal to the derived signal
This commit is contained in:
+184
-30
@@ -1,9 +1,9 @@
|
||||
# DynaLab Core API
|
||||
|
||||
`Core` is the Python interface for running a DynaLab Core instance, inspecting
|
||||
connected signals and their current values, recording incoming data, and
|
||||
creating derived signals. Connectors provide data to a running core using the
|
||||
[DynaLab protocol](Protocol.md).
|
||||
signals and their current values, recording incoming data, playing recordings,
|
||||
and creating derived signals. Connectors provide realtime data to a running
|
||||
core using the [DynaLab protocol](Protocol.md).
|
||||
|
||||
> [!WARNING]
|
||||
> DynaLab Core is in alpha. Its public API may change between releases.
|
||||
@@ -63,8 +63,9 @@ Starts the configured server and begins accepting connector connections. This
|
||||
method returns after the server start sequence completes.
|
||||
|
||||
Call `start()` once per `Core` instance. Calling it in any state other than the
|
||||
initial state raises `CoreStateMismatchError`. Server startup failures, such as
|
||||
an address already in use, are propagated by the underlying server.
|
||||
initial state raises `CoreError` with code `"invalid_state"`. Server startup
|
||||
failures, such as an address already in use, raise `JsonServerError` while
|
||||
retaining the underlying exception as their cause.
|
||||
|
||||
### `wait(timeout: float | None = None) -> None`
|
||||
|
||||
@@ -72,15 +73,51 @@ Blocks until `stop()` is called or until `timeout` seconds have elapsed. Omit
|
||||
`timeout` to wait indefinitely. This is useful for keeping a command-line
|
||||
application alive without a busy loop.
|
||||
|
||||
### `stop() -> None`
|
||||
### `stop() -> bool`
|
||||
|
||||
Stops the server, disconnects connectors, signals the input worker to stop, and
|
||||
stops all bound derive units. It also releases any call currently blocked in
|
||||
`wait()`.
|
||||
stops the playback engine and all bound derive units. It also releases any call
|
||||
currently blocked in `wait()`.
|
||||
|
||||
Returns `True` when the server, connector registry, derive registry, and input
|
||||
worker stop within their allowed timeouts, or `False` when shutdown is
|
||||
incomplete.
|
||||
|
||||
Call this during application shutdown, including when startup or runtime work
|
||||
raises an exception. A stopped core cannot be started again.
|
||||
|
||||
## Modes
|
||||
|
||||
Core operates in one of two modes:
|
||||
|
||||
| Mode | Signal source | Available operation |
|
||||
| --- | --- | --- |
|
||||
| `"realtime"` | Connected connectors | Recording |
|
||||
| `"playback"` | A loaded recording | Playback |
|
||||
|
||||
The initial mode is `"realtime"`. Connected endpoints remain connected in
|
||||
playback mode, but their incoming values are not routed into Core.
|
||||
|
||||
`CoreMode` is defined in `dynalab_core.types` as the literal union of these two
|
||||
strings.
|
||||
|
||||
### `set_mode(mode: CoreMode) -> None`
|
||||
|
||||
Changes the active mode and clears all cached live values. `mode` must be
|
||||
`"realtime"` or `"playback"`; any other value raises `CoreError` with code
|
||||
`"invalid_mode"`.
|
||||
|
||||
The mode cannot be changed while a recording is active. Attempting to do so
|
||||
raises `CoreError` with code `"recording_active"`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Changing mode does not automatically pause active playback. Call `pause()`
|
||||
> before switching from playback to realtime mode.
|
||||
|
||||
### `get_mode() -> CoreMode`
|
||||
|
||||
Returns the active mode as either `"realtime"` or `"playback"`.
|
||||
|
||||
## Signals
|
||||
|
||||
Signals are registered by connectors during their protocol handshake. A signal
|
||||
@@ -117,17 +154,20 @@ signal = SignalDescriptor(
|
||||
### `get_signal_descriptor(signal_id: UUID) -> SignalDescriptor | None`
|
||||
|
||||
Returns the descriptor for `signal_id`, including a derived-signal output, or
|
||||
`None` when no matching signal is registered. Use a UUID, not its string
|
||||
representation.
|
||||
`None` when no matching signal is available. In realtime mode, source
|
||||
descriptors come from connected connectors. In playback mode, they come from
|
||||
the loaded recording. Use a UUID, not its string representation.
|
||||
|
||||
### `get_all_signal_descriptors() -> list[SignalDescriptor]`
|
||||
|
||||
Returns descriptors for every signal currently registered by connected
|
||||
connectors and bound derive units. The list is empty when no connectors have
|
||||
completed a handshake and no derive units are bound.
|
||||
Returns the source descriptors available in the current mode followed by the
|
||||
descriptors from bound derive units. In realtime mode, source descriptors come
|
||||
from connected connectors. In playback mode, they come from the loaded
|
||||
recording; previously recorded derived descriptors are omitted because bound
|
||||
derive units recalculate those values.
|
||||
|
||||
Connector membership is dynamic: a disconnected connector's signals are no
|
||||
longer returned.
|
||||
longer returned in realtime mode.
|
||||
|
||||
## Live Values
|
||||
|
||||
@@ -160,12 +200,15 @@ Incoming data timestamps use the monotonic-nanosecond timebase. See
|
||||
|
||||
## Recording
|
||||
|
||||
Recording captures incoming connector values in an in-memory buffer.
|
||||
Recording captures incoming connector and derived values in an in-memory
|
||||
buffer. Recording is only available in realtime mode.
|
||||
|
||||
### `start_recording() -> None`
|
||||
|
||||
Clears the current recording buffer, records a new UTC start timestamp, and
|
||||
begins capturing subsequent values.
|
||||
begins capturing subsequent values. Calling this method in playback mode raises
|
||||
`CoreError` with code `"incorrect_mode"`; calling it while already recording
|
||||
raises `CoreError` with code `"recording_active"`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Starting a recording discards any values captured by a previous recording.
|
||||
@@ -173,16 +216,96 @@ begins capturing subsequent values.
|
||||
### `stop_recording() -> None`
|
||||
|
||||
Stops capture, normalizes the recorded data, and creates a processing buffer
|
||||
containing the completed recording and its signal manifest.
|
||||
containing the completed recording and its signal manifest. Timestamps in the
|
||||
completed recording are nanoseconds relative to its first sample.
|
||||
|
||||
Calling this method in playback mode raises `CoreError` with code
|
||||
`"incorrect_mode"`; calling it when no recording is active raises `CoreError`
|
||||
with code `"not_recording"`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Stopping a recording replaces the previous processing buffer. Persist or
|
||||
> process it before stopping another recording.
|
||||
|
||||
There is currently no public `Core` method for retrieving or writing the
|
||||
completed processing buffer. The `.dlpak` writer is implemented by the
|
||||
internal `DLPak` type; applications relying on it must use private state and
|
||||
therefore should expect that integration to change.
|
||||
### `get_recording_state() -> bool`
|
||||
|
||||
Returns `True` while a recording is active and `False` otherwise.
|
||||
|
||||
### `write(dir: str | Path, filename: str) -> None`
|
||||
|
||||
Writes the most recently completed recording to a DLPak archive. The `.dlpak`
|
||||
extension is added to `filename` when it is not already present.
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
core.write(Path("recordings"), "dyno-run-001")
|
||||
```
|
||||
|
||||
Complete a recording with `stop_recording()` before calling `write()`. If no
|
||||
completed recording is available, the method raises `CoreError` with code
|
||||
`"no_recording"`. Archive write failures raise `DLPakError` with code
|
||||
`"write_failed"` and retain the underlying exception as their cause.
|
||||
|
||||
## Playback
|
||||
|
||||
Playback feeds a completed recording through the same live-value and derive
|
||||
pipeline used for realtime data. Switch Core to playback mode and load data
|
||||
before starting playback:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
core.set_mode("playback")
|
||||
core.load_playback_engine(Path("recordings/dyno-run-001.dlpak"))
|
||||
core.play()
|
||||
```
|
||||
|
||||
### `load_playback_engine(input: Path | None = None) -> None`
|
||||
|
||||
Loads playback data. Pass a DLPak archive path to load a saved recording, or
|
||||
omit `input` to load the recording most recently completed by this `Core`
|
||||
instance.
|
||||
|
||||
This method is only available in playback mode; otherwise it raises `CoreError`
|
||||
with code `"invalid_mode"`. Omitting `input` before a recording has been
|
||||
completed raises `CoreError` with code `"no_playback_data"`. A file that cannot
|
||||
be read or validated raises `DLPakError` with code `"read_failed"`. Replacing
|
||||
data while playback is active raises `PlaybackError` with code
|
||||
`"already_playing"`.
|
||||
|
||||
Loading data does not start playback.
|
||||
|
||||
### `play() -> None`
|
||||
|
||||
Starts or resumes playback from the current position. Playback stops
|
||||
automatically at the end of the recording and resets its position to the
|
||||
beginning.
|
||||
|
||||
Calling this method outside playback mode raises `CoreError` with code
|
||||
`"invalid_mode"`. Starting before data is loaded raises `PlaybackError` with
|
||||
code `"no_data"`.
|
||||
|
||||
### `pause() -> None`
|
||||
|
||||
Pauses playback. A subsequent `play()` resumes from the current position.
|
||||
Calling this method outside playback mode raises `CoreError` with code
|
||||
`"invalid_mode"`. Calling it when playback is already paused has no effect.
|
||||
|
||||
### `seek(timestamp_ns: int) -> None`
|
||||
|
||||
Sets the playback position to `timestamp_ns`, measured in nanoseconds from the
|
||||
recording's first sample. Samples after that timestamp are emitted when
|
||||
playback starts or resumes. A negative timestamp raises `PlaybackError` with
|
||||
code `"invalid_timestamp"`.
|
||||
|
||||
Calling this method outside playback mode raises `CoreError` with code
|
||||
`"invalid_mode"`.
|
||||
|
||||
### `get_playback_state() -> bool`
|
||||
|
||||
Returns `True` while the playback engine is actively emitting data and `False`
|
||||
while it is paused, has not started, or has reached the end of the recording.
|
||||
|
||||
## Derived Signals
|
||||
|
||||
@@ -234,9 +357,10 @@ The parameter annotations must use the imported `ValueDescriptor` and
|
||||
`SignalDescriptor` classes shown above. The source string is executed with
|
||||
`exec()`, so only bind code from trusted sources.
|
||||
|
||||
The returned UUID identifies the bound unit. Binding source that defines more
|
||||
or fewer than one function raises `DeriveUnitMultipleFunctionsFoundError`; an
|
||||
invalid function signature raises `DeriveUnitInvalidSignatureError`.
|
||||
The returned UUID identifies the bound unit. Invalid source or function shape
|
||||
raises `DeriveError`. Its code is `"invalid_source"` when the source cannot be
|
||||
loaded or does not define exactly one function, and `"invalid_signature"` when
|
||||
the function annotations or parameter order are invalid.
|
||||
|
||||
### `unbind_derive_unit(unit_id: UUID) -> None`
|
||||
|
||||
@@ -248,10 +372,40 @@ to resume derived-value processing.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Core-specific exceptions are defined in `dynalab_core.errors`.
|
||||
All expected library exceptions are defined in `dynalab_core.errors` and derive
|
||||
from `DynaLabError`. Exceptions are grouped by subsystem rather than by every
|
||||
individual failure reason:
|
||||
|
||||
| Exception | Raised when |
|
||||
| --- | --- |
|
||||
| `CoreStateMismatchError` | `start()` is called after the core has already started or stopped. |
|
||||
| `DeriveUnitMultipleFunctionsFoundError` | A derive-unit source string does not define exactly one function. |
|
||||
| `DeriveUnitInvalidSignatureError` | A derive function's annotations or parameter order are invalid. |
|
||||
| Exception | Area | Codes |
|
||||
| --- | --- | --- |
|
||||
| `CoreError` | Core lifecycle, mode, and recording operations. | `invalid_state`, `invalid_mode`, `incorrect_mode`, `recording_active`, `not_recording`, `no_recording`, `no_playback_data` |
|
||||
| `DLPakError` | Archive preparation, reading, and writing. | `no_data`, `no_manifest`, `read_failed`, `write_failed` |
|
||||
| `DeriveError` | Derive source, signatures, arguments, and registration. | `invalid_source`, `invalid_signature`, `input_signal_mismatch`, `argument_mismatch`, `already_registered` |
|
||||
| `PlaybackError` | Playback state and data. | `no_data`, `incomplete_data`, `already_playing`, `invalid_timestamp`, `stopped` |
|
||||
| `ConnectorError` | Connector queues and registration. | `queue_full`, `already_registered` |
|
||||
| `JsonServerError` | JSON server startup and timeouts. | `start_timeout`, `startup_failed` |
|
||||
|
||||
Every exception has a human-readable message and a stable, machine-readable
|
||||
`code`. Catch a subsystem exception when the application can recover from that
|
||||
area, or catch `DynaLabError` at the application's outer boundary:
|
||||
|
||||
```python
|
||||
from dynalab_core.errors import CoreError, DynaLabError
|
||||
|
||||
try:
|
||||
core.start_recording()
|
||||
except CoreError as error:
|
||||
if error.code == "incorrect_mode":
|
||||
core.set_mode("realtime")
|
||||
core.start_recording()
|
||||
|
||||
try:
|
||||
run_application()
|
||||
except DynaLabError as error:
|
||||
print(f"DynaLab operation failed ({error.code}): {error}")
|
||||
```
|
||||
|
||||
Wrapped operating-system, validation, and archive errors are available through
|
||||
the standard `error.__cause__` attribute. Internal transport conditions such as
|
||||
a peer disconnect or an invalid incoming frame are handled by the server and
|
||||
logged instead of being raised from a background task to application code.
|
||||
|
||||
Reference in New Issue
Block a user