• Real-time web search capabilities
• Live weather updates
• News and information retrieval
• Website content summarization

🎨 User Interface

• Animated AI orb with multiple states (idle, listening, thinking, speaking)
• Modern glassmorphism design with backdrop blur effects
• Responsive layout for all screen sizes
• Dark theme with cyan/teal accent colors
• Smooth animations and transitions

� System Features

• Real-time system monitoring (CPU, RAM, Network)
• Application launcher integration
• File and folder management capabilities
• Cross-platform compatibility (Windows, macOS, Linux)

🚀 Installation

Prerequisites

• Python 3.8+ (3.9+ recommended)
• Modern web browser (Chrome, Firefox, Edge, Safari)
• Microphone for voice input (optional)
• Internet connection for AI models and web search

1. Clone the Repository

git clone https://github.com/JashanMaan28/Zorin.git
cd Zorin

2. Create Virtual Environment (Recommended)

# Windows
python -m venv env-zorin
env-zorin\Scripts\activate

# macOS/Linux
python3 -m venv env-zorin
source env-zorin/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Set Up Environment Variables

Create a .env file in the root directory:

# User Configuration
Username=YourName

# AI Model Configuration
Model=llama-3.3-70b-versatile
GroqAPIKey=your_groq_api_key_here
COHERE_API_KEY=your_cohere_api_key_here
HuggingFaceAPIKey=your_huggingface_api_key_here

# Voice Configuration
pvporcupine_ACCESS_KEY=your_picovoice_api_key_here

5. Run the Application

python run.py

The application will automatically open in your default web browser at http://localhost:8000

🔑 API Configuration

Required API Keys

Setting Up API Keys

1. Groq (Primary AI):

   • Sign up at groq.com
   • Navigate to API Keys section
   • Create new API key
   • Add to .env file

2. Cohere (Web Search):

   • Register at cohere.ai
   • Go to Dashboard → API Keys
   • Generate new key
   • Add to .env file

3. HuggingFace (Optional):

   • Create account at huggingface.co
   • Go to Settings → Access Tokens
   • Create new token
   • Add to .env file

4. Picovoice (Wake Word):

   • Sign up at picovoice.ai
   • Access Console → Porcupine
   • Copy access key
   • Add to .env file

🎮 Usage

Basic Interaction

1. Text Input: Type your question in the input field and press Enter or click Send
2. Voice Input: Click the microphone button and speak your question
3. Settings: Click the gear icon to configure API keys and models
4. Chat History: Click the chat icon to view conversation history

Voice Commands

• "Hey Zorin" - Wake word activation (if configured)
• Natural conversation - Ask questions, request information, get help
• System commands - "Open calculator", "Check weather", etc.

Keyboard Shortcuts

• Ctrl + Enter - Send message
• Cmd/Ctrl + J - Activate voice input
• Escape - Return to main interface

Advanced Features

Model Selection

Choose from multiple AI models in settings:

• Llama 3.3 70B (Recommended) - Balanced performance and accuracy
• DeepSeek R1 - Advanced reasoning capabilities
• Gemma 2 9B - Fast and efficient responses

Web Search Integration

Zorin automatically searches the web for current information when needed:

User: "What's the weather in Tokyo today?"
Zorin: *searches web* "Currently in Tokyo, it's 22°C with partly cloudy skies..."

Chat Management

• Auto-save: Conversations are automatically saved
• Archive: Old chats are archived by date
• Export: Download chat history as JSON

🏗️ Project Structure

Zorin/
├── 📁 backend/              # Python backend modules
│   ├── ChatBot.py          # Main AI chat logic
│   ├── Model.py            # AI model management
│   ├── RealtimeSearchEngine.py  # Web search functionality
│   ├── speechToText.py     # Voice recognition
│   ├── textToSpeech.py     # Voice synthesis
│   ├── commands.py         # System commands
│   ├── features.py         # Core features
│   └── settings.py         # Configuration management
├── 📁 frontend/             # Web interface
│   ├── index.html          # Main UI
│   ├── style.css           # Modern styling
│   ├── main.js             # Core JavaScript
│   ├── controller.js       # Backend communication
│   └── 📁 assets/          # Static assets
├── � Data/                 # User data and logs
│   ├── ChatLog.json        # Current conversation
│   └── 📁 Files/           # Generated content
├── 📁 chatlog_archives/     # Historical conversations
├── main.py                 # Core application logic
├── run.py                  # Application launcher
├── requirements.txt        # Python dependencies
└── .env                    # Environment configuration

� Development

Architecture

Zorin uses a hybrid architecture combining:

• Backend: Python with Eel for web app integration
• Frontend: Modern web technologies (HTML5, CSS3, ES6+)
• Communication: Eel framework for Python-JavaScript bridge
• AI: Multiple model providers via REST APIs
• Voice: Web Speech API + Edge TTS integration

Key Components

Backend (Python)

• ChatBot.py: Manages AI conversations and context
• Model.py: Handles multiple AI model integrations
• RealtimeSearchEngine.py: Web search and information retrieval
• speechToText.py: Voice input processing
• textToSpeech.py: Voice output generation

Frontend (JavaScript)

• OrbController: Manages visual AI orb animations
• WebSocket Communication: Real-time backend interaction
• Responsive UI: Modern glassmorphism design
• State Management: Handles conversation and UI states

Adding New Features

1. Backend Features: Add to /backend/ directory
2. UI Components: Modify /frontend/ files
3. API Integration: Update Model.py and settings
4. Commands: Extend commands.py for system integration

🎨 Customization

Themes & Styling

The UI uses CSS custom properties for easy theming:

:root {
  --primary-color: #0ab0d1;
  --secondary-color: #05738a;
  --accent-color: #29e9dd;
  --background-color: rgba(25, 25, 25, 0.95);
  --text-color: #ffffff;
}

Voice Configuration

Customize voice settings in .env:

# Voice Settings
VOICE_LANGUAGE=en-US
VOICE_SPEED=1.0
VOICE_PITCH=1.0
TTS_PROVIDER=edge

AI Personality

Modify the system prompt in backend/ChatBot.py:

System = f"""
You are Zorin, a helpful AI assistant.
Customize personality traits here...
"""

🚀 Deployment

Local Network Access

To access Zorin from other devices on your network:

1. Find your local IP address
2. Update run.py to bind to 0.0.0.0
3. Access via http://YOUR_IP:8000

Docker Deployment

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["python", "run.py"]

🔮 Roadmap

Upcoming Features

• � Media Control: Spotify, YouTube Music integration
• 📁 File Management: Advanced file operations and search
• 🔍 Screen OCR: Text extraction from screen content
• � Auto Startup: System tray integration
• 📧 Email Integration: Read and compose emails
• 🎨 Theme Engine: Light/dark mode with custom themes
• 🤖 Plugin System: Third-party extension support
• 🌐 Cloud Sync: Cross-device conversation sync
• 📱 Mobile App: Native mobile companion
• 🧠 Memory System: Long-term conversation memory

Version History

• v2.0.0 - Modern UI redesign with orb animations
• v1.5.0 - Multi-model AI support and web search
• v1.0.0 - Initial release with basic chat functionality

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Getting Started

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contribution Guidelines

• Code Style: Follow PEP 8 for Python, ESLint for JavaScript
• Documentation: Update README and code comments
• Testing: Add tests for new features
• Issues: Use GitHub issues for bug reports and feature requests

Areas for Contribution

• 🐛 Bug Fixes: Help improve stability
• 🎨 UI/UX: Enhance the user interface
• 🔧 Features: Add new functionality
• 📚 Documentation: Improve guides and tutorials
• 🌍 Localization: Add language support

📋 Troubleshooting

Common Issues

Installation Problems

Issue: pip install fails with permission errors

# Solution: Use virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Issue: Microphone not working

# Check microphone permissions in browser
# Ensure HTTPS or localhost for Web Speech API

Runtime Errors

Issue: "Module not found" errors

# Ensure virtual environment is activated
# Reinstall r