Skip to content

Scores

leadr.scores

Modules:

leadr.scores.adapters

Modules:

  • orm – Score ORM models.
leadr.scores.adapters.orm

Score ORM models.

Classes:

leadr.scores.adapters.orm.ScoreFlagORM

Bases: Base

Score flag ORM model for anti-cheat detections.

Records suspicious patterns detected by the anti-cheat system. Flags can be reviewed by admins to confirm or dismiss detections.

Functions:

  • from_domain – Convert domain entity to ORM model.
  • to_domain – Convert ORM model to domain entity.

Attributes:

# leadr.scores.adapters.orm.ScoreFlagORM.confidence
confidence: Mapped[str] = mapped_column(String, nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreFlagORM.created_at
created_at: Mapped[timestamp]
# leadr.scores.adapters.orm.ScoreFlagORM.deleted_at
deleted_at: Mapped[nullable_timestamp]
# leadr.scores.adapters.orm.ScoreFlagORM.flag_metadata
flag_metadata: Mapped[dict[str, Any]] = mapped_column('metadata', JSONB, nullable=False, default=dict, server_default='{}')
# leadr.scores.adapters.orm.ScoreFlagORM.flag_type
flag_type: Mapped[str] = mapped_column(String, nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreFlagORM.from_domain
from_domain(entity)

Convert domain entity to ORM model.

# leadr.scores.adapters.orm.ScoreFlagORM.id
id: Mapped[uuid_pk]
# leadr.scores.adapters.orm.ScoreFlagORM.reviewed_at
reviewed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreFlagORM.reviewer_decision
reviewer_decision: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreFlagORM.reviewer_id
reviewer_id: Mapped[UUID | None] = mapped_column(nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreFlagORM.score_id
score_id: Mapped[UUID] = mapped_column(ForeignKey('scores.id', ondelete='CASCADE'), nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreFlagORM.status
status: Mapped[str] = mapped_column(String, nullable=False, default='PENDING', index=True)
# leadr.scores.adapters.orm.ScoreFlagORM.to_domain
to_domain()

Convert ORM model to domain entity.

# leadr.scores.adapters.orm.ScoreFlagORM.updated_at
updated_at: Mapped[timestamp] = mapped_column(onupdate=(func.now()))
leadr.scores.adapters.orm.ScoreORM

Bases: Base

Score ORM model.

Represents a player's score submission for a board in the database. Maps to the scores table with foreign keys to accounts, devices, games, and boards.

Attributes:

# leadr.scores.adapters.orm.ScoreORM.account
account: Mapped[AccountORM] = relationship('AccountORM')
# leadr.scores.adapters.orm.ScoreORM.account_id
account_id: Mapped[UUID] = mapped_column(ForeignKey('accounts.id', ondelete='CASCADE'), nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreORM.board
board: Mapped[BoardORM] = relationship('BoardORM')
# leadr.scores.adapters.orm.ScoreORM.board_id
board_id: Mapped[UUID] = mapped_column(ForeignKey('boards.id', ondelete='CASCADE'), nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreORM.created_at
created_at: Mapped[timestamp]
# leadr.scores.adapters.orm.ScoreORM.deleted_at
deleted_at: Mapped[nullable_timestamp]
# leadr.scores.adapters.orm.ScoreORM.device_id
device_id: Mapped[UUID] = mapped_column(nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreORM.filter_city
filter_city: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreORM.filter_country
filter_country: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreORM.filter_timezone
filter_timezone: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreORM.game
game: Mapped[GameORM] = relationship('GameORM')
# leadr.scores.adapters.orm.ScoreORM.game_id
game_id: Mapped[UUID] = mapped_column(ForeignKey('games.id', ondelete='CASCADE'), nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreORM.id
id: Mapped[uuid_pk]
# leadr.scores.adapters.orm.ScoreORM.player_name
player_name: Mapped[str] = mapped_column(String, nullable=False)
# leadr.scores.adapters.orm.ScoreORM.score_metadata
score_metadata: Mapped[Any | None] = mapped_column('score_metadata', JSON, nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreORM.updated_at
updated_at: Mapped[timestamp] = mapped_column(onupdate=(func.now()))
# leadr.scores.adapters.orm.ScoreORM.value
value: Mapped[float] = mapped_column(Float, nullable=False)
# leadr.scores.adapters.orm.ScoreORM.value_display
value_display: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
leadr.scores.adapters.orm.ScoreSubmissionMetaORM

Bases: Base

Score submission metadata ORM model for anti-cheat tracking.

Tracks submission history per device/board combination to enable detection of suspicious patterns like rapid-fire submissions.

Functions:

  • from_domain – Convert domain entity to ORM model.
  • to_domain – Convert ORM model to domain entity.

Attributes:

# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.board_id
board_id: Mapped[UUID] = mapped_column(nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.created_at
created_at: Mapped[timestamp]
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.deleted_at
deleted_at: Mapped[nullable_timestamp]
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.device_id
device_id: Mapped[UUID] = mapped_column(nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.from_domain
from_domain(entity)

Convert domain entity to ORM model.

# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.id
id: Mapped[uuid_pk]
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.last_score_value
last_score_value: Mapped[float | None] = mapped_column(Float, nullable=True, default=None)
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.last_submission_at
last_submission_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.score_id
score_id: Mapped[UUID] = mapped_column(ForeignKey('scores.id', ondelete='CASCADE'), nullable=False, index=True)
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.submission_count
submission_count: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.to_domain
to_domain()

Convert ORM model to domain entity.

# leadr.scores.adapters.orm.ScoreSubmissionMetaORM.updated_at
updated_at: Mapped[timestamp] = mapped_column(onupdate=(func.now()))

leadr.scores.api

Modules:

leadr.scores.api.score_flag_routes

API routes for score flag management.

Functions:

Attributes:

leadr.scores.api.score_flag_routes.get_score_flag
get_score_flag(flag_id, service, auth)

Get a score flag by ID.

Parameters:

Returns:

Raises:

  • 403 – User does not have access to this flag's account.
  • 404 – Flag not found or soft-deleted.
leadr.scores.api.score_flag_routes.list_score_flags
list_score_flags(auth, service, account_id=None, board_id=None, game_id=None, status=None, flag_type=None)

List score flags for an account with optional filters.

Returns all non-deleted flags for the specified account, with optional filtering by board, game, status, or flag type.

For regular users, account_id is automatically derived from their API key. For superadmins, account_id is optional - if omitted, returns flags from all accounts.

Parameters:

  • auth (AdminAuthContextDep) – Authentication context with user info.
  • service (ScoreFlagServiceDep) – Injected score flag service dependency.
  • account_id (Annotated[AccountID | None, Query(description='Account ID filter')]) – Optional account_id query parameter (superadmins can omit to see all).
  • board_id (BoardID | None) – Optional board ID to filter by.
  • game_id (GameID | None) – Optional game ID to filter by.
  • status (str | None) – Optional status to filter by (PENDING, CONFIRMED_CHEAT, etc.).
  • flag_type (str | None) – Optional flag type to filter by (VELOCITY, DUPLICATE, etc.).

Returns:

Raises:

  • 403 – User does not have access to the specified account.
leadr.scores.api.score_flag_routes.router
router = APIRouter()
leadr.scores.api.score_flag_routes.update_score_flag
update_score_flag(flag_id, request, service, auth)

Update a score flag (review or soft-delete).

Allows reviewing a flag (updating status and reviewer decision) or soft-deleting the flag.

Parameters:

Returns:

Raises:

  • 403 – User does not have access to this flag's account.
  • 404 – Flag not found.
  • 400 – Invalid update request.
leadr.scores.api.score_flag_schemas

API request and response models for score flags.

Classes:

leadr.scores.api.score_flag_schemas.ScoreFlagResponse

Bases: BaseModel

Response model for a score flag.

Functions:

  • from_domain – Convert domain entity to response model.

Attributes:

# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.confidence
confidence: str = Field(description='Confidence level of the flag (LOW, MEDIUM, HIGH)')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.created_at
created_at: datetime = Field(description='Timestamp when the flag was created (UTC)')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.flag_type
flag_type: str = Field(description='Type of flag (e.g., VELOCITY, DUPLICATE, RATE_LIMIT)')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.from_domain
from_domain(flag)

Convert domain entity to response model.

Parameters:

  • flag (ScoreFlag) – The domain ScoreFlag entity to convert.

Returns:

  • ScoreFlagResponse – ScoreFlagResponse with all fields populated from the domain entity.
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.id
id: ScoreFlagID = Field(description='Unique identifier for the score flag')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.metadata
metadata: dict[str, Any] = Field(description='Additional metadata about the flag')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.reviewed_at
reviewed_at: datetime | None = Field(default=None, description='Timestamp when flag was reviewed, or null')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.reviewer_decision
reviewer_decision: str | None = Field(default=None, description="Admin's decision/notes, or null")
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.reviewer_id
reviewer_id: UserID | None = Field(default=None, description='ID of the user who reviewed this flag, or null')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.score_id
score_id: ScoreID = Field(description='ID of the score that was flagged')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.status
status: str = Field(description='Status: PENDING, CONFIRMED_CHEAT, FALSE_POSITIVE, or DISMISSED')
# leadr.scores.api.score_flag_schemas.ScoreFlagResponse.updated_at
updated_at: datetime = Field(description='Timestamp of last update (UTC)')
leadr.scores.api.score_flag_schemas.ScoreFlagUpdateRequest

Bases: BaseModel

Request model for updating a score flag (reviewing).

Attributes:

# leadr.scores.api.score_flag_schemas.ScoreFlagUpdateRequest.deleted
deleted: bool | None = Field(default=None, description='Set to true to soft delete the flag')
# leadr.scores.api.score_flag_schemas.ScoreFlagUpdateRequest.reviewer_decision
reviewer_decision: str | None = Field(default=None, description="Admin's decision/notes about the flag")
# leadr.scores.api.score_flag_schemas.ScoreFlagUpdateRequest.status
status: str | None = Field(default=None, description='Updated status: PENDING, CONFIRMED_CHEAT, FALSE_POSITIVE, or DISMISSED')
leadr.scores.api.score_routes

API routes for score management.

Functions:

Attributes:

leadr.scores.api.score_routes.client_router
client_router = APIRouter()
leadr.scores.api.score_routes.create_score_admin
create_score_admin(score_request, request, service, background_tasks, auth)

Create a new score (Admin API).

Creates a new score submission for a board. Performs three-level validation: board exists, board belongs to the specified account, and game matches the board's game.

For regular admins: account_id is derived from auth, must provide game_id and device_id. For superadmins: can provide account_id to create scores for any account.

Parameters:

  • score_request (ScoreCreateRequest) – Score creation details including board_id, player_name, value, and optionally account_id (superadmin only), game_id, device_id.
  • request (Request) – FastAPI request object for accessing geo data.
  • service (ScoreServiceDep) – Injected score service dependency.
  • background_tasks (BackgroundTasks) – FastAPI background tasks for async metadata updates.
  • auth (AdminAuthContextDep) – Admin authentication context.

Returns:

  • ScoreResponse – ScoreResponse with the created score including auto-generated ID and timestamps.

Raises:

  • 403 – Non-superadmin tries to specify account_id, or access denied.
  • 400 – Missing required fields (game_id or device_id).
  • 404 – Account, game, board, or device not found.
  • 400 – Validation failed (board doesn't belong to account, or game doesn't match board's game).
leadr.scores.api.score_routes.create_score_client
create_score_client(score_request, request, service, background_tasks, auth)

Create a new score (Client API).

Creates a new score submission for a board. All IDs (account_id, game_id, device_id) are automatically derived from the authenticated device session.

Parameters:

Returns:

Raises:

  • 404 – Board not found.
  • 400 – Validation failed (board doesn't belong to account, or game doesn't match board's game).
leadr.scores.api.score_routes.get_score
get_score(score_id, service, auth)

Get a score by ID.

Parameters:

Returns:

Raises:

  • 403 – User does not have access to this score's account.
  • 404 – Score not found or soft-deleted.
leadr.scores.api.score_routes.handle_list_scores
handle_list_scores(auth, service, pagination, account_id, board_id, game_id, device_id)

Handle list scores logic for both admin and client endpoints.

This shared handler implements the core list scores functionality and returns different response models based on the authentication type:

  • Admin auth: Returns ScoreResponse with device_id and geo fields
  • Client auth: Returns ScoreClientResponse without device_id and geo fields

Parameters:

  • auth (AuthContext) – Authentication context (admin or client).
  • service (ScoreService) – Score service for data access.
  • pagination (PaginationParams) – Pagination parameters (cursor, limit, sort).
  • account_id (AccountID | None) – Optional account ID filter.
  • board_id (BoardID | None) – Optional board ID filter.
  • game_id (GameID | None) – Optional game ID filter.
  • device_id (DeviceID | None) – Optional device ID filter.

Returns:

Raises:

  • HTTPException – 400 if cursor is invalid or sort field is invalid.
leadr.scores.api.score_routes.list_scores_admin
list_scores_admin(auth, service, pagination, account_id=None, board_id=None, game_id=None, device_id=None)

List scores for an account with optional filters and pagination.

Returns paginated scores for the specified account, with optional filtering by board, game, or device. Supports cursor-based pagination with bidirectional navigation and custom sorting.

For regular admin users, account_id is automatically derived from their API key. For superadmins, account_id must be explicitly provided as a query parameter.

Pagination:

  • Default: 20 items per page, sorted by created_at:desc,id:asc
  • Custom sort: Use ?sort=value:desc,created_at:asc
  • Valid sort fields: id, value, player_name, filter_timezone, filter_country, filter_city, created_at, updated_at
  • Navigation: Use next_cursor/prev_cursor from response
Example GET /v1/scores?board_id=brd_123&limit=50&sort=value:desc,created_at:asc

Parameters:

  • auth (AdminAuthContextDep) – Authentication context with user info.
  • service (ScoreServiceDep) – Injected score service dependency.
  • pagination (Annotated[PaginationParams, Depends()]) – Pagination parameters (cursor, limit, sort).
  • account_id (Annotated[AccountID | None, Query(description='Account ID filter')]) – Optional account_id query parameter (required for superadmins).
  • board_id (BoardID | None) – Optional board ID to filter by.
  • game_id (GameID | None) – Optional game ID to filter by.
  • device_id (DeviceID | None) – Optional device ID to filter by.

Returns:

Raises:

  • 400 – Invalid cursor, sort field, or cursor state mismatch.
  • 400 – Superadmin did not provide account_id.
  • 403 – User does not have access to the specified account.
leadr.scores.api.score_routes.list_scores_client
list_scores_client(auth, service, pagination, board_id=None)

List scores for an account with optional filters and pagination.

Returns paginated scores for the specified account, with optional filtering by board. Supports cursor-based pagination with bidirectional navigation and custom sorting.

Pagination:

  • Default: 20 items per page, sorted by created_at:desc,id:asc
  • Custom sort: Use ?sort=value:desc,created_at:asc
  • Valid sort fields: id, value, player_name, filter_timezone, filter_country, filter_city, created_at, updated_at
  • Navigation: Use next_cursor/prev_cursor from response
Example GET /v1/scores?board_id=brd_123&limit=50&sort=value:desc,created_at:asc

Parameters:

Returns:

Raises:

  • 400 – Invalid cursor, sort field, or cursor state mismatch.
  • 400 – Superadmin did not provide account_id.
  • 403 – User does not have access to the specified account.
leadr.scores.api.score_routes.router
router = APIRouter()
leadr.scores.api.score_routes.update_score
update_score(score_id, request, service, auth)

Update a score.

Supports partial updates of score fields. Any field not provided will remain unchanged. Set deleted: true to soft delete the score.

Parameters:

Returns:

  • ScoreResponse – ScoreResponse with the updated score details.

Raises:

  • 403 – User does not have access to this score's account.
  • 404 – Score not found or already soft-deleted.
leadr.scores.api.score_schemas

API request and response models for scores.

Classes:

leadr.scores.api.score_schemas.ScoreClientCreateRequest

Bases: ScoreCreateRequestBase

Request model for creating a score (Client API).

For client authentication, account_id, game_id, and device_id are automatically derived from the authenticated device session. Only game-specific fields are required.

Note: Timezone, country, and city are automatically populated from the client's IP address via GeoIP middleware.

Functions:

Attributes:

leadr.scores.api.score_schemas.ScoreClientResponse

Bases: BaseModel

Response model for a score (client API - excludes device_id and geo fields).

Functions:

  • from_domain – Convert domain entity to client response model (without device_id or geo fields).

Attributes:

# leadr.scores.api.score_schemas.ScoreClientResponse.account_id
account_id: AccountID = Field(description='ID of the account this score belongs to')
# leadr.scores.api.score_schemas.ScoreClientResponse.board_id
board_id: BoardID = Field(description='ID of the board this score belongs to')
# leadr.scores.api.score_schemas.ScoreClientResponse.created_at
created_at: datetime = Field(description='Timestamp when the score was created (UTC)')
# leadr.scores.api.score_schemas.ScoreClientResponse.from_domain
from_domain(score)

Convert domain entity to client response model (without device_id or geo fields).

Parameters:

  • score (Score) – The domain Score entity to convert.

Returns:

  • ScoreClientResponse – ScoreClientResponse with all fields except device_id, timezone, country, and city.
# leadr.scores.api.score_schemas.ScoreClientResponse.game_id
game_id: GameID = Field(description='ID of the game this score belongs to')
# leadr.scores.api.score_schemas.ScoreClientResponse.id
id: ScoreID = Field(description='Unique identifier for the score')
# leadr.scores.api.score_schemas.ScoreClientResponse.metadata
metadata: Any | None = Field(default=None, description='Game-specific metadata, or null')
# leadr.scores.api.score_schemas.ScoreClientResponse.player_name
player_name: str = Field(description='Display name of the player')
# leadr.scores.api.score_schemas.ScoreClientResponse.updated_at
updated_at: datetime = Field(description='Timestamp of last update (UTC)')
# leadr.scores.api.score_schemas.ScoreClientResponse.value
value: float = Field(description='Numeric value of the score')
# leadr.scores.api.score_schemas.ScoreClientResponse.value_display
value_display: str | None = Field(default=None, description='Formatted display string, or null')
leadr.scores.api.score_schemas.ScoreCreateRequest

Bases: ScoreCreateRequestBase

Request model for creating a score (Admin API).

Note: Timezone, country, and city are automatically populated from the client's IP address via GeoIP middleware but can be overriden by admins in the request body.

For regular admins: account_id is derived from auth context, must provide game_id and device_id. For superadmins: can provide account_id to create scores for any account, must provide game_id and device_id.

Functions:

Attributes:

# leadr.scores.api.score_schemas.ScoreCreateRequest.account_id
account_id: AccountID | None = Field(default=None, description='ID of the account (only for superadmins, regular admins use their auth account)')
# leadr.scores.api.score_schemas.ScoreCreateRequest.board_id
board_id: BoardID = Field(description='ID of the board this score belongs to')
# leadr.scores.api.score_schemas.ScoreCreateRequest.city
city: str | None = Field(default=None, description='Optional override of GeoIP metadata')
# leadr.scores.api.score_schemas.ScoreCreateRequest.country
country: str | None = Field(default=None, description='Optional override of GeoIP metadata')
# leadr.scores.api.score_schemas.ScoreCreateRequest.device_id
device_id: DeviceID = Field(description='ID of the device that submitted this score (required for admin API)')
# leadr.scores.api.score_schemas.ScoreCreateRequest.game_id
game_id: GameID = Field(description='ID of the game this score belongs to (required for admin API)')
# leadr.scores.api.score_schemas.ScoreCreateRequest.metadata
metadata: Any | None = Field(default=None, description='Optional JSON metadata for game-specific data (max 1KB)')
# leadr.scores.api.score_schemas.ScoreCreateRequest.player_name
player_name: str = Field(description='Display name of the player')
# leadr.scores.api.score_schemas.ScoreCreateRequest.timezone
timezone: str | None = Field(default=None, description='Optional override of GeoIP metadata')
# leadr.scores.api.score_schemas.ScoreCreateRequest.validate_metadata_size
validate_metadata_size(v)

Validate that metadata does not exceed size limit.

# leadr.scores.api.score_schemas.ScoreCreateRequest.value
value: float = Field(description='Numeric value of the score for sorting/comparison')
# leadr.scores.api.score_schemas.ScoreCreateRequest.value_display
value_display: str | None = Field(default=None, description="Optional formatted display string (e.g., '1:23.45', '1,234 points')")
leadr.scores.api.score_schemas.ScoreCreateRequestBase

Bases: BaseModel

Base request model for score creation with common fields.

Functions:

Attributes:

# leadr.scores.api.score_schemas.ScoreCreateRequestBase.board_id
board_id: BoardID = Field(description='ID of the board this score belongs to')
# leadr.scores.api.score_schemas.ScoreCreateRequestBase.metadata
metadata: Any | None = Field(default=None, description='Optional JSON metadata for game-specific data (max 1KB)')
# leadr.scores.api.score_schemas.ScoreCreateRequestBase.player_name
player_name: str = Field(description='Display name of the player')
# leadr.scores.api.score_schemas.ScoreCreateRequestBase.validate_metadata_size
validate_metadata_size(v)

Validate that metadata does not exceed size limit.

# leadr.scores.api.score_schemas.ScoreCreateRequestBase.value
value: float = Field(description='Numeric value of the score for sorting/comparison')
# leadr.scores.api.score_schemas.ScoreCreateRequestBase.value_display
value_display: str | None = Field(default=None, description="Optional formatted display string (e.g., '1:23.45', '1,234 points')")
leadr.scores.api.score_schemas.ScoreResponse

Bases: BaseModel

Response model for a score.

Functions:

  • from_domain – Convert domain entity to response model.

Attributes:

# leadr.scores.api.score_schemas.ScoreResponse.account_id
account_id: AccountID = Field(description='ID of the account this score belongs to')
# leadr.scores.api.score_schemas.ScoreResponse.board_id
board_id: BoardID = Field(description='ID of the board this score belongs to')
# leadr.scores.api.score_schemas.ScoreResponse.city
city: str | None = Field(default=None, description='City for categorization, or null')
# leadr.scores.api.score_schemas.ScoreResponse.country
country: str | None = Field(default=None, description='Country for categorization, or null')
# leadr.scores.api.score_schemas.ScoreResponse.created_at
created_at: datetime = Field(description='Timestamp when the score was created (UTC)')
# leadr.scores.api.score_schemas.ScoreResponse.device_id
device_id: DeviceID = Field(description='ID of the device that submitted this score')
# leadr.scores.api.score_schemas.ScoreResponse.from_domain
from_domain(score)

Convert domain entity to response model.

Parameters:

  • score (Score) – The domain Score entity to convert.

Returns:

  • ScoreResponse – ScoreResponse with all fields populated from the domain entity.
# leadr.scores.api.score_schemas.ScoreResponse.game_id
game_id: GameID = Field(description='ID of the game this score belongs to')
# leadr.scores.api.score_schemas.ScoreResponse.id
id: ScoreID = Field(description='Unique identifier for the score')
# leadr.scores.api.score_schemas.ScoreResponse.metadata
metadata: Any | None = Field(default=None, description='Game-specific metadata, or null')
# leadr.scores.api.score_schemas.ScoreResponse.player_name
player_name: str = Field(description='Display name of the player')
# leadr.scores.api.score_schemas.ScoreResponse.timezone
timezone: str | None = Field(default=None, description='Timezone for categorization, or null')
# leadr.scores.api.score_schemas.ScoreResponse.updated_at
updated_at: datetime = Field(description='Timestamp of last update (UTC)')
# leadr.scores.api.score_schemas.ScoreResponse.value
value: float = Field(description='Numeric value of the score')
# leadr.scores.api.score_schemas.ScoreResponse.value_display
value_display: str | None = Field(default=None, description='Formatted display string, or null')
leadr.scores.api.score_schemas.ScoreUpdateRequest

Bases: BaseModel

Request model for updating a score.

Functions:

Attributes:

# leadr.scores.api.score_schemas.ScoreUpdateRequest.city
city: str | None = Field(default=None, description='Updated city')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.country
country: str | None = Field(default=None, description='Updated country')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.deleted
deleted: bool | None = Field(default=None, description='Set to true to soft delete the score')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.metadata
metadata: Any | None = Field(default=None, description='Updated metadata')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.player_name
player_name: str | None = Field(default=None, description='Updated player name')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.timezone
timezone: str | None = Field(default=None, description='Updated timezone')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.validate_metadata_size
validate_metadata_size(v)

Validate that metadata does not exceed size limit.

# leadr.scores.api.score_schemas.ScoreUpdateRequest.value
value: float | None = Field(default=None, description='Updated score value')
# leadr.scores.api.score_schemas.ScoreUpdateRequest.value_display
value_display: str | None = Field(default=None, description='Updated display string')
leadr.scores.api.score_submission_meta_routes

API routes for score submission metadata management.

Functions:

Attributes:

leadr.scores.api.score_submission_meta_routes.get_submission_meta
get_submission_meta(meta_id, service, auth)

Get score submission metadata by ID.

Parameters:

Returns:

Raises:

  • 403 – User does not have access to this metadata's account.
  • 404 – Submission metadata not found or soft-deleted.
leadr.scores.api.score_submission_meta_routes.list_submission_meta
list_submission_meta(auth, service, account_id=None, board_id=None, device_id=None)

List score submission metadata for an account with optional filters.

Returns all non-deleted submission metadata for the specified account, with optional filtering by board or device.

For regular users, account_id is automatically derived from their API key. For superadmins, account_id is optional - if omitted, returns metadata from all accounts.

Parameters:

  • auth (AdminAuthContextDep) – Authentication context with user info.
  • service (ScoreSubmissionMetaServiceDep) – Injected submission metadata service dependency.
  • account_id (Annotated[AccountID | None, Query(description='Account ID filter')]) – Optional account_id query parameter (superadmins can omit to see all).
  • board_id (BoardID | None) – Optional board ID to filter by.
  • device_id (DeviceID | None) – Optional device ID to filter by.

Returns:

Raises:

  • 403 – User does not have access to the specified account.
leadr.scores.api.score_submission_meta_routes.router
router = APIRouter()
leadr.scores.api.score_submission_meta_schemas

API schemas for score submission metadata.

Classes:

leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse

Bases: BaseModel

Response model for score submission metadata.

Functions:

  • from_domain – Convert domain entity to API response.

Attributes:

# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.board_id
board_id: BoardID
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.created_at
created_at: datetime
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.device_id
device_id: DeviceID
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.from_domain
from_domain(meta)

Convert domain entity to API response.

# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.id
id: ScoreSubmissionMetaID
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.last_score_value
last_score_value: float | None
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.last_submission_at
last_submission_at: datetime
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.score_id
score_id: ScoreID
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.submission_count
submission_count: int
# leadr.scores.api.score_submission_meta_schemas.ScoreSubmissionMetaResponse.updated_at
updated_at: datetime

leadr.scores.domain

Modules:

  • anti_cheat – Anti-cheat domain models and enums.
  • score – Score domain entity.
leadr.scores.domain.anti_cheat

Anti-cheat domain models and enums.

Modules:

  • enums – Anti-cheat enums for flag types, confidence levels, and actions.
  • models – Anti-cheat domain models.

Classes:

  • AntiCheatResult – Result of anti-cheat analysis on a score submission.
  • FlagAction – Action to take based on anti-cheat analysis.
  • FlagConfidence – Confidence level for anti-cheat detection.
  • FlagType – Type of anti-cheat flag detected.
  • ScoreFlag – Record of an anti-cheat flag raised for a score submission.
  • ScoreSubmissionMeta – Metadata tracking submission history for anti-cheat analysis.
  • TrustTier – Trust tier for devices/users, determining anti-cheat thresholds.
leadr.scores.domain.anti_cheat.AntiCheatResult

Bases: BaseModel

Result of anti-cheat analysis on a score submission.

This is a value object that encapsulates the decision made by the anti-cheat system. It indicates whether to accept, flag, or reject a score submission, along with the reasoning and supporting metadata.

Attributes:

# leadr.scores.domain.anti_cheat.AntiCheatResult.action
action: FlagAction = Field(description='Action to take (ACCEPT/FLAG/REJECT)')
# leadr.scores.domain.anti_cheat.AntiCheatResult.confidence
confidence: FlagConfidence | None = Field(default=None, description='Confidence level of detection (if flagged/rejected)')
# leadr.scores.domain.anti_cheat.AntiCheatResult.flag_type
flag_type: FlagType | None = Field(default=None, description='Type of flag detected (if flagged/rejected)')
# leadr.scores.domain.anti_cheat.AntiCheatResult.metadata
metadata: dict[str, Any] | None = Field(default=None, description='Additional context and data supporting the decision')
# leadr.scores.domain.anti_cheat.AntiCheatResult.model_config
model_config = {'frozen': True}
# leadr.scores.domain.anti_cheat.AntiCheatResult.reason
reason: str | None = Field(default=None, description='Human-readable reason for the action')
leadr.scores.domain.anti_cheat.FlagAction

Bases: str, Enum

Action to take based on anti-cheat analysis.

Determines how the score submission should be handled.

Attributes:

  • ACCEPT – Accept the score submission without any flags.
  • FLAG – Accept the score but flag it for manual review.
  • REJECT – Reject the score submission (do not save to database).
# leadr.scores.domain.anti_cheat.FlagAction.ACCEPT
ACCEPT = 'ACCEPT'

Accept the score submission without any flags.

# leadr.scores.domain.anti_cheat.FlagAction.FLAG
FLAG = 'FLAG'

Accept the score but flag it for manual review.

# leadr.scores.domain.anti_cheat.FlagAction.REJECT
REJECT = 'REJECT'

Reject the score submission (do not save to database).

leadr.scores.domain.anti_cheat.FlagConfidence

Bases: str, Enum

Confidence level for anti-cheat detection.

Determines the action taken when a flag is raised:

  • HIGH: Auto-reject submission
  • MEDIUM: Flag for manual review, accept submission
  • LOW: Log for analysis, accept submission

Attributes:

  • HIGH – High confidence detection - reject submission.
  • LOW – Low confidence detection - log but accept.
  • MEDIUM – Medium confidence detection - flag for review but accept.
# leadr.scores.domain.anti_cheat.FlagConfidence.HIGH
HIGH = 'HIGH'

High confidence detection - reject submission.

# leadr.scores.domain.anti_cheat.FlagConfidence.LOW
LOW = 'LOW'

Low confidence detection - log but accept.

# leadr.scores.domain.anti_cheat.FlagConfidence.MEDIUM
MEDIUM = 'MEDIUM'

Medium confidence detection - flag for review but accept.

leadr.scores.domain.anti_cheat.FlagType

Bases: str, Enum

Type of anti-cheat flag detected.

Each flag type represents a different detection tactic used to identify potentially suspicious score submissions.

Attributes:

  • CLUSTER – Multiple users submitting identical scores in short time window.
  • DUPLICATE – Identical score value submitted multiple times in short time window.
  • IMPOSSIBLE_VALUE – Score contains mathematically impossible value (negative, NaN, etc).
  • OUTLIER – Score is statistically anomalous compared to board distribution.
  • PATTERN – Suspicious pattern detected in submission history (all round numbers, etc).
  • PROGRESSION – Unrealistic improvement percentage between submissions.
  • RATE_LIMIT – Score submission exceeds rate limits for the user/board.
  • VELOCITY – Submissions are happening too quickly (< 2 seconds apart).
# leadr.scores.domain.anti_cheat.FlagType.CLUSTER
CLUSTER = 'CLUSTER'

Multiple users submitting identical scores in short time window.

# leadr.scores.domain.anti_cheat.FlagType.DUPLICATE
DUPLICATE = 'DUPLICATE'

Identical score value submitted multiple times in short time window.

# leadr.scores.domain.anti_cheat.FlagType.IMPOSSIBLE_VALUE
IMPOSSIBLE_VALUE = 'IMPOSSIBLE_VALUE'

Score contains mathematically impossible value (negative, NaN, etc).

# leadr.scores.domain.anti_cheat.FlagType.OUTLIER
OUTLIER = 'OUTLIER'

Score is statistically anomalous compared to board distribution.

# leadr.scores.domain.anti_cheat.FlagType.PATTERN
PATTERN = 'PATTERN'

Suspicious pattern detected in submission history (all round numbers, etc).

# leadr.scores.domain.anti_cheat.FlagType.PROGRESSION
PROGRESSION = 'PROGRESSION'

Unrealistic improvement percentage between submissions.

# leadr.scores.domain.anti_cheat.FlagType.RATE_LIMIT
RATE_LIMIT = 'RATE_LIMIT'

Score submission exceeds rate limits for the user/board.

# leadr.scores.domain.anti_cheat.FlagType.VELOCITY
VELOCITY = 'VELOCITY'

Submissions are happening too quickly (< 2 seconds apart).

leadr.scores.domain.anti_cheat.ScoreFlag

Bases: Entity

Record of an anti-cheat flag raised for a score submission.

Represents a suspicious pattern detected by the anti-cheat system. Flags can be reviewed by admins to confirm or dismiss the detection.

Functions:

Attributes:

# leadr.scores.domain.anti_cheat.ScoreFlag.confidence
confidence: FlagConfidence = Field(description='Confidence level of detection')
# leadr.scores.domain.anti_cheat.ScoreFlag.created_at
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp when entity was created (UTC)')
# leadr.scores.domain.anti_cheat.ScoreFlag.deleted_at
deleted_at: datetime | None = Field(default=None, description='Timestamp when entity was soft-deleted (UTC), or null if active')
# leadr.scores.domain.anti_cheat.ScoreFlag.flag_type
flag_type: FlagType = Field(description='Type of suspicious behavior detected')
# leadr.scores.domain.anti_cheat.ScoreFlag.id
id: ScoreFlagID = Field(frozen=True, default_factory=ScoreFlagID, description='Unique score flag identifier')
# leadr.scores.domain.anti_cheat.ScoreFlag.is_deleted
is_deleted: bool

Check if entity is soft-deleted.

Returns:

  • bool – True if the entity has a deleted_at timestamp, False otherwise.
# leadr.scores.domain.anti_cheat.ScoreFlag.metadata
metadata: dict[str, Any] = Field(default_factory=dict, description='Supporting data for the detection')
# leadr.scores.domain.anti_cheat.ScoreFlag.model_config
model_config = ConfigDict(validate_assignment=True)
# leadr.scores.domain.anti_cheat.ScoreFlag.restore
restore()

Restore a soft-deleted entity.

Clears the deleted_at timestamp, making the entity active again.

Example > > > account.soft_delete() > > > account.restore() > > > assert account.is_deleted is False
# leadr.scores.domain.anti_cheat.ScoreFlag.reviewed_at
reviewed_at: datetime | None = Field(default=None, description='When the flag was reviewed by an admin')
# leadr.scores.domain.anti_cheat.ScoreFlag.reviewer_decision
reviewer_decision: str | None = Field(default=None, description="Admin's decision/notes on the flag")
# leadr.scores.domain.anti_cheat.ScoreFlag.reviewer_id
reviewer_id: UserID | None = Field(default=None, description='ID of the admin who reviewed the flag')
# leadr.scores.domain.anti_cheat.ScoreFlag.score_id
score_id: ScoreID = Field(description='ID of the flagged score')
# leadr.scores.domain.anti_cheat.ScoreFlag.soft_delete
soft_delete()

Mark entity as soft-deleted.

Sets the deleted_at timestamp to the current UTC time. Entities that are already deleted are not affected (deleted_at remains at original deletion time).

Example > > > account = Account(name="Test", slug="test") > > > account.soft_delete() > > > assert account.is_deleted is True
# leadr.scores.domain.anti_cheat.ScoreFlag.status
status: ScoreFlagStatus = Field(default=(ScoreFlagStatus.PENDING), description='Review status (PENDING/CONFIRMED_CHEAT/FALSE_POSITIVE/DISMISSED)')
# leadr.scores.domain.anti_cheat.ScoreFlag.updated_at
updated_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp of last update (UTC)')
leadr.scores.domain.anti_cheat.ScoreSubmissionMeta

Bases: Entity

Metadata tracking submission history for anti-cheat analysis.

Tracks the number and timing of score submissions per device/board combination to enable detection of suspicious patterns like rapid-fire submissions or excessive submission rates.

Functions:

Attributes:

# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.board_id
board_id: BoardID = Field(description='ID of the board being submitted to')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.created_at
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp when entity was created (UTC)')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.deleted_at
deleted_at: datetime | None = Field(default=None, description='Timestamp when entity was soft-deleted (UTC), or null if active')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.device_id
device_id: DeviceID = Field(description='ID of the device submitting scores')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.id
id: ScoreSubmissionMetaID = Field(frozen=True, default_factory=ScoreSubmissionMetaID, description='Unique submission metadata identifier')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.is_deleted
is_deleted: bool

Check if entity is soft-deleted.

Returns:

  • bool – True if the entity has a deleted_at timestamp, False otherwise.
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.last_score_value
last_score_value: float | None = Field(default=None, description='Value of the most recent score submission for duplicate detection')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.last_submission_at
last_submission_at: datetime = Field(description='Timestamp of the most recent submission')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.model_config
model_config = ConfigDict(validate_assignment=True)
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.restore
restore()

Restore a soft-deleted entity.

Clears the deleted_at timestamp, making the entity active again.

Example > > > account.soft_delete() > > > account.restore() > > > assert account.is_deleted is False
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.score_id
score_id: ScoreID = Field(description='ID of the most recent score submission')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.soft_delete
soft_delete()

Mark entity as soft-deleted.

Sets the deleted_at timestamp to the current UTC time. Entities that are already deleted are not affected (deleted_at remains at original deletion time).

Example > > > account = Account(name="Test", slug="test") > > > account.soft_delete() > > > assert account.is_deleted is True
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.submission_count
submission_count: int = Field(default=1, description='Total number of submissions by this device to this board')
# leadr.scores.domain.anti_cheat.ScoreSubmissionMeta.updated_at
updated_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp of last update (UTC)')
leadr.scores.domain.anti_cheat.TrustTier

Bases: str, Enum

Trust tier for devices/users, determining anti-cheat thresholds.

Different tiers have different rate limits and detection thresholds:

  • Tier A (Trusted): Most lenient thresholds, highest rate limits
  • Tier B (Verified): Moderate thresholds and rate limits
  • Tier C (Unverified): Strictest thresholds, lowest rate limits

Attributes:

  • A – Tier A - Trusted devices with verified attestation.
  • B – Tier B - Verified devices without full attestation.
  • C – Tier C - Unverified or new devices.
# leadr.scores.domain.anti_cheat.TrustTier.A
A = 'A'

Tier A - Trusted devices with verified attestation.

# leadr.scores.domain.anti_cheat.TrustTier.B
B = 'B'

Tier B - Verified devices without full attestation.

# leadr.scores.domain.anti_cheat.TrustTier.C
C = 'C'

Tier C - Unverified or new devices.

leadr.scores.domain.anti_cheat.enums

Anti-cheat enums for flag types, confidence levels, and actions.

Classes:

  • FlagAction – Action to take based on anti-cheat analysis.
  • FlagConfidence – Confidence level for anti-cheat detection.
  • FlagType – Type of anti-cheat flag detected.
  • ScoreFlagStatus – Status of a score flag review.
  • TrustTier – Trust tier for devices/users, determining anti-cheat thresholds.
# leadr.scores.domain.anti_cheat.enums.FlagAction

Bases: str, Enum

Action to take based on anti-cheat analysis.

Determines how the score submission should be handled.

Attributes:

  • ACCEPT – Accept the score submission without any flags.
  • FLAG – Accept the score but flag it for manual review.
  • REJECT – Reject the score submission (do not save to database).
## leadr.scores.domain.anti_cheat.enums.FlagAction.ACCEPT
ACCEPT = 'ACCEPT'

Accept the score submission without any flags.

## leadr.scores.domain.anti_cheat.enums.FlagAction.FLAG
FLAG = 'FLAG'

Accept the score but flag it for manual review.

## leadr.scores.domain.anti_cheat.enums.FlagAction.REJECT
REJECT = 'REJECT'

Reject the score submission (do not save to database).

# leadr.scores.domain.anti_cheat.enums.FlagConfidence

Bases: str, Enum

Confidence level for anti-cheat detection.

Determines the action taken when a flag is raised:

  • HIGH: Auto-reject submission
  • MEDIUM: Flag for manual review, accept submission
  • LOW: Log for analysis, accept submission

Attributes:

  • HIGH – High confidence detection - reject submission.
  • LOW – Low confidence detection - log but accept.
  • MEDIUM – Medium confidence detection - flag for review but accept.
## leadr.scores.domain.anti_cheat.enums.FlagConfidence.HIGH
HIGH = 'HIGH'

High confidence detection - reject submission.

## leadr.scores.domain.anti_cheat.enums.FlagConfidence.LOW
LOW = 'LOW'

Low confidence detection - log but accept.

## leadr.scores.domain.anti_cheat.enums.FlagConfidence.MEDIUM
MEDIUM = 'MEDIUM'

Medium confidence detection - flag for review but accept.

# leadr.scores.domain.anti_cheat.enums.FlagType

Bases: str, Enum

Type of anti-cheat flag detected.

Each flag type represents a different detection tactic used to identify potentially suspicious score submissions.

Attributes:

  • CLUSTER – Multiple users submitting identical scores in short time window.
  • DUPLICATE – Identical score value submitted multiple times in short time window.
  • IMPOSSIBLE_VALUE – Score contains mathematically impossible value (negative, NaN, etc).
  • OUTLIER – Score is statistically anomalous compared to board distribution.
  • PATTERN – Suspicious pattern detected in submission history (all round numbers, etc).
  • PROGRESSION – Unrealistic improvement percentage between submissions.
  • RATE_LIMIT – Score submission exceeds rate limits for the user/board.
  • VELOCITY – Submissions are happening too quickly (< 2 seconds apart).
## leadr.scores.domain.anti_cheat.enums.FlagType.CLUSTER
CLUSTER = 'CLUSTER'

Multiple users submitting identical scores in short time window.

## leadr.scores.domain.anti_cheat.enums.FlagType.DUPLICATE
DUPLICATE = 'DUPLICATE'

Identical score value submitted multiple times in short time window.

## leadr.scores.domain.anti_cheat.enums.FlagType.IMPOSSIBLE_VALUE
IMPOSSIBLE_VALUE = 'IMPOSSIBLE_VALUE'

Score contains mathematically impossible value (negative, NaN, etc).

## leadr.scores.domain.anti_cheat.enums.FlagType.OUTLIER
OUTLIER = 'OUTLIER'

Score is statistically anomalous compared to board distribution.

## leadr.scores.domain.anti_cheat.enums.FlagType.PATTERN
PATTERN = 'PATTERN'

Suspicious pattern detected in submission history (all round numbers, etc).

## leadr.scores.domain.anti_cheat.enums.FlagType.PROGRESSION
PROGRESSION = 'PROGRESSION'

Unrealistic improvement percentage between submissions.

## leadr.scores.domain.anti_cheat.enums.FlagType.RATE_LIMIT
RATE_LIMIT = 'RATE_LIMIT'

Score submission exceeds rate limits for the user/board.

## leadr.scores.domain.anti_cheat.enums.FlagType.VELOCITY
VELOCITY = 'VELOCITY'

Submissions are happening too quickly (< 2 seconds apart).

# leadr.scores.domain.anti_cheat.enums.ScoreFlagStatus

Bases: str, Enum

Status of a score flag review.

Indicates whether a flag has been reviewed and what decision was made.

Attributes:

  • CONFIRMED_CHEAT – Admin confirmed this is cheating behavior.
  • DISMISSED – Admin dismissed the flag without a specific determination.
  • FALSE_POSITIVE – Admin determined this was legitimate gameplay.
  • PENDING – Flag has not been reviewed yet.
## leadr.scores.domain.anti_cheat.enums.ScoreFlagStatus.CONFIRMED_CHEAT
CONFIRMED_CHEAT = 'CONFIRMED_CHEAT'

Admin confirmed this is cheating behavior.

## leadr.scores.domain.anti_cheat.enums.ScoreFlagStatus.DISMISSED
DISMISSED = 'DISMISSED'

Admin dismissed the flag without a specific determination.

## leadr.scores.domain.anti_cheat.enums.ScoreFlagStatus.FALSE_POSITIVE
FALSE_POSITIVE = 'FALSE_POSITIVE'

Admin determined this was legitimate gameplay.

## leadr.scores.domain.anti_cheat.enums.ScoreFlagStatus.PENDING
PENDING = 'PENDING'

Flag has not been reviewed yet.

# leadr.scores.domain.anti_cheat.enums.TrustTier

Bases: str, Enum

Trust tier for devices/users, determining anti-cheat thresholds.

Different tiers have different rate limits and detection thresholds:

  • Tier A (Trusted): Most lenient thresholds, highest rate limits
  • Tier B (Verified): Moderate thresholds and rate limits
  • Tier C (Unverified): Strictest thresholds, lowest rate limits

Attributes:

  • A – Tier A - Trusted devices with verified attestation.
  • B – Tier B - Verified devices without full attestation.
  • C – Tier C - Unverified or new devices.
## leadr.scores.domain.anti_cheat.enums.TrustTier.A
A = 'A'

Tier A - Trusted devices with verified attestation.

## leadr.scores.domain.anti_cheat.enums.TrustTier.B
B = 'B'

Tier B - Verified devices without full attestation.

## leadr.scores.domain.anti_cheat.enums.TrustTier.C
C = 'C'

Tier C - Unverified or new devices.

leadr.scores.domain.anti_cheat.models

Anti-cheat domain models.

Classes:

  • AntiCheatResult – Result of anti-cheat analysis on a score submission.
  • ScoreFlag – Record of an anti-cheat flag raised for a score submission.
  • ScoreSubmissionMeta – Metadata tracking submission history for anti-cheat analysis.
# leadr.scores.domain.anti_cheat.models.AntiCheatResult

Bases: BaseModel

Result of anti-cheat analysis on a score submission.

This is a value object that encapsulates the decision made by the anti-cheat system. It indicates whether to accept, flag, or reject a score submission, along with the reasoning and supporting metadata.

Attributes:

## leadr.scores.domain.anti_cheat.models.AntiCheatResult.action
action: FlagAction = Field(description='Action to take (ACCEPT/FLAG/REJECT)')
## leadr.scores.domain.anti_cheat.models.AntiCheatResult.confidence
confidence: FlagConfidence | None = Field(default=None, description='Confidence level of detection (if flagged/rejected)')
## leadr.scores.domain.anti_cheat.models.AntiCheatResult.flag_type
flag_type: FlagType | None = Field(default=None, description='Type of flag detected (if flagged/rejected)')
## leadr.scores.domain.anti_cheat.models.AntiCheatResult.metadata
metadata: dict[str, Any] | None = Field(default=None, description='Additional context and data supporting the decision')
## leadr.scores.domain.anti_cheat.models.AntiCheatResult.model_config
model_config = {'frozen': True}
## leadr.scores.domain.anti_cheat.models.AntiCheatResult.reason
reason: str | None = Field(default=None, description='Human-readable reason for the action')
# leadr.scores.domain.anti_cheat.models.ScoreFlag

Bases: Entity

Record of an anti-cheat flag raised for a score submission.

Represents a suspicious pattern detected by the anti-cheat system. Flags can be reviewed by admins to confirm or dismiss the detection.

Functions:

Attributes:

## leadr.scores.domain.anti_cheat.models.ScoreFlag.confidence
confidence: FlagConfidence = Field(description='Confidence level of detection')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.created_at
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp when entity was created (UTC)')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.deleted_at
deleted_at: datetime | None = Field(default=None, description='Timestamp when entity was soft-deleted (UTC), or null if active')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.flag_type
flag_type: FlagType = Field(description='Type of suspicious behavior detected')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.id
id: ScoreFlagID = Field(frozen=True, default_factory=ScoreFlagID, description='Unique score flag identifier')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.is_deleted
is_deleted: bool

Check if entity is soft-deleted.

Returns:

  • bool – True if the entity has a deleted_at timestamp, False otherwise.
## leadr.scores.domain.anti_cheat.models.ScoreFlag.metadata
metadata: dict[str, Any] = Field(default_factory=dict, description='Supporting data for the detection')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.model_config
model_config = ConfigDict(validate_assignment=True)
## leadr.scores.domain.anti_cheat.models.ScoreFlag.restore
restore()

Restore a soft-deleted entity.

Clears the deleted_at timestamp, making the entity active again.

Example > > > account.soft_delete() > > > account.restore() > > > assert account.is_deleted is False
## leadr.scores.domain.anti_cheat.models.ScoreFlag.reviewed_at
reviewed_at: datetime | None = Field(default=None, description='When the flag was reviewed by an admin')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.reviewer_decision
reviewer_decision: str | None = Field(default=None, description="Admin's decision/notes on the flag")
## leadr.scores.domain.anti_cheat.models.ScoreFlag.reviewer_id
reviewer_id: UserID | None = Field(default=None, description='ID of the admin who reviewed the flag')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.score_id
score_id: ScoreID = Field(description='ID of the flagged score')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.soft_delete
soft_delete()

Mark entity as soft-deleted.

Sets the deleted_at timestamp to the current UTC time. Entities that are already deleted are not affected (deleted_at remains at original deletion time).

Example > > > account = Account(name="Test", slug="test") > > > account.soft_delete() > > > assert account.is_deleted is True
## leadr.scores.domain.anti_cheat.models.ScoreFlag.status
status: ScoreFlagStatus = Field(default=(ScoreFlagStatus.PENDING), description='Review status (PENDING/CONFIRMED_CHEAT/FALSE_POSITIVE/DISMISSED)')
## leadr.scores.domain.anti_cheat.models.ScoreFlag.updated_at
updated_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp of last update (UTC)')
# leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta

Bases: Entity

Metadata tracking submission history for anti-cheat analysis.

Tracks the number and timing of score submissions per device/board combination to enable detection of suspicious patterns like rapid-fire submissions or excessive submission rates.

Functions:

Attributes:

## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.board_id
board_id: BoardID = Field(description='ID of the board being submitted to')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.created_at
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp when entity was created (UTC)')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.deleted_at
deleted_at: datetime | None = Field(default=None, description='Timestamp when entity was soft-deleted (UTC), or null if active')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.device_id
device_id: DeviceID = Field(description='ID of the device submitting scores')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.id
id: ScoreSubmissionMetaID = Field(frozen=True, default_factory=ScoreSubmissionMetaID, description='Unique submission metadata identifier')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.is_deleted
is_deleted: bool

Check if entity is soft-deleted.

Returns:

  • bool – True if the entity has a deleted_at timestamp, False otherwise.
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.last_score_value
last_score_value: float | None = Field(default=None, description='Value of the most recent score submission for duplicate detection')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.last_submission_at
last_submission_at: datetime = Field(description='Timestamp of the most recent submission')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.model_config
model_config = ConfigDict(validate_assignment=True)
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.restore
restore()

Restore a soft-deleted entity.

Clears the deleted_at timestamp, making the entity active again.

Example > > > account.soft_delete() > > > account.restore() > > > assert account.is_deleted is False
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.score_id
score_id: ScoreID = Field(description='ID of the most recent score submission')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.soft_delete
soft_delete()

Mark entity as soft-deleted.

Sets the deleted_at timestamp to the current UTC time. Entities that are already deleted are not affected (deleted_at remains at original deletion time).

Example > > > account = Account(name="Test", slug="test") > > > account.soft_delete() > > > assert account.is_deleted is True
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.submission_count
submission_count: int = Field(default=1, description='Total number of submissions by this device to this board')
## leadr.scores.domain.anti_cheat.models.ScoreSubmissionMeta.updated_at
updated_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp of last update (UTC)')
leadr.scores.domain.score

Score domain entity.

Classes:

  • Score – Score represents a player's score submission for a board.
leadr.scores.domain.score.Score

Bases: Entity

Score represents a player's score submission for a board.

Scores are immutable in terms of their associations (account, game, board, device) but mutable in terms of their value and metadata for corrections/updates.

Functions:

Attributes:

# leadr.scores.domain.score.Score.account_id
account_id: AccountID = Field(frozen=True, description='ID of the account this score belongs to (immutable)')
# leadr.scores.domain.score.Score.board_id
board_id: BoardID = Field(frozen=True, description='ID of the board this score belongs to (immutable)')
# leadr.scores.domain.score.Score.city
city: str | None = Field(default=None, description='Optional city filter for score categorization')
# leadr.scores.domain.score.Score.country
country: str | None = Field(default=None, description='Optional country filter for score categorization')
# leadr.scores.domain.score.Score.created_at
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp when entity was created (UTC)')
# leadr.scores.domain.score.Score.deleted_at
deleted_at: datetime | None = Field(default=None, description='Timestamp when entity was soft-deleted (UTC), or null if active')
# leadr.scores.domain.score.Score.device_id
device_id: DeviceID = Field(frozen=True, description='ID of the device that submitted this score (immutable)')
# leadr.scores.domain.score.Score.game_id
game_id: GameID = Field(frozen=True, description='ID of the game this score belongs to (immutable)')
# leadr.scores.domain.score.Score.id
id: ScoreID = Field(frozen=True, default_factory=ScoreID, description='Unique score identifier')
# leadr.scores.domain.score.Score.is_deleted
is_deleted: bool

Check if entity is soft-deleted.

Returns:

  • bool – True if the entity has a deleted_at timestamp, False otherwise.
# leadr.scores.domain.score.Score.metadata
metadata: Any | None = Field(default=None, description='Optional JSON metadata for game-specific data (loadouts, seeds, etc.)')
# leadr.scores.domain.score.Score.model_config
model_config = ConfigDict(validate_assignment=True)
# leadr.scores.domain.score.Score.player_name
player_name: str = Field(description='Display name of the player')
# leadr.scores.domain.score.Score.restore
restore()

Restore a soft-deleted entity.

Clears the deleted_at timestamp, making the entity active again.

Example > > > account.soft_delete() > > > account.restore() > > > assert account.is_deleted is False
# leadr.scores.domain.score.Score.soft_delete
soft_delete()

Mark entity as soft-deleted.

Sets the deleted_at timestamp to the current UTC time. Entities that are already deleted are not affected (deleted_at remains at original deletion time).

Example > > > account = Account(name="Test", slug="test") > > > account.soft_delete() > > > assert account.is_deleted is True
# leadr.scores.domain.score.Score.timezone
timezone: str | None = Field(default=None, description='Optional timezone filter for score categorization')
# leadr.scores.domain.score.Score.updated_at
updated_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)), description='Timestamp of last update (UTC)')
# leadr.scores.domain.score.Score.validate_metadata_size
validate_metadata_size(v)

Validate that metadata does not exceed size limit.

Parameters:

  • v (Any) – The metadata to validate.

Returns:

  • Any – The validated metadata.

Raises:

  • ValueError – If metadata exceeds the configured size limit.
# leadr.scores.domain.score.Score.validate_player_name
validate_player_name(v)

Validate that player_name is not empty and strip whitespace.

Parameters:

  • v (str) – The player_name to validate.

Returns:

  • str – The validated and trimmed player_name.

Raises:

  • ValueError – If player_name is empty or whitespace only.
# leadr.scores.domain.score.Score.value
value: float = Field(description='Numeric value of the score for sorting/comparison')
# leadr.scores.domain.score.Score.value_display
value_display: str | None = Field(default=None, description="Optional formatted display string (e.g., '1:23.45', '1,234 points')")

leadr.scores.services

Modules:

leadr.scores.services.anti_cheat_repositories

Anti-cheat repository services.

Classes:

leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository

Bases: BaseRepository[ScoreFlag, ScoreFlagORM]

Repository for managing score flag persistence.

Functions:

  • create – Create a new entity in the database.
  • delete – Soft delete an entity by setting its deleted_at timestamp.
  • filter – Filter flags by account and optional criteria.
  • get_by_id – Get an entity by its ID.
  • get_flags_by_score_id – Get all flags for a specific score.
  • get_pending_flags – Get all pending (unreviewed) flags.
  • update – Update an existing entity in the database.

Attributes:

# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.create
create(entity)

Create a new entity in the database.

Parameters:

Returns:

# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.delete
delete(entity_id)

Soft delete an entity by setting its deleted_at timestamp.

Parameters:

Raises:

# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.filter
filter(account_id=None, board_id=None, game_id=None, status=None, flag_type=None, **kwargs)

Filter flags by account and optional criteria.

Joins with scores table to filter by account_id since flags don't have a direct account relation.

Parameters:

  • account_id (AccountID | None) – Optional account ID to filter by. If None, returns all flags (superadmin use case). Regular users should always pass account_id.
  • board_id (BoardID | None) – Optional board ID to filter by
  • game_id (GameID | None) – Optional game ID to filter by
  • status (str | None) – Optional status to filter by (PENDING, CONFIRMED_CHEAT, etc.)
  • flag_type (str | None) – Optional flag type to filter by (VELOCITY, DUPLICATE, etc.)
  • **kwargs (Any) – Additional filter parameters (reserved for future use)

Returns:

  • list[ScoreFlag] – List of flags for the account matching the filter criteria
# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.get_by_id
get_by_id(entity_id, include_deleted=False)

Get an entity by its ID.

Parameters:

  • entity_id (UUID4 | PrefixedID) – Entity ID to retrieve
  • include_deleted (bool) – If True, include soft-deleted entities. Defaults to False.

Returns:

  • DomainEntityT | None – Domain entity if found, None otherwise
# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.get_flags_by_score_id
get_flags_by_score_id(score_id)

Get all flags for a specific score.

Parameters:

  • score_id (ScoreID) – ID of the score to get flags for

Returns:

  • list[ScoreFlag] – List of flags for the score (excludes soft-deleted)
# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.get_pending_flags
get_pending_flags()

Get all pending (unreviewed) flags.

Returns:

  • list[ScoreFlag] – List of flags with status PENDING (excludes soft-deleted)
# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.session
session = session
# leadr.scores.services.anti_cheat_repositories.ScoreFlagRepository.update
update(entity)

Update an existing entity in the database.

Parameters:

Returns:

Raises:

leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository

Bases: BaseRepository[ScoreSubmissionMeta, ScoreSubmissionMetaORM]

Repository for managing score submission metadata persistence.

Functions:

  • create – Create a new entity in the database.
  • delete – Soft delete an entity by setting its deleted_at timestamp.
  • filter – Filter submission metadata by account and optional criteria.
  • get_by_device_and_board – Get submission metadata for a device/board combination.
  • get_by_id – Get an entity by its ID.
  • update – Update an existing entity in the database.

Attributes:

# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.create
create(entity)

Create a new entity in the database.

Parameters:

Returns:

# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.delete
delete(entity_id)

Soft delete an entity by setting its deleted_at timestamp.

Parameters:

Raises:

# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.filter
filter(account_id=None, board_id=None, device_id=None, **kwargs)

Filter submission metadata by account and optional criteria.

Joins with scores table to filter by account_id since submission meta doesn't have a direct account relation.

Parameters:

  • account_id (AccountID | None) – Optional account ID to filter by. If None, returns all metadata (superadmin use case). Regular users should always pass account_id.
  • board_id (BoardID | None) – Optional board ID to filter by
  • device_id (DeviceID | None) – Optional device ID to filter by
  • **kwargs (Any) – Additional filter parameters (reserved for future use)

Returns:

# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.get_by_device_and_board
get_by_device_and_board(device_id, board_id)

Get submission metadata for a device/board combination.

Parameters:

  • device_id (DeviceID) – ID of the device submitting scores
  • board_id (BoardID) – ID of the board being submitted to

Returns:

# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.get_by_id
get_by_id(entity_id, include_deleted=False)

Get an entity by its ID.

Parameters:

  • entity_id (UUID4 | PrefixedID) – Entity ID to retrieve
  • include_deleted (bool) – If True, include soft-deleted entities. Defaults to False.

Returns:

  • DomainEntityT | None – Domain entity if found, None otherwise
# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.session
session = session
# leadr.scores.services.anti_cheat_repositories.ScoreSubmissionMetaRepository.update
update(entity)

Update an existing entity in the database.

Parameters:

Returns:

Raises:

leadr.scores.services.anti_cheat_service

Anti-cheat service for detecting suspicious score submissions.

Classes:

leadr.scores.services.anti_cheat_service.AntiCheatService
AntiCheatService(session)

Service for anti-cheat detection and analysis.

Implements various detection tactics to identify suspicious score submissions:

  • Rate limiting: Prevents excessive submissions per device/board
  • Duplicate detection: Identifies repeated identical scores
  • Velocity detection: Detects rapid-fire submissions
  • Statistical outliers: Identifies anomalous scores
  • Pattern detection: Finds suspicious submission patterns

Functions:

Attributes:

Parameters:

  • session (AsyncSession) – Database session for querying metadata
# leadr.scores.services.anti_cheat_service.AntiCheatService.check_submission
check_submission(score, trust_tier, device_id, board_id)

Check a score submission for suspicious patterns.

Parameters:

  • score (Score) – Score being submitted
  • trust_tier (TrustTier) – Trust tier of the device (A/B/C)
  • device_id (DeviceID) – ID of the device submitting the score
  • board_id (BoardID) – ID of the board being submitted to

Returns:

  • AntiCheatResult – AntiCheatResult indicating action to take (ACCEPT/FLAG/REJECT)
# leadr.scores.services.anti_cheat_service.AntiCheatService.meta_repo
meta_repo = ScoreSubmissionMetaRepository(session)
# leadr.scores.services.anti_cheat_service.AntiCheatService.session
session = session
leadr.scores.services.dependencies

Score service dependencies for FastAPI dependency injection.

Functions:

Attributes:

leadr.scores.services.dependencies.ScoreFlagServiceDep
ScoreFlagServiceDep = Annotated[ScoreFlagService, Depends(get_score_flag_service)]
leadr.scores.services.dependencies.ScoreServiceDep
ScoreServiceDep = Annotated[ScoreService, Depends(get_score_service)]
leadr.scores.services.dependencies.ScoreSubmissionMetaServiceDep
ScoreSubmissionMetaServiceDep = Annotated[ScoreSubmissionMetaService, Depends(get_score_submission_meta_service)]
leadr.scores.services.dependencies.get_score_flag_service
get_score_flag_service(db)

Get ScoreFlagService dependency.

Parameters:

Returns:

leadr.scores.services.dependencies.get_score_service
get_score_service(db)

Get ScoreService dependency.

Parameters:

Returns:

leadr.scores.services.dependencies.get_score_submission_meta_service
get_score_submission_meta_service(db)

Get ScoreSubmissionMetaService dependency.

Parameters:

Returns:

leadr.scores.services.repositories

Score repository services.

Classes:

leadr.scores.services.repositories.ScoreRepository

Bases: BaseRepository[Score, ScoreORM]

Score repository for managing score persistence.

Functions:

  • create – Create a new entity in the database.
  • delete – Soft delete an entity by setting its deleted_at timestamp.
  • filter – Filter scores by account and optional criteria.
  • get_by_id – Get an entity by its ID.
  • update – Update an existing entity in the database.

Attributes:

# leadr.scores.services.repositories.ScoreRepository.SORTABLE_FIELDS
SORTABLE_FIELDS = {'id', 'value', 'player_name', 'filter_timezone', 'filter_country', 'filter_city', 'created_at', 'updated_at'}
# leadr.scores.services.repositories.ScoreRepository.create
create(entity)

Create a new entity in the database.

Parameters:

Returns:

# leadr.scores.services.repositories.ScoreRepository.delete
delete(entity_id)

Soft delete an entity by setting its deleted_at timestamp.

Parameters:

Raises:

# leadr.scores.services.repositories.ScoreRepository.filter
filter(account_id=None, board_id=None, game_id=None, device_id=None, pagination=None, **kwargs)

Filter scores by account and optional criteria.

Parameters:

  • account_id (UUID4 | PrefixedID | None) – Optional account ID to filter by. If None, returns all scores (superadmin use case). Regular users should always pass account_id.
  • board_id (BoardID | None) – Optional board ID to filter by
  • game_id (GameID | None) – Optional game ID to filter by
  • device_id (DeviceID | None) – Optional device ID to filter by
  • pagination (PaginationParams | None) – Optional pagination parameters
  • **kwargs (Any) – Additional filter parameters (reserved for future use)

Returns:

Raises:

# leadr.scores.services.repositories.ScoreRepository.get_by_id
get_by_id(entity_id, include_deleted=False)

Get an entity by its ID.

Parameters:

  • entity_id (UUID4 | PrefixedID) – Entity ID to retrieve
  • include_deleted (bool) – If True, include soft-deleted entities. Defaults to False.

Returns:

  • DomainEntityT | None – Domain entity if found, None otherwise
# leadr.scores.services.repositories.ScoreRepository.session
session = session
# leadr.scores.services.repositories.ScoreRepository.update
update(entity)

Update an existing entity in the database.

Parameters:

Returns:

Raises:

leadr.scores.services.score_flag_service

Score flag service for managing flag operations.

Classes:

  • ScoreFlagService – Service for managing score flag lifecycle and operations.
leadr.scores.services.score_flag_service.ScoreFlagService

Bases: BaseService[ScoreFlag, ScoreFlagRepository]

Service for managing score flag lifecycle and operations.

This service orchestrates flag listing, retrieval, and review operations by coordinating between the domain models and repository layer.

Functions:

  • delete – Soft-delete an entity.
  • get_by_id – Get an entity by its ID.
  • get_by_id_or_raise – Get an entity by its ID or raise EntityNotFoundError.
  • get_flag – Get a flag by its ID.
  • list_all – List all non-deleted entities.
  • list_flags – List score flags for an account with optional filters.
  • review_flag – Review a flag and update its status.
  • soft_delete – Soft-delete an entity and return it before deletion.
  • update_flag – Update a flag's status and/or reviewer decision.

Attributes:

# leadr.scores.services.score_flag_service.ScoreFlagService.delete
delete(entity_id)

Soft-delete an entity.

Parameters:

Raises:

# leadr.scores.services.score_flag_service.ScoreFlagService.get_by_id
get_by_id(entity_id)

Get an entity by its ID.

Parameters:

Returns:

  • DomainEntityT | None – The domain entity if found, None otherwise
# leadr.scores.services.score_flag_service.ScoreFlagService.get_by_id_or_raise
get_by_id_or_raise(entity_id)

Get an entity by its ID or raise EntityNotFoundError.

Parameters:

Returns:

Raises:

# leadr.scores.services.score_flag_service.ScoreFlagService.get_flag
get_flag(flag_id)

Get a flag by its ID.

Parameters:

  • flag_id (ScoreFlagID) – The ID of the flag to retrieve

Returns:

  • ScoreFlag | None – The flag if found, None otherwise
Example > > > flag = await service.get_flag(flag_id)
# leadr.scores.services.score_flag_service.ScoreFlagService.list_all
list_all()

List all non-deleted entities.

Returns:

# leadr.scores.services.score_flag_service.ScoreFlagService.list_flags
list_flags(account_id, board_id=None, game_id=None, status=None, flag_type=None)

List score flags for an account with optional filters.

Parameters:

  • account_id (AccountID | None) – Account ID to filter by. If None, returns all flags (superadmin use case).
  • board_id (BoardID | None) – Optional board ID to filter by
  • game_id (GameID | None) – Optional game ID to filter by
  • status (str | None) – Optional status to filter by (PENDING, CONFIRMED_CHEAT, etc.)
  • flag_type (str | None) – Optional flag type to filter by (VELOCITY, DUPLICATE, etc.)

Returns:

Example > > > flags = await service.list_flags( > > > ... account_id=account.id, > > > ... status="PENDING", > > > ... )
# leadr.scores.services.score_flag_service.ScoreFlagService.repository
repository = self._create_repository(session)
# leadr.scores.services.score_flag_service.ScoreFlagService.review_flag
review_flag(flag_id, status, reviewer_decision=None, reviewer_id=None)

Review a flag and update its status.

Parameters:

  • flag_id (ScoreFlagID) – The ID of the flag to review
  • status (ScoreFlagStatus) – New status (CONFIRMED_CHEAT, FALSE_POSITIVE, DISMISSED)
  • reviewer_decision (str | None) – Optional admin notes/decision
  • reviewer_id (UserID | None) – Optional ID of the reviewing admin

Returns:

Raises:

Example > > > flag = await service.review_flag( > > > ... flag_id=flag.id, > > > ... status=ScoreFlagStatus.CONFIRMED_CHEAT, > > > ... reviewer_decision="Verified cheating behavior", > > > ... )
# leadr.scores.services.score_flag_service.ScoreFlagService.soft_delete
soft_delete(entity_id)

Soft-delete an entity and return it before deletion.

Useful for endpoints that need to return the deleted entity in the response.

Parameters:

Returns:

Raises:

# leadr.scores.services.score_flag_service.ScoreFlagService.update_flag
update_flag(flag_id, status=None, reviewer_decision=None)

Update a flag's status and/or reviewer decision.

Parameters:

  • flag_id (ScoreFlagID) – The ID of the flag to update
  • status (ScoreFlagStatus | None) – Optional new status
  • reviewer_decision (str | None) – Optional new reviewer decision

Returns:

Raises:

Example > > > flag = await service.update_flag( > > > ... flag_id=flag.id, > > > ... status=ScoreFlagStatus.FALSE_POSITIVE, > > > ... )
leadr.scores.services.score_service

Score service for managing score operations.

Classes:

  • ScoreService – Service for managing score lifecycle and operations.
leadr.scores.services.score_service.ScoreService

Bases: BaseService[Score, ScoreRepository]

Service for managing score lifecycle and operations.

This service orchestrates score creation, updates, and retrieval by coordinating between the domain models and repository layer. Ensures business rules like board/game validation are enforced.

Functions:

Attributes:

# leadr.scores.services.score_service.ScoreService.create_score
create_score(account_id, game_id, board_id, device_id, player_name, value, value_display=None, timezone=None, country=None, city=None, metadata=None, trust_tier=TrustTier.B, background_tasks=None)

Create a new score.

Parameters:

  • account_id (AccountID) – The ID of the account this score belongs to.
  • game_id (GameID) – The ID of the game this score belongs to.
  • board_id (BoardID) – The ID of the board this score belongs to.
  • device_id (DeviceID) – The ID of the device that submitted this score.
  • player_name (str) – Display name of the player.
  • value (float) – Numeric value of the score for sorting/comparison.
  • value_display (str | None) – Optional formatted display string.
  • timezone (str | None) – Optional timezone filter for categorization.
  • country (str | None) – Optional country filter for categorization.
  • city (str | None) – Optional city filter for categorization.
  • metadata (Any | None) – Optional JSON metadata for game-specific data.
  • trust_tier (TrustTier) – Trust tier of the device (defaults to B/medium trust).

Returns:

Raises:

  • EntityNotFoundError – If the board doesn't exist.
  • ValueError – If validation fails (board doesn't belong to account, game doesn't match board's game, or anti-cheat rejects submission).
Example > > > score = await service.create_score( > > > ... account_id=account.id, > > > ... game_id=game.id, > > > ... board_id=board.id, > > > ... device_id=device.id, > > > ... player_name="SpeedRunner99", > > > ... value=123.45, > > > ... )
# leadr.scores.services.score_service.ScoreService.delete
delete(entity_id)

Soft-delete an entity.

Parameters:

Raises:

# leadr.scores.services.score_service.ScoreService.get_by_id
get_by_id(entity_id)

Get an entity by its ID.

Parameters:

Returns:

  • DomainEntityT | None – The domain entity if found, None otherwise
# leadr.scores.services.score_service.ScoreService.get_by_id_or_raise
get_by_id_or_raise(entity_id)

Get an entity by its ID or raise EntityNotFoundError.

Parameters:

Returns:

Raises:

# leadr.scores.services.score_service.ScoreService.get_score
get_score(score_id)

Get a score by its ID.

Parameters:

  • score_id (ScoreID) – The ID of the score to retrieve.

Returns:

  • Score | None – The Score domain entity if found, None otherwise.
# leadr.scores.services.score_service.ScoreService.list_all
list_all()

List all non-deleted entities.

Returns:

# leadr.scores.services.score_service.ScoreService.list_scores
list_scores(account_id, board_id=None, game_id=None, device_id=None, pagination=None)

List scores for an account with optional filters and pagination.

Parameters:

  • account_id (AccountID | None) – Account ID to filter by. If None, returns all scores (superadmin use case).
  • board_id (BoardID | None) – Optional board ID to filter by.
  • game_id (GameID | None) – Optional game ID to filter by.
  • device_id (DeviceID | None) – Optional device ID to filter by.
  • pagination (PaginationParams | None) – Optional pagination parameters.

Returns:

# leadr.scores.services.score_service.ScoreService.repository
repository = self._create_repository(session)
# leadr.scores.services.score_service.ScoreService.soft_delete
soft_delete(entity_id)

Soft-delete an entity and return it before deletion.

Useful for endpoints that need to return the deleted entity in the response.

Parameters:

Returns:

Raises:

# leadr.scores.services.score_service.ScoreService.update_score
update_score(score_id, player_name=None, value=None, value_display=None, timezone=None, country=None, city=None, metadata=None)

Update a score's mutable fields.

Parameters:

  • score_id (ScoreID) – The ID of the score to update.
  • player_name (str | None) – Optional new player name.
  • value (float | None) – Optional new value.
  • value_display (str | None) – Optional new value display string.
  • timezone (str | None) – Optional new timezone.
  • country (str | None) – Optional new country.
  • city (str | None) – Optional new city.
  • metadata (Any | None) – Optional new metadata.

Returns:

  • Score – The updated Score entity.

Raises:

# leadr.scores.services.score_service.ScoreService.update_submission_metadata
update_submission_metadata(saved_score, device_id, board_id, anti_cheat_result)

Update submission metadata and create flags if needed.

This method is designed to be called as a background task after score creation to avoid blocking the HTTP response.

Parameters:

  • saved_score (Score) – The score that was created
  • device_id (DeviceID) – ID of the device that submitted the score
  • board_id (BoardID) – ID of the board the score was submitted to
  • anti_cheat_result (AntiCheatResult | None) – Result from anti-cheat check (or None)
leadr.scores.services.score_submission_meta_service

Service for score submission metadata management.

Classes:

leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService

Bases: BaseService[ScoreSubmissionMeta, ScoreSubmissionMetaRepository]

Service for managing score submission metadata.

Provides read-only access to submission metadata for debugging and analysis.

Functions:

Attributes:

# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.delete
delete(entity_id)

Soft-delete an entity.

Parameters:

Raises:

# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.get_by_id
get_by_id(entity_id)

Get an entity by its ID.

Parameters:

Returns:

  • DomainEntityT | None – The domain entity if found, None otherwise
# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.get_by_id_or_raise
get_by_id_or_raise(entity_id)

Get an entity by its ID or raise EntityNotFoundError.

Parameters:

Returns:

Raises:

# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.get_submission_meta
get_submission_meta(meta_id)

Get submission metadata by its ID.

Parameters:

Returns:

Example > > > meta = await service.get_submission_meta(meta_id)
# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.list_all
list_all()

List all non-deleted entities.

Returns:

# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.list_submission_meta
list_submission_meta(account_id, board_id=None, device_id=None)

List score submission metadata for an account with optional filters.

Parameters:

  • account_id (AccountID | None) – Account ID to filter by. If None, returns all metadata (superadmin use case).
  • board_id (BoardID | None) – Optional board ID to filter by
  • device_id (DeviceID | None) – Optional device ID to filter by

Returns:

Example > > > metas = await service.list_submission_meta( > > > ... account_id=account.id, > > > ... board_id=board.id, > > > ... )
# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.repository
repository = self._create_repository(session)
# leadr.scores.services.score_submission_meta_service.ScoreSubmissionMetaService.soft_delete
soft_delete(entity_id)

Soft-delete an entity and return it before deletion.

Useful for endpoints that need to return the deleted entity in the response.

Parameters:

Returns:

Raises: