README.md

---
title: MultiAgentLogsAnalyze
emoji: 🔥
colorFrom: gray
colorTo: indigo
sdk: gradio
sdk_version: "5.23.1"
app_file: app.py
pinned: false
---

# 🔍 Мультиагентная система анализа логов

Интерактивное веб-приложение для автоматизированного анализа лог-файлов с использованием трёх логически разделённых агентов.

## 📋 Описание

Система обеспечивает автоматизированный анализ логов с:
- Структурированием данных
- Выявлением аномалий
- Интерпретацией причин и выдачей рекомендаций

## 🏗️ Архитектура

Проект реализован как мультиагентная система с **строго 3 независимыми агентами**, каждый из которых выполняет определённую функцию в цепочке анализа.

### Агент 1: Log Parser Agent (`agents/parser_agent.py`)

**Назначение:** Преобразование сырых логов в структурированное представление.

**Функциональность:**
- Разбор строк логов
- Извлечение временных меток
- Определение уровней логирования (INFO, WARNING, ERROR, CRITICAL, DEBUG)
- Извлечение сообщений
- Группировка по типам событий (CONNECTION, HTTP_REQUEST, DATABASE, AUTHENTICATION, EXCEPTION, SYSTEM, GENERAL)

**Выход:** Структурированный JSON-объект с полями:
- `events` - список всех распарсенных событий
- `errors` - список ошибок
- `warnings` - список предупреждений
- `statistics` - статистика по логам

### Агент 2: Anomaly Detection Agent (`agents/anomaly_agent.py`)

**Назначение:** Выявление аномалий и подозрительных паттернов в структурированных логах.

**Функциональность:**
- Подсчёт частоты событий
- Поиск повторяющихся ошибок
- Обнаружение временных всплесков
- Эвристический анализ последовательностей событий

**Типы обнаруживаемых аномалий:**
- **BURST_ERRORS** - всплески ошибок (более 5 ошибок в короткий промежуток времени)
- **REPEATED_ERRORS** - повторяющиеся ошибки (одна и та же ошибка более 3 раз)
- **ERROR_BEFORE_CRASH** - паттерны "ошибка перед крашем"
- **TEMPORAL_SPIKE** - временные всплески событий (превышение среднего в 2 раза)
- **REPEATED_STACK_TRACES** - повторяющиеся stack traces

**Выход:** JSON-отчёт об аномалиях с описанием, метаданными и статистикой.

### Агент 3: Root Cause & Recommendation Agent (`agents/rca_agent.py`)

**Назначение:** Интерпретация аномалий и формирование рекомендаций.

**Функциональность:**
- Определение возможных первопричин на основе типа аномалий
- Формирование человеко-читаемого отчёта в формате Markdown
- Генерация рекомендаций по устранению проблем с приоритетами
- Предоставление конкретных действий для решения проблем

**Выход:** Markdown-текст с анализом первопричин и рекомендациями.

## 🔄 Процесс анализа

Анализ выполняется последовательно:

1. **Пользователь** загружает или вставляет логи в интерфейс
2. **Agent 1** (Log Parser) обрабатывает сырые логи → структурированный JSON
3. **Agent 2** (Anomaly Detection) анализирует структурированные данные → отчёт об аномалиях
4. **Agent 3** (Root Cause) интерпретирует аномалии → Markdown с рекомендациями
5. **Результаты** отображаются в интерфейсе в трёх вкладках

## 🚀 Использование

### Локальный запуск

1. Установите зависимости:
```bash
pip install -r requirements.txt
```

2. Запустите приложение:
```bash
python app.py
```

3. Откройте браузер по адресу `http://localhost:7860`

### Использование в Hugging Face Spaces

Приложение автоматически развернётся при загрузке на Hugging Face Spaces.

## 📁 Структура проекта

```
MultiAgentLogsAnalyze/
├── agents/
│   ├── __init__.py          # Экспорт агентов
│   ├── parser_agent.py      # Agent 1: Log Parser Agent
│   ├── anomaly_agent.py     # Agent 2: Anomaly Detection Agent
│   └── rca_agent.py         # Agent 3: Root Cause Agent
├── app.py                   # Gradio приложение и оркестрация
├── requirements.txt         # Зависимости Python
├── README.md               # Документация проекта
└── space_config.yaml       # Конфигурация для Hugging Face Spaces
```

## 🔧 Технические детали

### Зависимости

- `gradio>=4.0.0,<5.0.0` - веб-интерфейс

Все агенты реализованы на чистом Python 3.10+ без использования LLM или трансформеров.

### Производительность

- Поддержка анализа до 10,000 строк логов
- Время обработки ≤ 10 секунд для типичных логов

### Обработка ошибок

- Валидация входных данных
- Обработка некорректных логов без падения приложения
- Информативные сообщения об ошибках

## 🎯 Пример использования

### Пример входных логов:

```
2024-01-15 10:00:00 INFO Application started
2024-01-15 10:00:05 INFO Database connection established
2024-01-15 10:01:00 ERROR Connection timeout to external API
2024-01-15 10:01:05 ERROR Connection timeout to external API
2024-01-15 10:01:10 ERROR Connection timeout to external API
2024-01-15 10:01:15 WARNING High memory usage detected: 85%
2024-01-15 10:02:00 CRITICAL System crash detected
2024-01-15 10:02:01 INFO Application shutdown
```

### Пример выхода Agent 1 (структурированные данные):

```json
{
  "events": [
    {
      "line_number": 1,
      "timestamp": "2024-01-15 10:00:00",
      "level": "INFO",
      "message": "Application started",
      "type": "SYSTEM"
    },
    ...
  ],
  "errors": [...],
  "warnings": [...],
  "statistics": {
    "total_lines": 8,
    "parsed_events": 8,
    "errors": 3,
    "warnings": 1,
    ...
  }
}
```

### Пример выхода Agent 2 (аномалии):

```json
{
  "anomalies": [
    {
      "type": "BURST_ERRORS",
      "severity": "HIGH",
      "description": "Обнаружен всплеск из 3 последовательных ошибок",
      "count": 3,
      ...
    },
    {
      "type": "ERROR_BEFORE_CRASH",
      "severity": "CRITICAL",
      "description": "Обнаружен паттерн: ошибка перед возможным крашем системы",
      ...
    }
  ],
  ...
}
```

### Пример выхода Agent 3 (рекомендации):

Markdown-отчёт с:
- Анализом первопричин
- Детальным описанием аномалий
- Приоритизированными рекомендациями
- Конкретными действиями для решения проблем

## 🔌 Расширяемость

Система разработана с учётом расширяемости:

- **Независимые агенты:** Каждый агент реализован как отдельный класс и может быть заменён без изменения остальных
- **Чёткий интерфейс:** Агенты взаимодействуют через стандартизированные форматы данных (JSON)
- **Добавление новых правил:** Легко добавить новые типы аномалий в `AnomalyDetectionAgent`
- **Кастомные парсеры:** Можно расширить `LogParserAgent` для поддержки новых форматов логов

## 📝 Лицензия

Этот проект создан в рамках технического задания для демонстрации мультиагентной архитектуры.

## 🤝 Вклад

Проект готов к расширению и улучшению. Возможные направления:
- Поддержка дополнительных форматов логов
- Интеграция с LLM для более глубокого анализа
- Поддержка потоковой обработки больших файлов
- Экспорт результатов в различные форматы
- Интеграция с системами мониторинга