spotify-analytics-core 0.1.0__tar.gz

spotify_analytics_core-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Git worktrees
+.worktrees/
+.claude/worktrees/
+
+# Project specific
+# Vector database and user data
+data/vectordb/
+# sqlite databases and wal, shm files - ignore all but keep directory
+data/*.db*
+# Exclude user's actual Spotify data, but keep sample data
+data/spotify_history/*
+!data/spotify_history/sample_history.json
+# logs
+logs/
+# Internal planning docs (superpowers/Claude Code session artifacts)
+docs/superpowers/

spotify_analytics_core-0.1.0/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_analytics_core-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,3 @@
+# spotify-analytics-core
+
+Core analytics, agent, database, and Spotify client library for Spotify AI Analytics.

spotify_analytics_core-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "spotify-analytics-core"
+version = "0.1.0"
+description = "Core analytics, agent, and Spotify client library for the Spotify AI Analytics project."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+authors = [{ name = "WC Chang" }]
+requires-python = ">=3.12"
+keywords = ["spotify", "analytics", "mcp", "listening-history"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "cryptography>=42.0",
+    "httpx>=0.27",
+    "python-dotenv>=1.0",
+    "langgraph-checkpoint-sqlite>=3.0.3",
+    "platformdirs>=4.0",
+]
+
+[project.optional-dependencies]
+agent = [
+    "langgraph>=1.0",
+    "langchain-core>=1.0",
+    "langchain-openai>=1.0",
+    "langchain-google-genai>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/wcnoname5/spotify-ai-analytics"
+Repository = "https://github.com/wcnoname5/spotify-ai-analytics"
+Issues = "https://github.com/wcnoname5/spotify-ai-analytics/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spotify_core"]

spotify_analytics_core-0.1.0/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_analytics_core-0.1.0/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_analytics_core-0.1.0/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_analytics_core-0.1.0/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_analytics_core-0.1.0/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_analytics_core-0.1.0/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_analytics_core-0.1.0/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]