matplobbot-shared 0.1.48__tar.gz

matplobbot_shared-0.1.48/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: matplobbot-shared
+Version: 0.1.48
+Summary: Shared library for the Matplobbot ecosystem (database, services, i18n).
+Author: Ackrome
+Author-email: ivansergeyevich@gmail.com
+Requires-Python: >=3.11
+Requires-Dist: asyncpg
+Requires-Dist: aiohttp
+Requires-Dist: certifi
+Requires-Dist: redis
+Dynamic: author
+Dynamic: author-email
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

matplobbot_shared-0.1.48/README.md

@@ -0,0 +1,302 @@
+<div align="center" style="border: none; padding: 0; margin: 0;">
+  <img src="image/logo/thelogo.png" alt="Matplobbot Logo" width="400" style="border: none; outline: none;">
+  <h1>Matplobbot & Stats Dashboard</h1>
+  <strong>A comprehensive solution: An Aiogram 3 Telegram bot for advanced code interaction and a FastAPI dashboard for real-time analytics.</strong>
+  <br>
+  </br>
+  <p align="center">
+    <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
+    <img src="https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker">
+    <img src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI">
+    <img src="https://img.shields.io/badge/Aiogram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Aiogram">
+    <img src="https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white" alt="PostgreSQL">
+    <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black" alt="JavaScript">
+    <img src="https://img.shields.io/badge/Pandoc-5A5A5A?style=for-the-badge&logo=pandoc&logoColor=white" alt="Pandoc">
+    <img src="https://img.shields.io/badge/LaTeX-008080?style=for-the-badge&logo=latex&logoColor=white" alt="LaTeX">
+    <img src ="https://img.shields.io/badge/Tailscale-000000?style=for-the-badge&logo=tailscale&logoColor=white">
+    <img src="https://img.shields.io/badge/Jenkins-D24939?style=for-the-badge&logo=jenkins&logoColor=white">
+    <img src="https://img.shields.io/badge/Ubuntu-E95420?style=for-the-badge&logo=ubuntu&logoColor=white">
+    <img src="https://img.shields.io/badge/markdown-%23000000.svg?style=for-the-badge&logo=markdown&logoColor=white" alt="Markdown">
+    <img src="https://img.shields.io/badge/Pydantic-E92063?style=for-the-badge&logo=Pydantic&logoColor=white" alt="Pydantic">
+    <img src="https://img.shields.io/badge/GitHub_Actions-2088FF?style=for-the-badge&logo=github-actions&logoColor=white" alt="GithubActions">
+    <img src="https://img.shields.io/badge/redis-%23DD0031.svg?&style=for-the-badge&logo=redis&logoColor=white" alt="Redis">
+  </p>
+</div>
+
+---
+
+## 🚀 Project Overview
+
+This project is a powerful, dual-component system designed for advanced interaction with programming content and real-time monitoring, all containerized with Docker for seamless deployment.
+
+1.  **Matplobbot (Telegram Bot)**: A sophisticated asynchronous bot built on `aiogram 3`. It serves as an intelligent gateway to programming libraries and educational materials. Its core features include interactive library browsing, full-text search, and a powerful on-demand rendering engine for LaTeX equations and Mermaid diagrams. All user interactions are meticulously logged to a shared SQLite database.
+
+2.  **Stats Dashboard (FastAPI Web App)**: A real-time monitoring dashboard powered by `FastAPI`. It features a clean, responsive frontend built with vanilla JavaScript and `Chart.js`. The dashboard provides deep insights into bot usage statistics by querying the shared **PostgreSQL** database and streams live log events directly from the bot's log file via WebSockets.
+
+The entire ecosystem is orchestrated by Docker Compose, utilizing shared volumes for the database and logs, which ensures data consistency and perfect integration between the two services.
+
+## ✨ Key Features
+
+### 🤖 Telegram Bot
+
+The bot provides a rich, interactive experience for developers, students, and researchers.
+
+#### Content Interaction
+-   **Library Browsing**: Interactively navigate the `matplobblib` library by modules and topics (`/matp_all`).
+-   **GitHub Repository Browsing**: Explore user-configured GitHub repositories file by file (`/lec_all`).
+-   **Full-Text Search**: Perform deep searches within the `matplobblib` source code (`/matp_search`) and across Markdown files in your linked GitHub repositories (`/lec_search`).
+
+#### 🔬 Dynamic On-Demand Rendering
+-   **LaTeX Rendering**: Convert LaTeX equations into crisp, high-quality PNG images using the `/latex` command. Results are cached in the database for instant retrieval on subsequent requests.
+-   **Mermaid.js Rendering**: Transform Mermaid diagram syntax into PNG images via the `/mermaid` command, utilizing a headless Chrome instance managed by Puppeteer.
+
+#### 📄 Advanced Markdown Processing
+The bot features a sophisticated pipeline for displaying `.md` files from GitHub. It uses **Pandoc** augmented with **custom Lua and Python filters** to correctly process and render complex documents containing embedded LaTeX and Mermaid code.
+
+| Display Mode | Description |
+| :--- | :--- |
+| 🖼 **Text + Images** | Renders the document directly into the chat, splitting it into a series of text messages and generated images for equations and diagrams. |
+| 📄 **HTML File** | Generates a fully self-contained `.html` file, bundling all necessary CSS and JS. Mermaid diagrams are interactive. |
+| ⚫ **MD File** | Sends the original, raw `.md` file without any processing. |
+
+#### ⚙️ Personalization & User Management
+-   **Favorites (`/favorites`)**: Bookmark useful code examples from your searches for quick access later.
+-   **Settings (`/settings`)**: A comprehensive inline menu allows users to:
+    -   Toggle the display of code docstrings.
+    -   Select their preferred Markdown display mode.
+    -   Fine-tune LaTeX rendering quality (DPI and padding).
+    -   Manage their personal list of GitHub repositories.
+
+#### 👑 Administration
+-   **Live Library Updates (`/update`)**: (Admin-only) Fetches the latest version of the `matplobblib` library from PyPI and dynamically reloads the module without bot downtime.
+-   **Cache Management (`/clear_cache`)**: (Admin-only) Instantly purges all application caches, including in-memory `TTLCache` for API calls and the persistent LaTeX cache in the database.
+
+### 📊 Web Dashboard
+
+The dashboard provides a live, data-rich view of the bot's health and user engagement.
+
+<div align="center">
+  <img src="https://github.com/Ackrome/matplobbot/blob/main/image/notes/Dashboard.png" alt="Dashboard Screenshot" width="800">
+</div>
+
+-   **Real-time Updates**: All statistical charts and counters update instantly via **WebSocket** connections, providing a true live monitoring experience.
+-   **Rich Data Visualization**:
+    -   Total user actions counter.
+    -   Leaderboard of the most active users, complete with their Telegram avatars.
+    -   Bar charts for the most frequently used commands and text messages.
+    -   A pie chart visualizing the distribution of action types (e.g., command vs. callback query).
+    -   A line chart illustrating user activity over time.
+-   **Live Log Streaming**: A live feed of the `bot.log` file is streamed directly to the web UI, enabling real-time operational monitoring.
+-   **Modern UI**: A clean, responsive interface with automatic **light and dark theme** support.
+
+## 🛠️ Architecture & Tech Stack
+
+
+
+The project is built on modern, asynchronous frameworks with a strong emphasis on modularity and separation of concerns.
+
+| Category | Technology & Key Libraries |
+| :--- | :--- |
+| **Backend** | Python 3.11+ |
+| **Bot Framework** | **Aiogram 3** (utilizing `Router` for modular handlers) |
+| **Web Framework** | **FastAPI**, Uvicorn |
+| **Database** | **PostgreSQL** (accessed asynchronously via `asyncpg`) |
+| **Frontend** | HTML5, CSS3, Vanilla JavaScript, **Chart.js** |
+| **Containerization** | **Docker, Docker Compose** |
+| **Rendering Pipeline** | **Pandoc** with custom Lua & Python filters, **TeX Live**, dvipng, **Mermaid-CLI**, Puppeteer |
+| **Key Libraries** | `aiohttp`, `cachetools`, `python-dotenv` |
+
+### Architectural Highlights
+-   **Decoupled Services**: The bot and the web dashboard run in separate Docker containers but communicate through a shared database and log volume, creating a robust, microservice-like architecture.
+-   **Modular Handlers**: The bot's logic is cleanly organized into feature-specific modules (`admin`, `rendering`, `settings`, etc.), each with its own `aiogram.Router`.
+-   **Service Layer**: Complex business logic, such as rendering documents and interacting with the GitHub API, is abstracted into a dedicated `services` package.
+-   **Asynchronous Everywhere**: From database calls (`asyncpg`) to external API requests (`aiohttp`), the entire stack is asynchronous to ensure high performance and scalability.
+-   **Intelligent Caching**: In-memory `TTLCache` is used extensively to cache GitHub API responses, reducing rate-limiting and speeding up user-facing operations.
+
+## ⚙️ Installation & Setup
+
+The project is fully containerized, enabling a simple and reproducible setup.
+
+### 1. Prerequisites
+-   **Docker** and **Docker Compose** must be installed on your system.
+
+### 2. Environment Variables
+
+Create a `.env` file in the project's root directory. Fill it out using the template below.
+
+```env
+# Get this from @BotFather on Telegram
+BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+
+# Comma-separated list of Telegram User IDs for admin command access
+ADMIN_USER_IDS=123456789,987654321
+
+# GitHub Personal Access Token with 'repo' scope for reading repositories
+# Required for /lec_search, /lec_all, and uploading rendered LaTeX images
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# --- PostgreSQL Credentials ---
+POSTGRES_USER=user
+POSTGRES_PASSWORD=password
+POSTGRES_DB=matplobbot_db
+POSTGRES_HOST=postgres # The service name in docker-compose
+POSTGRES_PORT=5432
+```
+
+### 3. Running with Docker Compose
+
+This is the recommended method for running the project.
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/Ackrome/matplobbot.git
+    cd matplobbot
+    ```
+
+2.  **Ensure your `.env` file is created and configured** as described above.
+
+3.  **Build and run the services in detached mode:**
+    ```bash
+    docker compose up --build -d
+    ```
+
+### 4. Accessing the Services
+
+-   **Telegram Bot**: Will be active and available on Telegram.
+-   **Web Dashboard**: Open `http://localhost:9583` in your browser.
+
+### 5. Stopping the Services
+
+-   To stop all running containers, execute:
+    ```bash
+    docker compose down
+    ```
+    -   Your database and log files will persist in named volumes. To remove all data, run `docker-compose down -v`.
+
+## 📚 Bot Command Reference
+
+| Command | Description | Usage |
+| :--- | :--- | :--- |
+| **General** | | |
+| `/start` | Initializes the bot and displays the main command keyboard. | Send to begin or reset your session. |
+| `/help` | Shows an interactive inline menu with descriptions of all available commands. | Send to get a quick overview of the bot's features. |
+| `/cancel` | Aborts any ongoing operation or conversation state. | Use if you get stuck waiting for input or want to return to the main menu. |
+| **Content Browsing & Search** | | |
+| `/matp_all` | Interactively browse the `matplobblib` library by modules and topics. | Send the command and navigate the library structure using inline buttons. |
+| `/matp_search` | Performs a full-text search for code examples within `matplobblib`. | Send the command, then type your search query (e.g., "line plot"). |
+| `/lec_all` | Interactively browse files in your configured GitHub repositories. | Send the command. If you have multiple repos, you'll be asked to choose one. |
+| `/lec_search` | Performs a full-text search within `.md` files in a chosen GitHub repository. | Send the command, choose a repository, then enter your search query. |
+| **Dynamic Rendering** | | |
+| `/latex` | Renders a LaTeX formula into a high-quality PNG image. | Send the command, then provide the LaTeX code (e.g., `\frac{a}{b}`). |
+| `/mermaid` | Renders a Mermaid.js diagram into a PNG image. | Send the command, then provide the Mermaid diagram code (e.g., `graph TD; A-->B;`). |
+| **Personalization** | | |
+| `/favorites` | View, manage, and access your saved favorite code examples. | Send the command to see your list. You can add items from search results or library browsing. |
+| `/settings` | Access and modify your personal settings. | Configure docstring visibility, Markdown display format, LaTeX quality, and manage your GitHub repositories. |
+| **Admin Commands** | | |
+| `/update` | Updates the `matplobblib` library to the latest version from PyPI. | *(Admin-only)* Send the command to perform a live update. |
+| `/clear_cache` | Clears all application caches (in-memory and database). | *(Admin-only)* Useful for forcing the bot to fetch fresh data. |
+
+### On-boarding users
+```mermaid
+graph TD
+    subgraph "User's First Interaction"
+        A[User sends /start] --> B{Is onboarding_completed == false?};
+    end
+
+    B -- Yes --> C[Onboarding Starts: Show Welcome Message & 'Next' button];
+    B -- No --> Z[Show Regular Welcome Message];
+
+    C --> D{User clicks 'Next'};
+    D --> E[Show GitHub Feature & 'Add Repository' button];
+
+    subgraph "Feature Interaction 1: GitHub"
+        E --> F{User clicks 'Add Repository'};
+        F --> G[User interacts with Repo Management];
+        G --> H{User clicks 'Back to Tour'};
+    end
+
+    E --> H;
+
+    H --> I[Show Library Feature & 'Next' button];
+    I --> J[Show Rendering Feature & 'Try LaTeX' button];
+
+    subgraph "Feature Interaction 2: Rendering"
+        J --> K{User can try LaTeX};
+    end
+
+    J --> L{User clicks 'Next'};
+    I --> L;
+
+    L --> M[Show Final Message & 'Finish Tour' button]
+
+    M --> N{User clicks 'Finish Tour'};
+    N --> O[Set onboarding_completed = true];
+    O --> P[Show Main Menu Keyboard];
+
+    style Z fill:#f9f,stroke:#333,stroke-width:2px
+    style P fill:#ccf,stroke:#333,stroke-width:2px
+```
+
+### 🚀 CI/CD Pipeline
+
+The project is built around a modern, secure, and fully automated CI/CD pipeline that handles everything from code validation to production deployment. This pipeline leverages a hybrid approach, using a self-hosted GitHub Runner to securely bridge the public cloud (GitHub) with a private deployment environment (Proxmox/Tailscale).
+
+**Key Technologies:**
+*   **Continuous Integration**: GitHub Actions
+*   **Continuous Deployment**: Jenkins
+*   **Containerization**: Docker & Docker Compose
+*   **Secure Networking**: Tailscale
+
+#### The Workflow
+
+The entire process is event-driven, starting with a simple `git push` and ending with the new version of the application running live, with no manual intervention required.
+
+```mermaid
+graph TD
+    subgraph "GitHub (Public Cloud)"
+        A[Developer pushes to main branch] --> B{GitHub Actions Trigger};
+    end
+
+    subgraph "Your Proxmox Network (Private & Secure)"
+        direction LR
+        C(Self-Hosted GitHub Runner VM)
+        D(Jenkins VM)
+        E(Application VM)
+
+        C -- "Executes Job Locally" --> F{Test, Build & Push};
+        F -- "Pushes images" --> G[GitHub Container Registry];
+        F -- "Triggers Deploy via Tailscale IP" --> D;
+        D -- "Executes Deploy via SSH" --> E;
+    end
+    
+    B -- "Assigns Job" --> C;
+    G -- "Images are pulled by App VM" --> E;
+
+    subgraph "Deployment Steps on Application VM"
+        direction TB
+        E --> H{1. Jenkins creates .env file from secrets};
+        H --> I{2. Pull new Docker images};
+        I --> J{3. docker-compose up -d};
+        J --> K[🚀 New version is live!];
+    end
+```
+
+#### Step-by-Step Breakdown:
+
+1.  **Commit & Push**: A developer pushes new code to the `main` branch on the GitHub repository.
+2.  **Job Assignment**: GitHub Actions detects the push and assigns a new workflow job to the registered **self-hosted runner**.
+3.  **CI on Self-Hosted Runner**: The runner, running on a dedicated VM within your private network, picks up the job. It performs the **Continuous Integration** steps locally:
+    *   Checks out the source code.
+    *   Sets up the Docker Buildx environment.
+    *   Builds the `matplobbot-bot` and `matplobbot-api` Docker images.
+    *   Pushes the newly tagged images to the GitHub Container Registry (GHCR).
+4.  **Secure Trigger for CD**: Upon successful completion of the CI stage, a subsequent step in the same workflow on the self-hosted runner sends a secure webhook (`cURL` request) to the Jenkins server. This communication is safe because the runner and Jenkins are on the same private Tailscale network.
+5.  **Deployment Orchestration**: Jenkins receives the webhook and triggers the `matplobbot-deploy` pipeline. This **Continuous Deployment** pipeline performs the final steps:
+    *   It securely loads the application's production secrets (like `BOT_TOKEN`) from its encrypted credentials store.
+    *   It connects to the dedicated **Application VM** via SSH.
+    *   It dynamically writes the secrets into a `.env` file on the Application VM.
+    *   It executes the `deploy.sh` script on the Application VM.
+6.  **Final Rollout**: The `deploy.sh` script orchestrates the final rollout by:
+    *   Pulling the new Docker images from GHCR.
+    *   Running `docker-compose up -d` to gracefully restart the services with the updated images and configuration.
+    *   Running `docker compose up -d` to gracefully restart the services with the updated images and configuration.

matplobbot_shared-0.1.48/matplobbot_shared.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: matplobbot-shared
+Version: 0.1.48
+Summary: Shared library for the Matplobbot ecosystem (database, services, i18n).
+Author: Ackrome
+Author-email: ivansergeyevich@gmail.com
+Requires-Python: >=3.11
+Requires-Dist: asyncpg
+Requires-Dist: aiohttp
+Requires-Dist: certifi
+Requires-Dist: redis
+Dynamic: author
+Dynamic: author-email
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

matplobbot_shared-0.1.48/matplobbot_shared.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+setup.py
+matplobbot_shared.egg-info/PKG-INFO
+matplobbot_shared.egg-info/SOURCES.txt
+matplobbot_shared.egg-info/dependency_links.txt
+matplobbot_shared.egg-info/requires.txt
+matplobbot_shared.egg-info/top_level.txt
+shared_lib/__init__.py
+shared_lib/database.py
+shared_lib/i18n.py
+shared_lib/redis_client.py
+shared_lib/services/__init__.py
+shared_lib/services/schedule_service.py
+shared_lib/services/university_api.py

matplobbot_shared-0.1.48/matplobbot_shared.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matplobbot_shared-0.1.48/matplobbot_shared.egg-info/requires.txt

@@ -0,0 +1,4 @@
+asyncpg
+aiohttp
+certifi
+redis

matplobbot_shared-0.1.48/matplobbot_shared.egg-info/top_level.txt

@@ -0,0 +1 @@
+shared_lib

matplobbot_shared-0.1.48/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matplobbot_shared-0.1.48/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="matplobbot-shared",
+    version="0.1.48", # Let's use the version from your requirements.txt
+    packages=find_packages(include=['shared_lib', 'shared_lib.*']),
+    description="Shared library for the Matplobbot ecosystem (database, services, i18n).",
+    author="Ackrome",
+    author_email="ivansergeyevich@gmail.com",
+    # Declare dependencies for this library
+    install_requires=[
+        "asyncpg",
+        "aiohttp", # Specify versions as needed
+        "certifi",
+        "redis"
+    ],
+    # This tells setuptools that the package data (like .json files) should be included
+    package_data={
+        'shared_lib.locales': ['*.json'],
+    },
+    include_package_data=True,
+    python_requires='>=3.11',
+)

matplobbot_shared-0.1.48/shared_lib/__init__.py

@@ -0,0 +1 @@
+# This file makes shared_lib a Python package

matplobbot_shared-0.1.48/shared_lib/database.py

@@ -0,0 +1,608 @@
+import asyncpg
+import datetime
+import logging
+import json
+import os
+
+logger = logging.getLogger(__name__)
+
+# --- PostgreSQL Database Configuration ---
+# The DATABASE_URL should be a complete connection string.
+# Example for Docker: postgresql://user:password@postgres:5432/matplobbot_db
+# Example for local:  postgresql://user:password@localhost:5432/matplobbot_db
+DATABASE_URL = os.getenv("DATABASE_URL")
+
+# Global connection pool
+pool = None
+
+async def init_db_pool():
+    global pool
+    if pool is None:
+        try:
+            if not DATABASE_URL:
+                logger.critical("DATABASE_URL environment variable is not set. Cannot initialize database pool.")
+                raise ValueError("DATABASE_URL is not set.")
+            pool = await asyncpg.create_pool(DATABASE_URL, min_size=5, max_size=20)
+            logger.info("Shared DB Pool: Database connection pool created successfully.")
+        except Exception as e:
+            logger.error(f"Failed to create database connection pool: {e}", exc_info=True)
+            raise
+
+async def close_db_pool():
+    global pool
+    if pool:
+        await pool.close()
+        logger.info("Shared DB Pool: Database connection pool closed.")
+
+def get_db_connection_obj():
+    if pool is None:
+        # In FastAPI context, this would be an HTTPException
+        raise ConnectionError("Database connection pool is not initialized.")
+    return pool.acquire()
+
+# --- User Settings Defaults ---
+DEFAULT_SETTINGS = {
+    'show_docstring': True,
+    'latex_padding': 15,
+    'md_display_mode': 'md_file',
+    'latex_dpi': 300,
+    'language': 'en',
+}
+
+async def init_db():
+    """Initializes the database and creates tables if they don't exist."""
+    if pool is None:
+        await init_db_pool()
+        
+    async with pool.acquire() as connection:
+        async with connection.transaction():
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS users (
+                user_id BIGINT PRIMARY KEY,
+                username TEXT,
+                full_name TEXT NOT NULL,
+                avatar_pic_url TEXT,
+                settings JSONB DEFAULT '{}'::jsonb,
+                onboarding_completed BOOLEAN DEFAULT FALSE
+            )
+            ''')
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS user_actions (
+                id SERIAL PRIMARY KEY,
+                user_id BIGINT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
+                action_type TEXT NOT NULL,
+                action_details TEXT,
+                timestamp TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+            )
+            ''')
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS user_favorites (
+                id SERIAL PRIMARY KEY,
+                user_id BIGINT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
+                code_path TEXT NOT NULL,
+                added_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+                UNIQUE(user_id, code_path)
+            )
+            ''')
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS latex_cache (
+                formula_hash TEXT PRIMARY KEY,
+                image_url TEXT NOT NULL,
+                created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+            )
+            ''')
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS user_github_repos (
+                id SERIAL PRIMARY KEY,
+                user_id BIGINT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
+                repo_path TEXT NOT NULL,
+                added_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+                UNIQUE(user_id, repo_path)
+            )
+            ''')
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS user_schedule_subscriptions (
+                id SERIAL PRIMARY KEY,
+                user_id BIGINT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
+                chat_id BIGINT NOT NULL,
+                entity_type TEXT NOT NULL,
+                entity_id TEXT NOT NULL,
+                entity_name TEXT NOT NULL,
+                notification_time TIME NOT NULL,
+                is_active BOOLEAN DEFAULT TRUE,
+                last_schedule_hash TEXT,
+                deactivated_at TIMESTAMPTZ DEFAULT NULL,
+                message_thread_id BIGINT DEFAULT NULL,
+                UNIQUE(chat_id, entity_type, entity_id, notification_time)
+            )
+            ''')
+            await connection.execute('''
+            CREATE TABLE IF NOT EXISTS chat_settings (
+                chat_id BIGINT PRIMARY KEY,
+                settings JSONB DEFAULT '{}'::jsonb
+            )
+            ''')
+
+    logger.info("Database tables initialized.")
+
+async def log_user_action(user_id: int, username: str | None, full_name: str, avatar_pic_url: str | None, action_type: str, action_details: str | None):
+    async with pool.acquire() as connection:
+        try:
+            await connection.execute('''
+                INSERT INTO users (user_id, username, full_name, avatar_pic_url)
+                VALUES ($1, $2, $3, $4)
+                ON CONFLICT(user_id) DO UPDATE SET
+                    username = EXCLUDED.username,
+                    full_name = EXCLUDED.full_name,
+                    avatar_pic_url = EXCLUDED.avatar_pic_url;
+            ''', user_id, username, full_name, avatar_pic_url)
+            await connection.execute('''
+                INSERT INTO user_actions (user_id, action_type, action_details)
+                VALUES ($1, $2, $3);
+            ''', user_id, action_type, action_details)
+        except Exception as e:
+            logger.error(f"Error logging user action to DB: {e}", exc_info=True)
+
+async def get_user_settings(user_id: int) -> dict:
+    async with pool.acquire() as connection:
+        settings_json = await connection.fetchval("SELECT settings FROM users WHERE user_id = $1", user_id)
+        db_settings = json.loads(settings_json) if settings_json else {}
+    merged_settings = DEFAULT_SETTINGS.copy()
+    merged_settings.update(db_settings)
+    return merged_settings
+
+async def get_chat_settings(chat_id: int) -> dict:
+    """Fetches settings for a specific chat, creating a default record if none exists."""
+    async with pool.acquire() as connection:
+        # Upsert to ensure a row exists for the chat.
+        await connection.execute("""
+            INSERT INTO chat_settings (chat_id) VALUES ($1)
+            ON CONFLICT (chat_id) DO NOTHING;
+        """, chat_id)
+        settings_json = await connection.fetchval("SELECT settings FROM chat_settings WHERE chat_id = $1", chat_id)
+        db_settings = json.loads(settings_json) if settings_json else {}
+    # Merge with defaults to ensure all keys are present.
+    merged_settings = DEFAULT_SETTINGS.copy()
+    merged_settings.update(db_settings)
+    return merged_settings
+
+async def update_user_settings_db(user_id: int, settings: dict):
+    async with pool.acquire() as connection:
+        await connection.execute("UPDATE users SET settings = $1 WHERE user_id = $2", json.dumps(settings), user_id)
+
+async def update_chat_settings_db(chat_id: int, settings: dict):
+    async with pool.acquire() as connection:
+        await connection.execute("UPDATE chat_settings SET settings = $1 WHERE chat_id = $2", json.dumps(settings), chat_id)
+
+# --- Favorites ---
+async def add_favorite(user_id: int, code_path: str):
+    async with pool.acquire() as connection:
+        try:
+            await connection.execute("INSERT INTO user_favorites (user_id, code_path) VALUES ($1, $2)", user_id, code_path)
+            return True
+        except asyncpg.UniqueViolationError:
+            return False
+
+async def remove_favorite(user_id: int, code_path: str):
+    async with pool.acquire() as connection:
+        await connection.execute("DELETE FROM user_favorites WHERE user_id = $1 AND code_path = $2", user_id, code_path)
+
+async def get_favorites(user_id: int) -> list:
+    async with pool.acquire() as connection:
+        rows = await connection.fetch("SELECT code_path FROM user_favorites WHERE user_id = $1", user_id)
+        return [row['code_path'] for row in rows]
+
+# --- LaTeX Cache ---
+async def clear_latex_cache():
+    async with pool.acquire() as connection:
+        await connection.execute("TRUNCATE TABLE latex_cache")
+
+# --- GitHub Repos ---
+async def add_user_repo(user_id: int, repo_path: str) -> bool:
+    async with pool.acquire() as connection:
+        try:
+            await connection.execute("INSERT INTO user_github_repos (user_id, repo_path) VALUES ($1, $2)", user_id, repo_path)
+            return True
+        except asyncpg.UniqueViolationError:
+            return False
+
+async def get_user_repos(user_id: int) -> list[str]:
+    async with pool.acquire() as connection:
+        rows = await connection.fetch("SELECT repo_path FROM user_github_repos WHERE user_id = $1 ORDER BY added_at ASC", user_id)
+        return [row['repo_path'] for row in rows]
+
+async def remove_user_repo(user_id: int, repo_path: str):
+    async with pool.acquire() as connection:
+        await connection.execute("DELETE FROM user_github_repos WHERE user_id = $1 AND repo_path = $2", user_id, repo_path)
+
+async def update_user_repo(user_id: int, old_repo_path: str, new_repo_path: str):
+    async with pool.acquire() as connection:
+        await connection.execute("UPDATE user_github_repos SET repo_path = $1 WHERE user_id = $2 AND repo_path = $3", new_repo_path, user_id, old_repo_path)
+
+# --- Onboarding ---
+async def is_onboarding_completed(user_id: int) -> bool:
+    async with pool.acquire() as connection:
+        completed = await connection.fetchval("SELECT onboarding_completed FROM users WHERE user_id = $1", user_id)
+        return completed or False
+
+async def set_onboarding_completed(user_id: int):
+    async with pool.acquire() as connection:
+        await connection.execute("UPDATE users SET onboarding_completed = TRUE WHERE user_id = $1", user_id)
+
+# --- Schedule Subscriptions ---
+async def add_schedule_subscription(user_id: int, chat_id: int, message_thread_id: int | None, entity_type: str, entity_id: str, entity_name: str, notification_time: datetime.time) -> bool:
+    async with pool.acquire() as connection:
+        try:
+            await connection.execute('''
+                INSERT INTO user_schedule_subscriptions (user_id, chat_id, message_thread_id, entity_type, entity_id, entity_name, notification_time)
+                VALUES ($1, $2, $3, $4, $5, $6, $7)
+                ON CONFLICT (chat_id, entity_type, entity_id, notification_time) DO UPDATE SET
+                    entity_name = EXCLUDED.entity_name,
+                    -- When the same time is re-added, ensure it's active
+                    is_active = TRUE,
+                    -- Also update the user who initiated it, in case it changes
+                    user_id = EXCLUDED.user_id;
+            ''', user_id, chat_id, message_thread_id, entity_type, entity_id, entity_name, notification_time)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to add schedule subscription for user {user_id}: {e}", exc_info=True)
+            return False
+ 
+async def get_user_subscriptions(user_id: int, page: int = 0, page_size: int = 5) -> tuple[list, int]:
+    """
+    Gets a paginated list of active schedule subscriptions for a specific user.
+    Returns a tuple: (list of subscriptions, total count).
+    """
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        # Query to get the paginated list
+        offset = page * page_size
+        rows = await connection.fetch("""
+            SELECT id, user_id, chat_id, entity_type, entity_id, entity_name, TO_CHAR(notification_time, 'HH24:MI') as notification_time, is_active
+            FROM user_schedule_subscriptions
+            WHERE user_id = $1
+            ORDER BY entity_name, notification_time
+            LIMIT $2 OFFSET $3
+        """, user_id, page_size, offset)
+        
+        # Query to get the total count for pagination
+        total_count = await connection.fetchval("SELECT COUNT(*) FROM user_schedule_subscriptions WHERE user_id = $1", user_id)
+
+        return [dict(row) for row in rows], total_count or 0
+
+async def get_chat_subscriptions(chat_id: int, page: int = 0, page_size: int = 5) -> tuple[list, int]:
+    """
+    Gets a paginated list of active schedule subscriptions for a specific chat.
+    Returns a tuple: (list of subscriptions, total count).
+    """
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        offset = page * page_size
+        rows = await connection.fetch("""
+            SELECT id, user_id, chat_id, entity_type, entity_id, entity_name, TO_CHAR(notification_time, 'HH24:MI') as notification_time, is_active
+            FROM user_schedule_subscriptions
+            WHERE chat_id = $1
+            ORDER BY entity_name, notification_time
+            LIMIT $2 OFFSET $3
+        """, chat_id, page_size, offset)
+        
+        total_count = await connection.fetchval("SELECT COUNT(*) FROM user_schedule_subscriptions WHERE chat_id = $1", chat_id)
+
+        return [dict(row) for row in rows], total_count or 0
+
+async def toggle_subscription_status(subscription_id: int, user_id: int, is_chat_admin: bool = False) -> tuple[bool, str] | None:
+    """
+    Toggles the is_active status of a subscription, checking for ownership or admin rights.
+    Returns a tuple of (new_status, entity_name) on success, otherwise None.
+    """
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        # First, verify the user has permission if they are not a chat admin
+        if not is_chat_admin:
+            owner_id = await connection.fetchval("SELECT user_id FROM user_schedule_subscriptions WHERE id = $1", subscription_id)
+            if owner_id != user_id:
+                logger.warning(f"User {user_id} attempted to toggle subscription {subscription_id} without permission.")
+                return None
+
+        # If permission is granted, toggle the status and return the new state
+        result = await connection.fetchrow(
+            """
+            UPDATE user_schedule_subscriptions
+            SET is_active = NOT is_active,
+                deactivated_at = CASE WHEN is_active THEN NOW() ELSE NULL END
+            WHERE id = $1
+            RETURNING is_active, entity_name
+            """,
+            subscription_id
+        )
+        return (result['is_active'], result['entity_name']) if result else None
+
+async def remove_schedule_subscription(subscription_id: int, user_id: int, is_chat_admin: bool = False) -> str | None:
+    """
+    Removes a specific schedule subscription, checking for ownership or admin rights.
+    - If is_chat_admin is False, it only deletes if user_id matches the creator.
+    - If is_chat_admin is True, it deletes regardless of the creator.
+    Returns the entity_name of the deleted subscription on success, otherwise None.
+    """
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        if is_chat_admin:
+            # Admin can delete any subscription in their chat.
+            deleted_name = await connection.fetchval(
+                "DELETE FROM user_schedule_subscriptions WHERE id = $1 RETURNING entity_name",
+                subscription_id)
+        else:
+            # Regular user can only delete their own subscriptions.
+            deleted_name = await connection.fetchval(
+                "DELETE FROM user_schedule_subscriptions WHERE id = $1 AND user_id = $2 RETURNING entity_name",
+                subscription_id, user_id)
+        return deleted_name
+
+async def update_subscription_notification_time(subscription_id: int, new_time: datetime.time, user_id: int, is_chat_admin: bool = False) -> str | None:
+    """
+    Updates the notification time for a specific subscription, checking for ownership or admin rights.
+    Returns the entity_name of the updated subscription on success, otherwise None.
+    """
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        if is_chat_admin:
+            # Admin can update any subscription in their chat.
+            updated_name = await connection.fetchval(
+                "UPDATE user_schedule_subscriptions SET notification_time = $1 WHERE id = $2 RETURNING entity_name",
+                new_time, subscription_id
+            )
+        else:
+            # Regular user can only update their own subscriptions.
+            updated_name = await connection.fetchval(
+                "UPDATE user_schedule_subscriptions SET notification_time = $1 WHERE id = $2 AND user_id = $3 RETURNING entity_name",
+                new_time, subscription_id, user_id
+            )
+        return updated_name
+
+
+async def delete_old_inactive_subscriptions(days_inactive: int = 30):
+    """
+    Deletes subscriptions that have been inactive for more than a specified number of days.
+    Returns the number of deleted subscriptions.
+    """
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        result = await connection.execute(
+            "DELETE FROM user_schedule_subscriptions WHERE is_active = FALSE AND deactivated_at < NOW() - INTERVAL '$1 days'",
+            str(days_inactive)
+        )
+        return int(result.split(' ')[-1]) # Returns "DELETE N", we want N
+
+async def get_subscriptions_for_notification(notification_time: str) -> list:
+    async with pool.acquire() as connection:
+        # Modified to select the subscription ID and the last hash
+        # Also select chat_id to know where to send the message
+        rows = await connection.fetch("""
+            SELECT id, user_id, chat_id, message_thread_id, entity_type, entity_id, entity_name, last_schedule_hash
+            FROM user_schedule_subscriptions
+            WHERE is_active = TRUE AND TO_CHAR(notification_time, 'HH24:MI') = $1
+        """, notification_time)
+        return [dict(row) for row in rows]
+
+async def get_all_active_subscriptions() -> list:
+    """Fetches all active schedule subscriptions from the database."""
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        rows = await connection.fetch("""
+            SELECT id, user_id, chat_id, message_thread_id, entity_type, entity_id, entity_name, last_schedule_hash
+            FROM user_schedule_subscriptions WHERE is_active = TRUE
+        """)
+        return [dict(row) for row in rows]
+
+async def update_subscription_hash(subscription_id: int, new_hash: str):
+    """Updates the schedule hash for a specific subscription."""
+    if not pool:
+        raise ConnectionError("Database pool is not initialized.")
+    async with pool.acquire() as connection:
+        await connection.execute("UPDATE user_schedule_subscriptions SET last_schedule_hash = $1 WHERE id = $2", new_hash, subscription_id)
+
+# --- FastAPI Specific Queries ---
+async def get_leaderboard_data_from_db(db_conn):
+    # The timestamp is stored in UTC (TIMESTAMPTZ). We convert it to Moscow time for display.
+    query = """
+        SELECT
+            u.user_id,
+            u.full_name,
+            COALESCE(u.username, 'N/A') AS username,
+            u.avatar_pic_url,
+            COUNT(ua.id)::int AS actions_count,
+            TO_CHAR(MAX(ua.timestamp AT TIME ZONE 'Europe/Moscow'), 'YYYY-MM-DD HH24:MI:SS') AS last_action_time
+        FROM users u
+        JOIN user_actions ua ON u.user_id = ua.user_id
+        GROUP BY u.user_id, u.full_name, u.username, u.avatar_pic_url
+        ORDER BY actions_count DESC LIMIT 100;
+    """
+    rows = await db_conn.fetch(query)
+    return [dict(row) for row in rows]
+
+async def get_popular_commands_data_from_db(db_conn):
+    query = """
+        SELECT action_details as command, COUNT(id) as command_count FROM user_actions
+        WHERE action_type = 'command' GROUP BY action_details ORDER BY command_count DESC LIMIT 10;
+    """
+    rows = await db_conn.fetch(query)
+    return [{"command": row['command'], "count": row['command_count']} for row in rows]
+
+async def get_popular_messages_data_from_db(db_conn):
+    query = """
+        SELECT CASE WHEN LENGTH(action_details) > 30 THEN SUBSTR(action_details, 1, 27) || '...' ELSE action_details END as message_snippet,
+        COUNT(id) as message_count FROM user_actions
+        WHERE action_type = 'text_message' AND action_details IS NOT NULL AND action_details != ''
+        GROUP BY message_snippet ORDER BY message_count DESC LIMIT 10;
+    """
+    rows = await db_conn.fetch(query)
+    return [{"message": row['message_snippet'], "count": row['message_count']} for row in rows]
+
+async def get_action_types_distribution_from_db(db_conn):
+    query = "SELECT action_type, COUNT(id) as type_count FROM user_actions GROUP BY action_type ORDER BY type_count DESC;"
+    rows = await db_conn.fetch(query)
+    return [{"action_type": row['action_type'], "count": row['type_count']} for row in rows]
+
+async def get_activity_over_time_data_from_db(db_conn, period='day'):
+    date_format = {'day': 'YYYY-MM-DD', 'week': 'IYYY-IW', 'month': 'YYYY-MM'}.get(period, 'YYYY-MM-DD')
+    # Convert timestamp to Moscow time before grouping
+    query = f"""
+        SELECT TO_CHAR(timestamp AT TIME ZONE 'Europe/Moscow', '{date_format}') as period_start, COUNT(id) as actions_count 
+        FROM user_actions GROUP BY period_start ORDER BY period_start ASC;
+    """
+    rows = await db_conn.fetch(query)
+    return [{"period": row['period_start'], "count": row['actions_count']} for row in rows]
+
+
+async def get_user_profile_data_from_db(
+    db_conn,
+    user_id: int,
+    page: int = 1,
+    page_size: int = 50,
+    sort_by: str = 'timestamp',
+    sort_order: str = 'desc'
+):
+    """Извлекает детали профиля пользователя и пагинированный список его действий."""
+    # --- Безопасная сортировка ---
+    allowed_sort_columns = ['id', 'action_type', 'action_details', 'timestamp'] # These are ua columns
+    if sort_by not in allowed_sort_columns:
+        sort_by = 'timestamp' # Значение по умолчанию
+    sort_order = 'ASC' if sort_order.lower() == 'asc' else 'DESC' # Безопасное определение порядка
+
+    # --- Единый запрос для получения всех данных ---
+    # Используем CTE и оконные функции для эффективности.
+    # 1. Выбираем все действия пользователя.
+    # 2. С помощью оконной функции COUNT(*) OVER () получаем общее количество действий без дополнительного запроса.
+    # 3. Присоединяем информацию о пользователе.
+    # 4. Применяем пагинацию и сортировку.
+    query = f"""
+        WITH UserActions AS (
+            SELECT
+                id,
+                action_type,
+                action_details,
+                TO_CHAR(timestamp AT TIME ZONE 'Europe/Moscow', 'YYYY-MM-DD HH24:MI:SS') AS timestamp
+            FROM user_actions
+            WHERE user_id = $1
+        )
+        SELECT
+            u.user_id,
+            u.full_name,
+            COALESCE(u.username, 'Нет username') AS username,
+            u.avatar_pic_url,
+            (SELECT COUNT(*) FROM UserActions) as total_actions,
+            ua.id as action_id,
+            ua.action_type,
+            ua.action_details,
+            ua.timestamp
+        FROM users u
+        LEFT JOIN UserActions ua ON 1=1
+        WHERE u.user_id = $2
+        ORDER BY ua.{sort_by} {sort_order}
+        LIMIT $3 OFFSET $4;
+    """
+    offset = (page - 1) * page_size
+    rows = await db_conn.fetch(query, user_id, user_id, page_size, offset)
+    if not rows:
+        # If user exists but has no actions, we might get no rows. Check user existence separately.
+        user_exists = await db_conn.fetchrow("SELECT 1 FROM users WHERE user_id = $1", user_id)
+        if not user_exists:
+            return None # User not found
+        # User exists but has no actions, return empty actions list
+        user_details_row = await db_conn.fetchrow("SELECT user_id, full_name, COALESCE(username, 'Нет username') AS username, avatar_pic_url FROM users WHERE user_id = $1", user_id)
+        return {
+            "user_details": dict(user_details_row),
+            "actions": [],
+            "total_actions": 0
+        }
+
+    first_row = dict(rows[0])
+    user_details = {
+        "user_id": first_row["user_id"],
+        "full_name": first_row["full_name"],
+        "username": first_row["username"],
+        "avatar_pic_url": first_row["avatar_pic_url"]
+    }
+    total_actions = first_row["total_actions"]
+
+    # Собираем действия, если они есть (может быть пользователь без действий)
+    actions = []
+    for row in rows:
+        row_dict = dict(row)
+        if row_dict["action_id"] is not None: # action_id не NULL
+            actions.append({
+                "id": row_dict["action_id"],
+                "action_type": row_dict["action_type"],
+                "action_details": row_dict["action_details"],
+                "timestamp": row_dict["timestamp"]
+            })
+
+    return {
+        "user_details": user_details,
+        "actions": actions,
+        "total_actions": total_actions
+    }
+
+async def get_users_for_action(db_conn, action_type: str, action_details: str, page: int = 1, page_size: int = 15, sort_by: str = 'full_name', sort_order: str = 'asc'):
+    """Извлекает пагинированный список уникальных пользователей, совершивших определенное действие."""
+    # Note: action_type for messages is 'text_message' in the DB
+    db_action_type = 'text_message' if action_type == 'message' else action_type
+    offset = (page - 1) * page_size
+
+    # --- Безопасная сортировка ---
+    allowed_sort_columns = ['user_id', 'full_name', 'username'] # These are u columns
+    if sort_by not in allowed_sort_columns:
+        sort_by = 'full_name' # Значение по умолчанию
+    sort_order = 'DESC' if sort_order.lower() == 'desc' else 'ASC' # Безопасное определение порядка
+    order_by_clause = f"ORDER BY u.{sort_by} {sort_order}"
+
+    # Query for total count of distinct users
+    count_query = """
+        SELECT COUNT(DISTINCT u.user_id)
+        FROM users u
+        JOIN user_actions ua ON u.user_id = ua.user_id
+        WHERE ua.action_type = $1 AND ua.action_details = $2;
+    """
+    total_users = await db_conn.fetchval(count_query, db_action_type, action_details)
+
+    # Query for the paginated list of users
+    users_query = f"""
+        SELECT DISTINCT
+            u.user_id,
+            u.full_name,
+            COALESCE(u.username, 'Нет username') AS username
+        FROM users u
+        JOIN user_actions ua ON u.user_id = ua.user_id
+        WHERE ua.action_type = $1 AND ua.action_details = $2
+        {order_by_clause}
+        LIMIT $3 OFFSET $4;
+    """
+    rows = await db_conn.fetch(users_query, db_action_type, action_details, page_size, offset)
+    users = [dict(row) for row in rows]
+
+    return {
+        "users": users,
+        "total_users": total_users
+    }
+
+async def get_all_user_actions(db_conn, user_id: int):
+    """Извлекает ВСЕ действия для указанного пользователя без пагинации."""
+    query = """
+        SELECT
+            id,
+            action_type,
+            action_details,
+            TO_CHAR(timestamp AT TIME ZONE 'Europe/Moscow', 'YYYY-MM-DD HH24:MI:SS') AS timestamp
+        FROM user_actions
+        WHERE user_id = $1
+        ORDER BY timestamp DESC;
+    """
+    rows = await db_conn.fetch(query, user_id)
+    return [dict(row) for row in rows]

matplobbot_shared-0.1.48/shared_lib/i18n.py

@@ -0,0 +1,56 @@
+import json
+from pathlib import Path
+import logging
+
+from .database import get_user_settings, get_chat_settings
+
+logger = logging.getLogger(__name__)
+
+
+class Translator:
+    def __init__(self, locales_dir: Path, default_lang: str = "en"):
+        self.locales_dir = locales_dir
+        self.default_lang = default_lang
+        self.translations = {}
+        self._load_translations()
+
+    def _load_translations(self):
+        """Loads all .json language files from the locales directory."""
+        for lang_file in self.locales_dir.glob("*.json"):
+            lang_code = lang_file.stem
+            try:
+                with open(lang_file, 'r', encoding='utf-8') as f:
+                    self.translations[lang_code] = json.load(f)
+                logger.info(f"Successfully loaded language: {lang_code}")
+            except (json.JSONDecodeError, IOError) as e:
+                logger.error(f"Failed to load language file {lang_file}: {e}")
+
+    async def get_language(self, user_id: int, chat_id: int | None = None) -> str:
+        """
+        Fetches the appropriate language.
+        - If chat_id is provided and it's a group chat, it uses the group's setting.
+        - Otherwise, it falls back to the user's personal setting.
+        """
+        # If it's a group chat (negative chat_id), check for a group-specific setting.
+        if chat_id and chat_id < 0:
+            chat_settings = await get_chat_settings(chat_id)
+            return chat_settings.get('language', self.default_lang)
+        
+        user_settings = await get_user_settings(user_id)
+        return user_settings.get('language', self.default_lang)
+
+    def gettext(self, lang: str, key: str, **kwargs) -> str:
+        """
+        Gets a translated string for a given key and language.
+        Falls back to the default language if the key is not found.
+        """
+        text = self.translations.get(lang, {}).get(key)
+        if text is None:
+            # Fallback to default language
+            text = self.translations.get(self.default_lang, {}).get(key, f"_{key}_")
+
+        return text.format(**kwargs)
+
+
+# Create a single instance of the translator
+translator = Translator(locales_dir=Path(__file__).parent / "locales")

matplobbot_shared-0.1.48/shared_lib/redis_client.py

@@ -0,0 +1,46 @@
+import redis.asyncio as redis
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+# TTL для кэша в секундах (например, 1 час)
+CACHE_TTL = 3600
+
+class RedisClient:
+    def __init__(self, host='localhost', port=6379):
+        # Используем connection_pool для более эффективного управления соединениями
+        self.pool = redis.ConnectionPool(host=host, port=port, db=0, decode_responses=True)
+        self.client = redis.Redis(connection_pool=self.pool)
+
+    async def set_user_cache(self, user_id: int, key: str, data: dict, ttl: int = CACHE_TTL):
+        """Сохраняет данные в кэш для конкретного пользователя."""
+        try:
+            redis_key = f"user_cache:{user_id}:{key}"
+            await self.client.set(redis_key, json.dumps(data), ex=ttl)
+        except Exception as e:
+            logger.error(f"Ошибка при записи в Redis для user_id={user_id}, key={key}: {e}")
+
+    async def get_user_cache(self, user_id: int, key: str) -> dict | None:
+        """Получает данные из кэша для конкретного пользователя."""
+        try:
+            redis_key = f"user_cache:{user_id}:{key}"
+            data = await self.client.get(redis_key)
+            if data:
+                return json.loads(data)
+            return None
+        except Exception as e:
+            logger.error(f"Ошибка при чтении из Redis для user_id={user_id}, key={key}: {e}")
+            return None
+
+    async def clear_all_user_cache(self):
+        """Очищает весь пользовательский кэш (ключи, начинающиеся с 'user_cache:')."""
+        try:
+            async for key in self.client.scan_iter("user_cache:*"):
+                await self.client.delete(key)
+            logger.info("Весь пользовательский кэш в Redis очищен.")
+        except Exception as e:
+            logger.error(f"Ошибка при очистке кэша Redis: {e}")
+
+# Создаем единственный экземпляр клиента
+redis_client = RedisClient(host='redis')

matplobbot_shared-0.1.48/shared_lib/services/schedule_service.py

@@ -0,0 +1,154 @@
+# bot/services/schedule_service.py
+
+from typing import List, Dict, Any
+from datetime import datetime, date
+from collections import defaultdict
+from ics import Calendar, Event
+from zoneinfo import ZoneInfo
+from aiogram.utils.markdown import hcode
+
+from shared_lib.i18n import translator
+
+names_shorter = defaultdict(lambda: 'Unknown')
+to_add = {
+    'Практические (семинарские) занятия': 'Семинар',
+    'Лекции': 'Лекция',
+    'Консультации текущие': 'Консультация',
+    'Повторная промежуточная аттестация (экзамен)':'Пересдача'
+    }
+names_shorter.update(to_add)
+
+def _format_lesson_for_diff(lesson: Dict[str, Any], lang: str) -> str:
+    """Formats a single lesson for display in a diff message."""
+    date_obj = datetime.strptime(lesson['date'], "%Y-%m-%d").date()
+    day_header = f"<b>{date_obj.strftime('%A, %d.%m.%Y')}</b>"
+    details = [
+        hcode(f"{lesson['beginLesson']} - {lesson['endLesson']} | {lesson['auditorium']}"),
+        f"{lesson['discipline']} ({names_shorter[lesson['kindOfWork']]})",
+        f"<i>{translator.gettext(lang, 'lecturer_prefix')}: {lesson.get('lecturer_title', 'N/A').replace('_', ' ')}</i>"
+    ]
+    return f"{day_header}\n" + "\n".join(details)
+
+def diff_schedules(old_data: List[Dict[str, Any]], new_data: List[Dict[str, Any]], lang: str) -> str | None:
+    """Compares two schedule datasets and returns a human-readable diff."""
+    old_lessons = {lesson['lessonOid']: lesson for lesson in old_data}
+    new_lessons = {lesson['lessonOid']: lesson for lesson in new_data}
+
+    added = [lesson for oid, lesson in new_lessons.items() if oid not in old_lessons]
+    removed = [lesson for oid, lesson in old_lessons.items() if oid not in new_lessons]
+    modified = []
+
+    # Fields to check for modifications
+    fields_to_check = ['beginLesson', 'endLesson', 'auditorium', 'lecturer_title']
+
+    for oid, old_lesson in old_lessons.items():
+        if oid in new_lessons:
+            new_lesson = new_lessons[oid]
+            changes = {}
+            for field in fields_to_check:
+                if old_lesson.get(field) != new_lesson.get(field):
+                    changes[field] = (old_lesson.get(field), new_lesson.get(field))
+            if changes:
+                modified.append({'new': new_lesson, 'changes': changes})
+
+    if not added and not removed and not modified:
+        return None
+
+    diff_parts = []
+    if added: diff_parts.append(f"<b>{translator.gettext(lang, 'schedule_change_added')}:</b>\n" + "\n\n".join([_format_lesson_for_diff(l, lang) for l in added]))
+    if removed: diff_parts.append(f"<b>{translator.gettext(lang, 'schedule_change_removed')}:</b>\n" + "\n\n".join([_format_lesson_for_diff(l, lang) for l in removed]))
+    if modified:
+        modified_texts = []
+        for mod in modified:
+            change_descs = [f"<i>{translator.gettext(lang, f'field_{f}')}: {hcode(v[0])} → {hcode(v[1])}</i>" for f, v in mod['changes'].items()]
+            modified_texts.append(f"{_format_lesson_for_diff(mod['new'], lang)}\n" + "\n".join(change_descs))
+        diff_parts.append(f"<b>{translator.gettext(lang, 'schedule_change_modified')}:</b>\n" + "\n\n".join(modified_texts))
+
+    return "\n\n---\n\n".join(diff_parts)
+    
+
+def format_schedule(schedule_data: List[Dict[str, Any]], lang: str, entity_name: str, entity_type: str, start_date: date, is_week_view: bool = False) -> str:
+    """Formats a list of lessons into a readable daily schedule."""
+    if not schedule_data:
+        # Different message for single day vs week
+        no_lessons_key = "schedule_no_lessons_week" if is_week_view else "schedule_no_lessons_day" # This was Russian text
+        return translator.gettext(lang, "schedule_header_for", entity_name=entity_name) + f"\n\n{translator.gettext(lang, no_lessons_key)}"
+
+    # Group lessons by date
+    days = defaultdict(list)
+    for lesson in schedule_data:
+        days[lesson['date']].append(lesson)
+
+    formatted_days = []
+    # Iterate through sorted dates to build the full schedule string
+    for date_str, lessons in sorted(days.items()):
+        date_obj = datetime.strptime(date_str, "%Y-%m-%d").date()
+
+        # --- LOCALIZATION FIX ---
+        day_of_week = translator.gettext(lang, f"day_{date_obj.weekday()}") # e.g., day_0 for Monday
+        month_name = translator.gettext(lang, f"month_{date_obj.month-1}_gen") # Genitive case for dates
+        day_header = f"<b>{day_of_week}, {date_obj.day} {month_name} {date_obj.year}</b>"
+        
+        formatted_lessons = []
+        for lesson in sorted(lessons, key=lambda x: x['beginLesson']):
+            lesson_details = [
+                hcode(f"{lesson['beginLesson']} - {lesson['endLesson']} | {lesson['auditorium']}"),
+                f"{lesson['discipline']} | {names_shorter[lesson['kindOfWork']]}"
+            ]
+
+            if entity_type == 'group':
+                lecturer_info = [lesson['lecturer_title'].replace('_',' ')]
+                if lesson.get('lecturerEmail'):
+                    lecturer_info.append(lesson['lecturerEmail'])
+                lesson_details.append("\n".join(lecturer_info))
+            elif entity_type == 'person': # Lecturer
+                lesson_details.append(f" {lesson.get('group', 'Группа не указана')}")
+            elif entity_type == 'auditorium':
+                lecturer_info = [f"{lesson.get('group', 'Группа не указана')} | {lesson['lecturer_title'].replace('_',' ')}"]
+                if lesson.get('lecturerEmail'):
+                    lecturer_info.append(lesson['lecturerEmail'])
+                lesson_details.append("\n".join(lecturer_info))
+            else: # Fallback to a generic format
+                lesson_details.append(f"{lesson['lecturer_title'].replace('_',' ')}")
+
+            formatted_lessons.append("\n".join(lesson_details))
+        
+        formatted_days.append(f"{day_header}\n" + "\n\n".join(formatted_lessons))
+
+    main_header = translator.gettext(lang, "schedule_header_for", entity_name=entity_name)
+    return f"{main_header}\n\n" + "\n\n---\n\n".join(formatted_days)
+
+def generate_ical_from_schedule(schedule_data: List[Dict[str, Any]], entity_name: str) -> str:
+    """
+    Generates an iCalendar (.ics) file string from schedule data.
+    """
+    cal = Calendar()
+    moscow_tz = ZoneInfo("Europe/Moscow")
+
+    if not schedule_data:
+        return cal.serialize()
+
+    for lesson in schedule_data:
+        try:
+            event = Event()
+            event.name = f"{lesson['discipline']} ({names_shorter[lesson['kindOfWork']]})"
+            
+            lesson_date = datetime.strptime(lesson['date'], "%Y-%m-%d").date()
+            start_time = time.fromisoformat(lesson['beginLesson'])
+            end_time = time.fromisoformat(lesson['endLesson'])
+
+            event.begin = datetime.combine(lesson_date, start_time, tzinfo=moscow_tz)
+            event.end = datetime.combine(lesson_date, end_time, tzinfo=moscow_tz)
+
+            event.location = f"{lesson['auditorium']}, {lesson['building']}"
+            
+            description_parts = [f"Преподаватель: {lesson['lecturer_title'].replace('_',' ')}"]
+            if 'group' in lesson: description_parts.append(f"Группа: {lesson['group']}")
+            event.description = "\n".join(description_parts)
+            
+            cal.events.add(event)
+        except (ValueError, KeyError) as e:
+            logging.warning(f"Skipping lesson due to parsing error: {e}. Lesson data: {lesson}")
+            continue
+            
+    return cal.serialize()

matplobbot_shared-0.1.48/shared_lib/services/university_api.py

@@ -0,0 +1,48 @@
+import aiohttp
+from datetime import datetime
+from typing import List, Dict, Any
+import ssl
+import certifi
+
+class RuzAPIError(Exception):
+    """Custom exception for RUZ API errors."""
+    pass
+
+class RuzAPIClient:
+    """Asynchronous API client for ruz.fa.ru."""
+    def __init__(self, session: aiohttp.ClientSession):
+        self.HOST = "https://ruz.fa.ru"
+        self.session = session
+
+    async def _request(self, sub_url: str) -> Dict[str, Any] | List[Dict[str, Any]]:
+        """Performs an asynchronous request to the RUZ API."""
+        full_url = self.HOST + sub_url
+        # Create an SSL context that uses the certifi bundle for verification.
+        # This is more reliable than the system's default trust store, especially in Docker.
+        ssl_context = ssl.create_default_context(cafile=certifi.where())
+        
+        async with self.session.get(full_url, ssl=ssl_context) as response:
+            if response.status == 200:
+                json_response = await response.json()
+                # The search API can return an empty object {} instead of an empty list [].
+                # We normalize this to always return a list for list-based endpoints.
+                return json_response if isinstance(json_response, list) else []
+            error_text = await response.text()
+            raise RuzAPIError(
+                f"RUZ API Error: Status {response.status} for URL {full_url}. Response: {error_text}"
+            )
+
+    async def search(self, term: str, search_type: str) -> List[Dict[str, Any]]:
+        """Generic search function."""
+        return await self._request(f"/api/search?term={term}&type={search_type}")
+
+    async def get_schedule(self, entity_type: str, entity_id: str, start: str, finish: str) -> List[Dict[str, Any]]:
+        """Generic function to get a schedule."""
+        return await self._request(f"/api/schedule/{entity_type}/{entity_id}?start={start}&finish={finish}&lng=1")
+
+def create_ruz_api_client(session: aiohttp.ClientSession) -> RuzAPIClient:
+    """
+    Creates and returns a RuzAPIClient instance.
+    This function is intended to be called once during application startup.
+    """
+    return RuzAPIClient(session)