Nimbus Agent

An AI-powered agent that provides intelligent summaries, recommendations, and historical data analysis using large language models, real-time APIs and MCP servers.

The agent is designed to be extensible, allowing custom tools, MCP servers and clients, and external services to be integrated with it.

It can answer user queries, interact with various systems through tool integrations, store and retrieve data via MCP servers and send automated reports on a task based on its configurations.

Overview

Nimbus Agent currently has been configured as a weather assistance system that:

• AI-Powered Analysis: Uses DeepSeek-V4-Flash model via HuggingFace for intelligent weather interpretation
• Real-Time Weather Data: Fetches current weather conditions via OpenWeatherMap API
• Historical Tracking: Stores weather data in PostgreSQL for historical analysis
• Multiple Interfaces: Available as both a CLI tool and Discord bot
• Scheduled Updates: Automated daily weather reports (Discord bot)

Current Features

• Current Weather Queries: Ask about weather in any city worldwide supported by the OpenWeatherMap API
• Intelligent Summaries: AI-generated weather summaries with context-aware recommendations
• Historical Data Analysis: Query and analyze historical weather patterns
• Natural Language Interface: Interact using conversational language
• Discord Integration: Bot for automated daily weather updates and on-demand queries
• Database Persistence: All weather data stored for future reference

Architecture

The project uses a modular architecture with MCP (Model Context Protocol) for database operations:

┌─────────────────┐
│  User Interface │
│  (CLI/Discord)  │
└────────┬────────┘
         │
┌────────▼────────┐
│  AI Agent       │
│  (agent.py)     │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼───┐ ┌──▼──────┐
│ Tools │ │  MCP    │
│       │ │ Servers │
└───┬───┘ └──┬──────┘
    │         │
┌───▼───┐ ┌──▼──────┐
│Weather│ │PostgreSQL│
│ API   │ │ Database │
└───────┘ └─────────┘

Requirements

System Requirements

• Python 3.12 or higher
• PostgreSQL database (local or remote)
• Internet connection for API calls

Python Dependencies

All dependencies are managed via pyproject.toml:

• mcp>=1.27.2 - Model Context Protocol
• huggingface-hub>=1.18.0 - HuggingFace API client
• fastmcp>=3.4.2 - Fast MCP server implementation
• asyncpg>=0.31.0 - PostgreSQL async driver
• discord.py>=2.3.0 - Discord bot library
• apscheduler>=3.10.0 - Task scheduling
• python-dotenv>=1.0.0 - Environment variable management
• pytz - Timezone support

API Keys Required

• HuggingFace Token: For AI model access (Get one here)
• OpenWeatherMap API Key: For weather data (Get one here)
• Discord Token: For Discord bot (see Discord setup below)

Setup Instructions

1. Clone and Navigate

cd weather_agent

2. Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies

pip install -e .

4. Set Up PostgreSQL Database

Create a PostgreSQL database named weather_db:

CREATE DATABASE weather_db;

Create the required table:

CREATE TABLE weather_data (
    id SERIAL PRIMARY KEY,
    date_time TIMESTAMP,
    location VARCHAR(100),
    temperature FLOAT,
    temperature_max FLOAT,
    temperature_min FLOAT,
    pressure FLOAT,
    humidity FLOAT,
    conditions TEXT,
    llm_summary TEXT,
    recommendations TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and add your credentials:

# Discord Bot Configuration (required for Discord bot only)
DISCORD_TOKEN=your_discord_bot_token_here
DISCORD_CHANNEL_ID=your_discord_channel_id_here

# API Keys (required for both CLI and Discord)
HF_TOKEN=your_hugging_face_token_here
OPEN_WEATHER_API_KEY=your_openweathermap_api_key_here

Note: Database connection parameters are currently hardcoded in db_mcp_server.py and retrieval_mcp_server.py. Update these files if your PostgreSQL configuration differs:

• Host: localhost
• Port: 5432
• Database: weather_db
• User: postgres
• Password: postgres

Running MCP Servers

Start the MCP servers:

python db_mcp_server.py
python retrieval_mcp_server.py

6. Verify Setup

Test the CLI interface:

python agent.py

Try asking: "What's the weather like in London?"

Usage

CLI Mode

Run the agent interactively:

python agent.py

Example queries:

• "What's the weather like in Paris?"
• "Tell me about the weather in Tokyo"
• "Show me historical weather data for London"

Type quit or exit to stop.

Discord Bot Mode

For detailed Discord setup instructions, see DISCORD_SETUP.md.

Quick start:

1. Create a Discord bot application
2. Configure bot permissions (Message Content Intent)
3. Add environment variables to .env
4. Run the bot:

python discord_weather_bot.py

Discord commands:

• !weather - Get current London weather with AI summary
• !schedule - View scheduled jobs
• Natural language queries - Ask any weather question directly

The bot sends automated daily weather updates at 7:00 AM (London timezone).

Project Structure

weather_agent/
├── agent.py                  # Main AI agent with tool calling
├── discord_weather_bot.py    # Discord bot integration
├── db_mcp_server.py         # MCP server for database writes
├── db_mcp_client.py         # MCP client for database operations
├── retrieval_mcp_server.py  # MCP server for database reads
├── retrieval_mcp_client.py  # MCP client for retrieval
├── pyproject.toml           # Project dependencies
├── .env.example             # Environment variables template
├── DISCORD_SETUP.md         # Discord setup guide
└── README.md               # This file

How It Works

1. User Query: User asks a weather question (CLI or Discord)
2. AI Processing: The agent uses DeepSeek-V4-Flash to understand the query
3. Tool Calling: Based on the query, the agent calls appropriate tools:
   • get_weather: Fetches current weather from OpenWeatherMap API
   • add_weather_to_db: Stores weather data in PostgreSQL via MCP
   • retrieve_weather_from_db: Queries historical data via MCP
4. Response Generation: AI generates intelligent summaries and recommendations
5. Output: Formatted response returned to user

Troubleshooting

Database connection errors:

• Ensure PostgreSQL is running
• Verify database credentials in MCP server files
• Check that weather_db database exists

API errors:

• Verify your API keys are correct
• Check internet connectivity
• Ensure you have API quota available

MCP Servers:

• Verify that the MCP servers are running for both CLI and Dischord based integration modes
• Check the 'Running MCP Servers' section for commands.

Discord bot issues:

• See DISCORD_SETUP.md for detailed troubleshooting
• Verify bot has proper permissions
• Check that channel ID is correct

Notice

This project is for educational and personal use.