Metadata-Version: 2.2
Name: naturalshell-mac
Version: 1.0.2
Summary: Natural language to shell command converter with bilingual support
Author-email: Brian Chan <brianchan020516@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/brianchanyan/naturalshell
Project-URL: Documentation, https://github.com/brianchanyan/naturalshell#readme
Project-URL: Repository, https://github.com/brianchanyan/naturalshell.git
Project-URL: Bug Tracker, https://github.com/brianchanyan/naturalshell/issues
Keywords: shell,cli,natural-language,ai,macos,terminal,chinese
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
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
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Classifier: Natural Language :: Chinese (Traditional)
Classifier: Natural Language :: English
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mlx>=0.2.0
Requires-Dist: mlx-lm>=0.0.11

# NaturalShell (NS)

**Natural Language to Shell Command Converter with Bilingual Support**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)

> **Note: This is currently a BETA version.** 

NaturalShell (NS) is a CLI tool that can convert natural language descriptions into shell commands. Optimized for macOS terminal usage with bilingual support (English and Traditional Chinese).

---

## Key Features

- **Bilingual Support**: Full support for both Traditional Chinese and English commands
- **High Accuracy**: 93.8% accuracy on 500 test cases
- **Smart Filtering**: Rule-based pre-filtering layer to reject irrelevant requests
- **macOS Optimized**: Specifically designed for macOS terminal usage
- **Safety First**: Two-stage verification mechanism ensures command safety
- **Runs Locally**: Powered by Apple MLX framework, runs completely offline after initial setup
- **Lightweight Model**: Based on Qwen2.5-3B-Instruct with LoRA fine-tuning

---

## Installation

### Requirements
- **Operating System**: macOS (Apple Silicon or Intel)
- **Python**: 3.9 or higher
- **RAM**: 8GB+ recommended

### Install via pip

```bash
pip install naturalshell-mac
```

After installation, the `ns` command will be available.

### Shell Integration

**Important:** Shell Integration is required for commands like `cd` and `export` to properly affect your current shell session.

To integrate NS into your shell:

```bash
# Display integration commands
ns --init

# Add to your shell configuration
# For Zsh (default macOS shell):
ns --init >> ~/.zshrc
source ~/.zshrc

# For Bash:
ns --init >> ~/.bashrc
source ~/.bashrc
```

---

## Quick Start

### Basic Usage

Simply type natural language commands in your terminal:

```bash
# English examples
ns list all files in current directory
# Output: ls -la

ns find all Python files
# Output: find . -name "*.py"

ns show disk usage
# Output: df -h

# Additional examples
ns list all files in the current folder
# Output: ls -la

ns go to Desktop folder
# Output: cd ~/Desktop

ns search for all Python files
# Output: find . -name "*.py"

ns copy this file to Downloads folder
# Output: cp <file> ~/Downloads/

ns delete temporary files
# Output: rm -rf /tmp/*
```

---

## Examples

### File Operations

```bash
ns create a new folder called "project"
# mkdir project

ns copy all jpg files to Desktop
# cp *.jpg ~/Desktop/

ns find files modified in last 24 hours
# find . -mtime -1
```

### Git Operations

```bash
ns show git status
# git status

ns commit with message "fix bug"
# git commit -m "fix bug"
```

### System Information

```bash
ns show CPU usage
# top -l 1 | grep "CPU usage"

ns check available disk space
# df -h
```

### Package Management

```bash
ns install python using brew
# brew install python

ns update all brew packages
# brew upgrade
```

---

## Technical Architecture

### Two-Stage Pipeline

1. **Stage 1: Rule-based Filter**
   - Quickly validates if requests are shell-command related
   - Includes shell keywords, Chinese keywords, and path pattern detection
   - Rejects irrelevant requests (e.g., weather queries, poetry composition)

2. **Stage 2: AI Model Inference**
   - Uses Qwen2.5-3B-Instruct base model
   - LoRA fine-tuned adapters (optimized for macOS shell commands)
   - Apple MLX framework for accelerated inference

### Model Specifications

- **Base Model**: Qwen/Qwen2.5-3B-Instruct
- **Fine-tuning Method**: LoRA (Low-Rank Adaptation)
- **Framework**: Apple MLX
- **Training Data**: Specialized macOS shell command dataset
- **Accuracy**: 93.8% (500 test cases)

---

## Supported Command Types

- File & Directory Operations: `ls`, `cd`, `mkdir`, `rm`, `cp`, `mv`, `find`, `grep`
- Version Control: `git` related commands
- Package Management: `brew`, `pip`, `npm`, `yarn`
- System Info: `top`, `ps`, `df`, `du`
- macOS Specific: `open`, `pbcopy`, `pbpaste`, `defaults`
- Network Tools: `curl`, `wget`, `ssh`, `ping`
- Compression: `tar`, `zip`, `unzip`, `gzip`
- Text Processing: `cat`, `head`, `tail`, `awk`, `sed`

---

## Safety Mechanisms

1. **Rule Filter**: Rejects non-shell related requests
2. **Command Validation**: AI model trained to emphasize safe command generation
3. **No Auto-execution**: Commands are only displayed by default, requiring manual execution or confirmation
4. **Scope Limitation**: Only processes macOS shell command related requests

---

## Development & Contributing

### Local Development

```bash
# Clone repository
git clone https://github.com/brianchanyan/naturalshell.git
cd naturalshell

# Install in development mode
pip install -e .

# Run tests
python -m pytest tests/
```

### Testing

```bash
# Test the rule-based filter
python naturalshell/shell_filter.py

# Test the full pipeline
ns "your test query"
```

---

## Troubleshooting

### Model Download Issues

On first run, NS will automatically download the Qwen2.5-3B-Instruct model (approximately 6GB). If download fails:

```bash
# Manually download model
python3 -c "from mlx_lm import load; load('Qwen/Qwen2.5-3B-Instruct')"
```

### Out of Memory

If you encounter memory issues, try closing other applications or restarting your terminal.

---

## Known Limitations

- macOS only (depends on MLX framework)
- Requires sufficient memory (8GB+ recommended)
- First run requires downloading approximately 6GB model
- Does not support complex multi-line script generation

---

## Changelog

### v1.0.2 (2026-02-22)
- Added `ns --uninstall` command to cleanly remove shell integration
- Added uninstall guide to tutorial page

### v1.0.1 (2026-02-22)
- Fix: Shell integration now uses `python3` to invoke script (no execute permission needed)
- Improved pip install experience for all users

### v1.0.0 (2026-02-21)
- Initial release
- 93.8% accuracy
- Bilingual support (English and Traditional Chinese)
- Two-stage processing architecture
- Complete macOS shell command support

---

## License

MIT License - See [LICENSE](LICENSE) file for details

---

## Author

**Brian** - [GitHub](https://github.com/brianchanyan)

---

## Acknowledgments

- **Qwen Team** - For providing excellent base model
- **Apple MLX** - For efficient machine learning framework
- **Community Contributors** - Thanks for all testing and feedback

---

## Links

- [PyPI Package](https://pypi.org/project/naturalshell/)
- [GitHub Repository](https://github.com/brianchanyan/naturalshell)
- [Issue Tracker](https://github.com/brianchanyan/naturalshell/issues)
- [Documentation](https://github.com/brianchanyan/naturalshell#readme)

