Metadata-Version: 2.4
Name: SiphoAI
Version: 1.0.1
Summary: AI-powered voice command assistant for desktop automation
Home-page: https://github.com/niquewrld/siphoai
Author: NiqueWrld
Author-email: NiqueWrld <niquewrld@outlook.com>
License: MIT License
        
        Copyright (c) 2025 Sipho AI Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/yourusername/siphoai
Project-URL: Bug Reports, https://github.com/yourusername/siphoai/issues
Project-URL: Source, https://github.com/yourusername/siphoai
Project-URL: Documentation, https://github.com/yourusername/siphoai#readme
Keywords: voice assistant,desktop automation,ai assistant,voice commands,home automation,productivity,flask api,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Systems Administration
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=2.3.3
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: python-dotenv
Requires-Dist: openai
Requires-Dist: pillow
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: voice
Requires-Dist: SpeechRecognition; extra == "voice"
Requires-Dist: pyttsx3; extra == "voice"
Requires-Dist: pyaudio; extra == "voice"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Sipho AI - Voice Command Assistant

An AI-powered voice command assistant for desktop automation that uses natural language processing to execute commands on your PC. Built  "alternative_message": "Message when app is missing"

## Command Examplesth Flask API and OpenAI integration for intelligent conversation handling.

[![PyPI version](https://badge.fury.io/py/siphoai.svg)](https://badge.fury.io/py/siphoai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)

## Features

- **AI-Powered Conversations**: Natural language processing with OpenAI integration
- **Smart Command Detection**: Automatically distinguishes between commands and conversations
- **REST API**: Flask-based API for web and mobile integration
- **JSON-Based Commands**: All commands stored in `commands.json` for easy management
- **Voice Confirmation**: Sensitive commands require confirmation for safety
- **Third-Party App Detection**: Automatically checks if required applications are installed
- **System Checker**: Comprehensive system scanning and installation suggestions
- **Web Integration**: Open websites, perform searches, launch applications
- **System Control**: Shutdown, restart, lock, volume control, and more

## Quick Start

### Installation

```bash
pip install siphoai
```

### Basic Usage

```bash
# Start the API server
siphoai

# View available commands
siphoai help-commands

# Test a command
siphoai test "open youtube"
```

The server will start on `http://localhost:5000` with the following endpoints:
- `POST /api/command` - Execute commands & handle conversations
- `GET /api/help` - Get available commands  
- `GET /api/status` - Server status

## Configuration

Create a `.env` file for AI features:

```bash
OPENROUTER_API_KEY=your_openrouter_api_key_here
FLASK_HOST=0.0.0.0
FLASK_PORT=5000
FLASK_DEBUG=false
```

Get your free API key from [OpenRouter](https://openrouter.ai/keys).

## Enhanced Features

### AI Integration
- Powered by OpenAI through OpenRouter API
- Natural conversation handling
- Smart command vs conversation detection
- Context-aware responses
- Enhanced command feedback

### Voice Confirmation
Sensitive commands (shutdown, restart, lock) require confirmation:
- Server asks "Are you sure you want to [action]?"
- Respond with confirmation to proceed
- Automatic timeout for safety

### Third-Party App Detection
- Automatically detects if required applications are installed
- Provides download links for missing apps
- Supports environment variable expansion
- Installation instructions included

### System Checker
Built-in utility to scan your system:
- Detects installed applications
- Checks voice command requirements  
- Generates installation suggestions
- Comprehensive system reports

## Package Structure

```
siphoai/
├── __init__.py           # Package initialization
├── app.py               # Main Flask application
├── cli.py               # Command-line interface
├── data/
│   └── commands.json    # Command configurations
└── utils/
    ├── command_manager.py # Command management tools
    └── system_checker.py  # System scanning utilities
```

## Supported Commands

The package comes with pre-configured commands in multiple categories:

### Web Commands
- **Social Media**: "Open YouTube", "Open Facebook", "Open Twitter", "Open Instagram"
- **Professional**: "Open LinkedIn", "Open GitHub"
- **Search**: "Open Google", "Search for [term]"
- **Entertainment**: "Open Netflix"

### Application Commands
- **System Tools**: "Open Calculator", "Open Notepad", "Open Paint"
- **File Management**: "Open File Explorer", "Open Command Prompt"
- **System**: "Open Task Manager", "Open Control Panel", "Open Settings"
- **Development**: "Open Visual Studio Code", "Open PowerShell"

### System Commands
- **Power**: "Shutdown computer", "Restart computer", "Sleep computer"
- **Security**: "Lock computer"
- **Control**: "Cancel shutdown", "Minimize all windows"

### Information Commands
- **Time**: "What time is it?"
- **Date**: "What date is it?" or "Today"

### Volume Control (requires nircmd)
- **Audio**: "Volume up", "Volume down", "Mute"

### Media Commands  
- **Players**: "Open music player", "Open photos"

### Vision Commands
- **Screenshot**: "Take screenshot", "Analyze screen"
- **AI Analysis**: "What's on my screen?", "Describe my screen"

## Adding New Commands

### Method 1: Using Command Manager (Recommended)
1. Run `launcher.bat` and select option 2
2. Choose the type of command to add
3. Follow the interactive prompts
4. Save your changes

### Method 2: Edit JSON Directly
Edit `commands.json` to add new commands. Each command has this structure:

```json
{
  "triggers": ["phrase1", "phrase2"],
  "action": "action_type",
  "response": "What the app will say",
  "url": "https://example.com",  // For web commands
  "command": ["executable", "arg1", "arg2"]  // For app/system commands
}
```

### Available Action Types:
- `web_open` - Opens a URL in the browser
- `run_application` - Runs an application/executable
- `system_command` - Executes a system command
- `volume_control` - Controls system volume
- `get_time` - Gets current time
- `get_date` - Gets current date
- `web_search` - Performs a web search
- `show_help` - Shows help information
- `exit_app` - Exits the application

### Additional Properties:
- `requires_confirmation` - Set to `true` for sensitive commands
- `confirmation_message` - Custom confirmation question
- `requires_third_party` - Object with third-party app information:
  - `app_name` - Display name of the application
  - `executable` - Path or name of executable to check
  - `download_url` - Where to download the app
  - `install_instructions` - How to install the app
  - `alternative_message` - Message when app is missing

## Command Examples

### Basic Command
```json
{
  "triggers": ["open notepad", "notepad"],
  "action": "run_application",
  "command": ["notepad.exe"],
  "response": "Opening Notepad"
}
```

### Command with Confirmation
```json
{
  "triggers": ["shutdown computer"],
  "action": "system_command",
  "command": ["shutdown", "/s", "/t", "30"],
  "response": "Shutting down computer",
  "requires_confirmation": true,
  "confirmation_message": "Are you sure you want to shutdown?"
}
```

### Third-Party App Command
```json
{
  "triggers": ["open discord"],
  "action": "run_application",
  "command": ["C:\\Users\\%USERNAME%\\AppData\\Local\\Discord\\Discord.exe"],
  "response": "Opening Discord",
  "requires_third_party": {
    "app_name": "Discord",
    "executable": "C:\\Users\\%USERNAME%\\AppData\\Local\\Discord\\Discord.exe",
    "download_url": "https://discord.com/download",
    "install_instructions": "Download and install Discord from the official website.",
    "alternative_message": "Discord is not installed."
  }
}
```

## API Usage

### Command Execution
```python
import requests

# Execute a command
response = requests.post('http://localhost:5000/api/command', 
                        json={'command': 'open youtube'})
print(response.json())

# Handle conversation
response = requests.post('http://localhost:5000/api/command',
                        json={'command': 'how are you today?'})
print(response.json())
```

### JavaScript Integration
```javascript
// Execute command from web app
async function executeCommand(command) {
    const response = await fetch('http://localhost:5000/api/command', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({command: command})
    });
    return await response.json();
}

// Usage
executeCommand('open calculator').then(result => console.log(result));
```

### Response Format
```json
{
  "success": true,
  "message": "Opening YouTube",
  "action": "web_open", 
  "url": "https://www.youtube.com",
  "ai_message": "I've opened YouTube for you!",
  "processing_time": 0.123
}
```

## Requirements

- **Python**: 3.7 or higher
- **OS**: Windows, macOS, or Linux (some commands are OS-specific)
- **Internet**: Required for AI features and web commands
- **Optional**: Microphone for voice input (when integrated with speech recognition)

## Command Management Tools

### Command Manager (`command_manager.py`)
- Add new commands interactively
- List all current commands
- Save/reload command configurations
- User-friendly interface for command management

### Backup Manager (`backup_manager.py`)
- Create timestamped backups of your commands
- Restore from previous backups
- Export commands to readable text format
- List all available backups

## Examples

### Adding a New Web Command
```json
{
  "triggers": ["open stackoverflow", "stack overflow"],
  "action": "web_open",
  "url": "https://stackoverflow.com",
  "response": "Opening Stack Overflow"
}
```

### Adding a New Application Command
```json
{
  "triggers": ["open discord", "discord"],
  "action": "run_application",
  "command": ["C:\\Users\\YourName\\AppData\\Local\\Discord\\Discord.exe"],
  "response": "Opening Discord"
}
```

## Notes

- The app uses Google's speech recognition service, so an internet connection is required
- For volume control commands, you may need to install nircmd (optional)
- Speak clearly and wait for the app to process your command before giving the next one
- Say "help" to hear the available commands
- Press Ctrl+C to force quit the application

## Troubleshooting

- If you get audio-related errors, make sure your microphone is working and properly configured
- If speech recognition isn't working, check your internet connection
- The app adjusts for ambient noise when it starts, so wait for the ready message before speaking

## Security Note

This app can execute system commands like shutdown and restart. Use with caution and only run commands you understand.
