Personal Travel Agent (V4)

🎓 Академический и образовательный контекст
Этот проект был создан для программы Agentic AI Program: Building Autonomous Systems for Real-World Applications, предлагаемой School of Computer Science at Carnegie Mellon University (CMU).
Автор: Anthony Wang | Разработан строго в образовательных и исследовательских целях.

🌟 Краткое содержание

Personal Travel Agent — это автономная мультимодальная система планирования путешествий, которая решает сложную задачу генерации многодневных комбинаторных маршрутов при строгих пространственных, финансовых, временных ограничениях и ограничениях темпа.

Стандартная одношаговая генерация LLM и линейные циклы ReAct страдают от высокого уровня сожалений (25–40%) при построении многодневных поездок из-за отсутствия прогнозирования, возврата назад и строгой проверки ограничений. Эта система решает эти ограничения, внедряя двухуровневую когнитивную архитектуру:

1. Уровень 1: Внешний цикл ReAct (диалог и привязка): Обрабатывает разговорный диалог, маршрутизацию намерений, извлечение предпочтений пользователя, семантическое извлечение из памяти через pgvector и базовую привязку инструментов (авиаперелеты, проживание, расчет остаточного бюджета).

2. Уровень 2: Внутренний поисковый движок Tree of Thought (ToT): Решает комбинаторную задачу оптимизации многодневного маршрута с помощью Beam Search ($b=4, k=3, N \le 7$) с детерминированными контролерами жестких ограничений, 5-мерным калиброванным рубричным критиком, 1 защищенным резервным слотом и вычислительными ограничениями.

3. Инструменты живой привязки через Open MCP Feeds: Подключается к реальным внешним API без моков, включая Open-Meteo API (живые метеорологические и геокодирующие каналы) и Frankfurter API (официальные курсы обмена валют Европейского центрального банка для 33+ мировых валют).

4. Глобальный каталог RAG направлений: Предварительно индексированное векторное хранилище, охватывающее 156 глобальных направлений (страны и города мира) с курируемыми местными районами, культурными достопримечательностями, базовыми транспортными показателями, кулинарными особенностями и эвристиками ценообразования.

5. Интерактивный интерфейс на Cloud Run: Веб-интерфейс в стиле glassmorphism с чатом в реальном времени, динамической визуализацией дерева поиска Tree of Thought в формате SVG, радиолокационными диаграммами, виджетами живой погоды/валют и переключателем темной/светлой темы.

Related MCP server: MCP Memory Server

🏛️ Архитектура системы

flowchart TD
    User(["👤 User Request / Prompt"]) --> UI["🌐 Glassmorphism Web UI / CLI / ADK Web"]
    
    subgraph Tier1 ["Tier 1: Outer ReAct Grounding & Intent Loop"]
        UI --> Router{"Intent Classifier"}
        Router -- "Weather / FX" --> LiveTools["Live Grounding MCP Services"]
        Router -- "Destination RAG" --> VectorStore[("PostgreSQL + pgvector\n(156 Destinations & User Memory)")]
        Router -- "Plan Trip" --> ReActAgent["TravelAgentRunner (ReAct Agent)"]
        
        ReActAgent --> G1["search_flights()"]
        ReActAgent --> G2["search_lodging()"]
        ReActAgent --> G3["compute_residual_budget()"]
        ReActAgent <--> VectorStore
        
        G1 & G2 & G3 --> Frame["PlanningFrame\n(Immutable Contract: Dates, Lodging, Residual Daily Budget)"]
    end

    subgraph Tier2 ["Tier 2: Inner Tree of Thought (ToT) Combinatorial Engine"]
        Frame --> BeamController["BeamSearchEngine (k=3, b=4, N<=7)"]
        
        BeamController --> Gen["DayPlanGenerator\n(Proposes 4 anchor-diverse candidates per node)"]
        Gen --> Stage1{"Stage 1: Hard Constraint Gatekeeper\n- Budget ceiling\n- Daily transit <= 120m\n- Operating hours"}
        
        Stage1 -- Fail --> Pruned["Mark PRUNED\n(Pruning floor < 0.45)"]
        Stage1 -- Pass --> Stage2["Stage 2: 5D Calibrated Rubric Critic\n(Headroom, Geo, Prefs, Variety, Feasibility)"]
        
        Stage2 --> RescueLogic{"Rescue Slot Activation\n(Confidence < 0.60 or Δscore <= 0.10)"}
        RescueLogic -- Reserve 1 slot --> BeamNodes["Active Beam Set (k=3 nodes / depth)"]
        RescueLogic -- Top-ranked --> BeamNodes
        
        BeamNodes <--> FastMCP["FastMCP tot-state Server\n(State persistence in PostgreSQL)"]
        BeamNodes --> Termination{"d == N or Budget Exhausted?"}
        Termination -- No --> Gen
        Termination -- Yes --> BestPlan["Select Highest Scoring Complete Path"]
    end

    subgraph LiveMCP ["Live Open MCP Grounding Feeds"]
        LiveTools --> OpenMeteo["🌤️ Open-Meteo API\n(Real-time Weather & Geocoding)"]
        LiveTools --> Frankfurter["💱 Frankfurter API\n(Live ECB Exchange Rates for 33+ Currencies)"]
    end

    BestPlan --> Formatter["Response Formatter & Graph Generator"]
    Formatter --> UI

📐 Математическая формулировка Tree of Thought (ToT)

1. Параметры поиска

• Коэффициент ветвления ($b$): $4$ разнообразных по якорям кандидатных мыслей генерируется на каждый активный узел луча.

• Ширина луча ($k$): $3$ активных ветвей сохраняется на каждую глубину дня $d \in [1, N]$ ($N \le 7$).

• Минимальный порог отсечения: $\text{Composite Score} < 0.45 \implies \text{PRUNED}$.

• Порог принятия: $\text{Composite Score} \ge 0.75$.

• Резервный слот: $1$ защищенный слот, зарезервированный в луче для высокопотенциальных кандидатов, сталкивающихся с неопределенностью оценки ($\text{Confidence} < 0.60$ или $\Delta \text{score} \le 0.10$).

• Вычислительные ограничения: Строгие лимиты 40 вызовов LLM и 45.0 секунд реального времени на сеанс поиска.

2. 5-мерная калиброванная рубрика

$$\text{Composite Score} = 0.20 \cdot S_{\text{headroom}} + 0.20 \cdot S_{\text{geo}} + 0.25 \cdot S_{\text{pref}} + 0.20 \cdot S_{\text{quality}} + 0.15 \cdot S_{\text{forward}}$$

📊 Бенчмарк и абляционное исследование

Мы оценили двухуровневую архитектуру Tree of Thought по сравнению с традиционным базовым линейным ReAct на 100 многодневных запросах на поездки со строгими бюджетными и транспортными ограничениями (включая проработанный пример Priya Tokyo):

🚀 Быстрый старт и локальная настройка

1. Предварительные требования

• Python 3.10+

• (Необязательно) Docker и Docker Compose для локального PostgreSQL + pgvector

• (Необязательно) Google Cloud SDK (gcloud) при развертывании в GCP

2. Клонирование репозитория и настройка виртуального окружения

git clone https://github.com/anthonywang-sg/Personal-Travel-Agent.git
cd Personal-Travel-Agent

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies in editable mode
pip install -e ".[dev]"

3. Конфигурация окружения

Скопируйте файл шаблона конфигурации:

cp .env.example .env

Отредактируйте .env, если используете Gemini Enterprise в Google Cloud, или укажите свой GEMINI_API_KEY:

# .env
APP_NAME="Personal Travel Agent V4"
ENVIRONMENT="development"

# Gemini Enterprise Agent Platform (or leave blank for standard API Key)
GOOGLE_GENAI_USE_ENTERPRISE=true
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GOOGLE_CLOUD_LOCATION=global

# Database (Optional local Docker default)
DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/travel_agent"

4. Запуск веб-приложения

uvicorn travel_agent.web.app:app --host 0.0.0.0 --port 8080 --reload

Перейдите по адресу http://localhost:8080, чтобы получить доступ к интерактивному веб-интерфейсу.

💻 Инструменты CLI и испытательный стенд

Система предоставляет богатый набор командной строки на основе Typer и Rich:

1. Планирование многодневной поездки

# Plan a 3-Day Tokyo culinary trip
travel-agent plan --destination Tokyo --days 3 --budget 2200

# Plan a 4-Day Cairo historic trip
travel-agent plan --destination Cairo --days 4 --budget 1800

# Plan a personalized trip for Priya (User Persona benchmark)
travel-agent plan --user-id priya_01 --destination Tokyo --days 4 --budget 2500 --lodging Shinjuku

2. Запуск офлайн-оценки сожалений и абляции

travel-agent evaluate --trials 5

3. Запуск предварительного сканера секретов и гигиены открытого кода

travel-agent scan-secrets

🧪 Автоматизированный набор тестов

Набор тестов охватывает модульные модели, инструменты эвристической привязки, жизненные циклы клиента/сервера FastMCP, поисковый движок Tree of Thought, интеграцию агента ReAct и безопасность репозитория:

# Run all 21 automated tests
pytest tests/ -v

============================== test session starts ==============================
tests/test_beam_search_engine.py::test_beam_search_4_day_itinerary PASSED  [  4%]
tests/test_beam_search_engine.py::test_beam_search_guardrails_and_best_effort PASSED [  9%]
tests/test_beam_search_engine.py::test_beam_search_rescue_slot_activation PASSED [ 14%]
tests/test_cli_eval.py::test_cli_plan_command PASSED                     [ 19%]
tests/test_cli_eval.py::test_ablation_harness_metrics PASSED             [ 23%]
tests/test_domain_models.py::test_day_plan_serialization PASSED          [ 28%]
tests/test_domain_models.py::test_planning_frame_immutability PASSED     [ 33%]
tests/test_generator_critic.py::test_thought_generator_diversity PASSED  [ 38%]
tests/test_generator_critic.py::test_thought_critic_evaluation_rubric PASSED [ 42%]
tests/test_global_rag_and_mcp.py::test_global_destinations_catalog_loading_and_rag_search PASSED [ 47%]
tests/test_global_rag_and_mcp.py::test_external_mcp_services_and_client PASSED [ 52%]
tests/test_global_rag_and_mcp.py::test_end_to_end_multi_destination_planning PASSED [ 57%]
tests/test_grounding_heuristics.py::test_grounding_tools PASSED          [ 61%]
tests/test_grounding_heuristics.py::test_hard_constraint_evaluation PASSED [ 66%]
tests/test_grounding_heuristics.py::test_heuristic_calculation PASSED    [ 71%]
tests/test_mcp_tot_state.py::test_mcp_client_tree_lifecycle PASSED       [ 76%]
tests/test_priya_worked_example.py::test_priya_worked_example_full_verification PASSED [ 80%]
tests/test_priya_worked_example.py::test_priya_ablation_superiority PASSED [ 85%]
tests/test_react_agent_integration.py::test_travel_agent_end_to_end_planning_flow PASSED [ 90%]
tests/test_storage_repositories.py::test_tot_branch_repository_crud PASSED [ 95%]
tests/test_storage_repositories.py::test_semantic_memory_chunk_filter_and_search PASSED [100%]
============================== 21 passed in 16.06s ==============================

☁️ Развертывание в Google Cloud

Репозиторий включает автоматизированные скрипты подготовки для Google Cloud:

• Вычисления / Фронтенд: Google Cloud Run (контейнеризированный веб-интерфейс)

• Оркестрация агентов: Gemini Enterprise Agent Platform (reasoningEngines)

• Модель рассуждений: gemini-3.7-flash (Расположение: global)

• Хранение и векторный поиск: Cloud SQL PostgreSQL 16 + pgvector

• Хранилище артефактов: Google Cloud Storage (gs://personal-travel-agent-artifacts-*)

# 1. Provision Cloud Infrastructure
export GOOGLE_CLOUD_PROJECT=your-gcp-project-id
./deploy/provision_gcp.sh

# 2. Deploy Web UI to Cloud Run
./deploy/cloudrun_ui.sh

# 3. Deploy to Agent Engine
./deploy/agent_engine_deploy.sh

🔒 Безопасность и гигиена открытого кода

• Ноль жестко закодированных секретов: Проверено с помощью специального навыка очистки репозитория (.agents/skills/sanitizing-repo-for-open-source/).

• Нет утечек PII: Все бенчмарки и пользовательские персоны на 100% синтетические.

• Изоляция окружения: Чувствительная конфигурация загружается строго через .env или облачные менеджеры секретов.

📄 Лицензия и академическая атрибуция

Этот проект лицензирован под лицензией MIT — см. файл LICENSE для подробностей.

Разработано Anthony Wang в рамках Agentic AI Program: Building Autonomous Systems for Real-World Applications от School of Computer Science at Carnegie Mellon University.