max-cli 0.2.0__tar.gz

max_cli-0.2.0/LICENSE

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

max_cli-0.2.0/PKG-INFO

@@ -0,0 +1,632 @@
+Metadata-Version: 2.4
+Name: max-cli
+Version: 0.2.0
+Summary: The Local, Fast, & Lazy Terminal Assistant for high-performance tasks.
+Author-email: Abubakr Alsheikh <abubakralsheikh@outlook.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: shellingham>=1.5.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pymupdf>=1.22.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: yt-dlp>=2023.0.0
+Requires-Dist: segno>=1.5.0
+Requires-Dist: pyperclip>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mkdocs>=1.5.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
+Dynamic: license-file
+
+# Max CLI ⚡
+
+[![PyPI Version](https://img.shields.io/pypi/v/max-cli.svg)](https://pypi.org/project/max-cli/)
+[![Python Version](https://img.shields.io/pypi/pyversions/max-cli.svg)](https://pypi.org/project/max-cli/)
+[![License](https://img.shields.io/pypi/l/max-cli.svg)](https://github.com/Abubakr-Alsheikh/max-cli/blob/main/LICENSE)
+[![Build Status](https://github.com/Abubakr-Alsheikh/max-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Abubakr-Alsheikh/max-cli/actions)
+[![Documentation](https://img.shields.io/badge/docs-MkDocs-blue)](https://Abubakr-Alsheikh.github.io/max-cli/)
+
+> **Your Lazy, Fast Terminal Assistant That Does the Work for You.**
+
+Max transforms complex tasks—like compressing videos, merging PDFs, or downloading from YouTube—into simple commands you can actually remember. Whether you're a casual user or a seasoned developer, Max speaks your language.
+
+---
+
+## 📚 Documentation
+
+**Full docs:** https://Abubakr-Alsheikh.github.io/max-cli/
+
+**Quick links:**
+- [Installation](https://Abubakr-Alsheikh.github.io/max-cli/installation/)
+- [Usage](https://Abubakr-Alsheikh.github.io/max-cli/usage/)
+- [Commands](https://Abubakr-Alsheikh.github.io/max-cli/commands/)
+- [API Reference](https://Abubakr-Alsheikh.github.io/max-cli/api/)
+- [Contributing](https://Abubakr-Alsheikh.github.io/max-cli/contributing/)
+
+---
+
+## 🤔 What Can Max Do?
+
+| Task | Max Command | Example |
+|------|-------------|---------|
+| **Compress videos** | `max video compress` | `max video compress movie.mp4` |
+| **Convert video to audio** | `max video to-audio` | `max video to-audio podcast.mp4` |
+| **Download videos/music** | `max grab` | `max grab "youtube.com/..."` |
+| **Merge PDFs** | `max pdf bundle` | `max pdf bundle contracts/` |
+| **Compress images** | `max img compress` | `max img compress photos/` |
+| **Resize images** | `max img resize` | `max img resize logo.png --width 800` |
+| **Ask AI anything** | `max ai ask` | `max ai ask "Merge and Compress those pdf files"` |
+| **Generate images** | `max ai create` | `max ai create "A cat on a bike"` |
+| **Organize files** | `max files smart-sort` | `max files smart-sort downloads/` |
+
+---
+
+## 🚀 Quick Start (5 Minutes)
+
+### Step 1: Install Python
+
+Max runs on Python. If you don't have it:
+
+- **Windows:** Download from [python.org](https://python.org) (check "Add to PATH")
+- **Mac:** Open Terminal and run: `brew install python`
+- **Linux:** `sudo apt install python3`
+
+### Step 2: Install FFmpeg (For Video/Audio)
+
+Max needs FFmpeg to process videos. Don't worry, it's easy:
+
+```bash
+# Mac
+brew install ffmpeg
+
+# Windows (run in PowerShell or Command Prompt)
+winget install Gyan.FFmpeg
+
+# Linux
+sudo apt install ffmpeg
+```
+
+### Step 3: Install Max
+
+```bash
+# Clone and install
+git clone https://github.com/Abubakr-Alsheikh/max-cli.git
+cd max-cli
+pip install -e .
+```
+
+### Step 4: Configure AI (Optional but Recommended)
+
+Max's AI features need an API key. The easiest setup:
+
+```bash
+max config setup
+```
+
+This wizard will guide you through:
+
+- Choosing your AI provider (Google Gemini, OpenAI, or custom)
+- Entering your API key
+- Setting preferences
+
+**Get a free API key:**
+
+- [Google AI Studio](https://aistudio.google.com/app/apikey) - Free tier available
+- [OpenAI](https://platform.openai.com/api-keys) - Pay-as-you-go
+
+### Step 5: Start Using Max
+
+```bash
+# See all available commands
+max --help
+
+# Download a video
+max grab "https://youtube.com/watch?v=..."
+
+# Compress a video
+max video compress mymovie.mp4
+
+# Compress images in a folder
+max img compress ./photos
+```
+
+---
+
+## 📖 User Guide
+
+### 🎥 Video & Audio
+
+#### Compress Video (Shrink File Size)
+
+```bash
+# Simple compression
+max video compress video.mp4
+
+# High quality compression
+max video compress video.mp4 --preset high
+
+# Specific quality (1-100)
+max video compress video.mp4 -q 75
+```
+
+#### Convert Video to Audio
+
+```bash
+# To MP3 (default, high quality)
+max video to-audio lecture.mp4
+
+# To WAV (lossless, for editing)
+max video to-audio lecture.mp4 --format wav
+
+# To MP3 320kbps
+max video to-audio lecture.mp4 -q x
+```
+
+#### Trim/Cut Video
+
+```bash
+# Cut from 0:30 to 1:00
+max video cut movie.mp4 --start 0:30 --end 1:00
+
+# First 30 seconds only
+max video cut movie.mp4 --duration 30
+```
+
+#### Other Video Commands
+
+```bash
+max video gif clip.mp4              # Convert to GIF
+max video louder audio.mp4 --db 10  # Boost volume by 10dB
+max video snap video.mp4 --time 1:30 # Take screenshot at 1:30
+max video mute video.mp4             # Remove audio track
+```
+
+---
+
+### 📄 PDF Documents
+
+#### Merge PDFs
+
+```bash
+# Merge all PDFs in a folder
+max pdf bundle mydocs/
+
+# Merge specific files
+max pdf bundle file1.pdf file2.pdf
+```
+
+#### Split PDF
+
+```bash
+# Extract pages 1-5 and page 8
+max pdf split document.pdf -p 1-5,8
+```
+
+#### Compress PDF
+
+```bash
+max pdf compress large.pdf
+```
+
+#### Add Watermark
+
+```bash
+max pdf stamp document.pdf "CONFIDENTIAL"
+```
+
+#### Password Protect
+
+```bash
+max pdf lock document.pdf
+```
+
+---
+
+### 📥 Downloading (YouTube, Spotify, etc.)
+
+Download from almost any website:
+
+```bash
+# Download video (best quality)
+max grab "https://youtube.com/watch?v=..."
+
+# Download audio only (MP3)
+max grab "https://youtube.com/watch?v=..." -a
+
+# Choose quality: s=480p, m=720p, h=1080p, x=4K
+max grab "..." -q h
+
+# Download a playlist
+max grab "https://youtube.com/playlist?list=..."
+
+# Download specific video from playlist
+max grab "..." -i 3
+```
+
+#### Quality Presets Explained
+
+| Flag | Video Quality | Audio Quality | Best For |
+|------|---------------|---------------|----------|
+| `-q s` | 480p | 64kbps | Saving data |
+| `-q m` | 720p | 128kbps | Phone viewing |
+| `-q h` | 1080p | 192kbps | Desktop viewing |
+| `-q x` | 4K | 320kbps | Best quality |
+
+#### Save Your Download Preferences
+
+```bash
+# Set your defaults once
+max config grab
+
+# Now just run:
+max grab "url"  # Uses your saved preferences
+```
+
+---
+
+### 🖼 Images
+
+#### Compress Images
+
+```bash
+# Compress all images in folder (75% quality)
+max img compress ./photos
+
+# Compress single image
+max img compress photo.jpg
+
+# Force JPEG output
+max img compress ./photos --jpeg
+
+# Limit max dimension to 1080px
+max img compress ./photos --max 1080
+```
+
+#### Resize Images
+
+```bash
+# Resize to specific width
+max img resize image.png --width 800
+
+# Resize to specific height
+max img resize image.png --height 600
+
+# Scale down by percentage
+max img resize image.png --scale 50
+```
+
+#### Convert Format
+
+```bash
+# Convert to WebP (modern, smaller)
+max img convert photo.jpg --to webp
+
+# Convert to PNG
+max img convert photo.png --to png
+```
+
+#### Remove Metadata (Privacy)
+
+```bash
+# Strip EXIF data (GPS, camera info, etc)
+max img strip ./photos
+```
+
+---
+
+### 🤖 AI Assistant
+
+Max has a smart AI that understands what you want.
+
+#### Ask Anything
+
+```bash
+# Get help with a task
+max ai ask "How do I compress this video?"
+
+# In a folder with a file, just describe what you want
+max ai ask "Make this image smaller"
+# Max figures out which file you mean!
+```
+
+#### Analyze Images
+
+```bash
+# Analyze a screenshot
+max ai analyze screenshot.png -p "What error is shown?"
+
+# Extract data from receipt
+max ai analyze receipt.jpg -p "What is the total amount?"
+```
+
+#### Generate Images
+
+```bash
+# Create from text description
+max ai create "A cute cat sitting on a beach" -o cat.png
+
+# Edit existing image
+max ai edit photo.jpg "Add a sunset background" -o new_photo.jpg
+```
+
+#### Chat Mode
+
+```bash
+# Start an interactive conversation
+max ai chat
+```
+
+---
+
+### 📂 File Management
+
+#### Smart Sort (AI Organizer)
+
+```bash
+# Automatically organize files into categories
+max files smart-sort ./downloads
+
+# Max reads filenames and sorts them into folders like:
+# Invoices/, Images/, Documents/, etc.
+```
+
+#### Rename Sequentially
+
+```bash
+# Rename to 1_file, 2_file, etc.
+max files order ./photos
+```
+
+---
+
+### 🔧 System Tools
+
+```bash
+# Generate QR code from URL
+max share "https://example.com"
+
+# Copy file contents to clipboard
+max copy file.txt
+
+# Save clipboard image to file
+max paste screenshot.png
+```
+
+---
+
+## ⚙️ Configuration
+
+### Setting Up Your API Key
+
+The easiest way:
+
+```bash
+max config setup
+```
+
+### Manual Configuration
+
+Create a `.env` file in your project folder:
+
+```ini
+# For Google Gemini (recommended - has free tier)
+OPENAI_API_KEY=your_api_key_here
+OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
+AI_MODEL=gemini-1.5-flash
+AI_IMAGE_MODEL=gemini-2.0-flash-exp
+
+# For OpenAI
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://api.openai.com/v1
+AI_MODEL=gpt-4o-mini
+
+# Default settings
+DEFAULT_QUALITY=80
+GRAB_QUALITY=h
+GRAB_AUDIO_FORMAT=mp3
+```
+
+### Configuration Locations
+
+- **Global:** `~/.max_config.env` - Applied everywhere
+- **Local:** `.env` - Applied to current folder
+
+Local settings override global settings.
+
+### Other Config Commands
+
+```bash
+max config show     # View current configuration
+max config grab     # Configure downloader defaults
+max config save     # Save local settings as global defaults
+```
+
+---
+
+## 💡 Tips & Tricks
+
+### Working with Folders
+
+Most commands work on folders too:
+
+```bash
+# Compress ALL images in a folder
+max img compress ./videos
+
+# Merge ALL PDFs in a folder
+max pdf bundle ./documents
+```
+
+### Default Directory
+
+If you don't specify a path, Max uses the current folder:
+
+```bash
+cd ./myphotos
+max img compress   # Compresses everything in myphotos
+```
+
+### Chain Commands
+
+You can run multiple commands:
+
+```bash
+# Merge PDFs then compress
+max pdf bundle ./docs && max pdf compress merged.pdf
+```
+
+### Get Help
+
+```bash
+# See all commands
+max --help
+
+# See help for specific command
+max video --help
+max img --help
+max pdf --help
+```
+
+---
+
+## 🆘 Troubleshooting
+
+### "FFmpeg not found"
+
+Install FFmpeg (see Step 2 above) and restart your terminal.
+
+### "API key not found"
+
+Run `max config setup` to configure your AI provider.
+
+### "Permission denied" (Windows)
+
+Run Command Prompt as Administrator, or use a virtual environment.
+
+### Something else not working?
+
+- Check: `max --version`
+- Get help: `max --help`
+- Report issues: [GitHub Issues](https://github.com/Abubakr-Alsheikh/max-cli/issues)
+
+---
+
+## 🔧 For Developers
+
+### Installation (Development Mode)
+
+```bash
+# Clone
+git clone https://github.com/Abubakr-Alsheikh/max-cli.git
+cd max-cli
+
+# Install with dev dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest tests/
+
+# Lint code
+ruff check .
+ruff format .
+
+# Type check
+mypy src/
+```
+
+### Documentation
+
+Full documentation is available at: https://Abubakr-Alsheikh.github.io/max-cli/
+
+Local documentation development:
+
+```bash
+# Install mkdocs
+pip install mkdocs mkdocs-material
+
+# Serve locally
+mkdocs serve
+
+# Build for production
+mkdocs build
+```
+
+### Plugin System
+
+Max CLI supports plugins for extensibility. Plugins are stored in:
+- `~/.max_cli/plugins/` (user-level)
+- `./plugins/` (project-level)
+
+Example plugin structure:
+
+```python
+from max_cli.plugins.base import CLIPlugin
+import typer
+
+class MyPlugin(CLIPlugin):
+    @property
+    def name(self) -> str:
+        return "my-plugin"
+    
+    @property
+    def version(self) -> str:
+        return "1.0.0"
+    
+    @property
+    def description(self) -> str:
+        return "My custom plugin"
+    
+    def register(self, app: typer.Typer) -> None:
+        @app.command("my-command")
+        def my_command():
+            typer.echo("Hello from my plugin!")
+```
+
+### Architecture
+
+```
+src/max_cli/
+├── core/           # Business logic (engines)
+├── interface/      # CLI commands (Typer)
+├── common/         # Shared utilities
+└── __init__.py    # Package exports
+```
+
+---
+
+## 🤝 Contributing
+
+Found a bug or have a feature request?
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+1. Open an issue: [GitHub Issues](https://github.com/Abubakr-Alsheikh/max-cli/issues)
+2. Fork the repo
+3. Submit a PR
+
+---
+
+## 📄 License
+
+MIT License - Free to use, modify, and distribute.
+
+---
+
+## 🙏 Thank You
+
+Max was built to make your life easier. If you find it useful, star the repo and share it with others!
+
+Questions? Reach out or open an issue.
+
+<div style="text-align: center;">
+Build with 💗 to make life easier
+</div>