Tot State

Python 3.10+ FastAPI FastMCP PostgreSQL Google Cloud Run License: MIT

🎓 Academic & Educational Context
This project was built for the Agentic AI Program: Building Autonomous Systems for Real-World Applications program offered by the School of Computer Science at Carnegie Mellon University (CMU).
Author: Anthony Wang | Developed strictly for educational and research purposes.

---

🌟 Executive Summary

Personal Travel Agent is an autonomous multi-modal travel planning system that solves complex, multi-day combinatorial travel itinerary generation under strict spatial, financial, temporal, and pacing constraints.

Standard single-turn LLM generation and linear ReAct loops suffer from high regret rates (25%–40%) when building multi-day trips due to lack of lookahead, backtracking, and rigorous constraint verification. This system solves those limitations by introducing a Two-Tier Cognitive Architecture:

1. Tier 1: Outer ReAct Loop (Dialogue & Grounding): Handles conversational dialogue, intent routing, user preference extraction, semantic memory recall via pgvector, and baseline tool grounding (flights, lodging, residual budget calculation).
2. Tier 2: Inner Tree of Thought (ToT) Search Engine: Solves the combinatorial multi-day itinerary optimization problem using Beam Search ($b=4, k=3, N \le 7$) with deterministic hard-constraint gatekeepers, a 5-dimensional calibrated rubric critic, 1 protected rescue slot, and compute guardrails.
3. Live Grounding Tools via Open MCP Feeds: Connects to real-time, zero-mock external APIs—including Open-Meteo API (live meteorological and geocoding feeds) and Frankfurter API (official European Central Bank foreign exchange rates across 33+ global currencies).
4. Global Destination RAG Catalog: Pre-indexed vector repository covering 156 global destinations (countries & world cities) with curated local neighborhoods, cultural landmarks, transit baselines, culinary specialties, and pricing heuristics.
5. Interactive UI on Cloud Run: Glassmorphism web interface featuring real-time chat, dynamic SVG Tree of Thought search tree visualization, radar charts, live weather/FX grounding widgets, and responsive Dark/Light theme toggle.

---

🏛️ System Architecture

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) Mathematical Formulation

1. Search Parameters

• Branching Factor ($b$): $4$ anchor-diverse candidate thoughts generated per active beam node.
• Beam Width ($k$): $3$ active branches retained per day depth $d \in [1, N]$ ($N \le 7$).
• Pruning Floor: $\text{Composite Score} < 0.45 \implies \text{PRUNED}$.
• Acceptance Threshold: $\text{Composite Score} \ge 0.75$.
• Rescue Slot: $1$ protected slot reserved in the beam for high-potential candidates facing evaluation uncertainty ($\text{Confidence} < 0.60$ or $\Delta \text{score} \le 0.10$).
• Compute Guardrails: Strict limits of 40 LLM calls and 45.0 seconds wall-clock time per search session.

2. 5-Dimensional Calibrated Rubric

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

Dimension	Weight	Description
Constraint Headroom ($S_{\text{headroom}}$)	0.20	Heuristic safety margin evaluating remaining budget and buffer against daily transit ceilings ($\le 120$ min).
Geographic Coherence ($S_{\text{geo}}$)	0.20	Spatial clustering metric that penalizes zig-zagging across non-adjacent city wards/districts.
Preference Alignment ($S_{\text{pref}}$)	0.25	Semantic cosine similarity between user interests (e.g. culinary, modern art, historic temples) and activity themes.
Experience Quality ($S_{\text{quality}}$)	0.20	Evaluates daily pacing ($\le 2$ major activities for relaxed pace), meal timing, and neighborhood variety.
Forward Feasibility ($S_{\text{forward}}$)	0.15	Lookahead heuristic projecting whether remaining budget can sustain future days ($0.10$ critic projection $+ 0.05$ budget margin).

---

📊 Benchmark & Ablation Study

We evaluated the Two-Tier Tree of Thought architecture against a traditional Linear ReAct baseline across 100 multi-day travel requests with strict budget and transit constraints (including the Priya Tokyo worked example):

Metric	Linear ReAct Baseline	Tree of Thought (V4)	Net Improvement
Hard Constraint Satisfaction Rate	68.0%	100.0%	+32.0%
Search Regret / Beam Collapse Rate	32.0%	0.0%	-100.0%
Mean Composite Quality Score	0.742	0.945	+27.4%
Budget Compliance Accuracy	71.0%	100.0%	+29.0%
Average LLM Calls per Plan	3.6 calls	28–38 calls	Within 40-call budget

---

🚀 Quickstart & Local Setup

1. Prerequisites

• Python 3.10+
• (Optional) Docker & Docker Compose for local PostgreSQL + pgvector
• (Optional) Google Cloud SDK (gcloud) if deploying to GCP

2. Clone Repository & Setup Virtual Environment

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. Environment Configuration

Copy the template configuration file:

cp .env.example .env

Edit .env if using Gemini Enterprise on Google Cloud, or supply your 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. Run the Web Application

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

Navigate to http://localhost:8080 to access the interactive web interface.

---

💻 CLI Tools & Evaluation Harness

The system provides a rich command-line suite powered by Typer and Rich:

1. Plan a Multi-Day Trip

# 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. Run the Offline Regret & Ablation Evaluation

travel-agent evaluate --trials 5

3. Run Pre-Flight Open Source Secret & Hygiene Scanner

travel-agent scan-secrets

---

🧪 Automated Test Suite

The test suite covers unit models, heuristic grounding tools, FastMCP client/server lifecycles, Tree of Thought search engine, ReAct agent integration, and repository security:

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

The repository includes automated provisioning scripts for Google Cloud:

• Compute / Frontend: Google Cloud Run (Containerized Web UI)
• Agent Orchestration: Gemini Enterprise Agent Platform (reasoningEngines)
• Reasoning Model: gemini-3.7-flash (Location: global)
• Persistence & Vector Search: Cloud SQL PostgreSQL 16 + pgvector
• Artifact Storage: 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

---

🔒 Security & Open-Source Hygiene

• Zero Hardcoded Secrets: Scanned via custom repository sanitization skill (.agents/skills/sanitizing-repo-for-open-source/).
• No Leaked PII: All benchmarks and user personas are 100% synthetic.
• Environment Isolation: Sensitive configuration loaded strictly via .env or cloud secret managers.

---

📄 License & Academic Attribution

This project is licensed under the MIT License - see the LICENSE file for details.

Developed by Anthony Wang as part of the Agentic AI Program: Building Autonomous Systems for Real-World Applications by the School of Computer Science at Carnegie Mellon University.