Basic Spotify Support

[0xspacecreated]

Feature Request: Add Spotify Integration

---

Is your feature request related to a problem? Please describe.
The Nevron framework currently lacks integration with Spotify, a leading music streaming platform. This limitation prevents autonomous AI agents from interacting with Spotify to perform actions such as fetching playlists, retrieving song details, or controlling playback. By adding Spotify integration, the framework can enable use cases such as music recommendations, playlist curation, and user-specific music control.

---

Describe the solution you'd like
Implement Spotify integration using Spotify’s official Web API to enable the following features:

• Music Playback Control: Allow agents to control playback (play, pause, skip) on connected devices.
• Playlist Retrieval: Enable agents to fetch user playlists and their contents.
• Song Search: Allow agents to search for songs, albums, and artists.

The implementation should:

• Use direct API requests (e.g., via the requests library) to interact with Spotify’s Web API.
• Include functions for:
  • Authentication: Authenticate and authorize access to Spotify’s Web API using OAuth2.
  • Data Retrieval: Fetch playlists, tracks, and user data.
  • Playback Control: Play, pause, and skip tracks on user-connected devices.
• Develop tests to ensure the integration functions as intended for the supported scenarios.
• Provide documentation detailing the setup process, usage examples, and necessary configurations.
• Include TODOs for future enhancements, such as real-time listening session management or creating collaborative playlists.

---

Describe alternatives you've considered
An alternative approach could involve using third-party Python SDKs like Spotipy. However, using the official Spotify Web API provides full control and avoids dependency on third-party libraries.

---

Additional context
Reference: The [Spotify Web API Documentation](https://developer.spotify.com/documentation/web-api/) provides detailed information for implementing the integration.

---

Specifications:

1. API Authentication

   • Implement OAuth2 authorization flow to authenticate the user and obtain access tokens.
   • Use access tokens for subsequent API requests.

2. Functions to Implement:

   • Authentication:

     import requests
     from urllib.parse import urlencode
     
     def authenticate_spotify(client_id: str, client_secret: str, redirect_uri: str, code: str) -> str:
         """
         Authenticate with Spotify and return an access token.
     
         Args:
             client_id (str): Spotify API client ID.
             client_secret (str): Spotify API client secret.
             redirect_uri (str): Redirect URI for OAuth2.
             code (str): Authorization code from Spotify.
     
         Returns:
             str: Access token for Spotify API.
         """
         url = "https://accounts.spotify.com/api/token"
         headers = {"Content-Type": "application/x-www-form-urlencoded"}
         data = {
             "grant_type": "authorization_code",
             "code": code,
             "redirect_uri": redirect_uri,
             "client_id": client_id,
             "client_secret": client_secret,
         }
         response = requests.post(url, headers=headers, data=data)
         response.raise_for_status()
         return response.json()["access_token"]

   • Playlist Retrieval:

     def get_user_playlists(access_token: str) -> list:
         """
         Retrieve the user's playlists.
     
         Args:
             access_token (str): Spotify API access token.
     
         Returns:
             list: List of user playlists.
         """
         url = "https://api.spotify.com/v1/me/playlists"
         headers = {"Authorization": f"Bearer {access_token}"}
         response = requests.get(url, headers=headers)
         response.raise_for_status()
         return response.json()["items"]

   • Song Search:

     def search_song(access_token: str, query: str, limit: int = 1) -> list:
         """
         Search for a song by name.
     
         Args:
             access_token (str): Spotify API access token.
             query (str): Search query (e.g., song name, artist).
             limit (int): Maximum number of results.
     
         Returns:
             list: List of song details.
         """
         url = f"https://api.spotify.com/v1/search?{urlencode({'q': query, 'type': 'track', 'limit': limit})}"
         headers = {"Authorization": f"Bearer {access_token}"}
         response = requests.get(url, headers=headers)
         response.raise_for_status()
         return response.json()["tracks"]["items"]

   • Playback Control:

     def control_playback(access_token: str, action: str) -> None:
         """
         Control playback on connected devices.
     
         Args:
             access_token (str): Spotify API access token.
             action (str): Playback action (e.g., "play", "pause", "skip").
     
         Raises:
             ValueError: If the action is invalid.
         """
         base_url = "https://api.spotify.com/v1/me/player/"
         endpoints = {"play": "play", "pause": "pause", "skip": "next"}
         if action not in endpoints:
             raise ValueError("Invalid playback action.")
         url = f"{base_url}{endpoints[action]}"
         headers = {"Authorization": f"Bearer {access_token}"}
         response = requests.put(url, headers=headers)
         response.raise_for_status()

3. Testing:

   • Mock Spotify API responses using testing frameworks like unittest.mock or pytest.
   • Create tests for:
     • Successful OAuth2 token exchange.
     • Fetching playlists and songs.
     • Controlling playback actions.

4. Documentation:

   • Provide a setup guide for configuring Spotify integration, including:
     • Obtaining API credentials from Spotify Developer Dashboard.
     • Configuring the OAuth2 flow.
   • Include usage examples demonstrating how to:
     • Authenticate and retrieve an access token.
     • Fetch playlists and search for songs.
     • Control playback.

5. TODOs for Future Enhancements:

   • Add support for real-time listening session tracking.
   • Enable collaborative playlist creation and management.
   • Handle multi-device playback scenarios.
   • Add robust error handling and token refresh logic.

---

Acceptance Criteria

• Spotify integration is successfully implemented for playlist retrieval, song search, and playback control.
• Comprehensive tests validate the functionality.
• Documentation provides clear guidance on setup and usage.
• Existing functionality in the framework remains unaffected.

---

Estimated Complexity
Medium: Requires handling OAuth2 authentication, implementing structured API calls, and ensuring compatibility with existing workflows.