Personal Travel Agent (V4)

🎓 Contexto Académico y Educativo
Este proyecto fue construido para el programa Agentic AI Program: Building Autonomous Systems for Real-World Applications ofrecido por la School of Computer Science at Carnegie Mellon University (CMU).
Autor: Anthony Wang | Desarrollado estrictamente con fines educativos y de investigación.

🌟 Resumen Ejecutivo

Personal Travel Agent es un sistema autónomo de planificación de viajes multimodal que resuelve la generación compleja de itinerarios de viaje combinatorios de varios días bajo estrictas restricciones espaciales, financieras, temporales y de ritmo.

La generación estándar de LLM de un solo turno y los bucles lineales de ReAct sufren altas tasas de arrepentimiento (25%–40%) al construir viajes de varios días debido a la falta de anticipación, retroceso y verificación rigurosa de restricciones. Este sistema resuelve esas limitaciones al introducir una Arquitectura Cognitiva de Dos Niveles:

1. Nivel 1: Bucle ReAct Externo (Diálogo y Fundamentación): Maneja el diálogo conversacional, el enrutamiento de intenciones, la extracción de preferencias del usuario, el recuerdo de memoria semántica mediante pgvector y la fundamentación de herramientas de referencia (vuelos, alojamiento, cálculo de presupuesto residual).

2. Nivel 2: Motor de Búsqueda Interno Tree of Thought (ToT): Resuelve el problema de optimización combinatoria de itinerarios de varios días utilizando Beam Search ($b=4, k=3, N \le 7$) con guardianes deterministas de restricciones duras, un crítico de rúbrica calibrada de 5 dimensiones, 1 ranura de rescate protegida y salvaguardas de cómputo.

3. Herramientas de Fundamentación en Vivo a través de Feeds MCP Abiertos: Se conecta a APIs externas en tiempo real, sin simulaciones, incluyendo Open-Meteo API (feeds meteorológicos y de geocodificación en vivo) y Frankfurter API (tipos de cambio oficiales del Banco Central Europeo en más de 33 monedas globales).

4. Catálogo RAG Global de Destinos: Repositorio vectorial pre-indexado que cubre 156 destinos globales (países y ciudades del mundo) con barrios locales seleccionados, hitos culturales, líneas base de tránsito, especialidades culinarias y heurísticas de precios.

5. UI Interactiva en Cloud Run: Interfaz web de vidrio esmerilado con chat en tiempo real, visualización dinámica del árbol de búsqueda Tree of Thought en SVG, gráficos de radar, widgets de fundamentación de clima/FX en vivo y conmutador de tema oscuro/claro responsivo.

Related MCP server: MCP Memory Server

🏛️ Arquitectura del Sistema

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

📐 Formulación Matemática de Tree of Thought (ToT)

1. Parámetros de Búsqueda

• Factor de Ramificación ($b$): $4$ pensamientos candidatos diversos en anclaje generados por nodo de haz activo.

• Ancho del Haz ($k$): $3$ ramas activas retenidas por profundidad de día $d \in [1, N]$ ($N \le 7$).

• Umbral de Poda: $\text{Composite Score} < 0.45 \implies \text{PRUNED}$.

• Umbral de Aceptación: $\text{Composite Score} \ge 0.75$.

• Ranura de Rescate: $1$ ranura protegida reservada en el haz para candidatos de alto potencial que enfrentan incertidumbre de evaluación ($\text{Confidence} < 0.60$ o $\Delta \text{score} \le 0.10$).

• Salvaguardas de Cómputo: Límites estrictos de 40 llamadas LLM y 45.0 segundos de tiempo real por sesión de búsqueda.

2. Rúbrica Calibrada de 5 Dimensiones

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

📊 Estudio de Benchmark y Ablación

Evaluamos la arquitectura Tree of Thought de dos niveles contra una línea base lineal de ReAct tradicional en 100 solicitudes de viaje de varios días con estrictas restricciones de presupuesto y tránsito (incluyendo el ejemplo trabajado de Priya Tokio):

🚀 Inicio Rápido y Configuración Local

1. Requisitos Previos

• Python 3.10+

• (Opcional) Docker y Docker Compose para PostgreSQL + pgvector local

• (Opcional) Google Cloud SDK (gcloud) si se despliega en GCP

2. Clonar el Repositorio y Configurar el Entorno Virtual

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. Configuración del Entorno

Copie el archivo de configuración de plantilla:

cp .env.example .env

Edite .env si usa Gemini Enterprise en Google Cloud, o proporcione su 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. Ejecutar la Aplicación Web

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

Navegue a http://localhost:8080 para acceder a la interfaz web interactiva.

💻 Herramientas CLI y Arnés de Evaluación

El sistema proporciona un completo conjunto de herramientas de línea de comandos impulsado por Typer y Rich:

1. Planificar un Viaje de Varios Días

# 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. Ejecutar la Evaluación de Arrepentimiento y Ablación Offline

travel-agent evaluate --trials 5

3. Ejecutar el Escáner de Secretos e Higiene de Código Abierto Pre-Vuelo

travel-agent scan-secrets

🧪 Suite de Pruebas Automatizadas

La suite de pruebas cubre modelos unitarios, herramientas de fundamentación heurística, ciclos de vida de cliente/servidor FastMCP, motor de búsqueda Tree of Thought, integración del agente ReAct y seguridad del repositorio:

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

☁️ Despliegue en Google Cloud

El repositorio incluye scripts automatizados de aprovisionamiento para Google Cloud:

• Cómputo / Frontend: Google Cloud Run (UI Web Contenerizada)

• Orquestación de Agentes: Gemini Enterprise Agent Platform (reasoningEngines)

• Modelo de Razonamiento: gemini-3.7-flash (Ubicación: global)

• Persistencia y Búsqueda Vectorial: Cloud SQL PostgreSQL 16 + pgvector

• Almacenamiento de Artefactos: 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

🔒 Seguridad e Higiene de Código Abierto

• Cero Secretos Codificados: Escaneado mediante la habilidad personalizada de saneamiento del repositorio (.agents/skills/sanitizing-repo-for-open-source/).

• Sin PII Filtrada: Todos los benchmarks y personas de usuario son 100% sintéticos.

• Aislamiento del Entorno: La configuración sensible se carga estrictamente a través de .env o administradores de secretos en la nube.

📄 Licencia y Atribución Académica

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

Desarrollado por Anthony Wang como parte del Agentic AI Program: Building Autonomous Systems for Real-World Applications de la School of Computer Science at Carnegie Mellon University.