dynalab-core/docs/API.md

DynaLab Core API

Core is the Python interface for running a DynaLab Core instance, inspecting 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.

Warning

DynaLab Core is in alpha. Its public API may change between releases.

Quick Start

Create a configuration, construct the core, then start it. Always stop the core when the application exits so its server and worker threads are shut down.

from dynalab_core import Core
from dynalab_core.config import CoreConfig

core = Core(CoreConfig(host="127.0.0.1", port=58763))

try:
    core.start()
    core.wait()  # Blocks until stop() is called or a timeout expires.
finally:
    core.stop()

Core does not currently implement the context-manager protocol. Use try/finally when the core may be started.

Configuration

CoreConfig is defined in dynalab_core.config.

from dynalab_core.config import CoreConfig

config = CoreConfig(
    host="127.0.0.1",  # Default
    port=58763,         # Default; must be in the range 0 through 65535
)

Field	Type	Default	Description
host	str	"127.0.0.1"	Address on which the core server listens.
port	int	58763	TCP port on which the core server listens.

CoreConfig.bind_str() -> str returns the configured address in "host:port" form.

Lifecycle

Core(config: CoreConfig)

Creates a core and starts its internal input worker. The network server is not started until start() is called.

start() -> None

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 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

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() -> bool

Stops the server, disconnects connectors, signals the input worker to stop, and 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 is described by SignalDescriptor from dynalab_core.protocols.packets.handshake.

from uuid import UUID

from dynalab_core.protocols.packets.handshake import SignalDescriptor

signal = SignalDescriptor(
    id=UUID("2d60a378-f37c-4c37-867b-c68f5116598b"),
    name="Engine RPM",
    type="number",
    min_value=0.0,
    max_value=6000.0,
    unit="rpm",
    timeout_ms=2_000,
)

Field	Type	Default	Description
id	UUID	Required	Stable, unique signal identifier.
name	str	Required	Human-readable signal name.
type	"number" or "binary"	Required	Signal value category. Values are represented as float by the current data API.
min_value	float | None	None	Optional lower bound.
max_value	float | None	None	Optional upper bound.
unit	str | None	None	Optional display unit.
timeout_ms	int	2000	How long a received value remains live.
origin	"source" or "derived"	"source"	Whether a connector or a derive unit produces the signal.

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 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 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 in realtime mode.

Live Values

After a connector sends a value, Core retains its latest value until the signal's timeout_ms has elapsed. A stale, unknown, or not-yet-received value is represented by None.

get_live_value(signal_id: UUID) -> float | None

Returns the latest non-stale value for one signal.

rpm = core.get_live_value(signal_id)
if rpm is not None:
    print(f"Engine speed: {rpm:.0f} rpm")

get_all_live_values() -> dict[UUID, float]

Returns a snapshot mapping signal IDs to their latest non-stale values. Signals without a current value are omitted.

for signal_id, value in core.get_all_live_values().items():
    print(signal_id, value)

Incoming data timestamps use the monotonic-nanosecond timebase. See Protocol timestamps when implementing a connector.

Recording

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. 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.

stop_recording() -> None

Stops capture, normalizes the recorded data, and creates a processing buffer 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.

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.

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:

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

A derive unit calculates a new value whenever one of its input signals receives an update and all inputs have non-stale live values. Package the calculation, its input descriptors, and its output descriptor in a DLUnit, then bind it with bind_derive_unit().

bind_derive_unit(dlunit: DLUnit | None = None, file: Path | None = None) -> UUID

Provide exactly one of dlunit or file:

• dlunit binds an in-memory DLUnit.
• file loads and binds a .dlunit archive.

To create and bind an in-memory unit:

from uuid import uuid4

from dynalab_core.dlunit import DLUnit
from dynalab_core.protocols.packets.handshake import SignalDescriptor

processing_function = """
from dynalab_core.protocols.packets.data import ValueDescriptor
from dynalab_core.protocols.packets.handshake import SignalDescriptor

def add(left: ValueDescriptor, right: ValueDescriptor, output: SignalDescriptor) -> ValueDescriptor:
    return ValueDescriptor(
        signal_id=output.id,
        value=left.value + right.value,
        timestamp=left.timestamp,
    )
"""

return_signal = SignalDescriptor(
    id=uuid4(),
    name="Total",
    type="number",
    origin="derived",
)

derive_unit = DLUnit()
derive_unit.set_manifest(
    uuid4(),
    [left_signal, right_signal],
    return_signal,
)
derive_unit.set_data(processing_function)

unit_id = core.bind_derive_unit(dlunit=derive_unit, file=None)

To bind a previously saved archive instead, pass None for dlunit and its path for file:

from pathlib import Path

unit_id = core.bind_derive_unit(
    dlunit=None,
    file=Path("units/total.dlunit"),
)

The unit's Python source must define exactly one function. Its parameters must be:

1. Zero or more ValueDescriptor parameters, in the same order as the manifest's input_signals.
2. One final SignalDescriptor parameter for the manifest's return_signal.
3. A return annotation of ValueDescriptor.

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. 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

Stops and removes the derive unit identified by unit_id. Passing an unknown or already unbound ID has no effect.

The returned ID is no longer valid after unbinding. Create and bind a new unit to resume derived-value processing.

Exceptions

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	Area	Codes
CoreError	Core lifecycle, mode, recording, and derive-unit binding operations.	invalid_state, invalid_mode, incorrect_mode, recording_active, not_recording, no_recording, no_playback_data, bind_derive_failed
DLPakError	Recording archive preparation, reading, and writing.	no_data, no_manifest, read_failed, write_failed
DLUnitError	Derive-unit 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:

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.