naturalshell-mac 1.0.0__tar.gz

naturalshell_mac-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian
+
+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.

naturalshell_mac-1.0.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include naturalshell *.py
+recursive-include naturalshell/adapters *.safetensors *.json
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

naturalshell_mac-1.0.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.2
+Name: naturalshell-mac
+Version: 1.0.0
+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
+```
+
+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.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)
+

naturalshell_mac-1.0.0/README.md

@@ -0,0 +1,284 @@
+# 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
+```
+
+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.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)
+

naturalshell_mac-1.0.0/naturalshell/__init__.py

@@ -0,0 +1,32 @@
+"""
+NaturalShell - Natural Language to Shell Command Converter
+
+A powerful CLI tool that converts natural language descriptions into shell commands
+using AI, specifically optimized for macOS terminal usage.
+
+Features:
+- Natural language to shell command conversion
+- Bilingual support (English and Traditional Chinese)
+- Rule-based safety filters
+- Optimized for macOS
+- 93.8% accuracy on 500 test cases
+
+Example:
+    $ ns list all files in current directory
+    -> ls -la
+
+    $ ns 進入桌面資料夾
+    -> cd ~/Desktop
+
+For more information, visit: https://github.com/brianchanyan/naturalshell
+"""
+
+__version__ = "1.0.0"
+__author__ = "Brian Chan"
+__license__ = "MIT"
+
+from pathlib import Path
+
+PACKAGE_DIR = Path(__file__).parent
+
+__all__ = ["__version__", "__author__", "__license__", "PACKAGE_DIR"]

naturalshell_mac-1.0.0/naturalshell/adapters/adapter_config.json

@@ -0,0 +1,40 @@
+{
+    "adapter_path": "/Users/brian/Desktop/NaturalShell/adapters",
+    "batch_size": 4,
+    "config": null,
+    "data": "/Users/brian/Desktop/NaturalShell/training_data/mlx_data",
+    "fine_tune_type": "lora",
+    "grad_accumulation_steps": 1,
+    "grad_checkpoint": false,
+    "iters": 100,
+    "learning_rate": 1e-06,
+    "lora_parameters": {
+        "rank": 8,
+        "dropout": 0.0,
+        "scale": 20.0
+    },
+    "lr_schedule": null,
+    "mask_prompt": false,
+    "max_seq_length": 2048,
+    "model": "Qwen/Qwen2.5-3B-Instruct",
+    "num_layers": 16,
+    "optimizer": "adam",
+    "optimizer_config": {
+        "adam": {},
+        "adamw": {},
+        "muon": {},
+        "sgd": {},
+        "adafactor": {}
+    },
+    "project_name": null,
+    "report_to": null,
+    "resume_adapter_file": "/Users/brian/Desktop/NaturalShell/adapters/r9_iter50_adapters.safetensors",
+    "save_every": 25,
+    "seed": 0,
+    "steps_per_eval": 25,
+    "steps_per_report": 25,
+    "test": false,
+    "test_batches": 500,
+    "train": true,
+    "val_batches": 25
+}