Enum Module

mosaicolabs.enum.SerializationFormat

Bases: Enum

Defines the structural format used when serializing ontology data for storage or transmission.

The format dictates how the data is organized (e.g., fixed-schema tables vs. variable-length structures) and may imply specific handling during the serialization and deserialization process.

Default class-attribute instance-attribute

Default = 'default'

Represents data that conforms to a strict, fixed-width tabular format (like a standard DataFrame or a PyArrow Table of records). Suitable for simple sensors with a constant number of fields and fixed-size data.

Ragged class-attribute instance-attribute

Ragged = 'ragged'

Represents data containing variable-length lists or sequences (e.g., point clouds, lists of detections, or non-uniform arrays). This format is typically serialized using specialized PyArrow features to handle the non-uniform structure efficiently.

Image class-attribute instance-attribute

Image = 'image'

Represents raw or compressed image data. This format signals that the data consists primarily of a binary blob (the image content) along with associated metadata (width, height, format), often requiring specialized compression/decompression handling.

mosaicolabs.enum.SessionStatus

Bases: Enum

Represents the operational lifecycle state of a Session upload for a Sequence during the ingestion process (see also SequenceWriter).

This enumeration tracks the state of a session from its initial creation through data writing until it reaches a terminal state (Finalized or Error).

Null class-attribute instance-attribute

Null = 'null'

The initial state of a writer before server-side registration.

In this state, the local SequenceWriter instance has been created but the SESSION_CREATE handshake has not yet been performed or completed.

Pending class-attribute instance-attribute

Pending = 'pending'

The session is registered on the server and actively accepting data.

This state is entered upon successful execution of the __enter__ method of the SequenceWriter class. While pending, the session allows for the creation of new topics and the ingestion of data batches.

Finalized class-attribute instance-attribute

Finalized = 'finalized'

The session has been successfully closed and its data is now immutable.

This terminal state indicates that the SequenceWriter._finalize() action was acknowledged by the server. Once finalized, the session is typically locked and cannot be deleted unless explicitly unlocked by an administrator.

Error class-attribute instance-attribute

Error = 'error'

The ingestion process failed or was explicitly aborted.

This state is reached if an exception occurs within the with block or during the finalization phase. Depending on the SessionLevelErrorPolicy, the data may have been purged (Delete) or retained in an unlocked state for debugging (Report).

mosaicolabs.enum.SequenceStatus module-attribute

SequenceStatus = SessionStatus

Represents the operational lifecycle state of a Sequence during the ingestion process

Alias for SessionStatus.

mosaicolabs.enum.TopicWriterStatus

Bases: Enum

Represents the operational lifecycle state of a Topic upload for a specific Session during the ingestion process (see also TopicWriter).

This enumeration tracks the state of a topic writer from its initial creation through data writing until it reaches a terminal state.

Note

The FinalizedWithError, IgnoredLastError and RaisedException values can only be tracked if the TopicWriter is used in a with context.

Active class-attribute instance-attribute

Active = 'active'

The initial state of a topic writer before server-side registration.

In this state, the local TopicWriter instance has been created and the TOPIC_CREATE handshake has completed.

Finalized class-attribute instance-attribute

Finalized = 'finalized'

The topic writer has been successfully closed and its data is now immutable.

This terminal state indicates that the TopicWriter._finalize() action was acknowledged by the server. Once finalized, the topic writer is locked and cannot be used to push records.

FinalizedWithError class-attribute instance-attribute

FinalizedWithError = 'finalized_with_error'

The topic writer has been finalized with an error.

This state is reached when the TopicWriter is used in a context and its error policy is set to TopicLevelErrorPolicy.Finalize.

This terminal state indicates that the TopicWriter._finalize() function was called with an error. Once finalized, the topic writer is locked and cannot be used to push records.

IgnoredLastError class-attribute instance-attribute

IgnoredLastError = 'ignored_last_error'

The topic writer is still active and can be used to push data on the platform.

This state is reached when the TopicWriter is used in a context and its error policy is set to TopicLevelErrorPolicy.Ignore.

This temporary state indicates that the last time the with context exited, it was due to an error.

RaisedException class-attribute instance-attribute

RaisedException = 'raised_exception'

The topic writer encountered an error in its with block. The error handling is delegated to the outer SequenceWriter error handling policy (SessionLevelErrorPolicy) , or any try-except outer block.

This state is reached when the TopicWriter is used in a context and its error policy is set to TopicLevelErrorPolicy.Raise.

mosaicolabs.enum.APIKeyPermissionEnum

Bases: Enum

Read class-attribute instance-attribute

Read = 'read'

Read-Only access to resources

This permission allows to: - List resources - Retrieve Sequences, Topics and the related Data streams - Query the data catalogs via the MosaicoClient.query() method

Write class-attribute instance-attribute

Write = 'write'

Write access to resources

This permission allows to: - List resources - Retrieve Sequences, Topics and the related Data streams - Query the data catalogs via the MosaicoClient.query() method - Create and update Sequences

Delete class-attribute instance-attribute

Delete = 'delete'

Delete access to resources

This permission allows to: - List resources - Retrieve Sequences, Topics and the related Data streams - Query the data catalogs via the MosaicoClient.query() method - Create and update Sequences - Delete Sequences, Sessions and Topics

Manage class-attribute instance-attribute

Manage = 'manage'

Full access to resources

This permission allows to: - List resources - Retrieve Sequences, Topics and the related Data streams - Query the data catalogs via the MosaicoClient.query() method - Create and update Sequences - Delete Sequences, Sessions and Topics - Manage API keys (create, retrieve the status, revoke)

mosaicolabs.enum.SessionLevelErrorPolicy

Bases: Enum

Defines the behavior of the SequenceWriter or the SequenceUpdater when an exception occurs during ingestion.

This policy determines how the platform handles partially uploaded data if the ingestion process is interrupted or fails.

Report class-attribute instance-attribute

Report = 'report'

Notify the server of the error but retain partial data.

The system will attempt to finalize the session and notify the server of the specific failure, allowing existing data chunks to remain accessible for inspection.

Note

When the connection is established via the authorization middleware (i.e. using an API Key), this policy requires the minimum APIKeyPermissionEnum.Read permission.

Lock Status

Unlike standard successful finalization, a session finalized via a Report policy is not placed in a locked state. This means the sequence remains mutable at a system level and can be deleted in a later moment once debugging or triage is complete.

Delete class-attribute instance-attribute

Delete = 'delete'

Abort the sequence and instruct the server to discard all data.

This is the default "all-or-nothing" strategy. If a failure occurs, the SequenceWriter or the SequenceUpdater will send an abort command to ensure the server purges all traces of the failed ingestion, preventing inconsistent or incomplete sequences from appearing in the catalog.

Note

When the connection is established via the authorization middleware (i.e. using an API Key), this policy is successfully executed by the server only if the API Key has APIKeyPermissionEnum.Delete permission.

mosaicolabs.enum.TopicLevelErrorPolicy

Bases: Enum

Defines the behavior of the TopicWriter when an exception occurs during ingestion.

This policy determines how the platform handles partially uploaded data if the ingestion process is interrupted or fails.

Finalize class-attribute instance-attribute

Finalize = 'finalize'

Notify server and close the topic (is_active = False).

Ignore class-attribute instance-attribute

Ignore = 'ignore'

Notify server but keep topic open for future push() calls.

Raise class-attribute instance-attribute

Raise = 'raise'

Propagate exception to trigger session-level policy.

mosaicolabs.enum.OnErrorPolicy

Bases: Enum

Defines the behavior of the SequenceWriter when an exception occurs during ingestion.

This policy determines how the platform handles partially uploaded data if the ingestion process is interrupted or fails.

Report class-attribute instance-attribute

Report = 'report'

Notify the server of the error but retain partial data.

The system will attempt to finalize the sequence and notify the server of the specific failure, allowing existing data chunks to remain accessible for inspection.

Note

When the connection is established via the authorization middleware (i.e. using an API Key), this policy requires the minimum APIKeyPermissionEnum.Read permission.

Lock Status

Unlike standard successful finalization, a sequence finalized via a Report policy is not placed in a locked state. This means the sequence remains mutable at a system level and can be deleted in a later moment once debugging or triage is complete.

Delete class-attribute instance-attribute

Delete = 'delete'

Delete the sequence and instruct the server to discard all data.

This is the default "all-or-nothing" strategy. If a failure occurs, the SequenceWriter will send an abort command to ensure the server purges all traces of the failed ingestion, preventing inconsistent or incomplete sequences from appearing in the catalog.

Note

When the connection is established via the authorization middleware (i.e. using an API Key), this policy is successfully executed by the server only if the API Key has APIKeyPermissionEnum.Delete permission.

mosaicolabs.enum.TopicLevelErrorPolicy

Bases: Enum

Defines the behavior of the TopicWriter when an exception occurs during ingestion.

This policy determines how the platform handles partially uploaded data if the ingestion process is interrupted or fails.

Finalize class-attribute instance-attribute

Finalize = 'finalize'

Notify server and close the topic (is_active = False).

Ignore class-attribute instance-attribute

Ignore = 'ignore'

Notify server but keep topic open for future push() calls.

Raise class-attribute instance-attribute

Raise = 'raise'

Propagate exception to trigger session-level policy.

mosaicolabs.enum.SessionLevelErrorPolicy

Bases: Enum

Defines the behavior of the SequenceWriter or the SequenceUpdater when an exception occurs during ingestion.

This policy determines how the platform handles partially uploaded data if the ingestion process is interrupted or fails.

Report class-attribute instance-attribute

Report = 'report'

Notify the server of the error but retain partial data.

The system will attempt to finalize the session and notify the server of the specific failure, allowing existing data chunks to remain accessible for inspection.

Note

When the connection is established via the authorization middleware (i.e. using an API Key), this policy requires the minimum APIKeyPermissionEnum.Read permission.

Lock Status

Unlike standard successful finalization, a session finalized via a Report policy is not placed in a locked state. This means the sequence remains mutable at a system level and can be deleted in a later moment once debugging or triage is complete.

Delete class-attribute instance-attribute

Delete = 'delete'

Abort the sequence and instruct the server to discard all data.

This is the default "all-or-nothing" strategy. If a failure occurs, the SequenceWriter or the SequenceUpdater will send an abort command to ensure the server purges all traces of the failed ingestion, preventing inconsistent or incomplete sequences from appearing in the catalog.

Note

When the connection is established via the authorization middleware (i.e. using an API Key), this policy is successfully executed by the server only if the API Key has APIKeyPermissionEnum.Delete permission.

mosaicolabs.enum.FlightAction

Bases: Enum

Internal enumeration of PyArrow Flight action identifiers.

This enum serves as the single source of truth for all action names used in the handshakes between the SDK and the Mosaico server.

Internal Use Only

This class is part of the internal communication protocol. End-users should never need to use these identifiers directly, as they are abstracted by the public methods in MosaicoClient, SequenceWriter, and TopicWriter.

SEQUENCE_CREATE class-attribute instance-attribute

SEQUENCE_CREATE = 'sequence_create'

Initiates the registration of a new sequence on the server.

SESSION_CREATE class-attribute instance-attribute

SESSION_CREATE = 'session_create'

Initiates the registration of a new session for an existing sequence on the server.

SESSION_FINALIZE class-attribute instance-attribute

SESSION_FINALIZE = 'session_finalize'

Marks a session as complete and makes its data immutable.

SEQUENCE_NOTIFICATION_CREATE class-attribute instance-attribute

SEQUENCE_NOTIFICATION_CREATE = (
    "sequence_notification_create"
)

Sends asynchronous notifications or error reports during the sequence creation phase.

SEQUENCE_NOTIFICATION_LIST class-attribute instance-attribute

SEQUENCE_NOTIFICATION_LIST = 'sequence_notification_list'

Request the list of notifications for a specific sequence

SEQUENCE_NOTIFICATION_PURGE class-attribute instance-attribute

SEQUENCE_NOTIFICATION_PURGE = 'sequence_notification_purge'

Request the deletion of the list of notifications for a specific sequence

SESSION_DELETE class-attribute instance-attribute

SESSION_DELETE = 'session_delete'

Requests the permanent removal of a session and all associated topics from the server.

SEQUENCE_DELETE class-attribute instance-attribute

SEQUENCE_DELETE = 'sequence_delete'

Requests the permanent removal of a sequence and all associated topics from the server.

TOPIC_CREATE class-attribute instance-attribute

TOPIC_CREATE = 'topic_create'

Registers a new topic within an existing sequence context.

TOPIC_NOTIFICATION_CREATE class-attribute instance-attribute

TOPIC_NOTIFICATION_CREATE = 'topic_notification_create'

Reports errors or status updates specific to an individual topic stream.

TOPIC_NOTIFICATION_LIST class-attribute instance-attribute

TOPIC_NOTIFICATION_LIST = 'topic_notification_list'

Request the list of notifications for a specific topic in a sequence

TOPIC_NOTIFICATION_PURGE class-attribute instance-attribute

TOPIC_NOTIFICATION_PURGE = 'topic_notification_purge'

Request the deletion of the list of notifications for a topic in a sequence

TOPIC_DELETE class-attribute instance-attribute

TOPIC_DELETE = 'topic_delete'

Requests the permanent removal of a specific topic from the platform.

QUERY class-attribute instance-attribute

QUERY = 'query'

Commands a multi-layer search query against the platform.

API_KEY_CREATE class-attribute instance-attribute

API_KEY_CREATE = 'api_key_create'

Creates a new API key.

API_KEY_REVOKE class-attribute instance-attribute

API_KEY_REVOKE = 'api_key_revoke'

Revokes an existing API key.

API_KEY_STATUS class-attribute instance-attribute

API_KEY_STATUS = 'api_key_status'

Checks the status of a specific API key.

VERSION class-attribute instance-attribute

VERSION = 'version'

Requests the backend version