Runtime Orchestration

Routing, shared state, and worker coordination that bind the Python runtime into the supervised SmrtHub fabric.

python_core.runtime.router

Routing helpers that map extensions to folders and enrich filenames.

EXTENSION_FOLDER_MAP provides extension-to-folder labels. Note that SmrtSpace save layout is implemented in file_saver.py; text saves are intentionally kept directly under the source folder (no dedicated text subfolder).

apply_filename_suffix

apply_filename_suffix(filename: str, filetype: str) -> str

Apply routing-rule filename suffixes (date/filetype) to filename when configured.

:param filename: Candidate filename that may receive suffixes. :param filetype: Extension detected for the payload. :returns: Filename updated with suffixes when rules require it.

get_display_date

get_display_date() -> str

Return today's date using routing_rules['display_date_format'].

:returns: Human-readable date string for UI display.

get_folder_date

get_folder_date() -> str

Return today's date in ISO YYYY-MM-DD format.

SmrtSpace no longer creates date-based folders; this helper remains for filename suffix modes and human-readable display.

map_extension_to_folder

map_extension_to_folder(filetype: str) -> str

Translate an extension into a readable folder name via EXTENSION_FOLDER_MAP.

:param filetype: Extension (with or without dot) to evaluate. :returns: Folder label associated with the extension.

python_core.runtime.shared_state

Thread-safe runtime state for clipboard context, sources, and save queues.

Helpers here coordinate shared dictionaries, queues, and snapshot logging for runtime consumers. See README.md for the full workflow diagram.

Filetype Detection

Text clipboard fragments may include a detection dict containing filetype metadata attached at ingestion time. This metadata (type_id, group, confidence, extension) is preserved through deepcopy operations and displayed in terminal snapshots. The detection data flows through to the save pipeline for consistent type handling.

append_backup

append_backup(content, max_len=3)

Push content into the rolling backup buffer while enforcing max_len.

:param content: Clipboard payload to retain. :param max_len: Maximum number of entries to keep in the buffer. :returns: None.

clear_smrtspace_alert

clear_smrtspace_alert() -> None

Clear any active SmrtSpace alert from shared state.

is_valid_clipboard_fragment

is_valid_clipboard_fragment(obj)

Validate clipboard fragment structure expected by the runtime.

Fragments may optionally include a detection dict containing filetype metadata (type_id, group, confidence, extension) attached at ingestion. Detection metadata is not required for validity—only the base fragment structure (type + content/path) is checked.

:param obj: Candidate clipboard fragment to inspect. :returns: True when the fragment contains the minimum fields per type.

log_snapshot

log_snapshot()

Log a structured snapshot of current shared state for debugging.

:returns: None.

open_editor

open_editor()

Mark the editor as opened and emit a structured log event.

:returns: None.

set_clipboard_payload

set_clipboard_payload(payload_list)

Replace the clipboard state with a validated list of fragment objects.

:param payload_list: Ordered collection of clipboard fragments. :returns: None. :raises ValueError: Raised when payload_list is not a list or contains invalid fragments.

set_encounter_metadata

set_encounter_metadata(encounter)

Persist encounter metadata in shared state for downstream save operations.

set_smrtspace_alert

set_smrtspace_alert(
    reason: str, origin: str, details: dict | None = None
) -> dict

Persist a SmrtSpace-required alert for UI consumers.

:param reason: Short token describing why SmrtSpace is required. :param origin: Component emitting the alert. :param details: Optional diagnostic payload for UI routing. :returns: Alert payload stored in shared state.

update_source_data

update_source_data(source_obj, source_type)

Normalize source metadata, persist it, and emit a single structured event.

:param source_obj: Source payload describing the originating app/url/path. :param source_type: Token describing the detected source classification. :returns: True once the snapshot has been recorded.

python_core.runtime.save_worker

Background worker that drains the save queue and hands payloads to file_saver.

save_and_route_worker

save_and_route_worker()

Continuously pull payloads from shared_state.save_queue and call save_to_file.

:returns: None; the loop runs until the process stops.

start_save_worker

start_save_worker()

Launch the daemon thread that runs :func:save_and_route_worker. Call once at startup.

:returns: threading.Thread instance for optional diagnostics.

python_core.runtime.save_trigger

Trigger handler that snapshots shared state and enqueues a save request.

user_triggered_save

user_triggered_save()

Snapshot clipboard and source metadata, then push the payload to save_queue.

:returns: None.