Installation Extras

Optional dependencies and feature packages for specialized PraisonAI functionality

PraisonAI provides optional dependency groups (extras) for specific features like bot integrations, gateway servers, and storage backends.

Quick Start

1. Choose Your Use Case

   Select installation based on your requirements:

   # Basic agent development
   pip install praisonai
   
   # Bot integrations (Telegram, Discord, Slack)
   pip install "praisonai[bot]"
   
   # Gateway server with WebSocket/REST
   pip install "praisonai[api]"
   
   # Gateway + bots (most common)
   pip install "praisonai[bot,api]"
   
   # Everything included
   pip install "praisonai[all]"
   

   praisonaiagents[all] also installs the [autonomy] and [os] optional groups (verification hooks, OS/gateway helpers). The wrapper extra praisonai[all] focuses on bots, gateway, and tools — add pip install "praisonaiagents[autonomy]" or "praisonaiagents[os]" when you need only those slices.

2. Verify Installation

   Test that required dependencies are available:

   # Test core functionality
   from praisonaiagents import Agent
   agent = Agent(name="test", instructions="Hello")
   
   # Test bot integration (if [bot] installed)
   from praisonai.bots import TelegramBot
   
   # Test gateway (if [api] installed)
   from praisonai.gateway import WebSocketGateway
   
3. Handle Missing Dependencies

   If you encounter import errors, install the required extra:

   # Error: Gateway requires starlette and uvicorn
   pip install "praisonai[api]"
   
   # Error: No module named 'python-telegram-bot'
   pip install "praisonai[bot]"
   

---

Available Extras

Bot Integration ([bot])

Enables chat platform integrations:

pip install "praisonai[bot]"

Includes:

• python-telegram-bot - Telegram bot API
• discord.py - Discord bot integration
• slack-sdk - Slack app development
• twilio - WhatsApp Business API
• requests - HTTP client for webhooks

Use cases:

• Telegram bot deployment
• Discord server integration
• Slack workspace apps
• WhatsApp Business messaging
• Multi-platform chat bots

Example:

from praisonai.bots import TelegramBot, DiscordBot

telegram = TelegramBot(token="your_token")
discord = DiscordBot(token="your_token")

API Server ([api])

Enables gateway and web server functionality:

pip install "praisonai[api]"

Includes:

• uvicorn - ASGI server
• fastapi - Web framework
• starlette - WebSocket support
• python-multipart - File upload handling
• websockets - WebSocket protocol

Use cases:

• PraisonAI Gateway deployment
• REST API endpoints
• WebSocket real-time communication
• Agent-as-a-Service hosting
• Dashboard and UI backends

Example:

from praisonai.gateway import WebSocketGateway
from praisonaiagents.gateway import GatewayConfig

config = GatewayConfig(host="127.0.0.1", port=8765)
gateway = WebSocketGateway(config=config)

Tools Collection ([tools])

Specialized tools and integrations:

pip install "praisonai[tools]"

Includes:

• tavily-python - Web search API
• requests - HTTP requests
• beautifulsoup4 - HTML parsing
• PyPDF2 - PDF processing
• python-docx - Word document handling

Use cases:

• Web search capabilities
• Document processing
• File format conversion
• Data extraction and parsing
• Research and analysis

Storage Backends ([storage])

Database and vector store integrations:

pip install "praisonai[storage]"

Includes:

• chromadb - Vector database
• qdrant-client - Qdrant vector store
• pinecone-client - Pinecone vector database
• redis - Redis caching
• pymongo - MongoDB integration

Use cases:

• Knowledge base storage
• Vector similarity search
• Session state persistence
• Caching and performance
• Multi-agent coordination

Complete Installation ([all])

All optional dependencies included:

pip install "praisonai[all]"

Includes: All extras above plus additional integrations.

Best for:

• Development environments
• Full-featured deployments
• Experimenting with all features
• Production systems using multiple capabilities

---

Common Use Cases

Gateway Deployment

Requirement: Multi-channel bot gateway with WebSocket support

pip install "praisonai[bot,api]"

Why both extras:

• [bot] provides Telegram, Discord, Slack integration
• [api] provides gateway WebSocket server and REST endpoints

Configuration:

# gateway.yaml
gateway:
  host: "127.0.0.1"
  port: 8765

channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}

Agent Development

Requirement: Basic agent creation and testing

pip install praisonai
# No extras needed for core agent functionality

Example:

from praisonaiagents import Agent

agent = Agent(
    name="researcher", 
    instructions="Research topics thoroughly",
    model="gpt-4o-mini"
)

Production Bot

Requirement: Robust bot with search, storage, and monitoring

pip install "praisonai[all]"

Features enabled:

• Bot platform integration
• Web search and document processing
• Vector knowledge storage
• REST API for monitoring
• All available tools and integrations

---

Installation Troubleshooting

Common Import Errors

Gateway requires starlette and uvicorn

Error:

ImportError: Gateway requires starlette and uvicorn.
Install with: pip install praisonai[api]

Solution:

pip install "praisonai[api]"
# or
pip install "praisonai[bot,api]" # for bot + gateway

No module named 'python-telegram-bot'

Error:

ModuleNotFoundError: No module named 'python-telegram-bot'

Solution:

pip install "praisonai[bot]"

This happens when trying to use Telegram integration without the bot extra.

No module named 'chromadb'

Error:

ModuleNotFoundError: No module named 'chromadb'

Solution:

pip install "praisonai[storage]"
# or
pip install "praisonai[all]"

Vector storage requires the storage extra.

Cannot install on Windows

Symptoms: Package installation fails on Windows

Solutions:

For encoding issues:

$env:PYTHONUTF8 = "1"
pip install "praisonai[bot,api]"

For build errors:

# Install Visual Studio Build Tools
# or use conda-forge
conda install -c conda-forge praisonai

Dependency Conflicts

Handle version conflicts between extras:

# Clean installation
pip uninstall praisonai
pip cache purge

# Reinstall with specific extras
pip install "praisonai[bot,api]==latest"

# Check for conflicts
pip check

Minimal Installation

For resource-constrained environments:

# Core only (smallest footprint)
pip install praisonai --no-deps
pip install openai  # Manual essential deps

# Specific platform only
pip install "praisonai[bot]" --no-deps
pip install python-telegram-bot openai

---

Extra Dependency Reference

Complete dependency listing by extra:

Extra	Key Dependencies	Size	Use Case
[bot]	python-telegram-bot, discord.py, slack-sdk	~50MB	Chat platform integration
[api]	uvicorn, fastapi, starlette	~30MB	Web server and WebSocket
[tools]	tavily-python, beautifulsoup4, PyPDF2	~25MB	Document and web processing
[storage]	chromadb, qdrant-client, pymongo	~100MB	Databases and vector stores
[all]	All of the above + additional	~200MB	Complete functionality

Platform-Specific Notes

Windows:

• Some packages may require Visual Studio Build Tools
• UTF-8 encoding setup recommended: $env:PYTHONUTF8 = "1"
• Consider using conda for complex dependencies

macOS:

• May require Xcode Command Line Tools
• Install via Homebrew Python for best compatibility

Linux:

• Usually installs without issues
• May need system packages for some features (e.g., libssl-dev)

---

Best Practices

Use virtual environments

Always isolate PraisonAI installations:

# Create dedicated environment
python -m venv praisonai-env
source praisonai-env/bin/activate  # Linux/macOS
# or
praisonai-env\Scripts\activate     # Windows

# Install with extras
pip install "praisonai[bot,api]"

Pin versions in production

Use specific versions for reproducible builds:

# requirements.txt
praisonai[bot,api]==1.2.3
python-telegram-bot==20.7
fastapi==0.104.1

Install only needed extras

Minimize dependency footprint:

# Development: everything
pip install "praisonai[all]"

# Production bot: minimal
pip install "praisonai[bot]"

# Gateway only: minimal  
pip install "praisonai[api]"

Monitor dependency security

Keep dependencies updated:

# Check for vulnerabilities
pip-audit

# Update safely
pip install --upgrade "praisonai[all]"
pip check  # Verify no conflicts

---

Related

Gateway Overview

Gateway requires [api] extra

Bot Integrations

Bot platforms require [bot] extra