Personal Travel Agent (V4)

🎓 Akademischer & Bildungskontext
Dieses Projekt wurde für das Programm Agentic AI Program: Building Autonomous Systems for Real-World Applications der School of Computer Science at Carnegie Mellon University (CMU) entwickelt.
Autor: Anthony Wang | Ausschließlich für Bildungs- und Forschungszwecke entwickelt.

🌟 Zusammenfassung

Personal Travel Agent ist ein autonomes multimodales Reiseplanungssystem, das die Generierung komplexer, mehrtägiger kombinatorischer Reiseitinerare unter strengen räumlichen, finanziellen, zeitlichen und Taktungsbeschränkungen löst.

Standardmäßige Single-Turn-LLM-Generierung und lineare ReAct-Schleifen leiden beim Erstellen mehrtägiger Reisen unter hohen Regret-Raten (25 %–40 %), da es ihnen an Vorausschau, Backtracking und strenger Constraint-Überprüfung mangelt. Dieses System löst diese Einschränkungen durch die Einführung einer Zweistufigen kognitiven Architektur:

1. Stufe 1: Äußere ReAct-Schleife (Dialog & Grounding): Verwaltet den Konversationsdialog, das Intent-Routing, die Extraktion von Benutzerpräferenzen, den semantischen Gedächtnisabruf über pgvector sowie das Basis-Tool-Grounding (Flüge, Unterkünfte, Restbudgetberechnung).

2. Stufe 2: Innere Tree-of-Thought-Suchmaschine (ToT): Löst das kombinatorische Optimierungsproblem für mehrtägige Reiseitinerare mithilfe von Beam Search ($b=4, k=3, N \le 7$) mit deterministischen Hard-Constraint-Gatekeepern, einem 5-dimensionalen kalibrierten Rubrik-Kritiker, 1 geschütztem Rettungsslot und Compute-Guardrails.

3. Live-Grounding-Tools über offene MCP-Feeds: Stellt Verbindungen zu Echtzeit-Extern-APIs ohne Mocks her – einschließlich Open-Meteo API (Live-Wetter- und Geocoding-Feeds) und Frankfurter API (offizielle Wechselkurse der European Central Bank für über 33 globale Währungen).

4. Globaler Destination-RAG-Katalog: Vordefinierter Vektor-Repository, der 156 globale Reiseziele (Länder & Weltstädte) mit kuratierten lokalen Vierteln, kulturellen Wahrzeichen, Transit-Basiswerten, kulinarischen Spezialitäten und Preis-Heuristiken abdeckt.

5. Interaktive UI auf Cloud Run: Glassmorphism-Weboberfläche mit Echtzeit-Chat, dynamischer SVG-Visualisierung des Tree-of-Thought-Suchbaums, Radardiagrammen, Live-Wetter-/FX-Grounding-Widgets und responsivem Dark/Light-Theme-Umschalter.

Related MCP server: MCP Memory Server

🏛️ Systemarchitektur

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

📐 Mathematische Formulierung von Tree of Thought (ToT)

1. Suchparameter

• Verzweigungsfaktor ($b$): $4$ anker-diverse Kandidatengedanken werden pro aktivem Beam-Knoten generiert.

• Beam-Breite ($k$): $3$ aktive Zweige werden pro Tagestiefe $d \in [1, N]$ ($N \le 7$) beibehalten.

• Pruning-Untergrenze: $\text{Composite Score} < 0.45 \implies \text{PRUNED}$.

• Akzeptanzschwelle: $\text{Composite Score} \ge 0.75$.

• Rettungsslot: $1$ geschützter Slot im Beam, der für vielversprechende Kandidaten mit Bewertungsunsicherheit reserviert ist ($\text{Confidence} < 0.60$ oder $\Delta \text{score} \le 0.10$).

• Compute-Guardrails: Strenge Grenzen von 40 LLM-Aufrufen und 45,0 Sekunden Wanduhrzeit pro Suchsitzung.

2. 5-dimensionale kalibrierte Rubrik

$$\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}}$$

📊 Benchmark- und Ablationsstudie

Wir haben die zweistufige Tree-of-Thought-Architektur gegen eine traditionelle lineare ReAct-Baseline über 100 mehrtägige Reiseanfragen mit strengen Budget- und Transitbeschränkungen evaluiert (einschließlich des ausgearbeiteten Priya-Tokio-Beispiels):

🚀 Schnellstart & lokale Einrichtung

1. Voraussetzungen

• Python 3.10+

• (Optional) Docker & Docker Compose für lokales PostgreSQL + pgvector

• (Optional) Google Cloud SDK (gcloud) bei Bereitstellung auf GCP

2. Repository klonen & virtuelle Umgebung einrichten

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. Umgebungskonfiguration

Kopieren Sie die Vorlagenkonfigurationsdatei:

cp .env.example .env

Bearbeiten Sie .env, wenn Sie Gemini Enterprise auf Google Cloud verwenden, oder geben Sie Ihren GEMINI_API_KEY an:

# .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. Webanwendung ausführen

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

Navigieren Sie zu http://localhost:8080, um die interaktive Weboberfläche aufzurufen.

💻 CLI-Tools & Evaluations-Harness

Das System bietet eine umfangreiche Befehlszeilen-Suite, die auf Typer und Rich basiert:

1. Mehrtägige Reise planen

# 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. Offline-Regret- und Ablationsauswertung ausführen

travel-agent evaluate --trials 5

3. Pre-Flight-Open-Source-Secret- und Hygiene-Scanner ausführen

travel-agent scan-secrets

🧪 Automatisierte Testsuite

Die Testsuite umfasst Einheitsmodelle, heuristische Grounding-Tools, FastMCP-Client-/Server-Lebenszyklen, die Tree-of-Thought-Suchmaschine, die ReAct-Agentenintegration und die Repository-Sicherheit:

# 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-Bereitstellung

Das Repository enthält automatisierte Bereitstellungsskripte für Google Cloud:

• Compute / Frontend: Google Cloud Run (Containerisierte Weboberfläche)

• Agent-Orchestrierung: Gemini Enterprise Agent Platform (reasoningEngines)

• Reasoning-Modell: gemini-3.7-flash (Standort: global)

• Persistenz & Vektorsuche: Cloud SQL PostgreSQL 16 + pgvector

• Artefaktspeicher: 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

🔒 Sicherheit & Open-Source-Hygiene

• Null hartkodierte Secrets: Überprüft durch eine benutzerdefinierte Repository-Bereinigungskompetenz (.agents/skills/sanitizing-repo-for-open-source/).

• Keine geleakten personenbezogenen Daten (PII): Alle Benchmarks und Benutzer-Personas sind zu 100 % synthetisch.

• Umgebungsisolierung: Vertrauliche Konfiguration wird strikt über .env oder Cloud-Secret-Manager geladen.

📄 Lizenz & akademische Zuschreibung

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe die Datei LICENSE für Details.

Entwickelt von Anthony Wang im Rahmen des Agentic AI Program: Building Autonomous Systems for Real-World Applications der School of Computer Science at Carnegie Mellon University.