Merge remote-tracking branch 'origin/feature/filtering-tool' into dev

DOCUMENTATION.md

@@ -10,6 +10,7 @@ The project is a monorepo containing two primary components:
     *   **Batch Manager**: Optimizes high-volume embedding requests.
     *   **Detailed Logger**: Provides per-request file logging for debugging.
     *   **OpenAI-Compatible Endpoints**: `/v1/chat/completions`, `/v1/embeddings`, etc.
+    *   **Model Filter GUI**: Visual interface for configuring model ignore/whitelist rules per provider (see Section 6).
 2.  **The Resilience Library (`rotator_library`)**: This is the core engine that provides high availability. It is consumed by the proxy app to manage a pool of API keys, handle errors gracefully, and ensure requests are completed successfully even when individual keys or provider endpoints face issues.
 
 This architecture cleanly separates the API interface from the resilience logic, making the library a portable and powerful tool for any application needing robust API key management.
@@ -1452,3 +1453,83 @@ stats = cache.get_stats()
 # Includes: {"disk_available": True, "disk_errors": 0, ...}
 ```
 
+---
+
+## 6. Model Filter GUI
+
+The Model Filter GUI (`model_filter_gui.py`) provides a visual interface for configuring model ignore and whitelist rules per provider. It replaces the need to manually edit `IGNORE_MODELS_*` and `WHITELIST_MODELS_*` environment variables.
+
+### 6.1. Overview
+
+**Purpose**: Visually manage which models are exposed via the `/v1/models` endpoint for each provider.
+
+**Launch**: 
+```bash
+python -c "from src.proxy_app.model_filter_gui import run_model_filter_gui; run_model_filter_gui()"
+```
+
+Or via the launcher TUI if integrated.
+
+### 6.2. Features
+
+#### Core Functionality
+
+- **Provider Selection**: Dropdown to switch between available providers with automatic model fetching
+- **Ignore Rules**: Pattern-based rules (supports wildcards like `*-preview`, `gpt-4*`) to exclude models
+- **Whitelist Rules**: Pattern-based rules to explicitly include models, overriding ignore rules
+- **Real-time Preview**: Typing in rule input fields highlights affected models before committing
+- **Rule-Model Linking**: Click a model to highlight the affecting rule; click a rule to highlight all affected models
+- **Persistence**: Rules saved to `.env` file in standard `IGNORE_MODELS_<PROVIDER>` and `WHITELIST_MODELS_<PROVIDER>` format
+
+#### Dual-Pane Model View
+
+The interface displays two synchronized lists:
+
+| Left Pane | Right Pane |
+|-----------|------------|
+| All fetched models (plain text) | Same models with color-coded status |
+| Shows total count | Shows available/ignored count |
+| Scrolls in sync with right pane | Color indicates affecting rule |
+
+**Color Coding**:
+- **Green**: Model is available (no rule affects it, or whitelisted)
+- **Red/Orange tones**: Model is ignored (color matches the specific ignore rule)
+- **Blue/Teal tones**: Model is explicitly whitelisted (color matches the whitelist rule)
+
+#### Rule Management
+
+- **Comma-separated input**: Add multiple rules at once (e.g., `*-preview, *-beta, gpt-3.5*`)
+- **Wildcard support**: `*` matches any characters (e.g., `gemini-*-preview`)
+- **Affected count**: Each rule shows how many models it affects
+- **Tooltips**: Hover over a rule to see the list of affected models
+- **Instant delete**: Click the × button to remove a rule immediately
+
+### 6.3. Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+S` | Save changes to `.env` |
+| `Ctrl+R` | Refresh models from provider |
+| `Ctrl+F` | Focus search field |
+| `F1` | Show help dialog |
+| `Escape` | Clear search / Clear highlights |
+
+### 6.4. Context Menu
+
+Right-click on any model to access:
+
+- **Add to Ignore List**: Creates an ignore rule for the exact model name
+- **Add to Whitelist**: Creates a whitelist rule for the exact model name
+- **View Affecting Rule**: Highlights the rule that affects this model
+- **Copy Model Name**: Copies the full model ID to clipboard
+
+### 6.5. Integration with Proxy
+
+The GUI modifies the same environment variables that the `RotatingClient` reads:
+
+1. **GUI saves rules** → Updates `.env` file
+2. **Proxy reads on startup** → Loads `IGNORE_MODELS_*` and `WHITELIST_MODELS_*`
+3. **Proxy applies rules** → `get_available_models()` filters based on rules
+
+**Note**: The proxy must be restarted to pick up rule changes made via the GUI (or use the Launcher TUI's reload functionality if available).
+

requirements.txt

@@ -19,3 +19,9 @@ aiohttp
 colorlog
 
 rich
+
+# GUI for model filter configuration
+customtkinter
+
+# For building the executable
+pyinstaller

src/proxy_app/build.py

@@ -3,6 +3,7 @@ import sys
 import platform
 import subprocess
 
+
 def get_providers():
     """
     Scans the 'src/rotator_library/providers' directory to find all provider modules.
@@ -24,6 +25,7 @@ def get_providers():
             hidden_imports.append(f"--hidden-import={module_name}")
     return hidden_imports
 
+
 def main():
     """
     Constructs and runs the PyInstaller command to build the executable.
@@ -47,22 +49,27 @@ def main():
         "--collect-data",
         "litellm",
         # Optimization: Exclude unused heavy modules
-        "--exclude-module=tkinter",
         "--exclude-module=matplotlib",
         "--exclude-module=IPython",
         "--exclude-module=jupyter",
         "--exclude-module=notebook",
         "--exclude-module=PIL.ImageTk",
         # Optimization: Enable UPX compression (if available)
-        "--upx-dir=upx" if platform.system() != "Darwin" else "--noupx",  # macOS has issues with UPX
+        "--upx-dir=upx"
+        if platform.system() != "Darwin"
+        else "--noupx",  # macOS has issues with UPX
         # Optimization: Strip debug symbols (smaller binary)
-        "--strip" if platform.system() != "Windows" else "--console",  # Windows gets clean console
+        "--strip"
+        if platform.system() != "Windows"
+        else "--console",  # Windows gets clean console
     ]
 
     # Add hidden imports for providers
     provider_imports = get_providers()
     if not provider_imports:
-        print("Warning: No providers found. The build might not include any LLM providers.")
+        print(
+            "Warning: No providers found. The build might not include any LLM providers."
+        )
     command.extend(provider_imports)
 
     # Add the main script
@@ -80,5 +87,6 @@ def main():
     except FileNotFoundError:
         print("Error: PyInstaller is not installed or not in the system's PATH.")
 
+
 if __name__ == "__main__":
     main()

src/proxy_app/settings_tool.py

@@ -749,23 +749,20 @@ class SettingsTool:
         self.console.print("   3. ⚡ Concurrency Limits")
         self.console.print("   4. 🔄 Rotation Modes")
         self.console.print("   5. 🔬 Provider-Specific Settings")
-        self.console.print("   6. 💾 Save & Exit")
-        self.console.print("   7. 🚫 Exit Without Saving")
+        self.console.print("   6. 🎯 Model Filters (Ignore/Whitelist)")
+        self.console.print("   7. 💾 Save & Exit")
+        self.console.print("   8. 🚫 Exit Without Saving")
 
         self.console.print()
         self.console.print("━" * 70)
 
         self.console.print(self._get_pending_status_text())
 
-        self.console.print()
-        self.console.print(
-            "[dim]⚠️  Model filters not supported - edit .env for IGNORE_MODELS_* / WHITELIST_MODELS_*[/dim]"
-        )
         self.console.print()
 
         choice = Prompt.ask(
             "Select option",
-            choices=["1", "2", "3", "4", "5", "6", "7"],
+            choices=["1", "2", "3", "4", "5", "6", "7", "8"],
             show_choices=False,
         )
 
@@ -780,8 +777,10 @@ class SettingsTool:
         elif choice == "5":
             self.manage_provider_settings()
         elif choice == "6":
-            self.save_and_exit()
+            self.launch_model_filter_gui()
         elif choice == "7":
+            self.save_and_exit()
+        elif choice == "8":
             self.exit_without_saving()
 
     def manage_custom_providers(self):
@@ -1393,6 +1392,28 @@ class SettingsTool:
 
         input("Press Enter to return...")
 
+    def launch_model_filter_gui(self):
+        """Launch the Model Filter GUI for managing ignore/whitelist rules"""
+        clear_screen()
+        self.console.print("\n[cyan]Launching Model Filter GUI...[/cyan]\n")
+        self.console.print(
+            "[dim]The GUI will open in a separate window. Close it to return here.[/dim]\n"
+        )
+
+        try:
+            from proxy_app.model_filter_gui import run_model_filter_gui
+
+            run_model_filter_gui()  # Blocks until GUI closes
+        except ImportError as e:
+            self.console.print(f"\n[red]Failed to launch Model Filter GUI: {e}[/red]")
+            self.console.print()
+            self.console.print(
+                "[yellow]Make sure 'customtkinter' is installed:[/yellow]"
+            )
+            self.console.print("  [cyan]pip install customtkinter[/cyan]")
+            self.console.print()
+            input("Press Enter to continue...")
+
     def manage_provider_settings(self):
         """Manage provider-specific settings (Antigravity, Gemini CLI)"""
         while True:

src/rotator_library/client.py

@@ -1,4 +1,5 @@
 import asyncio
+import fnmatch
 import json
 import re
 import codecs
@@ -297,7 +298,14 @@ class RotatingClient:
     def _is_model_ignored(self, provider: str, model_id: str) -> bool:
         """
         Checks if a model should be ignored based on the ignore list.
-        Supports exact and partial matching for both full model IDs and model names.
+        Supports full glob/fnmatch patterns for both full model IDs and model names.
+
+        Pattern examples:
+        - "gpt-4" - exact match
+        - "gpt-4*" - prefix wildcard (matches gpt-4, gpt-4-turbo, etc.)
+        - "*-preview" - suffix wildcard (matches gpt-4-preview, o1-preview, etc.)
+        - "*-preview*" - contains wildcard (matches anything with -preview)
+        - "*" - match all
         """
         model_provider = model_id.split("/")[0]
         if model_provider not in self.ignore_models:
@@ -314,52 +322,43 @@ class RotatingClient:
             provider_model_name = model_id
 
         for ignored_pattern in ignore_list:
-            if ignored_pattern.endswith("*"):
-                match_pattern = ignored_pattern[:-1]
-                # Match wildcard against the provider's model name
-                if provider_model_name.startswith(match_pattern):
-                    return True
-            else:
-                # Exact match against the full proxy ID OR the provider's model name
-                if (
-                    model_id == ignored_pattern
-                    or provider_model_name == ignored_pattern
-                ):
-                    return True
+            # Use fnmatch for full glob pattern support
+            if fnmatch.fnmatch(provider_model_name, ignored_pattern) or fnmatch.fnmatch(
+                model_id, ignored_pattern
+            ):
+                return True
         return False
 
     def _is_model_whitelisted(self, provider: str, model_id: str) -> bool:
         """
         Checks if a model is explicitly whitelisted.
-        Supports exact and partial matching for both full model IDs and model names.
+        Supports full glob/fnmatch patterns for both full model IDs and model names.
+
+        Pattern examples:
+        - "gpt-4" - exact match
+        - "gpt-4*" - prefix wildcard (matches gpt-4, gpt-4-turbo, etc.)
+        - "*-preview" - suffix wildcard (matches gpt-4-preview, o1-preview, etc.)
+        - "*-preview*" - contains wildcard (matches anything with -preview)
+        - "*" - match all
         """
         model_provider = model_id.split("/")[0]
         if model_provider not in self.whitelist_models:
             return False
 
         whitelist = self.whitelist_models[model_provider]
+
+        try:
+            # This is the model name as the provider sees it (e.g., "gpt-4" or "google/gemma-7b")
+            provider_model_name = model_id.split("/", 1)[1]
+        except IndexError:
+            provider_model_name = model_id
+
         for whitelisted_pattern in whitelist:
-            if whitelisted_pattern == "*":
+            # Use fnmatch for full glob pattern support
+            if fnmatch.fnmatch(
+                provider_model_name, whitelisted_pattern
+            ) or fnmatch.fnmatch(model_id, whitelisted_pattern):
                 return True
-
-            try:
-                # This is the model name as the provider sees it (e.g., "gpt-4" or "google/gemma-7b")
-                provider_model_name = model_id.split("/", 1)[1]
-            except IndexError:
-                provider_model_name = model_id
-
-            if whitelisted_pattern.endswith("*"):
-                match_pattern = whitelisted_pattern[:-1]
-                # Match wildcard against the provider's model name
-                if provider_model_name.startswith(match_pattern):
-                    return True
-            else:
-                # Exact match against the full proxy ID OR the provider's model name
-                if (
-                    model_id == whitelisted_pattern
-                    or provider_model_name == whitelisted_pattern
-                ):
-                    return True
         return False
 
     def _sanitize_litellm_log(self, log_data: dict) -> dict:

src/rotator_library/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rotator_library"
-version = "1.0"
+version = "1.05"
 authors = [
     { name="Mirrowel", email="nuh@uh.com" },
 ]
@@ -16,11 +16,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-dependencies = [
-    "litellm",
-    "filelock",
-    "httpx"
-]
+dependencies = []
 
 [project.urls]
 "Homepage" = "https://github.com/Mirrowel/LLM-API-Key-Proxy"