Path Seeker

Portuguese | English

About this project

This project delivery a 🤖 multi-agentic system to work together in order to find the better route for a Flight plan between two coordinates, take in account the weather conditions in the trajectory.

How it's work

The system receives the start and end coordinates along with the distance ratio between each point. With these 3 pieces of information, the system will follow the following workflow:

1. Coordinate Grid Generation:

   • The system takes the start coordinate, end coordinate, and step size to calculate the centroid between the two coordinates and generate an N×D matrix that contains both the start and end coordinates within the grid, with the distance between points equal to the step size.

2. Fetch Weather Conditions for Each Point:

   • The system takes a flat list of (latitude, longitude), splits this list into chunks of length 100, and consumes the Open-Meteo API, returning a list of dictionaries containing weather information.

3. Grid Interpolation with Climate Information:

   • The system interpolates the weather information with the grid information to obtain a grid for each tracked weather variable, maintaining the shape and position for each point.

4. Graph Construction:

   • The system constructs a graph where each node represents a coordinate point, and edges connect nodes based on their proximity in the grid. Each edge is weighted according to the interpolated weather conditions, reflecting the impact of weather on travel between points.

5. Best Route Search:

   • The system employs Dijkstra's algorithm to find the optimal path from the start to the end coordinate, minimizing the cumulative weight of the edges traversed, which corresponds to the most favorable weather conditions along the route.

Installation

Clone the repository and

git clone https://github.com/gabrieltotene/PathSeeker.git

Then move to the project folder:

cd ./PathSeeker

Ensure you have uv installed on your system or environment. For more information about how to install uv, visit: uv installation

Then initialize the environment and install dependencies:

uv sync

Running

Activate pathseeker env:

• Linux

  source .venv/bin/activate

• windows

  .venv\Scripts\activate

Then run the main script with:

python -m src.main

Or run with uv directly:

uv run python -m src.main

Configuration

The system use a .env file to load some configuration parameters, such as model API keys or URL to local models, follow the below structure to create your own .env in ./src/environment:

Hosted models:

$Your provider$_API_KEY=`your_api_key_here` # Your provider in UPPERCASE
$Your provider$_BASE_URL=`https://your_model_url_here`
... how many you want `YOur provider` will be the search key to load the model in the code

Exemple:

GROQ_API_KEY=`sk-xxxxxx`
GROQ_BASE_URL=`https://api.groq.ai/v1`

Local models:

$Local model url$_BASE_URL=`http://localhost:your_port_here/v1`
$Local model api$_API_KEY=`your_api_key_here_if_needed`
... how many you want `Local model url` will be the search key to load the model in the code

Exemple:

OPENAI_API_BASE_URL=`http://localhost:8080/v1`
OPENAI_API_KEY=`sk-xxxxxx`

Usage

Here will be showing a few shot example of hot to use the system:

In the src/main.py file, you can pass the prompt for the system:

    response = await runner.run_debug(
        user_messages="Generate a coordinate grid from Congonhas Airport [-23.6261, -46.6564] to Santos Dumont Airport [-22.9105, -43.1631] with a step size of 10000 meters.",
        verbose=True
    )

And run the script:

    uv run python -m src.main

or

    python -m src.main 

The system will start the workflow, to have acess to the output generated by the agents and their tool, in the project root folder, will have a ./PathSeeker/agent_state.db file, that is a sqlite database that store all the information generated by the agents and tools during the execution.

To see and debug the information stored in the database, you can run the src/debug.py to print the result of the tools, run with:

    uv run python -m src.debug

or

    python -m src.debug 

To see a graphic representation of the the best path found by the system, you can run the src/visualization.py script, that will generate a plot with the path and weather information, such as wind and temperature, run with:

    uv run python -m src.visualization

or

    python -m src.visualization 

Limitations

1. API Rate Limits: The current implementation may face challenges with weather API rate limits (e.g., Open-Meteo). On the free tier, the number of requests per minute, hour, and day is limited. Small step sizes may lead to exceeding these limits due to the large number of generated points.

2. Flexibility: The current implementation uses a multi-agent system in a sequential way, where each agent is executed one after the other. And some tools need parameters that are not dynamically passed from the previous agent output. This limits the flexibility and adaptability of the system.

3. Parameter Tuning: The current implementation needs to change some parameters from tools or agent tool call manually in the code due to the above point. This includes parameters used in the initialization of tools class, present in src/mcp_server/server.py or agents tool calls in agent's instructions at src/agents/specialists. So if you want to change some parameters, you need to change them in the code and re-run the system.

4. AI costs: The use of AI models (like Anthropic's Claude) incurs costs based on usage. Depending on the frequency and complexity of tasks, these costs can accumulate, especially if the system is used extensively.

Future Work

Above will be listed some future improvements that gonna be done in the project:

1. Architecture Improvement: Although the sequential multi-agent architecture is effective, it lacks in flexibility. Converting the architecture to a more dynamic using an orchestrator agent that can decide which sub-agent to call based on the current state and outputs of previous agents would enhance adaptability and efficiency.

2. Dynamic Parameter Passing: Implementing an orchestrator agent would allow for dynamic parameter passing between agents. This means that parameter such as what weather variables to track, step size, and others could be adjusted on the user prompt or based on previous agent outputs, rather than being hardcoded.

3. Enhanced logging message: Currently, the system provides basic logging for each tool execution. Enhancing the logging to agents and tool execution would provide better insight into debugging and understanding the system's workflow.

4. Optimization of API Calls: Current implementation has a cache and batch processing and a rate limit handling mechanism, but further optimization could be done to minimize the number of api calls, allowing for smaller step sizes without hitting rate limits. This could be achieved through batching the coordinates in areas equaly to the api precision.

5. User Interface: Developing a user-friendly interface (web or desktop application) would make it easier for users to input parameters, visualize the generated routes, and interact with the system without needing to modify the code directly.

6. Testing and Validation: Implementing comprehensive testing (unit tests, integration tests) and validating the system's outputs against known routes and weather conditions would ensure reliability and accuracy.

7. Adding more weather variables: Expanding the range of weather variables tracked and incorporated into the graph weighting system could provide a more comprehensive assessment of route conditions.

8. Implementation of the system to differents domains: The architecture and workflow developed in this project could be adapted to other domains that require pathfinding under varying conditions, such as maritime navigation, hiking trail planning, or urban transportation routing.

9. Deploy in different agent frameworks: Explore deploying the multi-agent system in different agent frameworks or platforms to evaluate performance, scalability, and ease of use.