Modl Documentation

Welcome to the official documentation for Modl, a modern toolkit for creating, training, and deploying AI agents. Modl combines Python’s robust AI capabilities with Next.js’s dynamic dashboards to offer a seamless, developer-friendly experience. Whether you're automating tasks, building conversational agents, or managing social media bots, Modl empowers you to deploy AI agents across platforms like Discord, Twitter, and Telegram effortlessly.

Key Features

• Hybrid Architecture: Python for backend AI logic, Next.js for frontend management.

• Cross-Platform Integration: Build agents for Discord, Twitter, Telegram, and more.

• Ease of Use: Prebuilt modules, APIs, and dashboards make development intuitive.

• Extensibility: Easily customize and expand functionality with Modl’s modular design.

---

Getting Started

Prerequisites

Ensure you have the following installed:

• Python (3.8 or higher)

• Node.js (Latest LTS version)

• npm or yarn (for managing frontend dependencies)

Installation

1. Set Up Python Dependencies Create a requirements.txt file and include the following:

   Copy

   plaintextCopy codenumpy
   pandas
   scikit-learn
   tensorflow
   torch
   transformers
   requests
   flask
   python-dotenv

   Then install the dependencies:

   Copy

   bashCopy codepip install -r requirements.txt

2. Set Up Node.js Dependencies Install the required frontend dependencies:

   Copy

   bashCopy codenpm install

   Or use yarn:

   Copy

   bashCopy codeyarn install

3. Configure Environment Variables Create a .env file in the root of your project and include your platform API keys:

   Copy

   plaintextCopy codeDISCORD_API_KEY=your_discord_key
   TWITTER_API_KEY=your_twitter_key
   TELEGRAM_API_KEY=your_telegram_key

---

Core Concepts

Agents

Agents are the heart of Modl. They encapsulate AI functionality, connecting your logic to external platforms like Discord, Twitter, or Telegram.

Training

Modl allows you to train AI models using prebuilt pipelines or custom datasets. You can incorporate libraries like TensorFlow, PyTorch, or transformers to optimize performance.

Platform Integrations

Modl simplifies connecting your agents to platforms via API keys. Each platform has dedicated modules for quick integration.

Deployment Workflows

Deploy agents with minimal setup. Use Next.js dashboards for real-time monitoring, performance insights, and updates.

---

Quickstart Guide

Follow these steps to create, train, and deploy a simple Discord chatbot.

1. Create an Agent

   Copy

   pythonCopy codefrom modl.agent import DiscordAgent
   
   agent = DiscordAgent(name="MyChatBot", token="DISCORD_API_KEY")

2. Train the Agent

   Copy

   pythonCopy codefrom modl.training import Trainer
   
   trainer = Trainer(agent)
   trainer.train(dataset="path/to/dataset")

3. Deploy the Agent Run the following command to deploy the agent:

   Copy

   bashCopy codenpm run deploy

4. Monitor and Manage Open the dashboard:

   Copy

   plaintextCopy codehttp://localhost:3000

   Use it to track performance and fine-tune configurations.

---

API Reference

Python API

DiscordAgent

Copy

pythonCopy codeclass DiscordAgent:
    def __init__(self, name: str, token: str):
        """Create a new Discord agent."""

Trainer

Copy

pythonCopy codeclass Trainer:
    def __init__(self, agent):
        """Initialize a trainer for the given agent."""

    def train(self, dataset: str):
        """Train the agent using the provided dataset."""

JavaScript API

deploy

Copy

javascriptCopy codefunction deploy() {
    // Deploys the Next.js application
}

---

Platform Integrations

Discord

1. Register your bot on the Discord Developer Portal.

2. Obtain your bot’s token and add it to your .env file.

3. Start your agent:

   Copy

   pythonCopy codeagent.start()

Twitter

1. Create a developer account on the Twitter Developer Portal.

2. Generate API keys and add them to your .env file.

3. Use Modl’s TwitterAgent to integrate:

   Copy

   pythonCopy codefrom modl.agent import TwitterAgent
   
   agent = TwitterAgent(name="MyTwitterBot", token="TWITTER_API_KEY")
   agent.start()

Telegram

1. Register your bot with BotFather.

2. Add your bot token to the .env file.

3. Deploy the bot:

   Copy

   pythonCopy codeagent.start()

---

Customization

Adding Custom Logic

Extend Modl’s functionality by subclassing its core classes:

Copy

pythonCopy codefrom modl.agent import BaseAgent

class CustomAgent(BaseAgent):
    def respond(self, message):
        return f"Hello, you said: {message}"

Creating New Integrations

1. Refer to the platform’s API documentation.

2. Wrap the functionality in a custom class compatible with Modl.

---

Best Practices

1. Prepare Your Data: Ensure datasets are clean, labeled, and diverse.

2. Monitor Performance: Use the Next.js dashboard to track key metrics.

3. Scale Responsibly: For high traffic, consider hosting agents on cloud services.

---

Troubleshooting

Common Issues

• Environment Variables Not Found: Ensure .env is correctly configured.

• Dependency Errors: Re-run installation commands (pip install -r requirements.txt and npm install).

• Agent Not Responding: Verify API keys and check the agent’s status.

Debugging Tips

• Use logging for detailed error tracking:

  Copy

  pythonCopy codeimport logging
  
  logging.basicConfig(level=logging.DEBUG)

• Refer to the platform’s API documentation for common error codes.

---

Frequently Asked Questions

Q: Can I use Modl without the dashboard? Yes, but the dashboard significantly enhances usability and monitoring.

Q: Does Modl support other platforms? Yes, Modl is extensible and can support additional platforms through custom integrations.

Twitter Integration

Modl makes it easy to build, train, and deploy AI agents for Twitter. This section will guide you through the process of creating a Twitter bot using Modl’s tools and integrating it with the Twitter API. You’ll learn how to set up a basic bot that can respond to tweets, retweet, and post updates automatically.

---

Setting Up Your Twitter Agent

Step 1: Obtain Twitter API Keys

To interact with Twitter, you need API keys. Follow these steps:

1. Go to the Twitter Developer Portal and log in with your account.

2. Create a new project and app.

3. Generate the following keys:

   • API Key

   • API Key Secret

   • Access Token

   • Access Token Secret

4. Add these keys to your .env file:

   Copy

   plaintextCopy codeTWITTER_API_KEY=your_api_key
   TWITTER_API_KEY_SECRET=your_api_key_secret
   TWITTER_ACCESS_TOKEN=your_access_token
   TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret

---

Writing Your Twitter Agent

Create a file (e.g., twitter_bot.py) and write the following code:

Copy

pythonCopy codefrom modl.agent import TwitterAgent

# Step 1: Create a Twitter Agent
class MyTwitterAgent(TwitterAgent):
    def on_tweet(self, tweet):
        """Respond to tweets mentioning the bot."""
        if "hello" in tweet.text.lower():
            return f"Hi @{tweet.user_screen_name}, how can I help you today?"

    def on_hashtag(self, tweet):
        """Retweet and like tweets with specific hashtags."""
        if "#MyHashtag" in tweet.text:
            self.retweet(tweet.id)
            self.like(tweet.id)
            return "Thanks for using #MyHashtag!"

# Step 2: Initialize the agent with API keys
agent = MyTwitterAgent(
    name="MyTwitterBot",
    api_key="TWITTER_API_KEY",
    api_key_secret="TWITTER_API_KEY_SECRET",
    access_token="TWITTER_ACCESS_TOKEN",
    access_token_secret="TWITTER_ACCESS_TOKEN_SECRET"
)

# Step 3: Start the bot
if __name__ == "__main__":
    agent.start()

---

Training the Agent

If your bot uses AI for advanced responses, you can train it using Modl’s training tools. For instance:

Copy

pythonCopy codefrom modl.training import Trainer

# Train the bot to recognize positive and negative sentiment
trainer = Trainer(agent)
trainer.train(dataset="path/to/twitter_sentiment_dataset.csv")

---

Deploying the Agent

To deploy your Twitter bot, follow these steps:

Step 1: Run Your Bot Locally

Run the script locally to test the bot:

Copy

bashCopy codepython twitter_bot.py

Step 2: Deploy Using Modl Dashboard

1. Launch the Modl Next.js dashboard:

   Copy

   bashCopy codenpm run dev

2. Navigate to the dashboard at http://localhost:3000.

3. Add your bot under the "Agents" section.

4. Configure deployment settings, including:

   • Frequency of actions (e.g., how often to check for new tweets).

   • Rules for responding to users or hashtags.

5. Click "Deploy" to launch your bot.

---

5. Example Use Case: Twitter Community Bot

Here’s an example of a bot that:

• Welcomes new followers.

• Responds to specific mentions.

• Retweets posts with a specific hashtag.

Copy

pythonCopy codeclass CommunityTwitterAgent(TwitterAgent):
    def on_new_follower(self, follower):
        """Welcome new followers."""
        self.tweet(f"Thanks for following, @{follower.screen_name}! 😊")

    def on_mention(self, tweet):
        """Respond to mentions."""
        if "help" in tweet.text.lower():
            return f"Hi @{tweet.user_screen_name}, how can I assist you?"

    def on_hashtag(self, tweet):
        """Retweet posts with #Community."""
        if "#Community" in tweet.text:
            self.retweet(tweet.id)
            return "Thanks for sharing #Community!"

Deploy the bot using the same steps as above to make it live.

---

6. Monitoring and Managing Your Twitter Bot

Use the Modl dashboard to monitor your bot in real time:

• Analytics: Track engagement metrics (e.g., tweets posted, followers gained, hashtags used).

• Logs: Review the bot’s activity for debugging or analysis.

• Updates: Modify bot behavior or retrain the model without downtime.

---

7. Troubleshooting

• Issue: Bot not responding to tweets.

  • Solution: Check your API keys in the .env file and ensure the bot is running.

• Issue: Deployment fails.

  • Solution: Ensure Node.js is installed and that you ran npm install in your project directory.

• Issue: Rate limits reached.

  • Solution: Use Twitter’s API documentation to optimize the bot’s activity.

Discord Integration

Modl makes it simple to create Discord bots that can interact with users, moderate communities, and automate tasks. This guide walks you through setting up, developing, and deploying your Discord agent using Modl.

---

1. Setting Up Your Discord Agent

Step 1: Register Your Bot

1. Go to the Discord Developer Portal and log in.

2. Click “New Application” to create a new bot.

3. Under the “Bot” section:

   • Click “Add Bot”.

   • Copy the bot token and store it securely.

Step 2: Add Your Bot to a Server

1. In the OAuth2 tab, under “URL Generator”, select:

   • bot under Scopes.

   • Permissions such as Send Messages, Read Message History, and Manage Roles under Bot Permissions.

2. Copy the generated URL and paste it into your browser to invite the bot to your server.

Step 3: Configure Environment Variables

Add the bot token to your .env file:

Copy

plaintextCopy codeDISCORD_API_KEY=your_discord_bot_token

---

2. Writing Your Discord Agent

Create a file (e.g., discord_bot.py) and write the following code:

Copy

pythonCopy codefrom modl.agent import DiscordAgent

# Step 1: Define the bot behavior
class MyDiscordAgent(DiscordAgent):
    def on_message(self, message):
        """Respond to user messages."""
        if message.content.lower() == "hello":
            return f"Hi {message.author.name}, how can I assist you today?"

    def on_command(self, command, args):
        """Handle bot commands."""
        if command == "!info":
            return "This is your friendly Modl-powered Discord bot!"

    def on_reaction(self, reaction, user):
        """Respond to reactions."""
        if reaction.emoji == "👍":
            return f"Thanks for the thumbs-up, {user.name}!"

# Step 2: Initialize the agent with the Discord API key
agent = MyDiscordAgent(name="MyDiscordBot", token="DISCORD_API_KEY")

# Step 3: Start the bot
if __name__ == "__main__":
    agent.start()

---

3. Training the Agent (Optional)

If your bot needs advanced AI capabilities, such as sentiment analysis or question-answering, you can train it using Modl’s tools:

Copy

pythonCopy codefrom modl.training import Trainer

trainer = Trainer(agent)
trainer.train(dataset="path/to/discord_training_data.json")

This allows your bot to handle more complex interactions like dynamic conversations or user-specific responses.

---

4. Deploying the Agent

Step 1: Run the Bot Locally

Test the bot locally to ensure it works as expected:

Copy

bashCopy codepython discord_bot.py

Step 2: Deploy Using Modl’s Dashboard

1. Launch the Modl Next.js dashboard:

   Copy

   bashCopy codenpm run dev

2. Navigate to http://localhost:3000 in your browser.

3. Add your Discord bot under the “Agents” section.

4. Configure deployment options:

   • Set response rules (e.g., commands, reaction handling).

   • Define server-specific behaviors.

5. Click “Deploy” to launch your bot.

---

5. Example Use Case: Moderation Bot

Here’s an example of a Discord bot that:

• Deletes messages containing banned words.

• Welcomes new users to the server.

• Assigns roles automatically.

Copy

pythonCopy codeclass ModerationBot(DiscordAgent):
    banned_words = ["spam", "offensive"]

    def on_message(self, message):
        """Delete messages with banned words."""
        if any(word in message.content.lower() for word in self.banned_words):
            self.delete_message(message)
            return f"Message deleted, {message.author.name}. Please follow the server rules."

    def on_member_join(self, member):
        """Welcome new members."""
        return f"Welcome to the server, {member.name}! 🎉"

    def on_command(self, command, args):
        """Assign roles."""
        if command == "!role":
            role = args[0] if args else "Member"
            self.assign_role(member=message.author, role_name=role)
            return f"Role '{role}' assigned to {message.author.name}."

Deploy this bot using the same steps as outlined above.

---

6. Monitoring and Managing Your Discord Bot

Use the Modl dashboard to:

• Track the bot’s activity, including messages processed, commands handled, and user interactions.

• Update banned words or server-specific settings dynamically.

• Stop or restart the bot without downtime.

---

7. Troubleshooting

• Issue: Bot not responding to messages.

  • Solution: Ensure the API key in the .env file is correct and matches the bot’s token in the Discord Developer Portal.

• Issue: Missing permissions.

  • Solution: Re-invite the bot with the correct permissions using the OAuth2 URL generator.

• Issue: Deployment issues.

  • Solution: Restart the Modl dashboard and verify Node.js dependencies are installed (npm install).

Telegram Integration

Modl makes it straightforward to create Telegram bots for automating tasks, engaging users, and managing communities. This guide will walk you through setting up, coding, and deploying a Telegram bot using Modl’s tools.

---

1. Setting Up Your Telegram Agent

Step 1: Register Your Bot

1. Open Telegram and search for BotFather.

2. Start a chat with BotFather and send the command:

   Copy

   plaintextCopy code/newbot

3. Follow the prompts to:

   • Name your bot.

   • Set a unique username for your bot (must end in bot).

4. Once created, BotFather will provide an API Token. Save it securely.

Step 2: Configure Environment Variables

Add the token to your .env file:

Copy

plaintextCopy codeTELEGRAM_API_KEY=your_telegram_bot_token

---

2. Writing Your Telegram Agent

Create a file (e.g., telegram_bot.py) and write the following code:

Copy

pythonCopy codefrom modl.agent import TelegramAgent

# Step 1: Define bot behavior
class MyTelegramAgent(TelegramAgent):
    def on_message(self, message):
        """Respond to user messages."""
        if "hello" in message.text.lower():
            return f"Hi {message.chat.first_name}, how can I assist you?"

    def on_command(self, command, args):
        """Handle bot commands."""
        if command == "/start":
            return "Welcome to my Telegram bot! Type /help to see available commands."
        elif command == "/help":
            return "Available commands:\n/start - Start the bot\n/help - List commands"

    def on_callback(self, callback_data):
        """Handle button callbacks."""
        if callback_data == "info":
            return "This is a Modl-powered bot!"

# Step 2: Initialize the agent with the Telegram API key
agent = MyTelegramAgent(name="MyTelegramBot", token="TELEGRAM_API_KEY")

# Step 3: Start the bot
if __name__ == "__main__":
    agent.start()

---

3. Training the Agent (Optional)

If your bot requires more advanced AI-driven responses, you can train it using Modl’s tools:

Copy

pythonCopy codefrom modl.training import Trainer

trainer = Trainer(agent)
trainer.train(dataset="path/to/telegram_training_data.json")

---

4. Deploying the Agent

Step 1: Run the Bot Locally

Test your bot locally before deployment:

Copy

bashCopy codepython telegram_bot.py

Step 2: Deploy Using Modl’s Dashboard

1. Launch the Modl Next.js dashboard:

   Copy

   bashCopy codenpm run dev

2. Open the dashboard in your browser at http://localhost:3000.

3. Add your Telegram bot under the "Agents" section.

4. Configure deployment options:

   • Set rules for responding to messages and commands.

   • Enable or disable specific features like inline queries.

5. Click "Deploy" to make your bot live.

---

5. Example Use Case: FAQ Bot

Here’s an example of a Telegram bot that:

• Provides answers to frequently asked questions.

• Sends rich content like images or buttons.

Copy

pythonCopy codeclass FAQTelegramAgent(TelegramAgent):
    faqs = {
        "pricing": "Our pricing starts at $10/month. Visit our website for more details.",
        "support": "Contact our support team at [e-mail].",
    }

    def on_message(self, message):
        """Respond to FAQs."""
        question = message.text.lower()
        if question in self.faqs:
            return self.faqs[question]
        return "I'm not sure about that. Type /help for a list of topics."

    def on_command(self, command, args):
        """Provide a list of FAQs."""
        if command == "/help":
            return "Available topics: pricing, support"

    def on_callback(self, callback_data):
        """Send additional information."""
        if callback_data == "pricing":
            return {
                "text": "Visit our pricing page: https://example.com/pricing",
                "photo": "https://example.com/images/pricing.png"
            }

Deploy this bot using the same steps as described earlier.

---

6. Monitoring and Managing Your Telegram Bot

The Modl dashboard allows you to:

• View bot interactions, including messages handled and commands executed.

• Adjust FAQ topics or custom callbacks dynamically.

• Monitor the bot’s uptime and performance metrics.

---

7. Troubleshooting

• Issue: Bot not responding to messages.

  • Solution: Verify that the API token in the .env file matches the token provided by BotFather.

• Issue: Deployment fails.

  • Solution: Ensure the Modl dashboard is running and all dependencies are installed (npm install).

• Issue: Callback buttons not working.

  • Solution: Double-check the callback data and ensure the bot is properly handling it.

Getting Started

Create your first site

Basics

Learn the basics of GitBook

Publish your docs

Share your docs online