# 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](https://developer.twitter.com/en/portal/dashboard). 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](https://developer.twitter.com/en/portal/dashboard) 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 support@example.com.", } 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 StartedCreate your first site/files/wscrKA1knmzZgHX0xVrV/pages/CyH2xJQs9yWJ1S8BYNav
BasicsLearn the basics of GitBook/files/wscrKA1knmzZgHX0xVrV/pages/7aUFmnCMx9m4smGncsXL
Publish your docsShare your docs online/files/wscrKA1knmzZgHX0xVrV/pages/JjjojIyKxaiBPzzLwvtg
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://modl-2.gitbook.io/modl-documentation/readme.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.