Core Package

# Submodules section with toctree removed as automodule below will cover them. # ———- # .. toctree:: # :maxdepth: 1 # # core.exceptions # core.goal_manager # core.interfaces # core.metrics

exception core.exceptions.BotError(message, user_friendly=None)

Базовые классы: Exception

Base class for bot errors with a user-friendly message.

Параметры:

• message (str)

• user_friendly (str | None)

__init__(message, user_friendly=None)

Initialize the BotError.

Параметры:

• message (str) – The internal error message.

• user_friendly (str | None) – A user-friendly message to display.

exception core.exceptions.StorageError(message, user_friendly=None)

Базовые классы: BotError

Errors related to data storage operations.

Параметры:

• message (str)

• user_friendly (str | None)

exception core.exceptions.LLMError(message, user_friendly=None)

Базовые классы: BotError

Errors related to interaction with the LLM (OpenAI).

Параметры:

• message (str)

• user_friendly (str | None)

exception core.exceptions.RateLimitExceeded(message, user_friendly=None)

Базовые классы: BotError

Error raised when a rate limit is exceeded.

Параметры:

• message (str)

• user_friendly (str | None)

Core logic for managing user goals, plans, and progress via LLM and storage.

class core.goal_manager.GoalManager(storage, llm)

Базовые классы: object

Asynchronously manages user goals, tasks, and interactions.

Orchestrates operations with storage (e.g., Google Sheets via AsyncStorageInterface) and LLM (e.g., OpenAI via AsyncLLMInterface) for planning and motivation. All public methods are asynchronous.

Параметры:

• storage (AsyncStorageInterface)

• llm (AsyncLLMInterface)

__init__(storage, llm)

Initializes GoalManager with async storage and LLM clients.

Параметры:

• storage (AsyncStorageInterface)

• llm (AsyncLLMInterface)

async setup_user(user_id)

Asynchronously sets up the user by creating/opening their Google Spreadsheet.

Параметры:

user_id (int)

Тип результата:

None

async set_new_goal(user_id, goal_text, deadline_str, available_time_str)

Asynchronously sets a new goal, generates a plan, and saves all data.

Параметры:

• user_id (int)

• goal_text (str)

• deadline_str (str)

• available_time_str (str)

Тип результата:

str

async get_today_task(user_id)

Asynchronously retrieves today’s task.

Параметры:

user_id (int)

Тип результата:

Optional[Dict[str, Any]]

async update_today_task_status(user_id, status)

Asynchronously updates the status of today’s task. „status“ is expected to be a Russian user-facing string.

Параметры:

• user_id (int)

• status (str)

Тип результата:

None

async get_goal_status_details(user_id)

Asynchronously gets a brief string summary of goal progress.

Параметры:

user_id (int)

Тип результата:

str

async generate_motivation_message(user_id)

Asynchronously generates a motivational message.

Параметры:

user_id (int)

Тип результата:

str

async reset_user(user_id)

Asynchronously deletes all user data.

Параметры:

user_id (int)

Тип результата:

None

async get_detailed_status(user_id)

Asynchronously gets detailed statistics about the user’s current goal.

Параметры:

user_id (int)

Тип результата:

Dict[str, Any]

async batch_update_task_statuses(user_id, updates)

Asynchronously batch updates task statuses via the storage interface. „updates“ dict values are expected to be Russian user-facing strings.

Also, increments the TASKS_STATUS_UPDATED_TOTAL metric for each status update.

Параметры:

• user_id (int)

• updates (Dict[str, str])

Тип результата:

None

class core.interfaces.StorageInterface(*args, **kwargs)

Базовые классы: Protocol

Storage interface for goals and tasks with multi-goal support.

create_spreadsheet(user_id)

Create a new spreadsheet for user.

Параметры:

user_id (int)

Тип результата:

None

delete_spreadsheet(user_id)

Delete user’s spreadsheet.

Параметры:

user_id (int)

Тип результата:

None

get_all_goals(user_id)

Get all goals for a user.

Параметры:

user_id (int)

Тип результата:

List[Goal]

get_goal_by_id(user_id, goal_id)

Get a specific goal by ID.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

Optional[Goal]

get_active_goals(user_id)

Get only active goals.

Параметры:

user_id (int)

Тип результата:

List[Goal]

get_active_goals_count(user_id)

Count active goals.

Параметры:

user_id (int)

Тип результата:

int

get_next_goal_id(user_id)

Get next available goal ID.

Параметры:

user_id (int)

Тип результата:

int

save_goal_info(user_id, goal)

Save or update goal information.

Параметры:

• user_id (int)

• goal (Goal)

Тип результата:

str

update_goal_status(user_id, goal_id, status)

Update goal status.

Параметры:

• user_id (int)

• goal_id (int)

• status (GoalStatus)

Тип результата:

None

update_goal_progress(user_id, goal_id, progress)

Update goal progress percentage.

Параметры:

• user_id (int)

• goal_id (int)

• progress (int)

Тип результата:

None

update_goal_priority(user_id, goal_id, priority)

Update goal priority.

Параметры:

• user_id (int)

• goal_id (int)

• priority (GoalPriority)

Тип результата:

None

archive_goal(user_id, goal_id)

Archive a goal.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

None

delete_goal(user_id, goal_id)

Delete a goal completely.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

None

save_plan(user_id, goal_id, plan)

Save plan for a goal.

Параметры:

• user_id (int)

• goal_id (int)

• plan (List[Dict[str, Any]])

Тип результата:

None

get_plan_for_goal(user_id, goal_id)

Get plan for a specific goal.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

List[Task]

get_task_for_date(user_id, goal_id, date)

Get task for specific goal and date.

Параметры:

• user_id (int)

• goal_id (int)

• date (str)

Тип результата:

Optional[Task]

get_all_tasks_for_date(user_id, date)

Get all tasks for a specific date.

Параметры:

• user_id (int)

• date (str)

Тип результата:

List[Task]

update_task_status(user_id, goal_id, date, status)

Update task status.

Параметры:

• user_id (int)

• goal_id (int)

• date (str)

• status (str)

Тип результата:

None

batch_update_task_statuses(user_id, updates)

Batch update multiple task statuses.

Параметры:

• user_id (int)

• updates (Dict[Tuple[int, str], str])

Тип результата:

None

get_goal_statistics(user_id, goal_id)

Get statistics for a specific goal.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

GoalStatistics

get_overall_statistics(user_id)

Get overall statistics for all goals.

Параметры:

user_id (int)

Тип результата:

Dict[str, Any]

get_goal_info(user_id)

Get goal info (legacy, single goal).

Параметры:

user_id (int)

Тип результата:

Dict[str, str]

save_goal_and_plan(user_id, goal_data, plan)

Save goal and plan (legacy, single goal).

Параметры:

• user_id (int)

• goal_data (Dict[str, str])

• plan (List[Dict[str, Any]])

Тип результата:

str

get_status_message(user_id)

Get status message (legacy, single goal).

Параметры:

user_id (int)

Тип результата:

str

class core.interfaces.AsyncStorageInterface(*args, **kwargs)

Базовые классы: Protocol

Async storage interface for goals and tasks with multi-goal support.

async create_spreadsheet(user_id)

Create a new spreadsheet for user.

Параметры:

user_id (int)

Тип результата:

None

async delete_spreadsheet(user_id)

Delete user’s spreadsheet.

Параметры:

user_id (int)

Тип результата:

None

async get_all_goals(user_id)

Get all goals for a user.

Параметры:

user_id (int)

Тип результата:

List[Goal]

async get_goal_by_id(user_id, goal_id)

Get a specific goal by ID.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

Optional[Goal]

async get_active_goals(user_id)

Get only active goals.

Параметры:

user_id (int)

Тип результата:

List[Goal]

async get_active_goals_count(user_id)

Count active goals.

Параметры:

user_id (int)

Тип результата:

int

async get_next_goal_id(user_id)

Get next available goal ID.

Параметры:

user_id (int)

Тип результата:

int

async save_goal_info(user_id, goal)

Save or update goal information.

Параметры:

• user_id (int)

• goal (Goal)

Тип результата:

str

async update_goal_status(user_id, goal_id, status)

Update goal status.

Параметры:

• user_id (int)

• goal_id (int)

• status (GoalStatus)

Тип результата:

None

async update_goal_progress(user_id, goal_id, progress)

Update goal progress percentage.

Параметры:

• user_id (int)

• goal_id (int)

• progress (int)

Тип результата:

None

async update_goal_priority(user_id, goal_id, priority)

Update goal priority.

Параметры:

• user_id (int)

• goal_id (int)

• priority (GoalPriority)

Тип результата:

None

async archive_goal(user_id, goal_id)

Archive a goal.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

None

async delete_goal(user_id, goal_id)

Delete a goal completely.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

None

async save_plan(user_id, goal_id, plan)

Save plan for a goal.

Параметры:

• user_id (int)

• goal_id (int)

• plan (List[Dict[str, Any]])

Тип результата:

None

async get_plan_for_goal(user_id, goal_id)

Get plan for a specific goal.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

List[Task]

async get_task_for_date(user_id, goal_id, date)

Get task for specific goal and date.

Параметры:

• user_id (int)

• goal_id (int)

• date (str)

Тип результата:

Optional[Task]

async get_all_tasks_for_date(user_id, date)

Get all tasks for a specific date.

Параметры:

• user_id (int)

• date (str)

Тип результата:

List[Task]

async update_task_status(user_id, goal_id, date, status)

Update task status.

Параметры:

• user_id (int)

• goal_id (int)

• date (str)

• status (str)

Тип результата:

None

async batch_update_task_statuses(user_id, updates)

Batch update multiple task statuses.

Параметры:

• user_id (int)

• updates (Dict[Tuple[int, str], str])

Тип результата:

None

async get_goal_statistics(user_id, goal_id)

Get statistics for a specific goal.

Параметры:

• user_id (int)

• goal_id (int)

Тип результата:

GoalStatistics

async get_overall_statistics(user_id)

Get overall statistics for all goals.

Параметры:

user_id (int)

Тип результата:

Dict[str, Any]

async get_goal_info(user_id)

Get goal info (legacy, single goal).

Параметры:

user_id (int)

Тип результата:

Dict[str, str]

async save_goal_and_plan(user_id, goal_data, plan)

Save goal and plan (legacy, single goal).

Параметры:

• user_id (int)

• goal_data (Dict[str, str])

• plan (List[Dict[str, Any]])

Тип результата:

str

async get_status_message(user_id)

Get status message (legacy, single goal).

Параметры:

user_id (int)

Тип результата:

str

async get_task_for_today(user_id)

Get today’s task (legacy, single goal).

Параметры:

user_id (int)

Тип результата:

Optional[Dict[str, Any]]

async update_task_status_old(user_id, date, status)

Update task status (legacy, single goal).

Параметры:

• user_id (int)

• date (str)

• status (str)

Тип результата:

None

async get_extended_statistics(user_id, count=7)

Get extended statistics (legacy method).

Параметры:

• user_id (int)

• count (int)

Тип результата:

Dict[str, Any]

class core.interfaces.LLMInterface(*args, **kwargs)

Базовые классы: Protocol

Interface for LLM interactions.

generate_plan(goal_text, deadline_str, available_time_str)

Generate a plan for achieving a goal.

Параметры:

• goal_text (str)

• deadline_str (str)

• available_time_str (str)

Тип результата:

List[Dict[str, Any]]

generate_motivation(goal_info, progress_summary)

Generate motivational message based on goal and progress.

Параметры:

• goal_info (str)

• progress_summary (str)

Тип результата:

str

class core.interfaces.AsyncLLMInterface(*args, **kwargs)

Базовые классы: Protocol

Async interface for LLM interactions.

async generate_plan(goal_text, deadline_str, available_time_str)

Generate a plan for achieving a goal.

Параметры:

• goal_text (str)

• deadline_str (str)

• available_time_str (str)

Тип результата:

List[Dict[str, Any]]

async generate_motivation(goal_info, progress_summary)

Generate motivational message based on goal and progress.

Параметры:

• goal_info (str)

• progress_summary (str)

Тип результата:

str

Prometheus metrics definitions for the Target Assistant Bot.

This module defines various counters, gauges, and histograms used for monitoring the application’s performance and behavior.