# 🤖 nlpcmd-ai

[![PyPI version](https://img.shields.io/pypi/v/nlpcmd-ai.svg)](https://pypi.org/project/nlpcmd-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/nlpcmd-ai.svg)](https://pypi.org/project/nlpcmd-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue.svg)](https://pypi.org/project/nlpcmd-ai/)

A **truly NLP-powered** command-line assistant for **Windows, Linux, and macOS** that understands natural language and executes system commands intelligently.

Unlike traditional CLI tools with pattern matching, nlpcmd-ai uses **AI/LLM** to understand complex, ambiguous commands and translate them into executable system operations - **automatically adapting commands to your operating system**.

## ✨ Features

- 🧠 **True Natural Language Understanding** - Uses AI models (OpenAI, Claude, or local Ollama)
- 🔒 **Safe Execution** - Confirms dangerous operations before execution
- 📝 **Context Awareness** - Remembers conversation history for follow-up commands
- 🎯 **Intent Detection** - Automatically determines what you want to do
- 🔧 **Extensible** - Easy to add custom command handlers
- 🌐 **Cross-platform** - Works on Windows, Linux, and macOS
- 💬 **Interactive Mode** - Chat-like interface for complex workflows

## 🚀 Installation

### Quick Install (All Platforms)

```bash
pip install nlpcmd-ai
```

### Platform-Specific Installation

#### Windows

**Option 1: Using pip (Recommended)**
```cmd
pip install nlpcmd-ai
```

**Option 2: Using installation script**
```cmd
# Download and run install.bat
curl -O https://raw.githubusercontent.com/yourusername/nlpcmd-ai/main/install.bat
install.bat
```

If `nlpai` command is not found, add Python Scripts to PATH or use:
```cmd
python -m nlpcmd_ai.cli "your command here"
```

#### Linux

**Option 1: Using pip (Recommended)**
```bash
pip3 install nlpcmd-ai
```

**Option 2: Using installation script**
```bash
curl -O https://raw.githubusercontent.com/yourusername/nlpcmd-ai/main/install.sh
bash install.sh
```

If `nlpai` not found, add to PATH:
```bash
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```

#### macOS

**Option 1: Using pip (Recommended)**
```bash
pip3 install nlpcmd-ai
```

**Option 2: Using installation script**
```bash
curl -O https://raw.githubusercontent.com/yourusername/nlpcmd-ai/main/install.sh
bash install.sh
```

### Advanced Installation

#### With Local LLM Support (Ollama)

```bash
pip install nlpcmd-ai[local]
```

#### From Source (Developers)

```bash
git clone https://github.com/yourusername/nlpcmd-ai.git
cd nlpcmd-ai
pip install -e .
```

#### All Optional Dependencies

```bash
pip install nlpcmd-ai[all]
```

## ⚙️ Configuration

Create a `.env` file or set environment variables:

```bash
# Choose your AI provider (openai, anthropic, or ollama)
NLP_PROVIDER=openai

# API Keys (if using cloud providers)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Ollama settings (if using local)
OLLAMA_MODEL=llama3.2
OLLAMA_HOST=http://localhost:11434

# Safety settings
REQUIRE_CONFIRMATION=true
DRY_RUN_MODE=false
LOG_COMMANDS=true
```

## 📖 Usage Examples

### One-off Commands

```bash
# Simple commands
nlpai "what is my ip address"
nlpai "show me disk usage"
nlpai "find all python files in this directory"

# Complex operations
nlpai "find all python files larger than 1MB modified in the last week"
nlpai "compress all log files from last month and move them to archive folder"
nlpai "show me the top 5 processes using most CPU"

# Development tasks
nlpai "create a git branch called feature/user-auth"
nlpai "install the requests library and add it to requirements.txt"
nlpai "run my tests and show me only the failures"

# File operations
nlpai "rename all .jpeg files to .jpg in the current folder"
nlpai "create a backup of all my python files"
nlpai "delete all cache folders recursively"

# Network operations
nlpai "check if port 8080 is open"
nlpai "download the file from this url and save it as data.json"
nlpai "what's the response time for google.com"
```

### Interactive Mode

```bash
nlpai

> show me the current directory
📁 Current directory: /home/user/projects

> list all python files
📄 Found 15 Python files:
  - main.py
  - utils.py
  ...

> show me the size of the largest one
📊 main.py: 15.3 KB

> open it in vim
✅ Opening main.py in vim...

> exit
👋 Goodbye!
```

### Conversation History

The AI remembers context within a session:

```bash
nlpai "create a folder called my_project"
nlpai "go into it"  # Remembers "my_project" from previous command
nlpai "create a python file named main.py"
nlpai "add a hello world function to it"  # Knows which file you're referring to
```

## 🎯 Supported Command Categories

### System Operations
- File and directory management
- Process management
- System information
- User management
- Environment variables

### Network Operations
- IP address information
- Port scanning
- Network connectivity tests
- DNS lookups
- HTTP requests

### Development Tools
- Git operations
- Package management (pip, npm, etc.)
- Docker commands
- Code formatting/linting
- Test execution

### Data Processing
- CSV/JSON manipulation
- Text file operations
- Data transformation
- Batch file operations

### Custom Extensions
- Plugin system for custom handlers
- Easy to add domain-specific commands

## 🔒 Safety Features

### Confirmation Prompts
Dangerous operations require confirmation:

```bash
nlpai "delete all files in /tmp"

⚠️  WARNING: This will delete files
Command: rm -rf /tmp/*
Execute? [y/N]:
```

### Dry Run Mode
Test commands without executing:

```bash
nlpai --dry-run "remove all .pyc files"

🔍 DRY RUN MODE
Would execute: find . -name "*.pyc" -delete
Affected files: 23 files
```

### Command Logging
All executed commands are logged:

```bash
cat ~/.nlpcmd_ai/history.log

2025-01-15 10:23:45 | User: "show my ip" | Executed: ip addr show
2025-01-15 10:24:12 | User: "delete old logs" | Executed: rm logs/*.log.old
```

## 🛠️ Advanced Usage

### Custom Handlers

Add your own command handlers:

```python
# ~/.nlpcmd_ai/handlers/custom.py

from nlpcmd_ai.handlers.base import BaseHandler

class MyCustomHandler(BaseHandler):
    def can_handle(self, intent: str, params: dict) -> bool:
        return intent == "deploy_app"
    
    def execute(self, params: dict) -> str:
        # Your custom deployment logic
        return "Deployment successful!"
```

### Configuration File

Advanced settings in `~/.nlpcmd_ai/config.yaml`:

```yaml
ai:
  provider: openai
  model: gpt-4-turbo-preview
  temperature: 0.3
  
safety:
  require_confirmation: true
  dangerous_patterns:
    - "rm -rf"
    - "dd if="
    - "mkfs"
  allowed_directories:
    - "/home/user"
    - "/tmp"
    
logging:
  level: INFO
  file: ~/.nlpcmd_ai/nlpcmd.log
  
handlers:
  custom_path: ~/.nlpcmd_ai/handlers
```

## 🔄 How It Works

1. **Natural Language Input** → User types command in plain English
2. **AI Processing** → LLM analyzes intent and extracts parameters
3. **Intent Classification** → Determines command category
4. **Handler Selection** → Routes to appropriate handler
5. **Command Generation** → Creates safe, executable command
6. **Safety Check** → Validates and optionally asks for confirmation
7. **Execution** → Runs command and captures output
8. **Response** → Formats and displays result to user

## 📊 Comparison with Traditional CLI Tools

| Feature | Traditional CLI | nlpcmd-ai |
|---------|----------------|-----------|
| Input Style | Exact syntax required | Natural language |
| Learning Curve | Steep | Minimal |
| Flexibility | Limited to defined patterns | Understands variations |
| Context Awareness | None | Full conversation history |
| Error Handling | Cryptic errors | Helpful explanations |
| Discovery | Man pages/help flags | Just ask what you want |

## 🤝 Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details

## 🙏 Acknowledgments

- Built on top of powerful LLM APIs
- Inspired by natural human-computer interaction
- Community-driven command handlers

## 🔗 Links

- **Documentation**: https://nlpcmd-ai.readthedocs.io
- **PyPI**: https://pypi.org/project/nlpcmd-ai
- **GitHub**: https://github.com/yourusername/nlpcmd-ai
- **Issues**: https://github.com/yourusername/nlpcmd-ai/issues

---

**Note**: This tool executes system commands based on AI interpretation. Always review commands before execution and use safety features appropriately.
