max-cli 0.2.0__tar.gz → 0.3.3__tar.gz

{max_cli-0.2.0/src/max_cli.egg-info → max_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: max-cli
-Version: 0.2.0
+Version: 0.3.3
 Summary: The Local, Fast, & Lazy Terminal Assistant for high-performance tasks.
 Author-email: Abubakr Alsheikh <abubakralsheikh@outlook.com>
 Requires-Python: >=3.9
@@ -17,6 +17,7 @@ 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
+Requires-Dist: mutagen>=1.47.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -60,7 +61,13 @@ Max transforms complex tasks—like compressing videos, merging PDFs, or downloa
 |------|-------------|---------|
 | **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/..."` |
+| **Get audio metadata** | `max audio get` | `max audio get song.mp3` |
+| **Set audio metadata** | `max audio set` | `max audio set song.mp3 --artist "Artist" --album "Album"` |
+| **Batch organize audio** | `max audio batch` | `max audio batch "folder/*.mp3" --album "My Album" --artist "Band"` |
+| **Organize to folders** | `max audio organize` | `max audio organize "*.mp3" --pattern artist` |
+| **Download videos/music** | `max grab download` | `max grab download youtube.com/...` |
+| **Check download queue** | `max grab queue` | `max grab queue` |
+| **Download history** | `max grab history` | `max grab history` |
 | **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` |
@@ -114,14 +121,33 @@ max config setup
 
 This wizard will guide you through:
 
-- Choosing your AI provider (Google Gemini, OpenAI, or custom)
-- Entering your API key
+- Choosing your AI provider (Google Gemini, OpenAI, Ollama, or custom)
+- Entering your API key (not needed for Ollama)
 - Setting preferences
 
-**Get a free API key:**
+**AI Provider Options:**
 
-- [Google AI Studio](https://aistudio.google.com/app/apikey) - Free tier available
-- [OpenAI](https://platform.openai.com/api-keys) - Pay-as-you-go
+| Provider | API Key Required | Best For |
+|----------|------------------|----------|
+| [Google Gemini](https://aistudio.google.com/app/apikey) | Yes | Free tier, vision support |
+| [OpenAI](https://platform.openai.com/api-keys) | Yes | GPT models, image generation |
+| **Ollama** | No | Local/private AI, no internet needed |
+
+**Using Ollama (Local AI):**
+
+If you want to run AI locally without an internet connection:
+
+1. Install [Ollama](https://ollama.com)
+2. Run `max config setup` and select "ollama"
+3. Choose your model (e.g., llama3, mistral, codellama)
+
+```bash
+# Example Ollama .env settings
+OLLAMA_ENABLED=true
+OLLAMA_MODEL=llama3
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_API_KEY=ollama
+```
 
 ### Step 5: Start Using Max
 
@@ -237,19 +263,49 @@ Download from almost any website:
 
 ```bash
 # Download video (best quality)
-max grab "https://youtube.com/watch?v=..."
+max grab download "https://youtube.com/watch?v=..."
 
 # Download audio only (MP3)
-max grab "https://youtube.com/watch?v=..." -a
+max grab download "https://youtube.com/watch?v=..." -a
+
+# Force video download (override default)
+max grab download "https://youtube.com/watch?v=..." -v
 
 # Choose quality: s=480p, m=720p, h=1080p, x=4K
-max grab "..." -q h
+max grab download "..." -q h
+
+# Interactive mode - add URLs and download in background
+max grab download
+
+# Download to specific folder
+max grab download "..." -o ./my-videos
+
+# Add to queue without processing (batch mode)
+max grab download "..." --no-process
+```
+
+#### Interactive Mode
+
+Run `max grab download` without a URL to enter interactive mode:
+
+```bash
+max grab download
+# Enter URL and press Enter - download starts in background
+# Enter another URL while the first is downloading
+# Press Enter with empty input to exit
+```
+
+#### Queue System
+
+```bash
+# Check download queue
+max grab queue
 
-# Download a playlist
-max grab "https://youtube.com/playlist?list=..."
+# Show download history
+max grab history
 
-# Download specific video from playlist
-max grab "..." -i 3
+# Clear completed/failed downloads
+max grab clear
 ```
 
 #### Quality Presets Explained
@@ -267,8 +323,13 @@ max grab "..." -i 3
 # Set your defaults once
 max config grab
 
-# Now just run:
-max grab "url"  # Uses your saved preferences
+# Configure:
+# - Default quality (s/m/h/x)
+# - Auto-strip playlist info
+# - Embed metadata
+# - Default type (video/audio)
+# - Default download folder
+# - Enable/disable queue system
 ```
 
 ---
@@ -433,6 +494,9 @@ AI_MODEL=gpt-4o-mini
 DEFAULT_QUALITY=80
 GRAB_QUALITY=h
 GRAB_AUDIO_FORMAT=mp3
+GRAB_DEFAULT_PATH=~/Max Downloads
+GRAB_DEFAULT_TYPE=video
+GRAB_QUEUE_ENABLED=true
 ```
 
 ### Configuration Locations
@@ -566,39 +630,97 @@ Max CLI supports plugins for extensibility. Plugins are stored in:
 - `~/.max_cli/plugins/` (user-level)
 - `./plugins/` (project-level)
 
-Example plugin structure:
+#### Plugin Commands
+
+```bash
+# List all installed plugins
+max plugins list
+max plugins list --all    # Include disabled plugins
+
+# Get detailed info about a plugin
+max plugins info <plugin-name>
+
+# Enable or disable a plugin
+max plugins enable <plugin-name>
+max plugins disable <plugin-name>
+```
+
+#### Creating a Plugin
 
 ```python
-from max_cli.plugins.base import CLIPlugin
 import typer
+from max_cli.plugins.base import CLIPlugin
+
 
 class MyPlugin(CLIPlugin):
+    """My custom plugin."""
+
+    def __init__(self):
+        super().__init__(
+            name="my-plugin",
+            version="1.0.0",
+            description="My custom plugin description",
+            author="Your Name",
+            author_email="you@example.com",
+            url="https://github.com/you/plugin",
+            license="MIT",
+            tags=["custom", "example"],
+        )
+
     @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 priority(self) -> int:
+        """Lower = registered first. Default is 100."""
+        return 100
+
+    def validate(self) -> tuple[bool, str | None]:
+        """Validate plugin requirements."""
+        return True, None
+
+    def on_load(self, context) -> None:
+        """Called when plugin loads."""
+        pass
+
+    def on_unload(self) -> None:
+        """Called when plugin unloads."""
+        pass
+
     def register(self, app: typer.Typer) -> None:
         @app.command("my-command")
-        def my_command():
-            typer.echo("Hello from my plugin!")
+        @app.command("mc")  # Alias
+        def my_command(
+            name: str = typer.Option("World", "--name", "-n", help="Name to greet"),
+        ) -> None:
+            """My custom command."""
+            typer.echo(f"Hello, {name}!")
+
+
+# IMPORTANT: Instantiate at module level
+plugin = MyPlugin()
 ```
 
+For detailed documentation, see `PLANS/docs/plugins.md`.
+
 ### Architecture
 
 ```
 src/max_cli/
-├── core/           # Business logic (engines)
-├── interface/      # CLI commands (Typer)
-├── common/         # Shared utilities
-└── __init__.py    # Package exports
+├── core/
+│   ├── engines/          # Business logic (AI, media, PDF, etc.)
+│   │   ├── ai_engine.py
+│   │   ├── file_organizer.py
+│   │   ├── image_processor.py
+│   │   ├── media_engine.py
+│   │   ├── network_engine.py
+│   │   ├── pdf_engine.py
+│   │   ├── queue_manager.py
+│   │   └── system_engine.py
+│   └── cli/              # CLI command registration
+│       ├── commands/     # Command modules
+│       ├── plugins.py    # Plugin lifecycle
+│       └── registry.py   # Command registry
+├── interface/            # Typer CLI command interfaces
+├── common/              # Shared utilities and exceptions
+└── __init__.py          # Package exports
 ```
 
 ---

{max_cli-0.2.0 → max_cli-0.3.3}/README.md

@@ -31,7 +31,13 @@ Max transforms complex tasks—like compressing videos, merging PDFs, or downloa
 |------|-------------|---------|
 | **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/..."` |
+| **Get audio metadata** | `max audio get` | `max audio get song.mp3` |
+| **Set audio metadata** | `max audio set` | `max audio set song.mp3 --artist "Artist" --album "Album"` |
+| **Batch organize audio** | `max audio batch` | `max audio batch "folder/*.mp3" --album "My Album" --artist "Band"` |
+| **Organize to folders** | `max audio organize` | `max audio organize "*.mp3" --pattern artist` |
+| **Download videos/music** | `max grab download` | `max grab download youtube.com/...` |
+| **Check download queue** | `max grab queue` | `max grab queue` |
+| **Download history** | `max grab history` | `max grab history` |
 | **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` |
@@ -85,14 +91,33 @@ max config setup
 
 This wizard will guide you through:
 
-- Choosing your AI provider (Google Gemini, OpenAI, or custom)
-- Entering your API key
+- Choosing your AI provider (Google Gemini, OpenAI, Ollama, or custom)
+- Entering your API key (not needed for Ollama)
 - Setting preferences
 
-**Get a free API key:**
+**AI Provider Options:**
 
-- [Google AI Studio](https://aistudio.google.com/app/apikey) - Free tier available
-- [OpenAI](https://platform.openai.com/api-keys) - Pay-as-you-go
+| Provider | API Key Required | Best For |
+|----------|------------------|----------|
+| [Google Gemini](https://aistudio.google.com/app/apikey) | Yes | Free tier, vision support |
+| [OpenAI](https://platform.openai.com/api-keys) | Yes | GPT models, image generation |
+| **Ollama** | No | Local/private AI, no internet needed |
+
+**Using Ollama (Local AI):**
+
+If you want to run AI locally without an internet connection:
+
+1. Install [Ollama](https://ollama.com)
+2. Run `max config setup` and select "ollama"
+3. Choose your model (e.g., llama3, mistral, codellama)
+
+```bash
+# Example Ollama .env settings
+OLLAMA_ENABLED=true
+OLLAMA_MODEL=llama3
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_API_KEY=ollama
+```
 
 ### Step 5: Start Using Max
 
@@ -208,19 +233,49 @@ Download from almost any website:
 
 ```bash
 # Download video (best quality)
-max grab "https://youtube.com/watch?v=..."
+max grab download "https://youtube.com/watch?v=..."
 
 # Download audio only (MP3)
-max grab "https://youtube.com/watch?v=..." -a
+max grab download "https://youtube.com/watch?v=..." -a
+
+# Force video download (override default)
+max grab download "https://youtube.com/watch?v=..." -v
 
 # Choose quality: s=480p, m=720p, h=1080p, x=4K
-max grab "..." -q h
+max grab download "..." -q h
+
+# Interactive mode - add URLs and download in background
+max grab download
+
+# Download to specific folder
+max grab download "..." -o ./my-videos
+
+# Add to queue without processing (batch mode)
+max grab download "..." --no-process
+```
+
+#### Interactive Mode
+
+Run `max grab download` without a URL to enter interactive mode:
+
+```bash
+max grab download
+# Enter URL and press Enter - download starts in background
+# Enter another URL while the first is downloading
+# Press Enter with empty input to exit
+```
+
+#### Queue System
+
+```bash
+# Check download queue
+max grab queue
 
-# Download a playlist
-max grab "https://youtube.com/playlist?list=..."
+# Show download history
+max grab history
 
-# Download specific video from playlist
-max grab "..." -i 3
+# Clear completed/failed downloads
+max grab clear
 ```
 
 #### Quality Presets Explained
@@ -238,8 +293,13 @@ max grab "..." -i 3
 # Set your defaults once
 max config grab
 
-# Now just run:
-max grab "url"  # Uses your saved preferences
+# Configure:
+# - Default quality (s/m/h/x)
+# - Auto-strip playlist info
+# - Embed metadata
+# - Default type (video/audio)
+# - Default download folder
+# - Enable/disable queue system
 ```
 
 ---
@@ -404,6 +464,9 @@ AI_MODEL=gpt-4o-mini
 DEFAULT_QUALITY=80
 GRAB_QUALITY=h
 GRAB_AUDIO_FORMAT=mp3
+GRAB_DEFAULT_PATH=~/Max Downloads
+GRAB_DEFAULT_TYPE=video
+GRAB_QUEUE_ENABLED=true
 ```
 
 ### Configuration Locations
@@ -537,39 +600,97 @@ Max CLI supports plugins for extensibility. Plugins are stored in:
 - `~/.max_cli/plugins/` (user-level)
 - `./plugins/` (project-level)
 
-Example plugin structure:
+#### Plugin Commands
+
+```bash
+# List all installed plugins
+max plugins list
+max plugins list --all    # Include disabled plugins
+
+# Get detailed info about a plugin
+max plugins info <plugin-name>
+
+# Enable or disable a plugin
+max plugins enable <plugin-name>
+max plugins disable <plugin-name>
+```
+
+#### Creating a Plugin
 
 ```python
-from max_cli.plugins.base import CLIPlugin
 import typer
+from max_cli.plugins.base import CLIPlugin
+
 
 class MyPlugin(CLIPlugin):
+    """My custom plugin."""
+
+    def __init__(self):
+        super().__init__(
+            name="my-plugin",
+            version="1.0.0",
+            description="My custom plugin description",
+            author="Your Name",
+            author_email="you@example.com",
+            url="https://github.com/you/plugin",
+            license="MIT",
+            tags=["custom", "example"],
+        )
+
     @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 priority(self) -> int:
+        """Lower = registered first. Default is 100."""
+        return 100
+
+    def validate(self) -> tuple[bool, str | None]:
+        """Validate plugin requirements."""
+        return True, None
+
+    def on_load(self, context) -> None:
+        """Called when plugin loads."""
+        pass
+
+    def on_unload(self) -> None:
+        """Called when plugin unloads."""
+        pass
+
     def register(self, app: typer.Typer) -> None:
         @app.command("my-command")
-        def my_command():
-            typer.echo("Hello from my plugin!")
+        @app.command("mc")  # Alias
+        def my_command(
+            name: str = typer.Option("World", "--name", "-n", help="Name to greet"),
+        ) -> None:
+            """My custom command."""
+            typer.echo(f"Hello, {name}!")
+
+
+# IMPORTANT: Instantiate at module level
+plugin = MyPlugin()
 ```
 
+For detailed documentation, see `PLANS/docs/plugins.md`.
+
 ### Architecture
 
 ```
 src/max_cli/
-├── core/           # Business logic (engines)
-├── interface/      # CLI commands (Typer)
-├── common/         # Shared utilities
-└── __init__.py    # Package exports
+├── core/
+│   ├── engines/          # Business logic (AI, media, PDF, etc.)
+│   │   ├── ai_engine.py
+│   │   ├── file_organizer.py
+│   │   ├── image_processor.py
+│   │   ├── media_engine.py
+│   │   ├── network_engine.py
+│   │   ├── pdf_engine.py
+│   │   ├── queue_manager.py
+│   │   └── system_engine.py
+│   └── cli/              # CLI command registration
+│       ├── commands/     # Command modules
+│       ├── plugins.py    # Plugin lifecycle
+│       └── registry.py   # Command registry
+├── interface/            # Typer CLI command interfaces
+├── common/              # Shared utilities and exceptions
+└── __init__.py          # Package exports
 ```
 
 ---

{max_cli-0.2.0 → max_cli-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "max-cli"
-version = "0.2.0"
+version = "0.3.3"
 description = "The Local, Fast, & Lazy Terminal Assistant for high-performance tasks."
 authors = [{name = "Abubakr Alsheikh", email = "abubakralsheikh@outlook.com"}]
 readme = "README.md"
@@ -20,7 +20,8 @@ dependencies = [
     "requests>=2.31.0",
     "yt-dlp>=2023.0.0",
     "segno>=1.5.0",
-    "pyperclip>=1.8.0"
+    "pyperclip>=1.8.0",
+    "mutagen>=1.47.0"
 ]
 
 [project.optional-dependencies]
@@ -36,7 +37,7 @@ ocr = [
 ]
 
 [project.scripts]
-max = "max_cli.main:app"
+max = "max_cli.main:main"
 
 [tool.ruff]
 line-length = 88

{max_cli-0.2.0 → max_cli-0.3.3}/src/max_cli/common/logger.py

@@ -15,8 +15,8 @@ console = Console(theme=custom_theme)
 
 
 def log_error(message: str):
-    console.print(f"[error]✖ Error:[/error] {message}")
+    console.print(f"[error]X Error:[/error] {message}")
 
 
 def log_success(message: str):
-    console.print(f"[success]✔ Success:[/success] {message}")
+    console.print(f"[success]V Success:[/success] {message}")

{max_cli-0.2.0 → max_cli-0.3.3}/src/max_cli/config.py

@@ -21,11 +21,17 @@ class Settings(BaseSettings):
     # AI Configuration
     # If using OpenAI, leave BASE_URL as None.
     # If using Gemini, set to: https://generativelanguage.googleapis.com/v1beta/openai/
+    # If using Ollama, set to: http://localhost:11434/v1
     OPENAI_API_KEY: Optional[str] = None
     OPENAI_BASE_URL: Optional[str] = None
     # Models
     AI_MODEL: str = "gpt-5-nano"  # For 'ask', 'chat', 'analyze'
-    AI_IMAGE_MODEL: str = "gemini-2.5-flash-image"  # For 'create', 'edit'
+    AI_IMAGE_MODEL: str = "gpt-image-1"  # For 'create', 'edit'
+
+    # Ollama Configuration
+    OLLAMA_ENABLED: bool = False
+    OLLAMA_BASE_URL: str = "http://localhost:11434"
+    OLLAMA_MODEL: str = "llama3"
 
     # --- GRAB (DOWNLOADER) DEFAULTS ---
     # These save your preferences
@@ -34,6 +40,11 @@ class Settings(BaseSettings):
     GRAB_STRIP_PLAYLIST: bool = True  # If True, removes '&list=...' from video URLs
     GRAB_INCLUDE_METADATA: bool = True  # If True, embeds tags/thumbnails
 
+    # New: Default path and type for downloads
+    GRAB_DEFAULT_PATH: Path = Path.home() / "Max Downloads"
+    GRAB_DEFAULT_TYPE: str = "video"  # "video" or "audio"
+    GRAB_QUEUE_ENABLED: bool = False
+
     class Config:
         env_file = [str(Path.home() / ".max_config.env"), ".env"]
         env_file_encoding = "utf-8"

max_cli-0.3.3/src/max_cli/core/cli/commands/__init__.py

@@ -0,0 +1,22 @@
+# Command registration modules
+from max_cli.core.cli.commands import (
+    ai,
+    audio,
+    config,
+    files,
+    media,
+    network,
+    plugins as plugin_commands,
+    tools,
+)
+
+__all__ = [
+    "ai",
+    "audio",
+    "config",
+    "files",
+    "media",
+    "network",
+    "plugin_commands",
+    "tools",
+]

max_cli-0.3.3/src/max_cli/core/cli/commands/ai.py

@@ -0,0 +1,12 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typer import Typer
+
+from max_cli.interface import cli_ai
+
+
+def register(app: "Typer") -> None:
+    """Register AI assistant commands."""
+    app.add_typer(cli_ai.app, name="ai", help="Ask AI to run commands.")
+    cli_ai.MAIN_APP_REF = app

max_cli-0.3.3/src/max_cli/core/cli/commands/audio.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typer import Typer
+
+from max_cli.interface import cli_audio
+
+
+def register(app: "Typer") -> None:
+    """Register audio metadata commands."""
+    app.add_typer(
+        cli_audio.app, name="audio", help="Read, write, and manage audio metadata."
+    )
+    app.add_typer(cli_audio.app, name="a", hidden=True)

max_cli-0.3.3/src/max_cli/core/cli/commands/config.py

@@ -0,0 +1,11 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typer import Typer
+
+from max_cli.interface import cli_config
+
+
+def register(app: "Typer") -> None:
+    """Register configuration commands."""
+    app.add_typer(cli_config.app, name="config", help="Manage API keys and settings.")

max_cli-0.3.3/src/max_cli/core/cli/commands/files.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typer import Typer
+
+from max_cli.interface import cli_files, cli_pdf
+
+
+def register(app: "Typer") -> None:
+    """Register file management commands."""
+    app.add_typer(cli_files.app, name="files", help="Organize and bulk-rename files.")
+    app.add_typer(cli_files.app, name="file", hidden=True)
+
+    app.add_typer(cli_pdf.app, name="pdf", help="Merge, split, and compress PDFs.")