Kairos (Python)

This repository contains the Python implementation of the Kairos project, an AI-powered automation that finds the best weather in Europe for spontaneous travel.

The script fetches multi-day weather forecasts for a predefined list of European cities, processes this data, and uses a Large Language Model (LLM) via OpenRouter to analyze the forecasts and provide a travel recommendation. This project serves as a demonstration of building a data pipeline and integrating with multiple APIs in Python.

Features

• Fetches 8-day weather forecasts from the OpenWeatherMap API.
• Processes and transforms complex JSON data into a clean, LLM-ready format.
• Calls a powerful LLM (e.g., Gemini, Claude) via the OpenRouter API.
• Uses a detailed system prompt to get a structured JSON analysis in return.
• Built with a clean, modular architecture separating services, configuration, and orchestration.
• Manages API keys securely using a .env file.

Getting Started

Follow these instructions to get a copy of the project up and running on your local machine.

Prerequisites

• Python 3.10+
• An API key from OpenWeatherMap.
• An API key from OpenRouter.

Installation

1. Clone the repository:

   git clone [https://github.com/your-username/kairos-python.git](https://github.com/your-username/kairos-python.git)
   cd kairos-python

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. Install the required dependencies:

   pip install -r requirements.txt

4. Create your environment file: Create a new file named .env in the root of the project and add your API keys:

   OPENWEATHER_API_KEY="your_openweathermap_key_here"
   OPENROUTER_API_KEY="your_openrouter_key_here"
   OPENROUTER_BASE_URL="[https://openrouter.ai/api/v1](https://openrouter.ai/api/v1)"
   

Usage

Once the setup is complete, you can run the script with the following command:

python main.py