Tripper: Embabel Travel Planner Agent

---

🚀 Quick Start

Warning: Tripper is a genuinely useful travel planner. But be aware that its extensive LLM usage will cost money. A typical run costs around $0.10c.

Prerequisites

• Java 21+
• Docker
• Maven 3.6+
• Make sure you have 'Docker Model Runner' up and running and exposed on port 12434 ( docker desktop enable model-runner --tcp=12434)

Environment Setup

1. Configure API Keys

   export OPENAI_API_KEY=your_openai_api_key_here
   export ANTHROPIC_API_KEY=your_anthropic_api_key_here
   # Set your Brave API key for image search
   export BRAVE_API_KEY=your_brave_api_key_here
   
   

2. Set MCP Environment variables for MCP tools running in Docker

   # Copy the example environment file
   cp mcp.env.example .mcp.env
   
   # Edit mcp.env with your configuration
   nano .mcp.env
   

Running the Application

1. Start Background Services

   docker compose --file compose.yaml --file compose.dmr.yaml up
   

2. Launch the Travel Planner

   Option A: Using Shell Script

   ./run.sh
   

   Option B: Using IDE

   • Open the project in your IDE
   • Run it in the way your IDE runs Spring Boot apps. In IntelliJ IDEA, simply run the main method in TripperApplication.kt.

3. Access the Application

   • Travel Planner: http://localhost:8080/
   • Platform Info: http://localhost:8080/platform

Running the Application with Docker

1. Launch the Travel Planner

   docker compose --profile in-docker up
   

2. Access the Application

   • Travel Planner: http://localhost:8747/
   • Platform Info: http://localhost:8747/platform

Note that the default port is 8747 not the usual Java 8080. This is because we often run multiple Embabel servers at once and don't want them to conflict. The specific port is a reference to an iconic aircraft. It's easy to change the port in application.properties.

Setup OAuth Credentials

Enable security by changing the following line in application.properties:

embabel.security.enabled=true

Then follow these steps to set up Google OAuth:

1. Get Google OAuth credentials from Google Cloud Console
2. Add redirect URI: http://localhost:8747/login/oauth2/code/google
3. Set your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables:

   export GOOGLE_CLIENT_ID=your_google_client_id_here
   export GOOGLE_CLIENT_SECRET=your_google_client_secret_here
   

For more details, see the Security Guide.

📸 Screenshots

🏗️ Architecture

The Tripper agent follows a modern microservices architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Spring Boot/  │    │      LLMs       │
│   (htmx)        │◄──►│ Embabel Backend │◄──►│ (Claude,GPT 4)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │   Docker        │
                       │   MCP tools     │
                       └─────────────────┘

Components:

• Frontend: Modern web interface built with htmx for seamless interactions
• Backend: Kotlin-based Spring Boot application handling business logic. Key flow is defined in TripperAgent.kt.
• LLMs: Illustrates use of multiple LLMs
• Containerization: Docker for consistent deployment across environments and MCP tool management

🛠️ Development

Tech Stack

• Backend: Kotlin, Embabel, Spring Boot, Apache Tomcat
• Frontend: htmx, JSON APIs
• Build: Apache Maven
• DevOps: Docker, GitHub Actions

Note For Linux Developers

• Ensure proper software version: Docker Desktop 4.43.1
• Linux Docker Desktop does not support yet Model Runner in GUI. Please follow Model Runner Documentation
• Validation step:

  docker model pull  jimclark106/all-minilm:23M-F16

• Thereafter below compose would not be required (due to temparary lack of support on Linux):

  docker compose --file compose.dmr.yaml up

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🤝 Support

For questions, issues, or contributions, please visit our GitHub repository or open an issue.

Contributors

---