spotify-analytics-core 0.1.0__py3-none-any.whl

spotify_analytics_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: spotify-analytics-core
+Version: 0.1.0
+Summary: Core analytics, agent, and Spotify client library for the Spotify AI Analytics project.
+Project-URL: Homepage, https://github.com/wcnoname5/spotify-ai-analytics
+Project-URL: Repository, https://github.com/wcnoname5/spotify-ai-analytics
+Project-URL: Issues, https://github.com/wcnoname5/spotify-ai-analytics/issues
+Author: WC Chang
+License: MIT
+License-File: LICENSE
+Keywords: analytics,listening-history,mcp,spotify
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: langgraph-checkpoint-sqlite>=3.0.3
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: agent
+Requires-Dist: langchain-core>=1.0; extra == 'agent'
+Requires-Dist: langchain-google-genai>=4.0; extra == 'agent'
+Requires-Dist: langchain-openai>=1.0; extra == 'agent'
+Requires-Dist: langgraph>=1.0; extra == 'agent'
+Description-Content-Type: text/markdown
+
+# spotify-analytics-core
+
+Core analytics, agent, database, and Spotify client library for Spotify AI Analytics.

spotify_analytics_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+spotify_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spotify_core/config.py,sha256=seifcK5xXvM3V0QJq8ecn8qIqEtwMl3G4wgKlyaVMKk,2546
+spotify_core/env_file.py,sha256=bC1mr31EO2S6sI17w3MAQD3X7RpZVRJ2eAWjxtgiblY,2878
+spotify_core/logging.py,sha256=mrte60h6ra9psMkMVHEFsrJuP_2X_1jCMegsUxWdorg,2499
+spotify_core/paths.py,sha256=KjouqkOIbqIeYjDbPJJ1Gcox9rVB03GxspMXqbL-lUA,1590
+spotify_core/setup.py,sha256=QP9padSIATZSXe2Oye_K0SyO4pkJzABXLFuT6wmgLCk,4566
+spotify_core/agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spotify_core/agent/graph.py,sha256=WvgbwNEG006SeGQgZPOcfDzV4AK-V_4cXMdKbVhmrrA,1222
+spotify_core/agent/nodes.py,sha256=o0srMp3ZPvoVCpgF5-8lQf-uL4Gb3Hz8Zk9yNjiQx8w,6585
+spotify_core/agent/playback_tools.py,sha256=vtxB2dMPyVgFuaoD-zDxlijZP7Rdzu3LThiAhvmc75A,746
+spotify_core/agent/prompts.py,sha256=az4b_llzVh8wk5PDgR1CMG2t8aM6IFZvnZP8rH_k5ng,2105
+spotify_core/agent/resources.py,sha256=rzOkkFSxKJMZA3D65wC5gzFCskWM2m6KY33DkCM4ueU,1087
+spotify_core/agent/schemas.py,sha256=F7LdAZGu1N8umdYX4PgQpDSNyOLckVcQ_-UNDzYWDhE,2732
+spotify_core/agent/state.py,sha256=ahXcbqaBY5iP34rEaUbjtPlsKHjrE05zY_Ac20jr2vY,632
+spotify_core/agent/tools.py,sha256=-lh39ln5tG9w_iP87Da8faSreA-9GzpbNO2k7M31i6U,11973
+spotify_core/db/__init__.py,sha256=2wKS-0KhjioLAhBYUWTniTXOPA18n6tp0SvRM0lZJGY,47
+spotify_core/db/errors.py,sha256=Kawc5r7GVE2TlrNj0Yr5kjJyJJDgNpQVtuw2SkiJApg,640
+spotify_core/db/migrations.py,sha256=_4Ff8-CzMZCMIJgFpzpJzYk-CfP-Glg5tt6P_DYEjJI,5167
+spotify_core/db/pipeline.py,sha256=oL8J_4VpeXvU2jB292poU30kSrkF8uDjhoppMadsiyc,17728
+spotify_core/db/queries.py,sha256=Mw0Pf3QzvkjWfR7QjCAux_Mrmu7h5fbpEr2SQR254nM,17887
+spotify_core/db/schema.py,sha256=5JuGXxqeEtVjKKoftayE4Fwpp9OySbFHnvNEI4x6wrg,1483
+spotify_core/memory/__init__.py,sha256=isy_D7NZhGQ9W7QT_JjOdxWReqLRiFt_zXhuJpa712M,159
+spotify_core/memory/checkpointer.py,sha256=X78RTuZ2Q7kEWWflMmKRFKndmCTIuBeKLMo60Qp-XE4,555
+spotify_core/memory/store.py,sha256=beJXU8lCu3dw6pxVOGrG12t-COT7Ynjd4eue91X6Tas,1060
+spotify_core/spotify_client/__init__.py,sha256=1f7y7Gh0HkpGG0jYwyD0nUQRu7gShBv1his2Bm7DPzc,257
+spotify_core/spotify_client/auth.py,sha256=m_azR8_Lv0gt41y2EZlVGNRJIaOYo1a9GF3sBQy4jtg,5885
+spotify_core/spotify_client/client.py,sha256=wyfJEy94ZkTHJqQ2ZIW5ivPzAXV_WxJBxfF7py0HsWQ,20293
+spotify_core/spotify_client/errors.py,sha256=A4gd34DgoHiKqUp2t9enqRiLqJuYPbIMebE0s08dGA4,794
+spotify_core/spotify_client/pkce.py,sha256=EWEtHfyiU2cVc7OKCGguKXEQCiiCccR688VCzceaKyg,1497
+spotify_core/spotify_client/token_store.py,sha256=Oq9KpjxpGyZC2YiMKvEnG0S0T-Y3FGiW_vUZkCfNRfw,5887
+spotify_core/spotify_utils/__init__.py,sha256=CW5_s5oDFvpIDUot31qTxv-s5aXs0U4sZFeaMWQl5Go,79
+spotify_core/spotify_utils/spotify_facade.py,sha256=mKxFD5tBGfM9gfTVyWG8DPdzUVQAg9_Y8iPseNSD3Ko,9280
+spotify_analytics_core-0.1.0.dist-info/METADATA,sha256=C-g-3QivlgkgFUIVDV_Jjxh7uBQ36CcbLrOfeIY30EM,1444
+spotify_analytics_core-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+spotify_analytics_core-0.1.0.dist-info/licenses/LICENSE,sha256=8OYV8_GXjvn_R1sxgJXYpbhLWc_b6Q33dRIwu54gBwM,1065
+spotify_analytics_core-0.1.0.dist-info/RECORD,,

spotify_analytics_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

spotify_analytics_core-0.1.0.dist-info/licenses/LICENSE

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

spotify_core/agent/graph.py

@@ -0,0 +1,26 @@
+from typing import Optional
+from langgraph.graph import StateGraph, END
+from .state import AgentState
+from .nodes import make_nodes
+
+def build_app(llm, tools_list: list, checkpointer=None, store=None):
+    """Build and compile the LangGraph workflow.
+
+    Args:
+        llm: LangChain LLM instance (ChatOpenAI or ChatGoogleGenerativeAI)
+        tools_list: List of LangChain tools from initialize_tools()
+        checkpointer: Optional SqliteSaver for short-term per-thread memory.
+        store: Optional SqliteStore for long-term cross-session memory.
+    """
+    tool_executor = {t.name: t for t in tools_list}
+    intent_parser, data_fetch, analyst_node, should_continue = make_nodes(llm, tools_list, tool_executor)
+
+    workflow = StateGraph(AgentState)
+    workflow.add_node("IntentParser", intent_parser)
+    workflow.add_node("ToolExecute", data_fetch)
+    workflow.add_node("Analyst", analyst_node)
+    workflow.set_entry_point("IntentParser")
+    workflow.add_conditional_edges("IntentParser", should_continue, {"continue": "ToolExecute", "end": "Analyst"})
+    workflow.add_edge("ToolExecute", "Analyst")
+    workflow.add_edge("Analyst", END)
+    return workflow.compile(checkpointer=checkpointer, store=store)

spotify_core/agent/nodes.py

@@ -0,0 +1,131 @@
+import json
+import logging
+from datetime import datetime
+from typing import Dict, Any, List
+from langchain_core.messages import ToolMessage, AIMessage
+
+from .state import AgentState
+from .schemas import IntentPlan, ToolPlan
+from .prompts import INTENT_PARSER_SYSTEM_PROMPT
+
+def make_nodes(llm, tools_list: list, tool_executor: dict):
+    """Factory that returns graph node functions bound to the given resources via closure."""
+
+    def intent_parser(state: AgentState) -> Dict[str, Any]:
+        """Parse the user's intent and generate a strategic execution plan."""
+        logger = logging.getLogger(f'{__name__}.intent_parser')
+        logger.info(f"Planning for input: {state['input']}")
+
+        if llm is None:
+            error_msg = "AI model not initialized. Please check your API key."
+            return {"intent": "other", "messages": [AIMessage(content=error_msg)], "final_response": error_msg}
+
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        full_system_prompt = INTENT_PARSER_SYSTEM_PROMPT + f"\n\nCurrent date and time: {now}."
+        plan = llm.with_structured_output(IntentPlan).invoke([
+            {"role": "system", "content": full_system_prompt},
+            {"role": "user", "content": state["input"]}
+        ])
+
+        if not plan:
+            raise ValueError("Failed to parse intent plan.")
+
+        logger.info(f"Intent parsed: {plan.intent_type} | Tools: {[tp.tool_name for tp in plan.tool_plan]}")
+        return {"intent": plan.intent_type, "plan": plan, "messages": [AIMessage(content=f"Strategy: {plan.reasoning}")]}
+
+    def data_fetch(state: AgentState) -> Dict[str, Any]:
+        """Execute tools based on the plan."""
+        logger = logging.getLogger(f'{__name__}.data_fetch')
+        plan = state.get("plan")
+        if not plan or not plan.tool_plan:
+            return {"messages": []}
+
+        planned_tool_names = [tp.tool_name for tp in plan.tool_plan]
+        available_tools = [t for t in tools_list if t.name in planned_tool_names]
+        if not available_tools:
+            return {"messages": [AIMessage(content="Planned tools are unavailable.")]}
+
+        llm_with_tools = llm.bind_tools(available_tools)
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        response = llm_with_tools.invoke([
+            {"role": "system", "content": f"You are a Spotify Tool Specialist. Context: {plan.reasoning}. Time: {now}. Only call provided tools."},
+            {"role": "user", "content": state["input"]}
+        ])
+
+        results, tool_messages = [], []
+        if hasattr(response, 'tool_calls') and response.tool_calls:
+            tool_messages.append(response)
+            for i, tool_call in enumerate(response.tool_calls):
+                tool_name = tool_call["name"]
+                if tool_name not in planned_tool_names:
+                    logger.warning(f"Hallucinated tool call: {tool_name}")
+                    continue
+                tool_obj = tool_executor.get(tool_name)
+                if tool_obj is None:
+                    logger.error(f"Tool '{tool_name}' in plan but not in executor. Skipping.")
+                    continue
+                call_id = tool_call.get("id", f"call_{i}")
+                retrieved_data, last_error = None, None
+                for attempt in range(3):
+                    try:
+                        retrieved_data = tool_obj.invoke(tool_call["args"])
+                        break
+                    except Exception as e:
+                        last_error = str(e)
+                        if attempt == 2:
+                            retrieved_data = f"Error after 3 attempts: {last_error}"
+                obs_str = str(retrieved_data)
+                if len(obs_str) > 1000:
+                    obs_str = obs_str[:1000] + "... [truncated]"
+                tool_messages.append(ToolMessage(content=obs_str, name=tool_name, tool_call_id=call_id))
+                results.append(retrieved_data)
+                logger.info(f"Tool {tool_name}: success={last_error is None}")
+        return {"messages": tool_messages, "tool_results": results}
+
+    def analyst_node(state: AgentState) -> Dict[str, Any]:
+        """Synthesize the final response."""
+        logger = logging.getLogger(f'{__name__}.analyst_node')
+        if state.get("final_response"):
+            return {"final_response": state["final_response"]}
+
+        intent = state.get("intent", "other")
+        plan = state.get("plan")
+
+        system_prompts = {
+            "factual_query": "You are a Spotify analytics assistant. Be direct, use bullet points.",
+            "insight_analysis": f"You are a Spotify music critic. Tell a story. Focus: {plan.analysis_focus if plan else ''}",
+            "recommendation": "You are a Spotify recommendation expert. Suggest music based on listening history.",
+        }
+        system_prompt = system_prompts.get(intent, "You are a Spotify analytics assistant.")
+
+        tool_messages = [m for m in state.get("messages", []) if isinstance(m, ToolMessage)]
+
+        if intent == "other" and (not plan or not plan.tool_plan):
+            response_content = plan.reasoning if plan else "I'm a Spotify analytics assistant and can't help with that."
+        else:
+            data_str = ""
+            if tool_messages:
+                tool_results = state.get("tool_results", [])
+                for i, msg in enumerate(tool_messages):
+                    result = tool_results[i] if i < len(tool_results) else msg.content
+                    formatted = json.dumps(result, indent=2) if isinstance(result, (list, dict)) else str(result)
+                    data_str += f"### Tool: {getattr(msg, 'name', f'Tool_{i}')}\n{formatted}\n\n"
+
+            messages = [{"role": "system", "content": system_prompt}]
+            if data_str:
+                messages.append({"role": "user", "content": f"Spotify data:\n<data>\n{data_str}\n</data>"})
+            messages.append({"role": "user", "content": f"Address my request: {state['input']}"})
+            response_content = llm.invoke(messages).content
+
+        logger.info(f"[Monitoring] Node: analyst_node | Intent: {intent} | Tools Used: {len(tool_messages) > 0}")
+        logger.info(f"Final response length: {len(response_content)}")
+        return {"final_response": response_content}
+
+    def should_continue(state: AgentState) -> str:
+        """Route: continue to ToolExecute or go to Analyst."""
+        plan = state.get("plan")
+        if plan and plan.tool_plan:
+            return "continue"
+        return "end"
+
+    return intent_parser, data_fetch, analyst_node, should_continue

spotify_core/agent/playback_tools.py

@@ -0,0 +1,22 @@
+"""LangChain-wrapped playback tools for agent integration."""
+from langchain_core.tools import tool
+
+from ..spotify_utils.spotify_facade import SpotifyToolFacade
+
+
+class AgentPlaybackTools(SpotifyToolFacade):
+    """SpotifyPlaybackTools with LangChain tool wrapping for agent integration."""
+
+    def get_tools(self) -> list:
+        """Return all playback/sync methods as LangChain tools."""
+        return [
+            tool(self.get_now_playing),
+            tool(self.get_devices),
+            tool(self.play_track),
+            tool(self.pause),
+            tool(self.skip),
+            tool(self.set_volume),
+            tool(self.add_to_queue),
+            tool(self.create_playlist),
+            tool(self.sync_recent_history),
+        ]

spotify_core/agent/prompts.py

@@ -0,0 +1,33 @@
+INTENT_PARSER_SYSTEM_PROMPT = """
+You are a Spotify Data Assistant Orchestrator.
+Your job is to:
+1. Understand the user's request.
+2. Select the most appropriate tools from the list below to fetch necessary data.
+3. Classify the user's intent to guide the downstream analyst.
+
+### Available Tools:
+- **get_summary_stats**: Get overall listening summary (total records, time, date range).
+- **get_top_artists**: Get top artists by listening time. Supports date range and limit.
+- **get_top_tracks**: Get top tracks by play count. Supports artist filter, date range, and limit.
+- **free_query**: Execute complex filtering on raw data (e.g., filter by specific day, hour, or multiple fields).
+- **free_aggregate**: Perform custom aggregations (e.g., grouping by month, track, or artist with custom metrics).
+3. Classify the user's intent to guide the downstream analyst.
+
+### Tool Selection Guidelines:
+- **ALWAYS prioritize specific tools** (`get_top_artists`, `get_summary_stats`) over generic ones.
+- Use `free_query` or `free_aggregate` ONLY when the request involves complex filtering that standard tools cannot handle.
+- If the user asks for "Recommendations", you usually need to fetch their `get_top_artists` and `get_top_tracks` first as a baseline.
+- You only need to provide the `tool_name` and `reasoning`. Downstream execution logic will handle the specific arguments.
+
+### Intent Classification Guidelines:
+- **factual_query**: The user wants raw numbers, lists, or specific facts. (e.g., "Count of my tracks", "Top 5 songs")
+- **insight_analysis**: The user asks about habits, trends, or "Why/How". (e.g., "Am I listening to sadder music?", "Compare my listening between 2023 and 2024")
+- **recommendation**: The user explicitly asks for new music suggestions.
+- **other**: Greetings or questions unrelated to Spotify data.
+
+### Output Format:
+You must call the relevant tools (if any) AND return the intent classification structure.
+"""
+
+# TODO: Implement dynamic injection of tool docstrings into INTENT_PARSER_SYSTEM_PROMPT
+# for better maintainability and accuracy as tool schemas evolve.

spotify_core/agent/resources.py

@@ -0,0 +1,27 @@
+"""Pure resource factory. No Streamlit dependency."""
+import logging
+from typing import Optional, Tuple
+from langchain_openai import ChatOpenAI
+from langchain_google_genai import ChatGoogleGenerativeAI
+from spotify_dataloader import SpotifyDataLoader
+from .tools import initialize_tools
+from ..config import settings
+
+logger = logging.getLogger(__name__)
+
+def build_llm(provider: str, api_key: str):
+    """Build LLM instance from provider name and API key."""
+    if provider.lower() == "gemini":
+        return ChatGoogleGenerativeAI(model=settings.gemini_model, google_api_key=api_key, temperature=0)
+    return ChatOpenAI(model=settings.openai_model, api_key=api_key, temperature=0)
+
+def build_resources(provider: str, api_key: str, loader: Optional[SpotifyDataLoader] = None):
+    """Build LLM, tools list, and tool executor dict.
+
+    Returns:
+        (llm, tools_list, tool_executor) tuple
+    """
+    llm = build_llm(provider, api_key)
+    tools_list = initialize_tools(loader=loader)
+    tool_executor = {t.name: t for t in tools_list}
+    return llm, tools_list, tool_executor

spotify_core/agent/schemas.py

@@ -0,0 +1,57 @@
+import pydantic
+from typing import List, Optional, Any, Dict, Literal
+from pydantic import Field
+
+class ToolPlan(pydantic.BaseModel):
+    """Plan for a single tool execution."""
+    tool_name: Literal[
+        "get_summary_stats",
+        "get_top_artists",
+        "get_top_tracks",
+        "free_query",
+        "free_aggregate"
+    ] = Field(
+        ...,
+        description="Name of the tool to be executed"
+    )
+    reasoning: str = Field(
+        default="",
+        description="Reasoning for why this tool is selected"
+    )
+    args: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Arguments for the tool (Optional, will be refined by downstream node)"
+    )
+
+class IntentPlan(pydantic.BaseModel):
+    """Execution plan generated by the Planner node."""
+    intent_type: Literal["factual_query", "insight_analysis", "recommendation", "other"] = Field(
+        ...,
+        description="The category of the user's request."
+    )
+    reasoning: str = Field(..., description="Brief reason why this intent was chosen.")
+    analysis_focus: str = Field(
+        default="",
+        description="If intent is analysis, what specific patterns should be looked at?"
+    )
+    tool_plan: List[ToolPlan] = Field(
+        default_factory=list,
+        description="Planned tools to execute in order"
+    )
+
+class ToolFreeQueryArgs(pydantic.BaseModel):
+    """Arguments for the free_query tool."""
+    where: Optional[str] = pydantic.Field(None, description="Polars filter expression as a string, e.g., \"pl.col('artist') == 'Taylor Swift'\"")
+    select: Optional[List[str]] = pydantic.Field(None, description="List of column names to include")
+    limit: Optional[int] = pydantic.Field(None, description="Maximum number of rows to return")
+    sort_by: Optional[str] = pydantic.Field(None, description="Column name to sort by")
+    descending: bool = pydantic.Field(True, description="Whether to sort in descending order")
+
+class ToolFreeAggrgateArgs(pydantic.BaseModel):
+    """Arguments for the free_aggregate tool."""
+    group_by: List[str] = pydantic.Field(..., description="List of column names to group by")
+    metrics: Dict[str, Any] = pydantic.Field(..., description="Dictionary mapping columns to aggregation functions (sum, mean, count, n_unique). Value can be a string or a (function, alias) tuple.")
+    where: Optional[str] = pydantic.Field(None, description="Polars filter expression as a string")
+    sort_by: Optional[str] = pydantic.Field(None, description="Column name to sort by")
+    descending: bool = pydantic.Field(True, description="Whether to sort in descending order")
+    limit: Optional[int] = pydantic.Field(None, description="Maximum number of rows to return")

spotify_core/agent/state.py

@@ -0,0 +1,14 @@
+import operator
+from typing import TypedDict, List, Literal, Annotated, Sequence, Optional, Any
+from langchain_core.messages import BaseMessage
+from .schemas import IntentPlan
+
+class AgentState(TypedDict):
+    input: str
+    messages: Annotated[Sequence[BaseMessage], operator.add]
+    intent: Optional[Literal['factual_query', 'insight_analysis', 'recommendation', 'other',
+                             'playback_control', 'playlist_create', 'sync_history']]
+    plan: Optional[IntentPlan]
+    tool_results: List[Optional[Any]] # e.g., the queries and their results
+    final_response: Optional[str]
+    retry_count: Optional[int]