Event Monitor

Event Monitor is a system for monitoring and analyzing events from VK (VKontakte) groups. It automatically collects posts, classifies them as event announcements, and extracts structured event information.

Features

• Automatic monitoring of VK group posts
• Event announcement classification using AI
• Event information extraction (date, time, location, etc.)
• RESTful API for accessing event data
• Modern web interface with real-time filtering
• SQLite/PostgreSQL database support
• Containerized deployment with Docker

Architecture

The system consists of four main microservices:

1. Parser Service: Periodically fetches posts from configured VK groups
2. Classifier Service: Uses AI to identify event announcements
3. Analyzer Service: Extracts structured event information from classified posts
4. API Service: Provides RESTful access and web interface to the collected data

Межсервисное взаимодействие

Система построена на принципах микросервисной архитектуры со следующими правилами:

1. Единая точка доступа к данным:

   • Все взаимодействие с базой данных происходит ТОЛЬКО через API Service
   • Остальные сервисы (Parser, Classifier, Analyzer) работают с данными исключительно через REST API
   • Прямой доступ к базе данных из сервисов, кроме API Service, запрещен

2. Изоляция сервисов:

   • Каждый сервис работает независимо и не имеет прямого доступа к ресурсам других сервисов
   • Все взаимодействие происходит через четко определенные REST эндпоинты
   • Сервисы могут быть развернуты и масштабированы независимо

3. Обработка ошибок:

   • Каждый сервис должен корректно обрабатывать ошибки API
   • При недоступности API сервис должен логировать ошибку и продолжать работу
   • Реализована стратегия повторных попыток для критичных операций

4. Логирование:

   • Каждый сервис ведет собственное логирование
   • Взаимодействия с внешними API (VK, Novita.ai) логируются через API Service
   • Все значимые события и ошибки фиксируются в логах

Prerequisites

• Docker and Docker Compose
• Python 3.9 or higher (for local development)
• VK API access token
• Novita.ai API key
• UV package manager (recommended installation via curl -LsSf https://astral.sh/uv/install.sh | sh)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/event-monitor.git
   cd event-monitor

2. Copy the example environment file and configure your settings:

   cp .env.example .env

3. Edit .env with your configuration:

   • Set your VK API access token
   • Configure your Novita.ai API key
   • Adjust other settings as needed

4. Build and start the services:

   docker-compose up -d

Development Setup

Windows Installation

1. Install UV package manager:

   # Using PowerShell (Run as Administrator)
   iwr -useb https://astral.sh/uv/install.ps1 | iex

   Alternatively, you can download the latest release manually from: https://github.com/astral-sh/uv/releases

2. Create a virtual environment:

   # Create new virtual environment
   uv venv .venv
   
   # Activate the virtual environment
   .venv\Scripts\activate

3. Install dependencies:

   # Generate requirements.txt with all dependencies (including dev)
   uv pip compile --all-extras pyproject.toml > requirements.txt
   
   # Install dependencies from requirements.txt
   uv sync requirements.txt

4. Configure environment:

   # Copy example environment file
   Copy-Item .env.example .env
   
   # Edit .env file with your settings
   notepad .env

Linux/macOS Installation

1. Create a virtual environment:

   uv venv .venv
   source .venv/bin/activate

2. Install dependencies:

   # Generate requirements.txt with all dependencies
   uv pip compile --all-extras pyproject.toml > requirements.txt
   
   # Install dependencies from requirements.txt
   uv sync requirements.txt

Web Interface

The web interface provides a modern, responsive dashboard for managing and monitoring events:

Features

• Real-time filtering of posts by:
  • Processing stage (Parsed, Classified, Analyzed, Not Events)
  • Group
  • Time period
• Instant updates without page reloads
• Responsive design for all screen sizes
• Bootstrap 5 UI components
• Loading indicators for better UX
• Error handling with toast notifications

Pages

• Dashboard: Overview of system statistics and recent activity
• Posts: Real-time post management with filters
• Events: Event listing and details
• Groups: Group management interface

API Documentation

The API documentation is available at http://localhost:8000/docs when the API service is running.

Main Endpoints

• GET /groups: List all monitored groups
• GET /groups/{group_id}/posts: Get posts from a specific group
• GET /events: List all extracted events
• GET /events/{event_id}: Get details of a specific event
• POST /llm_interactions: Log LLM API interactions
• GET /llm_interactions: Get logged LLM interactions

Configuration

Key environment variables:

• VK_ACCESS_TOKEN: Your VK API access token
• VK_API_VERSION: VK API version (default: 5.131)
• NOVITA_API_KEY: Your Novita.ai API key
• NOVITA_API_URL: Novita.ai API URL
• PARSER_INTERVAL_MINUTES: How often to check for new posts (default: 15)
• DATABASE_URI: Database connection string (SQLite or PostgreSQL)
• API_PORT: Port for the API service (default: 8000)

See .env.example for all available configuration options.

Package Management with UV

UV is used for fast, reliable Python package management. Key commands:

# Create and activate virtual environment
uv venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Generate and install dependencies
uv pip compile --all-extras pyproject.toml > requirements.txt
uv sync requirements.txt

# Update dependencies
uv pip compile --upgrade pyproject.toml > requirements.txt
uv sync requirements.txt

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.