Skip to content

Commit c889ae5

Browse files
keskukesku
authored
Merge branch 'main' into main
2 parents 2ded1fa + f4f4b7b commit c889ae5

File tree

5 files changed

+307
-0
lines changed

5 files changed

+307
-0
lines changed

‎docs/examples/discord-py-bot/.env.example

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.env.example
2+
DISCORD_TOKEN="YOUR_DISCORD_BOT_TOKEN_HERE"
3+
PERPLEXITY_API_KEY="YOUR_PPLX_API_KEY_HERE"

‎docs/examples/discord-py-bot/README.mdx

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Perplexity Discord Bot
3+
description: A runnable discord.py bot that adds a /ask_perplexity command to your server, using the Sonar API for web-connected answers.
4+
sidebar_position: 4
5+
keywords: [discord, bot, discord.py, python, chatbot, perplexity, sonar api, command, slash command]
6+
---
7+
8+
# Perplexity Discord Bot
9+
10+
A runnable `discord.py` application that adds a `/ask_perplexity` slash command to your Discord server, using Perplexity's Sonar API for real-time, web-connected answers.
11+
12+
## 🌟 Features
13+
14+
- **Direct Sonar API Integration**: Uses Perplexity's API for real-time, web-connected answers.
15+
- **Slash Command Ready**: Implements a modern `/ask_perplexity` command that's easy to use.
16+
- **Secure Configuration**: Uses environment variables (`.env`) for both Discord and Perplexity keys, keeping them safe.
17+
- **Administrator Permissions**: Locked to server administrators by default for easy control over API usage.
18+
- **Formatted Embeds**: Delivers answers in a clean, professional Discord embed.
19+
- **Self-Contained Example**: Minimal, single-file code designed to be easy to run and understand.
20+
21+
## 📋 Prerequisites
22+
23+
- **Python 3.8+**
24+
- **A Perplexity API Key**
25+
- **A Discord Bot Token**
26+
27+
## 🚀 Installation & Setup
28+
29+
1. **Clone the Repository:** Fork and clone the `api-cookbook` repository to your local machine.
30+
31+
2. **Navigate to this Example:**
32+
```bash
33+
cd docs/examples/discord-py-bot/
34+
```
35+
3. **Install Dependencies:**
36+
```bash
37+
pip install -r requirements.txt
38+
```
39+
4. **Get Your Secret Keys:**
40+
- **Perplexity API Key:** Get your key from the [Perplexity AI Account Settings](https://www.perplexity.ai/settings/api).
41+
- **Discord Bot Token:**
42+
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
43+
2. Click **"New Application"** and give it a name.
44+
3. Go to the **"Bot"** tab and click **"Reset Token"** (or "Add Bot" first if needed).
45+
4. Copy the token. This is your bot's password – keep it safe!
46+
47+
5. **Set Up Your Environment File:**
48+
- Rename the `.env.example` file to `.env`.
49+
- Open the `.env` file and add your secret keys:
50+
```
51+
DISCORD_TOKEN="YOUR_DISCORD_BOT_TOKEN_HERE"
52+
PERPLEXITY_API_KEY="YOUR_PPLX_API_KEY_HERE"
53+
```
54+
55+
## 🔧 Usage
56+
57+
### 1. Invite Your Bot to a Server
58+
59+
- In the Discord Developer Portal, go to "OAuth2" -> "URL Generator".
60+
- Select the `bot` and `applications.commands` scopes.
61+
- Under "Bot Permissions," select **Administrator**.
62+
- Copy the generated URL, paste it into your browser, and invite the bot to your server.
63+
64+
### 2. Run the Bot Script
65+
66+
Simply execute the `bot.py` script from your terminal:
67+
```bash
68+
python bot.py
69+
This will connect the bot to Discord and sync the /ask_perplexity command.
70+
3. Use the Command in Discord
71+
In any channel in your server, an administrator can type:
72+
code
73+
Code
74+
/ask_perplexity prompt:What is the latest news in the world of generative AI?
75+
📄 Output Example
76+
The bot will defer the interaction and then respond with a formatted embed containing the answer:
77+
code
78+
Code
79+
HatchMate [APP]
80+
🌐 Perplexity's Response
81+
82+
The latest news in generative AI includes advancements in large language models... (and so on).
83+
84+
Your Prompt```
85+
What is the latest news in the world of generative AI?
86+
Requested by YourUsername
87+
code
88+
Code
89+
## 🛠️ Extending the Bot
90+
91+
- **Role-Based Access**: Modify the permission checks to allow specific roles, not just administrators.
92+
- **Model Selection**: Add an option to the slash command to choose between different models like `sonar-pro` or `sonar-small-online`.
93+
- **Conversation History**: Implement a database (like SQLite or Redis) to store recent messages and send them with new prompts for conversational context.
94+
95+
## ⚠️ Limitations
96+
97+
- The permission system is basic (administrator-only) to keep the example simple and database-free.
98+
- The command is single-turn and does not remember conversation history.
99+
- API rate limits may apply based on your Perplexity account status.
100+
101+
## 🙏 Acknowledgements
102+
103+
- This project uses the [Perplexity AI API](https://docs.perplexity.ai/).
104+
- Built with the [discord.py](https://discordpy.readthedocs.io/en/stable/) library.

‎docs/examples/discord-py-bot/bot.py

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# This code is a simplified example of a Discord bot that integrates with the Perplexity AI API. This is a complete, minimal bot script that someone can run directly. Notice I have simplified the permission logic to only check for administrators to remove the need for an external database, making the example much more focused on the Perplexity API.
2+
3+
# bot.py
4+
import os
5+
import discord
6+
from discord.ext import commands
7+
from discord import app_commands
8+
import openai
9+
from dotenv import load_dotenv
10+
11+
# --- Step 1: Load Environment Variables ---
12+
# This ensures your secret keys are kept safe in a .env file.
13+
load_dotenv()
14+
DISCORD_TOKEN = os.getenv("DISCORD_TOKEN")
15+
PERPLEXITY_API_KEY = os.getenv("PERPLEXITY_API_KEY")
16+
17+
# --- Step 2: Bot Setup ---
18+
# We define the bot's intents, which tell Discord what events our bot needs to receive.
19+
intents = discord.Intents.default()
20+
bot = commands.Bot(command_prefix="!", intents=intents)
21+
22+
# --- Step 3: Create a Command Cog ---
23+
# Cogs are how modern discord.py bots organize commands, listeners, and state.
24+
class AIChatCog(commands.Cog):
25+
def __init__(self, bot: commands.Bot):
26+
self.bot = bot
27+
28+
# Initialize the Perplexity AI Client using the key from our .env file.
29+
# The `base_url` is the crucial part that directs the OpenAI library to Perplexity's API.
30+
if PERPLEXITY_API_KEY:
31+
self.perplexity_client = openai.OpenAI(
32+
api_key=PERPLEXITY_API_KEY,
33+
base_url="https://api.perplexity.ai"
34+
)
35+
print("Perplexity AI Client Initialized.")
36+
else:
37+
self.perplexity_client = None
38+
print("CRITICAL: PERPLEXITY_API_KEY not found in .env file.")
39+
40+
# Define the slash command.
41+
# The `has_permissions` check restricts this command to server administrators.
42+
@app_commands.command(name="ask_perplexity", description="Ask a question to Perplexity AI (with web access).")
43+
@app_commands.describe(prompt="The question you want to ask.")
44+
@app_commands.checks.has_permissions(administrator=True)
45+
async def ask_perplexity(self, interaction: discord.Interaction, prompt: str):
46+
if not self.perplexity_client:
47+
return await interaction.response.send_message(
48+
"The Perplexity AI service is not configured on this bot.",
49+
ephemeral=True
50+
)
51+
52+
# Defer the response to give the API time to process without a timeout.
53+
await interaction.response.defer(thinking=True)
54+
55+
try:
56+
# Create the list of messages for the API call, following the standard format.
57+
messages = [{"role": "user", "content": prompt}]
58+
59+
# Call the Perplexity API with the desired model.
60+
response = self.perplexity_client.chat.completions.create(
61+
model="sonar-pro",
62+
messages=messages
63+
)
64+
65+
answer = response.choices[0].message.content
66+
67+
# Create and send a nicely formatted Discord embed for the response.
68+
embed = discord.Embed(
69+
title="🌐 Perplexity's Response",
70+
description=answer,
71+
color=discord.Color.from_rgb(0, 255, 0) # Perplexity Green
72+
)
73+
embed.set_footer(text=f"Requested by {interaction.user.display_name}")
74+
75+
# Truncate the original prompt if it's too long to fit in an embed field.
76+
truncated_prompt = (prompt[:1020] + '...') if len(prompt) > 1024 else prompt
77+
embed.add_field(name="Your Prompt", value=f"```{truncated_prompt}```", inline=False)
78+
79+
await interaction.followup.send(embed=embed)
80+
81+
except Exception as e:
82+
# Inform the user if an error occurs.
83+
error_message = f"An error occurred with the Perplexity API: {e}"
84+
print(error_message)
85+
await interaction.followup.send(error_message, ephemeral=True)
86+
87+
# A local error handler specifically for this command's permission check.
88+
@ask_perplexity.error
89+
async def on_ask_perplexity_error(self, interaction: discord.Interaction, error: app_commands.AppCommandError):
90+
if isinstance(error, app_commands.MissingPermissions):
91+
await interaction.response.send_message("You must be an administrator to use this command.", ephemeral=True)
92+
else:
93+
# For other errors, print them to the console.
94+
print(f"An unhandled error occurred: {error}")
95+
# Potentially send a generic error message back to the user as well.
96+
if not interaction.response.is_done():
97+
await interaction.response.send_message("An unexpected error occurred.", ephemeral=True)
98+
99+
100+
# --- Step 4: Main Bot Events and Startup Logic ---
101+
@bot.event
102+
async def on_ready():
103+
print(f'Logged in as {bot.user}!')
104+
try:
105+
# Add the cog to the bot so its commands are registered.
106+
await bot.add_cog(AIChatCog(bot))
107+
108+
# Sync the slash commands to Discord. This makes them appear for users.
109+
synced = await bot.tree.sync()
110+
print(f"Synced {len(synced)} command(s).")
111+
except Exception as e:
112+
print(f"Error during setup: {e}")
113+
114+
# This is the entry point for running the bot.
115+
if __name__ == "__main__":
116+
if not DISCORD_TOKEN or not PERPLEXITY_API_KEY:
117+
print("CRITICAL: DISCORD_TOKEN and/or PERPLEXITY_API_KEY not found in .env file. Bot cannot start.")
118+
else:
119+
bot.run(DISCORD_TOKEN)

‎docs/examples/discord-py-bot/requirements.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# requirements.txt
2+
discord.py
3+
openai
4+
python-dotenv

‎docs/showcase/monday.mdx

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Monday – Voice-First AI Learning Assistant
3+
description: An accessible, multimodal AI learning companion that delivers contextual reasoning, 3D visualizations, and curated educational content via natural voice interaction.
4+
sidebar_position: 9
5+
keywords: [monday, AI, VR, education, accessibility, voice-assistant, 3D-visualization, multimodal-learning, perplexity, elevenlabs]
6+
---
7+
8+
**Monday** is a voice-enabled AI learning companion designed to bridge the gap between natural language queries and high-quality educational content. Inspired by Marvel's JARVIS and FRIDAY, Monday delivers tailored responses in three modes—Basic, Reasoning, and Deep Research—while integrating immersive visualizations, curated video content, and accessibility-first design.
9+
10+
## Features
11+
12+
* **Three Learning Modes**: Basic factual answers, step-by-step reasoning, and deep research investigations
13+
* **Voice-first interaction** for hands-free learning with natural language processing
14+
* **Real-time 3D visualizations** of concepts using Three.js & WebXR
15+
* **Curated educational YouTube video integration** from trusted sources
16+
* **Multi-modal feedback** combining text, speech (via ElevenLabs), and spatial panels
17+
* **VR-optional design** for immersive experiences without requiring a headset
18+
* **Accessibility-focused interface** for mobility- and vision-impaired users
19+
20+
## Prerequisites
21+
22+
* Node.js 18 LTS or newer
23+
* Modern web browser (Chrome, Edge, or Firefox recommended)
24+
* Microphone for voice interaction
25+
* Optional: VR headset for immersive mode (WebXR compatible)
26+
* Perplexity API key, ElevenLabs API key, and YouTube API key
27+
28+
## Installation
29+
30+
```bash
31+
# Clone the repository
32+
git clone https://github.com/srivastavanik/monday.git
33+
cd monday
34+
git checkout final
35+
cd nidsmonday
36+
37+
# Install dependencies
38+
npm install
39+
40+
# Create a .env file and set your API keys
41+
PERPLEXITY_API_KEY=your_api_key
42+
ELEVENLABS_API_KEY=your_api_key
43+
YOUTUBE_API_KEY=your_api_key
44+
45+
# Start Backend Server
46+
node backend-server.js
47+
48+
# Start frontend
49+
npm run dev
50+
```
51+
52+
## Usage
53+
54+
1. Launch the app in your browser
55+
2. Say **"Hey Monday"** to activate the assistant
56+
3. Ask a question in one of three modes:
57+
- **Basic Mode** – "What is photosynthesis?"
58+
- **Reasoning Mode** – "Think about how blockchain works."
59+
- **Deep Research Mode** – "Research into the history of quantum mechanics."
60+
4. View answers as floating text panels, voice responses, and interactive 3D models
61+
62+
## Code Explanation
63+
64+
* **Frontend**: TypeScript with Three.js for 3D visualizations and WebXR for VR support
65+
* **Backend**: Node.js with Socket.IO for real-time voice command processing
66+
* **AI Integration**: Perplexity Sonar API for intelligent responses with reasoning extraction
67+
* **Voice Processing**: ElevenLabs for speech synthesis and natural language understanding
68+
* **Content Curation**: YouTube API integration with smart keyword extraction for educational videos
69+
* **Accessibility**: Voice-first design with spatial audio and haptic feedback support
70+
71+
## Links
72+
73+
- [GitHub Repository](https://github.com/srivastavanik/monday/tree/final)
74+
- [Live Demo](https://www.youtube.com/watch?v=BSN3Wp4uE-U)
75+
76+
77+

0 commit comments

Comments
 (0)