Metadata-Version: 2.4
Name: unishell-q
Version: 0.5.5
Summary: Let language models run code with intelligent action system
Home-page: https://github.com/QuantamAIDevelopment/unishell.git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9,<3.13
Description-Content-Type: text/markdown
Requires-Dist: setuptools
Requires-Dist: astor>=0.8.1
Requires-Dist: git-python>=1.0.3
Requires-Dist: inquirer>=3.1.3
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.4.2
Requires-Dist: six>=1.6.0
Requires-Dist: tokentrim>=0.1.13
Requires-Dist: wget>=3.2
Requires-Dist: psutil>=5.9.6
Requires-Dist: pyreadline3>=3.4.1; sys_platform == "win32"
Requires-Dist: html2image>=2.0.4.3
Requires-Dist: send2trash>=1.8.2
Requires-Dist: ipykernel>=6.26.0
Requires-Dist: jupyter-client>=8.6.0
Requires-Dist: matplotlib>=3.8.2
Requires-Dist: pandas>=2.0.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: plotly>=5.18.0
Requires-Dist: toml>=0.10.2
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: pydantic>=2.6.4
Requires-Dist: google-generativeai>=0.7.1
Requires-Dist: pyperclip>=1.9.0
Requires-Dist: yaspin>=3.0.2
Requires-Dist: shortuuid>=1.0.13
Requires-Dist: litellm>=1.41.26
Requires-Dist: starlette>=0.37.2
Requires-Dist: html2text>=2024.2.26
Requires-Dist: selenium>=4.24.0
Requires-Dist: webdriver-manager>=4.0.2
Requires-Dist: anthropic>=0.37.1
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: typer>=0.12.5
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn>=0.30.1
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pynput
Requires-Dist: requests>=2.31.0
Requires-Dist: pywin32>=306; sys_platform == "win32"
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# UniShell

AI-powered natural language command execution with cloud gateway integration.

## Features

- **Natural Language Commands**: Execute system operations using plain English
- **Gateway Integration**: Remote command execution through cloud gateway
- **Desktop Agent Mode**: Run as background agent for remote management
- **Action Registry**: 90+ pre-built actions for system, file, app, and network operations (including Excel, WiFi, and Docker)
- **Multi-LLM Support**: Works with OpenAI, Azure OpenAI, Anthropic (including Computer Use), and local models
- **Safe Execution**: Multi-layered safety with Policy Engine (RBAC), Path Validation, and Rollback capabilities
- **Terminal Magic**: Rich interactive interface with built-in commands for session management and exports
- **DevOps Ready**: Specialized agents for Kubernetes (AKS) and Docker management

## Installation

```bash
pip install unishell-q
```

## Quick Start

### Local Interactive Mode

```bash
# Basic usage
unishell

# With Azure OpenAI
unishell --model azure/gpt-4o --api_key YOUR_KEY --api_base YOUR_ENDPOINT --api_version 2024-08-01-preview

# With OpenAI
export OPENAI_API_KEY=your-key
unishell --model gpt-4o

# Auto-run mode (skip approval)
unishell -y
```

### Desktop Agent Mode (Gateway Integration)

Run UniShell as a background agent that executes commands from a cloud gateway:

```bash
# Start agent with gateway connection
unishell --model azure/gpt-4o --api_key YOUR_KEY --api_base YOUR_ENDPOINT --api_version 2024-08-01-preview --agent

# Configure gateway on first run
Gateway URL: http://192.168.100.227:8000
Device Token: <your-device-token>

# Agent runs in background, CLI accepts commands
> open notepad.exe
> create folder test in C:\Users\Desktop
```

**How Agent Mode Works:**
1. Agent polls gateway for pending commands
2. Executes commands locally on your desktop
3. Reports results back to gateway
4. Cloud UI shows execution status

### Gateway Configuration

Agent credentials are stored in `~/.unishell/gateway_config.json`:

```json
{
  "gateway_enabled": true,
  "gateway_url": "http://192.168.100.227:8000",
  "device_token": "your-device-token"
}
```

To reconfigure, delete the file and restart with `--agent` flag.

## Usage Examples

### System Operations
```bash
> lock my screen
> shutdown system in 60 seconds
> get system info
> check CPU and RAM usage
```

### File Operations
```bash
> create a file named test.txt in desktop
> copy file.txt to backup folder
> delete old_file.txt
> rename document.txt to report.txt
```

### Application Management
```bash
> open notepad.exe
> install chrome
> force close firefox
> list installed apps
```

### Network Operations
```bash
> ping google.com
> flush DNS cache
> check my IP address
> disconnect wifi
```

## Python API

```python
from unishell import unishell

# Configure LLM
unishell.llm.model = "gpt-4o"
unishell.llm.api_key = "your-key"

# Execute commands
unishell.chat("Create a Python script")

# Use gateway orchestrator
from unishell.core.gateway import ExecutionOrchestrator
from unishell.core.intent import LLMIntentClassifier, LLMParameterExtractor
from unishell.core.action_registry import DynamicActionLoader

loader = DynamicActionLoader()
registry = loader.load_all()

classifier = LLMIntentClassifier(llm_client, model_name="gpt-4o")
extractor = LLMParameterExtractor(llm_client, model_name="gpt-4o")

orchestrator = ExecutionOrchestrator(classifier, extractor, registry)
result = orchestrator.execute("open notepad", dry_run=False)
```

## Architecture

### Local Mode
```
User Input → Intent Classifier → Parameter Extractor → Policy Engine → Executor → Result
```

### Gateway Mode
```
Cloud UI → Gateway (Redis) → Desktop Agent → Local Executor → Gateway → Cloud UI
         ↓                      ↑
    Stores Action          Polls & Reports
```

## Command Line Options

```bash
# Model Configuration
--model, -m          Language model to use
--api_key, -ak       API key for LLM
--api_base, -ab      API base URL
--api_version, -av   API version
--temperature, -t    Model temperature

# Agent Mode
--agent, -ag         Start desktop agent mode
--gateway_url, -gu   Gateway URL for agent
--device_token, -dtoken  Device token for authentication

# Execution Options
--auto_run, -y       Automatically run generated code
--verbose, -v        Print detailed logs
--safe_mode          Enable safety mechanisms (off/ask/auto)

# Other Options
--profile, -p        Load configuration profile
--offline, -o        Disable online features
--version            Show version number
```

## Action Registry

UniShell includes 90+ pre-built actions across categories:

- **Application**: open, install, uninstall, update, force_close, list
- **File**: create, read, write, delete, copy, move, rename, search
- **Folder**: create, delete, list
- **System**: shutdown, restart, sleep, hibernate, lock, info, resources
- **Network**: ping, check_ip, flush_dns, wifi_connect, wifi_disconnect
- **Service**: start, stop, restart, enable, disable
- **Process**: kill, list
- **Monitoring**: cpu_threshold, ram_spike, disk_full, error_logs

Actions are defined in `unishell/core/action_registry/actions/`.

## Gateway Integration

### Desktop Registration

1. Access gateway UI: `http://your-gateway:8000`
2. Login with credentials
3. Register desktop to get device token
4. Use token with `--agent` flag

### Remote Command Execution

1. Submit command through gateway UI
2. Gateway queues action (PENDING)
3. Desktop agent polls and retrieves action
4. Agent executes locally (RUNNING)
5. Agent reports result (COMPLETED/FAILED)
6. UI displays result

### Agent Configuration

First run prompts for configuration:
```bash
🤖 Desktop Agent Configuration
==================================================
Gateway URL: http://192.168.100.227:8000
Device Token: <paste-your-token>
```

Or provide via command line:
```bash
unishell --agent --gateway_url http://gateway:8000 --device_token YOUR_TOKEN
```

## Security

- **Policy Engine**: Validates permissions before execution
- **Dry Run Mode**: Preview actions without executing
- **Path Validation**: Prevents directory traversal attacks
- **Safe Mode**: Optional code scanning and confirmation
- **Device Authentication**: Token-based gateway access

## Troubleshooting

### Agent Not Connecting
```bash
# Check gateway URL is accessible
curl http://192.168.100.227:8000/health

# Verify device token is valid
# Delete config and reconfigure
rm ~/.unishell/gateway_config.json
unishell --agent
```

### Command Execution Fails
```bash
# Run with verbose logging
unishell --agent --verbose

# Check action exists
# View available actions in unishell/core/action_registry/actions/
```

### Application Not Found
```bash
# Use full executable name
> open notepad.exe  # ✓ Correct
> open notepad      # ✗ May fail

# Check app is installed
> list installed apps
```

## Development

```bash
# Clone repository
git clone <repo-url>
cd unishell

# Install in development mode
pip install -e .

# Run tests
pytest tests/

# Add new action
# Create JSON definition in unishell/core/action_registry/actions/
# Implement handler in unishell/core/execution/safe_os_adapter.py
```

## Magic Commands

UniShell's terminal interface supports "Magic Commands" (prefixed with `%`) for advanced session management:

| Command | Description |
|---------|-------------|
| `%% [cmd]` | Run command directly in system shell |
| `%verbose` | Toggle verbose mode for detailed execution logs |
| `%reset` | Clear conversation history and reset session |
| `%undo` | Remove the last user message and its response |
| `%save_message [path]` | Export conversation to JSON file (defaults to `messages.json`) |
| `%load_message [path]` | Import conversation from JSON file |
| `%tokens [prompt]` | (Experimental) Calculate token usage and estimated cost |
| `%jupyter` | Export current conversation as a Jupyter Notebook (`.ipynb`) |
| `%markdown [path]` | Export conversation to a formatted Markdown file |
| `%info` | Display detailed system and UniShell environment information |

## Advanced Features

### Anthropic Computer Use Integration
UniShell integrates with Anthropic's **Computer Use API**, allowing models like `claude-3-5-sonnet` to:
- Take screenshots and analyze UI elements
- Perform precise mouse clicks and keyboard inputs
- Interact with desktop applications visually
- *Note: Requires `--model anthropic/...` and valid API key.*

### DevOps Agent (AKS & Docker)
The specialized `devops_agent` module provides deep integration for cloud-native workflows:
- **AKS Management**: Deploy applications, scale deployments, and manage services on Azure Kubernetes Service.
- **Docker Workflow**: Build, tag, and push images to registries (ACR/Docker Hub) directly from natural language.
- **Auto-healing**: Includes `autofix` actions for common configuration mismatches and deployment failures.

## Deep Architecture

### Policy Engine & Security
The `SimplePolicyEngine` implements a robust security layer:
- **RBAC (Role-Based Access Control)**: Supports `public`, `user`, `admin`, and `system` roles.
- **Environment Awareness**: In `production` mode, UniShell automatically:
    - Blocks `CRITICAL` risk actions (e.g., `disk.format`).
    - Prevents access to system paths (`C:\Windows`, `/etc`, etc.).
    - Forces confirmation for `HIGH` risk actions.
- **Path Validation**: Real-time checking of file paths to prevent traversal and unauthorized access.

### Snapshot & Rollback
For risky operations (like `file.move`), UniShell uses a `RollbackManager`:
1. **Pre-execution Snapshot**: Captures state (existence, path, type) before execution.
2. **Commit/Rollback**: If the operation fails or is cancelled, UniShell can restore the previous state.
3. **Audit Trail**: Every action is logged with its snapshot ID for accountability.

## Action Registry Categories

UniShell includes specialized actions beyond basic OS tasks:
- **Excel**: `excel.create`, `excel.update_cell`, `excel.save`
- **Networking**: `network.flush_dns`, `wifi.connect`, `firewall.open_port`
- **Monitoring**: `monitor.cpu_threshold`, `monitor.ram_spike`, `monitor.error_logs`
- **Environment**: `env.setup_python`, `env.setup_node`, `env.setup_virtualenv`

## Version

**Current Version**: 0.5.5

## License

MIT License

## Support

For issues and questions, please open an issue on GitHub.
