vector/SERVICES_README.md

Сервисы анализа SAR-MCHS

Обзор

Созданы два основных сервиса для анализа поисково-спасательных операций:

1. Claude Service (backend/services/claude_service.py)

Функция: analyze_case(case_data: dict) -> AnalysisResult

Использует Claude API (модель claude-sonnet-4-20250514) для интеллектуального анализа случаев пропажи людей.

Входные данные (case_data):

• age - возраст пропавшего
• gender - пол
• terrain - тип местности
• weather - погодные условия
• time_missing - время пропажи
• last_location - последнее известное местоположение
• circumstances - особые обстоятельства
• physical_condition - физическое состояние
• experience - опыт нахождения на природе

Возвращаемые данные (AnalysisResult):

{
    "urgency": "критическая|высокая|средняя|низкая",
    "primary_zones": [
        {
            "priority": 1,
            "name": "Зона А",
            "direction": "север",
            "distance": 2.5,
            "reason": "Обоснование выбора"
        }
    ],
    "search_radius_km": 5.0,
    "key_locations": ["водоемы", "дороги", "постройки"],
    "team_assignments": {
        "команда_1": "зона А",
        "команда_2": "зона Б"
    },
    "behavioral_prediction": "Прогноз поведения",
    "immediate_actions": ["Действие 1", "Действие 2"],
    "summary": "Краткое резюме"
}

2. Stats Service (backend/services/stats_service.py)

Функция: get_statistical_recommendation(case_data: dict, db_session: AsyncSession) -> StatsResult

Анализирует исторические данные из базы для получения статистических рекомендаций.

Входные данные:

• age - возраст (±2 года для фильтрации)
• season - сезон (winter, spring, summer, autumn)
• terrain_primary - основной тип местности

Логика фильтрации:

1. Первая попытка: возраст ±2 года + сезон + terrain
2. Если sample_size < 5: возраст ±2 года + сезон (без terrain)
3. Если данных нет: возвращает дефолтные значения

Возвращаемые данные (StatsResult):

{
    "median_distance_km": 2.5,
    "top_directions": [
        {
            "direction": "север",
            "count": 15,
            "percentage": 35.0
        }
    ],
    "top_location_types": ["водоемы", "дороги", "лесные тропы"],
    "survival_rate": 87.5,
    "sample_size": 43
}

API Endpoints

POST /api/v1/analyze/text

Анализ случая с помощью Claude AI.

Request:

{
    "age": 65,
    "gender": "мужской",
    "terrain": "лес",
    "weather": "дождь",
    "time_missing": "6 часов",
    "last_location": "лесная тропа у озера",
    "circumstances": "вышел за грибами",
    "physical_condition": "хорошее",
    "experience": "опытный грибник"
}

Response: AnalysisResult

POST /api/v1/analyze/combined

Комбинированный анализ: Claude AI + статистические данные.

Request: Тот же формат, что и /text

Response:

{
    "claude_analysis": { /* AnalysisResult */ },
    "statistical_data": { /* StatsResult */ }
}

POST /api/v1/analyze/document

Анализ загруженного документа (пока поддерживается только .txt).

Request: multipart/form-data с файлом

Response: AnalysisResult

Настройка

Переменные окружения

В файле .env должен быть установлен:

ANTHROPIC_API_KEY=your_api_key_here

База данных

Для работы stats_service требуется таблица cases со следующими полями:

• age (integer)
• season (string)
• terrain_primary (string)
• found_distance_km (float)
• found_direction (string)
• found_location_type (string)
• outcome (string: 'alive', 'found_alive', etc.)

Тестирование

Тест Claude Service

curl -X POST http://192.168.0.108:8000/api/v1/analyze/text \
  -H "Content-Type: application/json" \
  -d '{
    "age": 65,
    "gender": "мужской",
    "terrain": "лес",
    "weather": "дождь",
    "time_missing": "6 часов",
    "last_location": "лесная тропа у озера"
  }'

Тест Combined Analysis

curl -X POST http://192.168.0.108:8000/api/v1/analyze/combined \
  -H "Content-Type: application/json" \
  -d '{
    "age": 65,
    "season": "autumn",
    "terrain_primary": "forest"
  }'

TODO

• Настроить подключение к базе данных
• Добавить миграции Alembic для таблицы cases
• Реализовать извлечение текста из .docx и .pdf
• Добавить кэширование результатов анализа
• Добавить rate limiting для API запросов
• Добавить логирование запросов и ответов