NeptuneHub · rendyhd · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026
diff --git a/.gitignore b/.gitignore
@@ -37,6 +37,15 @@ env/
 .pytest_cache/
 htmlcov/
 nul
+testing_suite/reports/
+
+# Testing suite configs (contain API keys / DB passwords)
+testing_suite/instant_playlist_test_config.yaml
+testing_suite/ai_naming_test_config.yaml
+testing_suite/comparison_config.yaml
+
+# Deployment secrets
+deployment/main.env
 
 # Large model files in query folder
 /query/*.pt

diff --git a/README.md b/README.md
@@ -106,6 +106,13 @@ For the architecture design of AudioMuse-AI, take a look to the [ARCHITECTURE](d
    EMBY_TOKEN=your-api-token
    ```
 
+   **For Local Files (No Media Server):**
+   ```env
+   MEDIASERVER_TYPE=localfiles
+   LOCALFILES_MUSIC_DIRECTORY=/path/to/your/music
+   LOCALFILES_PLAYLIST_DIR=/path/to/your/music/playlists
+   ```
+
 3. **Start the services:**
    ```bash
    docker compose -f deployment/docker-compose.yaml up -d
@@ -129,6 +136,53 @@ For the architecture design of AudioMuse-AI, take a look to the [ARCHITECTURE](d
 docker compose -f deployment/docker-compose.yaml down
 ```
 
+## Multi-Provider Support
+
+AudioMuse-AI supports connecting to multiple media servers simultaneously, allowing you to:
+- Share analysis data across providers (analyze once, use everywhere)
+- Create playlists on multiple servers at once
+- Use a GUI Setup Wizard for easy configuration
+
+### GUI Setup Wizard
+
+Access the Setup Wizard at `http://localhost:8000/setup` to:
+1. Add and configure multiple providers
+2. Test connections before saving
+3. Auto-detect music path prefixes for cross-provider matching
+4. Set a primary provider for playlist creation
+
+### Local Files Provider
+
+The Local Files provider scans your music directory directly without requiring a media server:
+- Supports MP3, FLAC, OGG, M4A, WAV, WMA, AAC, and OPUS formats
+- Extracts metadata from embedded tags (ID3, Vorbis comments, etc.)
+- Creates M3U playlists in a configurable directory
+- Extracts ratings from POPM, TXXX:RATING, and Vorbis RATING tags
+
+**Configuration:**
+```env
+MEDIASERVER_TYPE=localfiles
+LOCALFILES_MUSIC_DIRECTORY=/music              # Path to your music library
+LOCALFILES_PLAYLIST_DIR=/music/playlists       # Where to save generated playlists
+LOCALFILES_FORMATS=.mp3,.flac,.ogg,.m4a,.wav   # Supported audio formats
+LOCALFILES_SCAN_SUBDIRS=true                   # Scan subdirectories
+```
+
+### Cross-Provider Track Matching
+
+When using multiple providers, tracks are matched across servers using normalized file paths. This allows:
+- Analysis data to be reused across providers
+- Playlists to be created on any provider using tracks from another
+- Automatic ID remapping when creating cross-provider playlists
+
+### Extended Metadata Fields
+
+AudioMuse-AI now stores additional metadata for each track:
+- **album_artist**: The album artist (useful for compilations)
+- **year**: Release year extracted from various tag formats
+- **rating**: User rating on 0-5 scale (from tags or media server)
+- **file_path**: Normalized file path for cross-provider linking
+
 > NOTE: by default AudioMuse-AI is deployed WITHOUT authentication layer and its suited only for LOCAL deployment. If you want to configure it have a look to the  [AUTHENTICATION](docs/AUTH.md) docs. If you enable the Authentication Layer, you need to be sure that any plugin used support and use the AudioMuse-AI API TOKEN
 
 ## **Hardware Requirements**

diff --git a/TEST_CHECKLIST.md b/TEST_CHECKLIST.md
diff --git a/TEST_RESULTS.md b/TEST_RESULTS.md
@@ -0,0 +1,252 @@
+# AudioMuse-AI v0.9.0 - Test Results
+
+**Date:** 2026-02-11
+**Branch:** `multi-provider-setup-gui`
+**Tester:** Claude + User
+**Environment:** Docker (NVIDIA GPU test stack) + Windows 11 local
+**Docker Compose:** `deployment/docker-compose-unified-nvidia-test.yaml`
+**Local Python:** 3.14.2 (Windows 11 Pro)
+**Container Python:** 3.12 (Ubuntu 24.04 + CUDA 12.8.1)
+
+---
+
+## Pre-flight: Collection Status
+
+### Local Environment (Python 3.14.2, Windows)
+- **622 tests collected** across all test files
+- **9 files blocked** (import `librosa` via `tasks/__init__.py` — not installed locally)
+  - `test_analysis.py`, `test_artist_gmm_manager.py`, `test_clustering_helper.py`,
+    `test_clustering_postprocessing.py`, `test_commons.py`, `test_memory_utils.py`,
+    `test_path_manager.py`, `test_song_alchemy.py`, `test_sonic_fingerprint_manager.py`
+- **213 runtime failures** — also `librosa` import (test_clustering, test_mediaserver, test_voyager_manager, etc.)
+- **407 passed, 2 skipped, 0 real failures** on tests that don't need `librosa`
+- Installed `audioop-lts` to fix Python 3.14 `pydub` compatibility
+
+### Docker Environment (Python 3.12.3, Ubuntu 24.04 + CUDA 12.8.1)
+- **833 tests collected**, 0 collection errors
+- **832 passed, 1 failed, 4 warnings**
+- Build time: ~15 min (GPU packages + model downloads)
+- Containers: redis (healthy), postgres (healthy), flask-app (up), worker (up)
+
+### Bug Found & Fixed During Testing
+| Test | Error | Fix |
+|------|-------|-----|
+| `test_mediaserver_localfiles.py::TestPathNormalization::test_posix_conversion` | Backslashes not converted on Linux | `normalize_file_path()`: replace `\` before creating `PurePosixPath` |
+
+### After Fix: 833 passed, 0 failed, 4 warnings (63.80s)
+
+### Warnings (non-blocking)
+- `analysis.py:387` — RuntimeWarning: invalid value in log10 (known, edge case in mel spectrogram)
+- `sklearn.linear_model` — FutureWarning: `penalty`/`n_jobs` deprecated in 1.8 (upgrade notice)
+
+---
+
+## Section 3: Multi-Provider Architecture
+
+### 3.1 Fresh Install (No Existing Data)
+_(pending)_
+
+### 3.2 Migration (Existing Single-Provider Data)
+_(pending)_
+
+### 3.3 Provider CRUD API
+_(pending)_
+
+### 3.4 Multi-Provider Playlist Creation
+_(pending)_
+
+---
+
+## Section 4: GUI Setup Wizard
+_(pending - manual)_
+
+---
+
+## Section 5: Environment / Config Setup
+
+### 5.1 Config Variable Validation
+_(pending)_
+
+### 5.2 Environment File
+_(pending)_
+
+### 5.3 Settings Persistence
+_(pending)_
+
+---
+
+## Section 6: API Endpoints
+
+### 6.1 Without Provider
+_(pending)_
+
+### 6.2 With Provider
+_(pending)_
+
+### 6.3 Error Handling
+_(pending)_
+
+---
+
+## Section 7: App Interactions (UI/UX)
+_(pending - manual)_
+
+---
+
+## Section 8: Instant Playlist & AI Changes
+
+### 8.1 Agentic Loop
+_(pending)_
+
+### 8.2 Pre-Execution Validation
+_(pending)_
+
+### 8.3 Proportional Sampling
+_(pending)_
+
+### 8.4 Artist Diversity
+_(pending)_
+
+### 8.5 System Prompt
+_(pending)_
+
+### 8.6 AI MCP Client
+_(pending)_
+
+### 8.7 AI Provider Integration
+_(pending)_
+
+### 8.8 Library Context
+_(pending)_
+
+---
+
+## Section 9: MCP Tools
+
+### 9.1 song_similarity
+_(pending)_
+
+### 9.2 text_search
+_(pending)_
+
+### 9.3 artist_similarity
+_(pending)_
+
+### 9.4 song_alchemy
+_(pending)_
+
+### 9.5 ai_brainstorm
+_(pending)_
+
+### 9.6 search_database
+_(pending)_
+
+---
+
+## Section 10: Provider-Specific Testing
+
+### 10.1 Common Provider Interface
+_(pending - manual)_
+
+### 10.2 LocalFiles Provider
+_(pending)_
+
+---
+
+## Section 11: Database & Schema Changes
+
+### 11.1 Schema Migration
+_(pending)_
+
+### 11.2 Data Integrity
+_(pending)_
+
+---
+
+## Section 12: Dark Mode
+
+### 12.1 Toggle & Persistence
+_(pending)_
+
+### 12.2 Visual Correctness
+_(pending - manual)_
+
+### 12.3 CSS Variables
+_(pending)_
+
+---
+
+## Section 13: Analysis Pipeline
+
+### 13.1 Analysis with New Fields
+_(pending)_
+
+### 13.2 Voyager Index
+_(pending)_
+
+---
+
+## Section 14: Playlist Ordering
+
+### 14.1 Greedy Nearest-Neighbor
+_(pending)_
+
+### 14.2 Composite Distance
+_(pending)_
+
+### 14.3 Circle of Fifths Key Distance
+_(pending)_
+
+### 14.4 Energy Arc
+_(pending)_
+
+---
+
+## Section 15: Deployment & Docker
+_(pending - manual)_
+
+---
+
+## Section 16: Regression Tests
+
+### 16.1 Features That Must Still Work
+_(pending)_
+
+### 16.2 Breaking Changes to Verify
+_(pending)_
+
+---
+
+## Section 17: Security
+
+### 17.1 XSS Prevention
+_(pending)_
+
+### 17.2 SQL Injection Prevention
+_(pending)_
+
+### 17.3 Authentication & Authorization
+_(pending)_
+
+---
+
+## Summary
+
+| Section | Pass | Fail | Skip | Total |
+|---------|------|------|------|-------|
+| 3. Multi-Provider | | | | |
+| 4. Setup Wizard | | | | |
+| 5. Config | | | | |
+| 6. API | | | | |
+| 7. UI/UX | | | | |
+| 8. Instant Playlist | | | | |
+| 9. MCP Tools | | | | |
+| 10. Providers | | | | |
+| 11. Database | | | | |
+| 12. Dark Mode | | | | |
+| 13. Analysis | | | | |
+| 14. Playlist Ordering | | | | |
+| 15. Docker | | | | |
+| 16. Regression | | | | |
+| 17. Security | | | | |
+| **TOTAL** | | | | |
diff --git a/ai_mcp_client.py b/ai_mcp_client.py
@@ -508,6 +508,7 @@ def _call_ollama_with_tools(user_message: str, tools: List[Dict], ai_config: Dic
         examples.append('"songs in minor key"\n{{"tool_calls": [{{"name": "search_database", "arguments": {{"scale": "minor", "get_songs": 200}}}}]}}')
         examples.append('"sounds like Iron Maiden and Metallica combined"\n{{"tool_calls": [{{"name": "song_alchemy", "arguments": {{"add_items": [{{"type": "artist", "id": "Iron Maiden"}}, {{"type": "artist", "id": "Metallica"}}], "get_songs": 200}}}}]}}')
         examples.append('"mix of Daft Punk and Gorillaz"\n{{"tool_calls": [{{"name": "song_alchemy", "arguments": {{"add_items": [{{"type": "artist", "id": "Daft Punk"}}, {{"type": "artist", "id": "Gorillaz"}}], "get_songs": 200}}}}]}}')
+
         examples_text = "\n\n".join(examples)
 
         prompt = f"""{system_prompt}
@@ -537,6 +538,7 @@ def _call_ollama_with_tools(user_message: str, tools: List[Dict], ai_config: Dic
 IMPORTANT: ONLY include parameters the user explicitly asked for. Do NOT invent extra filters (genres, ratings, moods, energy) the user never mentioned.
 For a specific year like "2026 songs", set BOTH year_min and year_max to 2026 (NOT year_min=1).
 
+
 Now analyze this request and return ONLY the JSON:
 Request: "{user_message}"
 """