Gideon Logo

Python 3.8+ Py-Cord 2.4+ License MIT

Your server's intelligent companion powered by cutting-edge AI models

Installation • Features • Commands • Models • Troubleshooting • Documentation

🤖 Gideon - AI Assistant for Discord

🌟 Overview

Gideon transforms your Discord server into an AI-powered hub, connecting members to state-of-the-art language and image models. With Gideon, users can have intelligent conversations, generate creative images, analyze visual content, summarize news feeds, manage URLs, play AI-powered trivia games, and organize discussions through an intuitive thread system.

✨ Features

🧠 Intelligence

dynamic-model-search

web-search-demo

web-search-demo

web-search-demo

analyze-demo

analyze-demo

imagine-queue

imagine-queue

imagine-queue

🎮 Entertainment

🧵 Organization

ai-thread-demo

ai-thread-demo

ai-thread-demo

url-summary-demo

url-summary-demo

🛠️ Customization

🚀 Installation

There are two ways to install and run Gideon: using Docker (recommended for ease of deployment and management) or directly with Python.

Prerequisites

For both methods:

For Docker Installation:

For Python Installation:

  1. Clone the Repository: 
    git clone https://github.com/eoko-dev/gideon
cd gideon
  2. Configure Environment:
    • Copy the example environment file: 
      cp .env.example .env
    • Edit the .env file with your actual API keys and tokens (DISCORD_TOKEN, OPENROUTER_API_KEY, etc.). Leave DATA_DIRECTORY blank or commented out when using Docker Compose with the provided configuration, as the volume mount handles data persistence.
  3. Build the Docker Image:
    • Build the image using the included Dockerfile. This command builds the image and tags it as gideon-bot:latest. 
      docker build -t gideon-bot:latest .
    • (Optional) If you plan to distribute the image or use a registry like Docker Hub or GHCR, you would tag and push the image here.
  4. Configure Docker Compose:
    • Open the docker-compose.yml file.
    • Verify the volumes section. The default docker-compose.yml is set up to use a bind mount. It maps a directory from your host machine to the /app/data directory inside the container. ```yaml

      Example docker-compose.yml volume section:

      volumes: # This maps a host directory to the container’s data directory

      • ./gideon_data:/app/data # Example: Creates ‘gideon_data’ in the current directory ```
    • Important: Ensure the host path part (./gideon_data in the example) points to a location where Docker has permission to create/write files. Using a relative path like ./gideon_data will create the directory within your gideon project folder.
    • (Optional) If you pushed your image to a registry in step 3, update the image: line to point to your registry image (e.g., image: your-dockerhub-username/gideon:latest or image: ghcr.io/your-github-username/gideon:latest). Otherwise, leave it as image: gideon-bot:latest to use the locally built image.
  5. Run the Container:
    • Start the bot using Docker Compose in detached mode (runs in the background): 
      docker-compose up -d
    • To view logs: docker-compose logs -f
    • To stop the bot: docker-compose down

Python Installation

# Clone and enter repository (if not already done)
# git clone https://github.com/eoko-dev/gideon
# cd gideon

# Set up environment and dependencies
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure bot
cp .env.example .env
# Edit .env with your Discord token, OpenRouter API key, AI Horde API key,
# AND set the DATA_DIRECTORY to an absolute path where the bot can write data.
# Example: DATA_DIRECTORY=/home/user/gideon_data
# If DATA_DIRECTORY is not set, data (including the SQLite database file, typically 'gideon.db')
# will be stored in a 'data' subdirectory within the project.

# Launch
python3 -m src

Discord Configuration

  1. Create an application at Discord Developer Portal
  2. Under “Bot” tab:
    • Enable “Message Content Intent”
    • Copy your bot token for the .env file
  3. Generate invite URL in “OAuth2 > URL Generator”:
    • Scopes: bot, applications.commands
    • Permissions: Send Messages, Read Message History, Embed Links, Use Slash Commands, Manage Threads (for /thread commands)

Intent Detection Configuration (Optional)

Gideon’s intent detection feature allows users to interact naturally with the bot through @mentions instead of slash commands. This feature is enabled by default.

Environment Variables (in .env):

How It Works: When you @mention Gideon, the bot uses AI to analyze your message and determine your intent:

Supported Intents:

  1. Reminder: Schedule notifications for future events
  2. Image Generation: Create images from text descriptions
  3. Search: Fetch current information from the web (OpenRouter only)
  4. Conversation: General chat and questions

Cloudflare Worker Configuration (Optional)

⚠️ IMPORTANT: Setting up and deploying the Cloudflare Worker is the responsibility of the end user. Gideon does not provide support for configuring or troubleshooting Cloudflare Workers.

If you want to use the /dream command for generating images or enable scene visualization in Adventure mode:

  1. Create and deploy your own Cloudflare Worker that can generate images (e.g., using Cloudflare’s AI platform or another service).
  2. The worker should accept a JSON payload with at least a prompt field and return image data.
  3. Set the CLOUDFLARE_WORKER_URL in your .env file to your worker’s URL.
  4. Optionally set CLOUDFLARE_API_KEY if your worker requires authentication (e.g., via a header like Authorization: Bearer YOUR_KEY).

An example Cloudflare worker that has been tested with Gideon can be found here: flux1-cloudflare-worker

Example /dream output

dream-output

ComfyUI Configuration (Optional)

ComfyUI is a powerful node-based UI for Stable Diffusion and other AI image generation models. Gideon supports ComfyUI as an image generation provider, giving you access to advanced workflows and custom models.

Prerequisites:

Setup Steps:

  1. Install ComfyUI: 
    # Clone and setup ComfyUI
git clone https://github.com/comfyanonymous/ComfyUI
cd ComfyUI
pip install -r requirements.txt

# Download at least one checkpoint model to ComfyUI/models/checkpoints/
# Example: Stable Diffusion 1.5, SDXL, FLUX, etc.
  2. Start ComfyUI Server: 
    # Local (default port 8188)
python main.py

# Or specify host/port
python main.py --listen 0.0.0.0 --port 8188
  3. Configure Gideon:
    • Edit your .env file and add: 
      COMFYUI_URL=http://127.0.0.1:8188  # Or your remote URL
    • Restart the bot
  4. Activate ComfyUI Provider: 
    /dream manage set_provider provider:comfyui
/dream manage comfyui_test  # Verify connection

Advanced Features:

Admin Commands:

🤖 Commands

Tip: Use /help in Discord to browse all commands with an interactive menu. Admin commands are automatically hidden from regular users.

General Commands

Command Description
/help View all commands with interactive category navigation
/chat Start a conversation with the AI (supports image uploads for vision models)
/search Search the web for current information using the AI
/reset Clear the conversation history for the current channel
/summarize Summarize the current conversation history
/memory Show conversation statistics (message count, history window)

Thread Commands

Gideon leverages Discord’s native thread system to organize conversations and create dedicated AI chat spaces.

Command Description
/thread new Create a new AI conversation thread
/thread message Send a message to a specific thread
/thread list View all active AI threads in the channel
/thread delete Remove an AI thread and its history
/thread rename Change the name of an AI thread
/thread show View thread configuration settings
/thread model Set the AI model for this thread
/thread system Set the system prompt for this thread

Trivia Commands

Play AI-generated trivia games with dynamic questions on any topic you choose.

Command Description
/trivia start Start a new trivia game (solo or competitive mode)
/trivia stop End the current trivia game
/trivia stats [user] View your trivia statistics or another player's stats
/trivia leaderboard [timeframe] View server rankings (daily/weekly/monthly/all-time)
/trivia achievements Display your earned achievement badges

How to Play:

  1. Use /trivia start and choose your mode (solo/competitive), category, and difficulty
  2. The bot creates a dedicated thread and posts questions
  3. Simply type your answer in the thread (A, B, C, D, or the full answer text)
  4. Earn points based on speed and accuracy - build streaks for bonus multipliers!
  5. Complete all questions to see final results and unlock achievements

Settings Commands (Admin)

Manage global bot configuration settings.

Command Description
/settings show View all current global settings
/settings model Set global AI model (format: provider/model)
/settings system Set global system prompt
/settings provider Set global AI provider (openrouter/openai)
/settings memory Set message history limit
/settings window Set time window for history (hours)
/settings restore Reset all settings to defaults

Channel Commands (Admin)

Configure channel-specific overrides for AI behavior.

Command Description
/channel show View current channel settings
/channel model Set AI model for this channel
/channel system Set system prompt for this channel
/channel provider Set AI provider for this channel
/channel reset Clear all channel overrides
/channel list List all channels with custom settings

Admin Commands

Administrative tools and diagnostics (Admin/Owner only).

Command Description
/admin sync Sync slash commands with Discord (Owner only)
/admin debug Show debug information
/admin state Display database state information
/admin diagnostic Run system diagnostics
/admin vision_models List all vision-capable AI models

Configuration Commands (Deprecated)

These commands are deprecated and will be removed in a future update. Please use the new grouped commands above.

Command Description Permissions
/setmodel Change the default AI model for the server Admin
/model View or change the current model for the channel/thread All Users
/setsystem Customize the default AI personality (system prompt) Admin
/setchannelmodel Set the AI model for the current channel Admin
/setchannelsystem Set the system prompt for the current channel Admin
/setmemory Set the message history limit (max messages) Admin
/setwindow Set the time window for memory (in hours) Admin

Image Commands

Gideon uses a unified command for image generation with support for multiple backend providers (AI Horde, Cloudflare, OpenAI, ComfyUI, OpenRouter).

Command Description Permissions
/dream Generate an image using the currently configured AI backend. All Users
/dream_manage set_provider Set the active image generation provider. Admin
/dream_manage view_config View the current active provider and configuration. Admin
/dream_manage configure ai_horde Configure AI Horde defaults (model, size, steps). Admin
/dream_manage configure cloudflare Configure Cloudflare defaults (size, steps, seed). Admin
/dream_manage configure openai Configure OpenAI/DALL-E defaults (model, quality, style). Admin
/dream_manage configure comfyui Configure ComfyUI defaults (model, size, steps). Admin
/dream_manage configure openrouter Configure OpenRouter defaults (model, aspect ratio, image size). Admin
/dream_manage comfyui_models List available ComfyUI checkpoint models. Admin
/dream_manage comfyui_test Test ComfyUI server connection. Admin
/dream_manage comfyui_workflow Set a custom ComfyUI workflow (JSON). Admin

📚 Supported Models

Text Models (via OpenRouter)

Image Models

Via AI Horde

Via Cloudflare Worker (requires self-setup)

Via OpenRouter

❓ Troubleshooting

📖 Documentation

For detailed technical information about Gideon’s architecture, implementation details, and advanced setup instructions, please refer to the Technical Documentation.

Made with ❤️ by eoko