TravelAgent AI

A CLI-based AI travel planning agent that builds complete end-to-end trip plans — transport, accommodation, day-by-day itinerary, and budget breakdown — from a single command.

Powered by LiteLLM, so you can use any supported LLM provider (Anthropic, OpenAI, Google, Mistral, etc.) with your own API key.

---

Features

• Searches flights, trains, and buses between cities
• Finds hotels across a range of budgets
• Builds a day-by-day itinerary with activities, restaurants, and attractions
• Validates the full plan fits within your budget
• Generates a formatted Markdown travel report saved to disk
• Interactive CLI — prompts for any missing inputs

---

Requirements

• Python 3.11+
• An API key for at least one supported LLM provider

---

Installation

1. Clone the repository

git clone <repo-url>
cd travel_planning_agent

2. Install dependencies

pip install -e .

For development (includes pytest):

pip install -e ".[dev]"

For PDF report generation (optional):

# macOS — install system libraries first
brew install pango

# Then install the Python extra
pip install -e ".[pdf]"

3. Configure your API key

Copy the example env file and fill in your credentials:

cp .env.example .env

Open .env and set your model and API key. Choose one of the following providers:

Option A — Anthropic (recommended)

TRAVELAGENT_MODEL=anthropic/claude-sonnet-4-20250514
ANTHROPIC_API_KEY=sk-ant-...

Available Anthropic models:

Model	Description
anthropic/claude-opus-4-6	Most capable, best for complex itineraries
anthropic/claude-sonnet-4-20250514	Recommended — fast and capable
anthropic/claude-haiku-4-5-20251001	Fastest and cheapest

Option B — OpenAI

TRAVELAGENT_MODEL=openai/gpt-4o
OPENAI_API_KEY=sk-...

Available OpenAI models:

Model	Description
openai/gpt-4o	Recommended — best balance of speed and quality
openai/gpt-4o-mini	Faster and cheaper
openai/gpt-4-turbo	High capability, higher cost

Other providers

Provider	Example model string	API key env var
Google	google/gemini-2.0-flash	GOOGLE_API_KEY
Mistral	mistral/mistral-large-latest	MISTRAL_API_KEY

Any model that supports function calling via LiteLLM will work. Models without function calling are not compatible.

See LiteLLM docs for the full list of supported models.

---

Quick Start

Non-interactive — provide all arguments upfront:

travelagent plan --origin "Singapore" --destination "Tokyo" --days 5 --budget 2000

Interactive — get prompted for anything missing:

travelagent plan

Departure city: Singapore
Destination city: Tokyo
Number of days: 5
Total budget: 2000
Departure date (YYYY-MM-DD): 2026-06-01

The agent will then research flights, hotels, and attractions, verify the budget, and print a complete travel report to your terminal. The report is also saved as a Markdown file in the current directory.

---

CLI Reference

travelagent plan

Plans a complete trip and generates a travel report.

Flag	Short	Description	Default
--origin	-o	Departure city	prompted
--destination	-d	Destination city	prompted
--days	-n	Number of travel days	prompted
--budget	-b	Total budget (number)	prompted
--currency	-c	Currency code	USD
--departure		Departure date YYYY-MM-DD	today
--output	-O	Output path for Markdown report	auto-named
--pdf		Also generate a PDF report	off
--email		Email address to send report to	—

Examples:

# 3-day Paris trip in EUR
travelagent plan --origin "London" --destination "Paris" --days 3 --budget 1500 --currency EUR --departure 2026-06-01

# Save report to a specific file
travelagent plan --origin "Bangkok" --destination "Bali" --days 7 --budget 1800 --output reports/bali_trip.md

# Generate PDF as well
travelagent plan --origin "Dubai" --destination "Istanbul" --days 4 --budget 2500 --pdf

travelagent config

Show the current configuration:

travelagent config

Current Configuration
  Model:          anthropic/claude-sonnet-4-20250514
  Max iterations: 15
  Temperature:    0.2

To change the model, update TRAVELAGENT_MODEL in your .env file.

---

Configuration Reference

All settings live in .env:

# Required
TRAVELAGENT_MODEL=anthropic/claude-sonnet-4-20250514
ANTHROPIC_API_KEY=sk-ant-...

# Optional
TRAVELAGENT_MAX_ITERATIONS=15   # Max agent reasoning steps (default: 15)
TRAVELAGENT_TEMPERATURE=0.2     # LLM temperature (default: 0.2)

---

Output

The agent saves a Markdown report to disk after every run. Example filename: travel_report_tokyo_2026-06-01.md

The report includes:

1. Trip Summary — origin, destination, dates, budget
2. Transport — chosen option with provider, times, cost, and booking URL
3. Accommodation — hotel details, rating, amenities, total cost
4. Day-by-Day Itinerary — activities per day with costs and durations
5. Budget Breakdown — table of all costs and remaining balance
6. Useful Info — currency tips, emergency contacts

---

Supported City Pairs (Phase 1 Mock Data)

The Phase 1 mock data includes realistic options for these routes. Any other city pair will return a generic set of options.

Route
Singapore ↔ Tokyo
London ↔ Paris
New York ↔ Los Angeles
Bangkok ↔ Bali
Dubai ↔ Istanbul

---

Running Tests

pytest tests/ -v

To run a specific test file:

pytest tests/test_tools.py -v
pytest tests/test_agent.py -v

With coverage:

pytest tests/ --cov=travelagent --cov-report=term-missing

All LLM calls are mocked in tests — no API key is needed to run the test suite.

---

Project Structure

travelagent/
├── agent.py              # ReAct agent loop
├── config.py             # Env var loading and validation
├── main.py               # CLI entry point (click)
├── models/trip.py        # Pydantic data models
├── prompts/system.py     # System prompt template
├── tools/
│   ├── base.py           # BaseTool abstract class
│   ├── registry.py       # Tool registration and dispatch
│   ├── flight_search.py  # search_flights tool
│   ├── hotel_search.py   # search_hotels tool
│   ├── attractions.py    # search_attractions tool
│   └── budget_calculator.py  # calculate_budget tool
├── report/
│   ├── generator.py      # Markdown/PDF report builder
│   └── templates/travel_report.md.j2
└── delivery/
    └── email_sender.py   # Email delivery (Phase 2 stub)

data/
├── mock_flights.json
├── mock_hotels.json
└── mock_attractions.json

---

Roadmap

Phase	Status	Description
1	Current	CLI agent with mock data, any LLM via LiteLLM
2	Planned	Real flight search (Amadeus API), PDF reports, email delivery
3	Planned	Real hotel & attractions APIs, multi-city trips
4	Planned	Web UI, WhatsApp delivery, trip history

---

Troubleshooting

Configuration error: No LLM provider API key found Copy .env.example to .env and add your API key.

Tool 'X' is not registered This is a bug — please open an issue with the full error output.

Agent returns a partial plan The agent hit the TRAVELAGENT_MAX_ITERATIONS limit. Try increasing it in .env or simplifying the trip parameters.

PDF generation fails with ImportError Install the optional PDF dependency: pip install travelagent[pdf]

PDF generation fails with OSError: cannot load library 'libpango-1.0-0' WeasyPrint requires the Pango system library which is not bundled with pip. On macOS:

brew install pango

On Linux (Debian/Ubuntu): sudo apt install libpango-1.0-0