Legate ✈️🪁

Your personal travel envoy, that remembers

Features • Architecture • Getting Started • Tech Stack

Overview

legate is an intelligent travel assistant that automatically ingests your booking confirmation emails, builds a comprehensive record of your trips, and provides a conversational AI agent that understands your travel history and preferences.

Unlike generic travel apps, legate learns your preferences over time with your explicit consent — never silently. It proactively flags itinerary issues, fills knowledge gaps, and becomes more useful with every trip.

Core Philosophy

• Structured facts (dates, bookings, confirmations) are always queried from the database — never hallucinated
• User preferences (travel habits, favorite neighborhoods) are only saved with explicit user confirmation
• Live data (weather, exchange rates) is always fetched fresh — never cached as "memory"

Features

Email Ingestion & Extraction

• Gmail OAuth integration — secure mailbox connection with granular scoping
• LLM-powered extraction using Instructor + Google Gemini — reliable structured parsing without brittle regex
• Multi-format support — flights, accommodations, and activities
• Automatic trip grouping — intelligently associates bookings with the correct trip

Conversational Concierge Agent

Built on PydanticAI with a deliberately constrained, typed toolset:

Query tools:

• query_trips — search and filter your trip database
• get_trip_detail — retrieve full booking details for a specific trip
• find_split_trips — identify trips that should be merged
• get_weather — live weather lookups for trip dates/locations

Mutation tools (propose → confirm → execute flow):

• Create, update, and delete trips with human-readable diffs
• Manage flight and accommodation bookings
• Merge mis-split trips with automatic itinerary gap-checking
• All mutations require explicit user confirmation tokens

Intelligent Features

• Itinerary gap detection — flags tight layovers, overlapping bookings, and missing connections
• Semantic memory (planned) — preference storage with pgvector for natural language retrieval
• Multi-user support — full user isolation with Google OAuth authentication
• Rate limiting — SlowAPI integration for abuse prevention
• Observability — Langfuse tracing for all LLM calls

Architecture

Backend (FastAPI + Python)

backend/
├── agent/              # PydanticAI concierge with typed tool definitions
├── extraction/         # Instructor-based email → structured data pipeline
├── routers/           # FastAPI endpoints (trips, chat, OAuth, etc.)
├── services/          # Business logic (ingestion, grouping, auth)
├── schemas/           # Pydantic v2 models for all I/O
├── models.py          # SQLModel database schema
└── main.py            # FastAPI app with CORS, rate limiting, error handling

Key Design Decisions:

• Instructor for one-shot extraction tasks (email → FlightBooking)
• PydanticAI for multi-step reasoning and tool orchestration
• SQLModel for type-safe database operations with SQLAlchemy under the hood
• Alembic for database migrations
• Loguru for structured logging

Getting Started

Prerequisites

• Python 3.12+ with uv installed
• Node.js 20+ and npm
• PostgreSQL 15+
• Google Cloud project with Gmail API enabled

1. Backend Setup

cd backend

# Copy and configure environment
cp .env.example .env
# Fill in:
#   - DATABASE_URL (PostgreSQL connection string)
#   - GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (OAuth credentials)
#   - GEMINI_API_KEY (Google AI API key)
#   - SESSION_SECRET_KEY (generate with `python -c "import secrets; print(secrets.token_urlsafe(32))"`)

# Install dependencies
uv sync

# Run migrations
uv run alembic upgrade head

# Start dev server
uv run uvicorn main:app --reload

Backend will be available at http://localhost:8000

2. Frontend Setup

cd frontend

# Install dependencies
npm install

# Generate TypeScript types from backend OpenAPI schema
npm run generate:types

# Start dev server
npm run dev

Frontend will be available at http://localhost:3000

3. Connect Your Gmail

1. Navigate to http://localhost:3000
2. Sign in with Google
3. Authorize Gmail access
4. legate will begin ingesting travel-related emails automatically

Tech Stack

Backend:

• FastAPI — modern Python web framework
• PydanticAI — agent framework with typed tools
• Instructor — structured LLM outputs
• SQLModel — SQL databases with Python types
• Google Gemini — LLM provider
• Alembic — database migrations
• Langfuse — LLM observability

Frontend:

• Next.js 14 — React framework with app router
• TypeScript — strict type safety
• react-markdown — render agent responses

Infrastructure:

• PostgreSQL — relational data storage
• (Planned) pgvector — semantic memory retrieval

Development Principles

See AGENTS.md for AI assistant guidelines and ARCHITECTURE.md for detailed design rationale.

Key tenets:

• All external I/O uses Pydantic models — no loose dicts
• Type hints are mandatory
• Agent toolset is deliberately constrained and documented
• Memory writes require explicit user confirmation
• New dependencies require justification

Roadmap

• Email ingestion + OAuth flow
• Structured extraction pipeline (flights, accommodations)
• Trip data model + schema
• Basic trip dashboard UI
• Concierge agent v1 (query, propose/confirm mutations)
• Itinerary gap-checking
• Multi-user support with auth isolation
• Semantic memory (pgvector) + preference learning
• Email notifications (Resend)
• Production deployment (Vercel + Railway/Fly.io)
• Mobile-responsive UI polish

License

MIT — see LICENSE for details.