INSTALLATION.md

Secure AI Agents Suite - Installation & Usage Guide

Table of Contents

1. Installation
2. Quick Start
3. Agent Descriptions
4. Configuration
5. Usage Examples
6. Deployment
7. Troubleshooting

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager
• Git (for cloning the repository)

Quick Installation

1. Clone the repository:

   git clone https://github.com/your-org/Secure-AI-Agents-Suite.git
   cd Secure-AI-Agents-Suite
   

2. Run the setup script:

   python3 setup.py
   

3. Configure your environment:

   cp .env.example .env
   # Edit .env with your API keys
   

Manual Installation

If you prefer manual installation:

1. Install dependencies:

   pip install -r requirements.txt
   

2. Create directories:

   mkdir -p logs data temp cache exports
   

3. Configure environment:

   cp .env.example .env
   

Quick Start

Launch Individual Agents

# Enterprise Agent (CRM, Tickets, Calendar)
python enterprise/enterprise_app.py

# Consumer Agent (Trip Planning, Reminders, Summaries)
python consumer/consumer_app.py

# Creative Agent (Content, Scripts, Assets)
python creative/creative_app.py

# Voice Agent (Speech Processing)
python voice/voice_app.py

Use the Launcher Script

# Linux/Mac
./launch_agents.sh

# Windows
launch_agents.bat

Access Web Interfaces

• Enterprise Agent: http://localhost:7860
• Consumer Agent: http://localhost:7861
• Creative Agent: http://localhost:7862
• Voice Agent: http://localhost:7863

Agent Descriptions

🏢 Enterprise Agent

Purpose: Business automation and CRM management

Key Features:

• CRM customer updates and contact management
• Support ticket creation and tracking
• Calendar event scheduling and management
• Role-based access control (RBAC)
• Audit logging for compliance

Use Cases:

• Update customer information in CRM systems
• Create support tickets for IT issues
• Schedule meetings and appointments
• Search for contacts and accounts
• Generate status reports

Example Commands:

• "Update customer 001 email to newemail@company.com"
• "Create ticket about login issues - high priority"
• "Schedule team meeting for tomorrow at 2 PM"
• "Show calendar events for today"

👥 Consumer Agent

Purpose: Personal concierge and lifestyle management

Key Features:

• Trip planning and itinerary creation
• Reminder and notification management
• Document summarization and extraction
• Expense tracking and budgeting
• Weather and travel assistance

Use Cases:

• Plan vacations and business trips
• Set personal reminders and alerts
• Summarize emails and documents
• Track expenses and budgets
• Check weather and travel conditions

Example Commands:

• "Plan a trip to Pokhara next week with medium budget"
• "Remind me to call mom tomorrow at 3 PM"
• "Summarize this email about project deadlines"
• "What's the weather like in Kathmandu?"
• "Search for hotels in Delhi for December"

🎨 Creative Agent

Purpose: Content creation and creative asset generation

Key Features:

• Bilingual content carousels (English + Nepali)
• Script writing and narrative creation
• Brand content and identity development
• Asset packaging and design systems
• Social media content generation

Use Cases:

• Create presentations and marketing materials
• Write commercial scripts and narratives
• Develop brand guidelines and identity
• Package logos and design assets
• Generate social media content

Example Commands:

• "Create a 5-slide carousel about our new product in English and Nepali"
• "Write a 60-second commercial script for a tech startup"
• "Design brand guidelines for 'TechCorp Nepal'"
• "Translate 'Hello, welcome to our website' to Nepali"
• "Package logo assets in high resolution"
• "Create a content calendar for social media"

🎤 Voice Agent

Purpose: Speech processing and voice interaction

Key Features:

• Speech-to-text transcription (Whisper)
• Text-to-speech synthesis (ElevenLabs)
• Full voice conversations with AI (GPT-4o)
• Multilingual voice processing
• Audio analysis and enhancement

Use Cases:

• Transcribe meetings and conversations
• Generate natural-sounding speech
• Conduct voice-based conversations
• Process multilingual audio content
• Analyze sentiment and speaker identification

Example Commands:

• "Transcribe this audio file"
• "Say 'Hello, welcome to our voice AI' in a female voice"
• "Start a voice conversation"
• "Analyze the sentiment of this audio"
• "Search for meeting recordings about project updates"
• "Enable multilingual voice mode"

Configuration

Environment Variables

Create a .env file based on .env.example:

# MCP Server URLs
ENTERPRISE_MCP_SERVER_URL=https://enterprise-mcp.yourdomain.com
CONSUMER_MCP_SERVER_URL=https://consumer-mcp.yourdomain.com
CREATIVE_MCP_SERVER_URL=https://creative-mcp.yourdomain.com
VOICE_MCP_SERVER_URL=https://voice-mcp.yourdomain.com

# API Keys
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_API_KEY=your_google_api_key_here
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

# Security
SECURITY_LEVEL=high
AUDIT_LOGGING=true
PROMPT_INJECTION_DEFENSE=true

# Environment
ENVIRONMENT=development
LOG_LEVEL=INFO

Security Configuration

The system includes multiple security layers:

1. Prompt Injection Defense: Detects and blocks malicious prompts
2. Output Sanitization: Removes sensitive information from responses
3. Role-Based Access Control (RBAC): Controls user permissions
4. Audit Logging: Records all MCP calls for compliance
5. Input Validation: Validates all user inputs

MCP Server Setup

For production deployment, set up dedicated MCP servers:

1. Enterprise MCP Server: Handle CRM, ticket, and calendar operations
2. Consumer MCP Server: Manage travel, reminders, and personal data
3. Creative MCP Server: Process content generation and asset creation
4. Voice MCP Server: Handle speech processing and voice synthesis

Usage Examples

Enterprise Agent Examples

CRM Management

User: "Search for John contacts"
Agent: "🔍 Contact Search Results for 'john'

👤 John Smith
   📧 john.smith@company.com
   🏢 Tech Corp
   🆔 ID: 001

👤 Sarah Johnson
   📧 sarah.j@startup.io
   🏢 Startup Inc
   🆔 ID: 002

📊 Found 2 contacts."

Ticket Creation

User: "Create ticket about login issues - high priority"
Agent: "🎫 Support Ticket Created!

🆔 Ticket ID: TKT-1234
📋 Title: "Create ticket about login issues - high priority"
⚡ Priority: High
📂 Category: Account

💬 Your ticket has been submitted to our support team."

Consumer Agent Examples

Trip Planning

User: "Plan a trip to Pokhara next week with medium budget"
Agent: "✈️ Trip Planned Successfully!

🗺️ Trip Plan for Pokhara

📅 Dates: 2025-12-08 to 2025-12-12
💰 Budget: Medium
👥 Travelers: 2
🎯 Interests: Cultural, Adventure

Day 1:
• Arrival and hotel check-in
• Welcome dinner at local restaurant
• Evening city walk

Day 2:
• Morning: Cultural activities
• Afternoon: Cultural sites tour
• Evening: Local entertainment

Day 3:
• Full day adventure exploration
• Lunch at recommended restaurant
• Sunset viewpoint visit

Estimated Cost: $300 USD

✅ Your personalized itinerary is ready. Would you like me to book flights or hotels?"

Creative Agent Examples

Content Carousel

User: "Create a 5-slide carousel about our new product in English and Nepali"
Agent: "🎨 Bilingual Content Carousel - Product

Slide 1 (English):
Title: "Welcome to Our Product"
Content: "Discover amazing features and benefits"

Slide 1 (नेपाली):
Title: "हाम्रो उत्पादनमा स्वागत छ"
Content: "आश्चर्यजनक विशेषताहरू र फाइदाहरू पत्ता लगाउनुहोस्"

Slide 2 (English):
Title: "Key Features"
Content: "• Feature 1: Easy to use\n• Feature 2: Reliable\n• Feature 3: Secure"

Slide 2 (नेपाली):
Title: "मुख्य विशेषताहरू"
Content: "• विशेषता १: प्रयोग गर्न सजिलो\n• विशेषता २: भरपर्दो\n• विशेषता ३: सुरक्षित"

✅ Carousel Created: 5 slides in English & Nepali
📱 Format: Optimized for social media sharing
🎨 Style: Modern, engaging design"

Voice Agent Examples

Speech Transcription

User: [Uploads audio file]
Agent: "🎤 Voice Transcription Complete

Transcribed Text:
'Hello, this is a test of the voice transcription system. The quality is excellent and the accuracy is very high.'

Transcription Details:
• Language: en (Auto-detected)
• Confidence: 97%
• Duration: 4.2 seconds
• Words: 17
• Processing Time: 1.8 seconds

✅ Transcription saved and ready for further processing"

Text-to-Speech

User: "Say 'Hello, welcome to our voice AI' in a female voice"
Agent: "🗣️ Voice Synthesis Complete

Generated Audio:
Text: 'Hello, welcome to our voice AI'
Voice: Rachel (Female, Warm)
Voice ID: 21m00Tcm4TlvDq8ikWAM

Audio Properties:
• Duration: 1.2 seconds
• Sample Rate: 44.1 kHz
• Format: MP3 (320 kbps)
• File Size: ~0.6 KB

✅ Audio ready for playback and download
🎵 Quality: Studio-grade voice synthesis
🔊 Naturalness: Human-like intonation and emotion"

Deployment

Local Development

1. Install dependencies:

   pip install -r requirements.txt
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your settings
   

3. Run agents:

   python enterprise/enterprise_app.py &
   python consumer/consumer_app.py &
   python creative/creative_app.py &
   python voice/voice_app.py &
   

Production Deployment

Hugging Face Spaces

1. Create a new Space on Hugging Face
2. Choose Gradio SDK
3. Upload your files
4. Configure environment variables
5. Deploy

Modal Deployment (Voice Agent)

1. Install Modal CLI:

   pip install modal
   

2. Deploy voice worker:

   modal deploy voice/voice_worker.py
   

3. Configure environment:

   export MODAL_TOKEN_ID=your_token_id
   export MODAL_TOKEN_SECRET=your_token_secret
   

Docker Deployment

Create a Dockerfile:

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 7860 7861 7862 7863

CMD ["python", "enterprise/enterprise_app.py"]

Build and run:

docker build -t secure-ai-agents .
docker run -p 7860:7860 secure-ai-agents

Troubleshooting

Common Issues

Import Errors

# Install missing dependencies
pip install -r requirements.txt

Port Already in Use

# Kill process using the port
lsof -ti:7860 | xargs kill -9

API Key Issues

• Check your .env file
• Verify API keys are valid
• Ensure environment variables are loaded

MCP Server Connection

• Verify MCP server URLs
• Check network connectivity
• Review server logs

Debug Mode

Enable debug mode in your .env:

ENVIRONMENT=development
GRADIO_DEBUG=true
LOG_LEVEL=DEBUG

Logs

Check logs in the logs/ directory:

tail -f logs/agents.log

Performance

• Monitor memory usage
• Check CPU utilization
• Review API rate limits
• Optimize concurrent sessions

Support

• Documentation: See README.md and docs/
• Issues: Report on GitHub Issues
• Community: Join our Discord/Slack
• Enterprise: Contact for enterprise support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Security

This project takes security seriously:

• Regular security audits
• Dependency vulnerability scanning
• Secure coding practices
• Encrypted data transmission
• Input validation and sanitization

For security issues, please email security@yourdomain.com