# ИИ-помощник туриста

Веб-сервис, который создает **персональные пешеходные маршруты**, понимая **свободную речь пользователя**. Наш AI-гид анализирует ваши желания, текущее местоположение и время, чтобы построить уникальную прогулку, которая подходит именно вам. Сервис доступен [здесь: https://gorkycode.nikidze.ru/](https://gorkycode.nikidze.ru/).

---

## Понимание контекста

В отличие от конкурентов, которые просто ищут по тегам, наш сервис **понимает логику и последовательность** запроса. Мы не просто находим "музей" и "кофе", мы строим маршрут так, как этого хотел пользователь.

Как система обработает внешне похожие запросы:

| Запрос пользователя | Интерпретация AI и результат |
| :--- | :--- |
| *«Хочу сходить в музей и попить кофе»* | Найдет музей и кофейню рядом. Порядок **не важен**. |
| *«Хочу попить кофе, потом в музей»* | Построит маршрут **сначала в кофейню**, а уже **потом в музей**. |
| *«Хочу походить по музеям, потом зайти за кофе»* | Включит в маршрут **несколько музеев**, а кофейня будет **финальной точкой**. |
| *«Хочу в музей или попить кофе, потом на канатку»* | Выберет **одно из двух** (музей или кафе), а затем **обязательно добавит** канатную дорогу. |

Эта способность понимать нюансы делает наш сервис по-настоящему персональным и умным.

---

## Основные возможности

- **Пошаговый интерфейс** — Удобный опрос в несколько шагов, который не перегружает пользователя и позволяет легко вернуться для корректировки.
- **Диалоговый режим** — Если данных не хватает, система задаст уточняющие вопросы, пока не получит всю необходимую информацию.
- **Умная маршрутизация** — Алгоритм учитывает время на дорогу пешком и посещение локаций, отсекая нерелевантные точки.
- **Гибкий анализ запроса** — AI (Gemini 2.5 Flash) извлекает теги, время и адрес, даже если они указаны неточно (например, *«свободен до 6 вечера»* или адрес с опечаткой).
- **Микросервисная архитектура** — Проект разбит на независимые Docker-контейнеры, что обеспечивает надежность и масштабируемость.

---

## Как это работает: от запроса до маршрута

1.  **Сбор данных (UI + AI)**
    Пользователь в свободной форме отвечает на вопросы о своих предпочтениях, времени и местоположении. Данные отправляются в основной сервис `input_to_route`.

2.  **Анализ и структурирование (AI: Gemini 2.5 Flash)**
    С помощью модели `Gemini 2.5 Flash` через `OpenRouter API` текстовый запрос преобразуется в структурированные данные:
    ```json
    {
      "tags": [["Музей"], ["Кофейня"]],
      "user_location": "улица Ошарская, дом 14",
      "time": 180
    }
    ```
    На этом же этапе нормализуется адрес пользователя с помощью отдельного сервиса на базе `libpostal`.

3.  **Поиск кандидатов (База данных)**
    Сервис находит в базе данных все объекты, соответствующие извлеченным тегам.

4.  **Построение маршрута (OSRM)**
    - Координаты пользователя и найденных точек передаются в `navigation-engine` (кастомная сборка `OSRM` с картой Нижнего Новгорода).
    - Алгоритм отсекает слишком удаленные точки.
    - Строится матрица временных затрат на перемещение между оставшимися точками.
    - На основе матрицы и логики тегов ("и", "или", "потом") генерируется список подходящих по времени маршрутов.
    - Из списка выбирается один (на данный момент — случайный).

5.  **Генерация описания (AI)**
    На основе выбранных точек маршрута `Gemini 2.5 Flash` генерирует красивое и связное текстовое описание прогулки для пользователя.

---

## Архитектура и технологии

Проект построен на основе микросервисной архитектуры и развернут в Docker-контейнерах на платформе `dockhost`. Такой подход обеспечивает изоляцию компонентов и простоту масштабирования.

| Компонент | Технологии | Роль |
| :--- | :--- | :--- |
| **web-ui** | **Vue 3, JavaScript** | Пользовательский интерфейс: пошаговый опрос и отображение результата. |
| **input_to_route** | **FastAPI (Python)** | **Мозг системы.** Оркестрирует весь процесс: общается с UI, AI, базой данных и другими сервисами. |
| **engine-wrapper** | **FastAPI (Python)** | Упрощенная обертка над движком OSRM для удобства взаимодействия. |
| **navigation-engine** | **OSRM Backend (C++)** | Высокопроизводительный движок для построения пешеходных маршрутов. |
| **libpostal-service** | **libpostal, REST API** | Сервис для нормализации и парсинга географических адресов. Вынесен в отдельный контейнер из-за большого веса библиотеки. |
| **AI-провайдер** | **OpenRouter API (Gemini 2.5 Flash)** | Предоставляет доступ к LLM для анализа запросов и генерации текста. |
| **Платформа** | **Dockhost** | Облачная платформа для хостинга Docker-контейнеров. |

---

## Почему наш стек эффективен

1.  **FastAPI** — Идеально подходит для создания асинхронных API, которые связывают разные сервисы. Быстрый, современный и легок в освоении.
2.  **Vue 3** — Реактивный фреймворк, который позволяет создавать динамичные и отзывчивые пользовательские интерфейсы, как наш пошаговый опросник.
3.  **OSRM** — Один из самых быстрых open-source движков для маршрутизации. Использование кастомной сборки только для Нижнего Новгорода делает его еще более производительным.
4.  **Gemini 2.5 Flash через OpenRouter** — Экономически эффективное решение. Модель обеспечивает высокую скорость, отличное качество понимания русского языка и следование сложным инструкциям, что является ядром нашего проекта.
5.  **Микросервисы на Docker** — Стандарт индустрии. Позволяет независимо разрабатывать, обновлять и масштабировать части приложения. `libpostal` в отдельном контейнере — классический пример правильного применения этого подхода.