https://github.com/eliabdiel/ip-geolocation-agent
A Chainlit-powered AI assistant that converts IP addresses into detailed geolocation profiles with: Real-time API lookups (ipapi.co), Conversational AI (Gemini-powered), Structured data (Python dataclasses), Visualized results.
https://github.com/eliabdiel/ip-geolocation-agent
agent ai ai-agent artificial-intelligence chainlit gemini openai openai-agent-sdk python
Last synced: about 2 months ago
JSON representation
A Chainlit-powered AI assistant that converts IP addresses into detailed geolocation profiles with: Real-time API lookups (ipapi.co), Conversational AI (Gemini-powered), Structured data (Python dataclasses), Visualized results.
- Host: GitHub
- URL: https://github.com/eliabdiel/ip-geolocation-agent
- Owner: EliAbdiel
- Created: 2025-07-22T23:41:00.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-07-23T00:06:02.000Z (3 months ago)
- Last Synced: 2025-07-23T02:23:58.576Z (3 months ago)
- Topics: agent, ai, ai-agent, artificial-intelligence, chainlit, gemini, openai, openai-agent-sdk, python
- Language: Python
- Homepage:
- Size: 221 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# π IP Geolocation Agent
[](https://chainlit.io)
[](https://python.org)A conversational AI agent that retrieves detailed geolocation information for IP addresses using Chainlit and Gemini API.
| GitHub | BBC UK |
|----------------|---------------|
||
|
## Features β¨
- πΊοΈ Real-time IP geolocation lookup
- π¬ Interactive chat interface with conversation history
- π Structured data presentation with emoji indicators
- π§ Custom agent with tool integration
- π Secure API key management## Prerequisites π
- Python 3.9+
- [Chainlit](https://chainlit.io) UI
- [Gemini API key](https://aistudio.google.com/app/apikey) (free tier available)## Installation π οΈ
```bash
# Clone repository
git clone https://github.com/EliAbdiel/geolocation-agent.git
cd geolocation-agent# Create virtual environment
python -m venv venv# Activate environment (Linux/Mac)
source venv/bin/activate# Activate environment (Windows)
venv\Scripts\activate# Install dependencies
pip install -r requirements.txt
```## Configuration βοΈ
Create a `.env` file with your credentials:
```
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_ENDPOINT=https://generativelanguage.googleapis.com/v1beta/openai/
GEMINI_MODEL=gemini-2.0-flash
```## Project Structure π
```
geolocation-agent/
βββ public/
βββ src/
β βββ geo_location_agent.py # Agent logic, tools, and LocationInfo dataclass
βββ app.py # Main Chainlit application
βββ requirements.txt # Dependencies
βββ .env # Environment configuration
βββ README.md # This documentation
```## Usage π
Start the application:
```bash
chainlit run app.py -h
```Access the web interface at `http://localhost:8000`
## Output Format π
The agent returns structured information including:
- IP address
- City and region
- Country
- Latitude/Longitude coordinates
- Timezone
- OrganizationExample output:
- π‘ **IP Geolocation Info**
- π IP: `8.8.8.8`
- π City: **Mountain View**, California
- π Country: **United States**
- π Location: `37.4056, -122.0775`
- π Timezone: `America/Los_Angeles`
- π’ Organization: Google LLC## Dependencies π¦
- `chainlit` - Conversational UI framework
- `agents` - Custom agent framework
- `requests` - HTTP requests
- `python-dotenv` - Environment management
- `openai` - Client for Gemini API## Troubleshooting π
**Common issues:**
1. `Invalid API Key` error: Verify your `.env` file configuration
2. `Location data unavailable`: Check if IP address is valid
3. `Connection errors`: Ensure internet connectivity and API endpoint accessibility
4. `AttributeError in LocationInfo`: Verify IP API response structure**Debugging tips:**
- Remove `set_tracing_disabled(True)` to enable debug tracing
- Add error handling in `get_location_info()` for API responses
- Validate IP format before API call
- Check for API rate limits (ipapi.co allows 1000/day)## License π
This project is licensed under the MIT License - see the LICENSE file for details.