app.repository.user_points_repository module

class app.repository.user_points_repository.UserPointsRepository(session_factory, model=<class 'app.model.user_points.UserPoints'>)

Bases: BaseRepository

Async repository class for user points.

Parameters:

session_factory (Callable[[...], AbstractAsyncContextManager[AsyncSession]])

async get_first_user_points_in_external_task_id_by_user_id(externalTaskId, externalUserId)

Return the earliest points row for a user on a given external task.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

Returns:

UserPoints | None – The oldest matching points row, or None.

async read_by_user_task_and_idempotency(user_id, task_id, idempotency_key, session=None)

Returns a previously persisted user-points row for the same (userId, taskId, idempotencyKey), if it exists.

Parameters:

• idempotency_key (str)

• session (AsyncSession | None)

async get_all_UserPoints_by_gameId(gameId)

Aggregate points per (task, user) for every task in a game.

Parameters:

gameId – Internal game identifier.

Returns:

list – Rows of (externalTaskId, externalUserId, points, timesAwarded) where points is the summed total and timesAwarded the number of awards.

async get_all_UserPoints_by_taskId(taskId)

Aggregate points per user for a single task.

Parameters:

taskId – Internal task identifier.

Returns:

list – Rows of (externalUserId, points, timesAwarded) with the summed points and award count per user.

async get_all_UserPoints_by_taskId_with_details(taskId)

Aggregate points per user for a task, including per-award detail.

Like get_all_UserPoints_by_taskId() but also returns a pointsData array aggregating each award’s points, caseName, data, description and created_at.

Parameters:

taskId – Internal task identifier.

Returns:

list – Rows of (externalUserId, points, timesAwarded, pointsData).

async get_points_and_users_by_taskId(taskId)

Aggregate points per user for a task with a compact award breakdown.

Parameters:

taskId – Internal task identifier.

Returns:

list – Rows of (externalUserId, points, timesAwarded, pointsData) where pointsData aggregates each award’s points, caseName and created_at.

async get_task_by_externalUserId(externalUserId)

Return all tasks a user has earned points on.

Parameters:

externalUserId – External identifier of the user.

Returns:

list[Tasks] – Distinct tasks linked to the user’s points rows.

async get_task_and_sum_points_by_userId(userId)

Sum a user’s points grouped by task.

Parameters:

userId – Internal user identifier.

Returns:

list – Rows of (externalTaskId, points) with the total points the user earned on each task.

async get_user_measurement_count(userId)

Count how many points rows (measurements) a user has.

Parameters:

userId – Internal user identifier.

Returns:

int – Number of points rows for the user.

async get_time_taken_for_last_task(userId)

Return the timestamp of a user’s most recent points row.

Parameters:

userId – Internal user identifier.

Returns:

datetime | None – The maximum created_at for the user, or None if they have no rows.

async get_individual_calculation(userId)

Return a user’s average points per award.

Parameters:

userId – Internal user identifier.

Returns:

float | None – Mean of points across the user’s rows, or None if they have none.

async get_global_calculation()

Return the average points per award across all users.

Returns:

float | None – Mean of points over every points row, or None if the table is empty.

async get_start_time_for_last_task(userId)

Return the timestamp of a user’s earliest points row.

Parameters:

userId – Internal user identifier.

Returns:

datetime | None – The minimum created_at for the user, or None if they have no rows.

async count_measurements_by_external_task_id(external_task_id)

Count all points rows recorded for an external task.

Parameters:

external_task_id – External identifier of the task.

Returns:

int – Number of points rows linked to the task.

async get_user_task_measurements(externalTaskId, externalUserId)

Return the ordered timestamps of a user’s awards on a task.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

Returns:

list – Rows of (timestamp,) ordered chronologically.

async get_user_task_measurements_count(externalTaskId, externalUserId)

Count a user’s awards on a given external task.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

Returns:

int – Number of points rows for the user on that task.

async get_user_task_measurements_count_the_last_seconds(externalTaskId, externalUserId, seconds)

Count a user’s recent awards on a task within a time window.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

• seconds – Length of the look-back window, in seconds.

Returns:

int – Number of points rows created within the last seconds.

async get_avg_time_between_tasks_by_user_and_game_task(externalGameId, externalTaskId, externalUserId)

Average the gap between a user’s consecutive awards on a task.

Parameters:

• externalGameId – External identifier of the game.

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

Returns:

float – Mean seconds between consecutive awards, or -1 when the user has fewer than two awards.

async get_avg_time_between_tasks_for_all_users(externalGameId, externalTaskId)

Average the gap between consecutive awards on a task across all users.

Parameters:

• externalGameId – External identifier of the game.

• externalTaskId – External identifier of the task.

Returns:

float – Mean seconds between consecutive awards, or -1 when fewer than two awards exist.

async get_last_window_time_diff(externalTaskId, externalUserId)

Return seconds between a user’s two most recent awards on a task.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

Returns:

float – Seconds between the last two awards, or 0 when the user has fewer than two.

async get_new_last_window_time_diff(externalTaskId, externalUserId, externalGameId)

Return seconds elapsed since a user’s most recent award on a task.

Measures the gap between now and the user’s latest award (scoped by game and task), normalizing both timestamps to UTC.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

• externalGameId – External identifier of the game.

Returns:

float – Seconds since the last award, or 0 if the user has none.

async count_personal_records_by_external_game_id(externalGameId, externalUserId)

Count a user’s total awards across a game.

Parameters:

• externalGameId – External identifier of the game.

• externalUserId – External identifier of the user.

Returns:

int – Number of points rows for the user within the game.

async user_has_record_before_in_externalTaskId_last_min(externalTaskId, externalUserId, minutes)

Check whether a user earned points on a task within recent minutes.

Parameters:

• externalTaskId – External identifier of the task.

• externalUserId – External identifier of the user.

• minutes – Length of the look-back window, in minutes.

Returns:

bool – True if at least one award exists within the window.

async get_global_avg_by_external_game_id(externalGameId)

Average the data["minutes"] measurement across a whole game.

Considers only rows with a positive minutes value in their JSON data payload.

Parameters:

externalGameId – External identifier of the game.

Returns:

float – Mean minutes over all users, or -1 when no qualifying rows exist.

async get_personal_avg_by_external_game_id(externalGameId, externalUserId)

Average one user’s data["minutes"] measurement across a game.

Considers only rows with a positive minutes value in their JSON data payload.

Parameters:

• externalGameId – External identifier of the game.

• externalUserId – External identifier of the user.

Returns:

float – Mean minutes for the user, or -1 when no qualifying rows exist.

async get_points_of_simulated_task(externalTaskId, simulationHash)

Return points rows produced by a specific strategy simulation run.

Matches rows whose JSON data carries the given simulationHash.

Parameters:

• externalTaskId (str) – External identifier of the task.

• simulationHash (str) – Hash identifying the simulation run.

Returns:

list[UserPoints] – Points rows belonging to that simulation.

async get_all_point_of_tasks_list(task_list, withData=False)

Retrieves all points associated with a list of task IDs.

Note: previously used yield_per to stream results – under async we materialize fully. For very large task_list batches consider streaming via stream_scalars (caller decides).

async get_last_task_by_userId(userId)

Return a user’s most recent points row.

Parameters:

userId – Internal user identifier.

Returns:

UserPoints | None – The latest award by created_at, or None.