Core

Core (atlas.core) is the central package of Atlas — the fundamental nucleus responsible for database persistence and abstraction.

Within this package, the foundations for all entities, database sessions, and transactional management are defined. Every other package in Atlas is built upon, or directly/indirectly depends on, the components provided by Core.

Below are the descriptions of each component.

Entity

Bases: declarative_base()

Entity is the abstract base class from which all persistent entities created for the API must inherit, ensuring a consistent and traceable structure.

This class defines the fundamental fields and behaviors of a database entity, including support for auto-generated UUIDs, polymorphic inheritance, and soft delete control.

Attributes:

Name	Type	Description
__abstract__	bool	Class attribute. Marks the class as abstract, preventing direct table creation. This value should not be changed.
__mapper_args__	dict	Class attribute. ORM mapping configurations, including polymorphism support. This value should not be changed.
__soft_delete__	bool	Class attribute. Indicates whether the model uses soft delete behavior. Can be overridden as False in subclasses to enable permanent deletion (hard delete), ideal for cases where database clutter from high record volume should be avoided.
uuid	str	Automatically generated universally unique identifier for each entity.
active	bool	Indicates whether the entity is active. Used for logical filtering.
created	datetime	UTC date and time when the entity was created.
modified	Optional[datetime]	UTC date and time of the last modification.
deleted	bool	Indicates whether the entity was marked as logically deleted (soft delete).
type	str	Entity type name, used for polymorphic inheritance.

SessionManager

SessionManager is the class responsible for managing SQLAlchemy sessions and providing static utility methods for transactional context control.

Attributes:

Name	Type	Description
session_context	ContextVar[Optional[Session]]	The current session context used to store the active session within the local thread/coroutine context.

expunge(entity) staticmethod

Detaches an entity from the current session, preventing it from participating in the next flush or commit. If the entity is not present in the session, the operation is silently ignored.

Parameters:

Name	Type	Description	Default
entity	object	The entity to be detached from the session.	required

expunge_all(entities) staticmethod

Detaches multiple entities from the current session, preventing them from participating in the next flush or commit. If any of the entities are not present in the session, the operation for that entity is silently ignored.

Parameters:

Name	Type	Description	Default
entities	List[object]	List of entities to be detached from the session.	required

get_session() staticmethod

Returns the current session from the context.

Returns:

Type	Description
Optional[Session]	Optional[Session]: The current session, or None if no session exists.

reset_session(token) staticmethod

Restores the session context to its previous state (the session prior to the current one, or None if no session existed before) using the provided token.

Parameters:

Name	Type	Description	Default
token	Token[Session]	The session identifier token.	required

set_session(session) staticmethod

Sets the given session as the current context session.

Parameters:

Name	Type	Description	Default
session	Session	The session to set as active.	required

Returns:

Type	Description
Token[Session]	Token[Session]: A token representing the session identifier.

transactional() staticmethod

Context manager for executing transactional code blocks. Automatically commits on success and rolls back in case of an exception.

Yields:

Name	Type	Description
Session	Session	The active session within the transactional context.

Raises:

Type	Description
RuntimeError	If a session cannot be created due to missing database configuration.

ORM

get_database_env_vars()

Attempts to load database credentials (DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, DB_NAME) from AWS Secrets Manager.

This function retrieves the secret specified by the environment variables AWS_DEFAULT_REGION and SECRET_ARN. If the secret cannot be retrieved or any required key is missing, it returns None.

Returns:

Type	Description
Optional[dict]	Optional[dict]: A dictionary containing database credentials if successfully loaded, otherwise None.

get_engine()

Returns the global SQLAlchemy Engine instance, creating it if necessary.

The engine is built from database credentials retrieved through get_database_env_vars(). It enables connection pooling and is configured with pool_pre_ping=True to maintain active connections.

Returns:

Type	Description
Optional[Engine]	Optional[Engine]: The SQLAlchemy Engine instance, or None if database credentials could not be loaded.

get_session_local()

Returns the global session factory (sessionmaker), creating it if necessary.

The session factory manages database sessions bound to the global SQLAlchemy Engine. It also automatically applies a soft delete filter for all ORM operations involving subclasses of Entity.

Returns:

Type	Description
Optional[sessionmaker]	Optional[sessionmaker]: The configured SQLAlchemy session factory, or None if the engine could not be initialized.

Behavior

• Soft delete filter:
  Automatically excludes records where Entity.deleted == True from queries, unless explicitly overridden by execution_options(include_deleted=True).

• Delete interception:
  When a soft-deletable entity (__soft_delete__ = True) is deleted, it is instead marked as inactive and flagged as deleted (active=False, deleted=True), preventing physical deletion.