# hetav01/agentic-travel-assistant architecture

> Architecture diagram of the GitHub repository hetav01/agentic-travel-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hetav01/agentic-travel-assistant
- Repository: https://github.com/hetav01/agentic-travel-assistant

## Overview

##### Project Type & Purpose
- This is a full-stack travel planning application that uses a conversational Streamlit UI to provide personalized travel recommendations. It leverages APIs such as OpenWeatherMap (for weather data) and OpenAI’s Agents SDK (for flight, hotel recommendations, guardrails, and agent handoffs). The primary purpose is to enable users to get customized travel itineraries while enforcing realistic budget constraints.

##### File Structure & Core Components
- Top-Level Files:
- README.md, requirements.txt – Project documentation and dependencies.
- context.py – Handles user preferences and context.
- home.py – The primary Streamlit application for interaction.
- tools.py – Contains core functions to search for flights, hotels, and weather data.
- output_with_guardrails_and_context.py – Implements budget guardrails using the Agents SDK.
- structured_output.py and structured_outputs_with_handoffs.py – Define and manage the structure of travel plans and agent handoffs.
- weather_test.py – A file to test weather API interactions.
- Additional Directories:
- .gitignore and __pycache__ indicate version control practices and caching.
- .logfire/ is used for advanced logging support.

##### Key Architectural Components
a. User Interface (Frontend):
- Represented by home.py (Streamlit chat interface) with user inputs and display sections.
- Integration of interactive chat components and the sidebar for setting preferences.
b. Application Logic & Business Layer:
- context.py: Manages user preferences and session context.
- tools.py: Encapsulates functions to query external APIs for flights, hotels, and weather.
- output_with_guardrails_and_context.py and structured_outputs_with_handoffs.py: Handle specialized functionalities such as budget analysis (guardrails) and agent handoffs.
- structured_output.py: Defines the reusable model for structured travel recommendations.
c. External API Services:
- OpenWeatherMap API for real-time weather data.
- OpenAI API for AI-driven recommendations and agent handoffs.
- Logfire (through .logfire/ directory) for enhanced logging.
d. Testing & Support:
- weather_test.py for ensuring API connectivity.

##### Relationships & Data Flow
- The UI sends user input and preference data (maintained by context.py) to the core application logic.
- tools.py functions are called to fetch data from external services (OpenWeatherMap and OpenAI) based on the user’s inputs.
- Functions in output_with_guardrails_and_context.py ensure budget feasibility via heuristic guardrails.
- structured_outputs_with_handoffs.py facilitates smooth transfers between domain-specific agents when a task requires specialized processing.
- Structured outputs (via structured_output.py) are assembled and then rendered back on the UI.

##### Architectural Patterns & Principles Highlighted
- Separation of Concerns: Components like UI (home.py), business logic (tools.py, context.py), and external integrations (APIs) are clearly modular.
- Agent-Based Architecture: Utilizing OpenAI’s Agents SDK for guardrails and handoffs, which emphasizes modular and decoupled agent responsibilities.
- Data Modeling and Interoperability: Use of structured outputs (likely leveraging pydantic models for data validation) ensures that different modules exchange consistent information.
- Logging & Testing Integration: Incorporation of Logfire for advanced logging and dedicated test files (weather_test.py) for API checks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend Layer"
        UI["Streamlit UI (home.py)"]:::frontend
    end

    %% Business Logic
    subgraph "Business Logic Layer"
        UC["User Context & Preferences (context.py)"]:::backend
        API["Core API Functions (tools.py)"]:::backend
        BG["Budget Guardrails (output_with_guardrails_and_context.py)"]:::backend
        ST["Structured Travel Recommendation Model (structured_output.py)"]:::backend
        AH["Agent Handoff Handling (structured_outputs_with_handoffs.py)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        OW["OpenWeatherMap API"]:::external
        OA["OpenAI API"]:::external
        LF["Logfire Logging"]:::external
    end

    %% Testing & Support
    subgraph "Testing & Support"
        WT["Testing External APIs (weather_test.py)"]:::testing
    end

    %% Data flows from Frontend to Business Logic
    UI -->|"send inputs"| UC
    UC -->|"prepare context"| API

    %% Business Logic calls External APIs
    API -->|"fetch weather data"| OW
    OW -->|"weather response"| API

    API -->|"fetch recommendations"| OA
    OA -->|"agent response"| API

    API -->|"record logs"| LF
    LF -->|"logging info"| API

    %% Business Logic processing internal flows
    API -->|"apply guardrails"| BG
    API -->|"initiate handoff"| AH

    BG -->|"refine itinerary"| ST
    AH -->|"integrate handoffs"| ST

    %% Final output back to UI
    ST -->|"assembled itinerary"| UI

    %% Click Events
    click UI "https://github.com/hetav01/agentic-travel-assistant/blob/main/home.py"
    click UC "https://github.com/hetav01/agentic-travel-assistant/blob/main/context.py"
    click API "https://github.com/hetav01/agentic-travel-assistant/blob/main/tools.py"
    click BG "https://github.com/hetav01/agentic-travel-assistant/blob/main/output_with_guardrails_and_context.py"
    click ST "https://github.com/hetav01/agentic-travel-assistant/blob/main/structured_output.py"
    click AH "https://github.com/hetav01/agentic-travel-assistant/blob/main/structured_outputs_with_handoffs.py"
    click WT "https://github.com/hetav01/agentic-travel-assistant/blob/main/weather_test.py"

    %% Styles
    classDef frontend fill:#FFE6E6,stroke:#FF0000,stroke-width:2px;
    classDef backend fill:#E6F7FF,stroke:#0080FF,stroke-width:2px;
    classDef external fill:#E6FFE6,stroke:#00CC00,stroke-width:2px;
    classDef testing fill:#FFF0E6,stroke:#FF8000,stroke-width:2px;
```
