zaturn 0.1.2__tar.gz → 0.1.4__tar.gz

{zaturn-0.1.2 → zaturn-0.1.4}/.gitignore

@@ -10,5 +10,5 @@ wheels/
 .venv
 
 # Project Related
-sample_dbs/
-localtests.py
+debug.py
+todo.md

{zaturn-0.1.2/zaturn.egg-info → zaturn-0.1.4}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: zaturn
-Version: 0.1.2
+Version: 0.1.4
 Summary: AI Data Analysis MCP
 Author-email: Karthik Devan <krtdvn@gmail.com>
 Maintainer-email: Karthik Devan <krtdvn@gmail.com>
 Project-URL: Homepage, https://github.com/kdqed/zaturn
 Project-URL: Issues, https://github.com/kdqed/zaturn/issues
-Project-URL: CI, https://github.com/kdqed/zaturn/actions
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -25,15 +24,31 @@ Requires-Dist: sqlalchemy>=2.0.40
 Requires-Dist: tabulate>=0.9.0
 Dynamic: license-file
 
-<p align="center">
-  <img src="https://github.com/kdqed/zaturn/raw/main/brand/logo.png" width="128" height="128">
-</p>
+<h1>
+  <img src="https://github.com/kdqed/zaturn/raw/main/brand/logo.png" width="24" height="24">
+  <span>Zaturn: Your Co-Pilot For Data Analytics & Business Insights</span>
+</h1>
 
-# Zaturn: Your Co-Pilot For Data Analytics & BI
+Zaturn let's you analyze your data using AI chat; without needing you to write SQL/Python code or fiddling with aesthetically pleasing (but overwhelming) dashboards. 
+
+You can add Zaturn MCP to Claude Desktop (or any MCP client), connect your data sources, ask questions in natural language, and get instant insights with visualizations. With Zaturn, your AI can automatically understand the kind of data you have, query it, and give you useful pointers with a coherent narrative. You can ask specific questions like "Who is our most valuable customer?", or let AI explore your data with a question like "Here's all the data we have, give us some ideas for the next quarter."
+
+[![PyPI Downloads](https://static.pepy.tech/badge/zaturn)](https://pepy.tech/projects/zaturn) 
+
+[Join The Discord](https://discord.gg/K8mECeVzpQ)
 
-https://github.com/user-attachments/assets/d42dc433-e5ec-4b3e-bef0-5cfc097396ab
 
-Zaturn is an open source, AI-powered data analysis/BI tool that can connect to your data sources, run SQL queries on it, and give you useful insights. Think of it like vibe data analysis, in the spirit of vibe coding. Currently Zaturn is available as an MCP (Model Context Protocol) Server that can be integrated into your favorite MCP Client (Claude, Cursor, etc.) A full fledged notebook interface is on the roadmap.
+<a href="https://glama.ai/mcp/servers/@kdqed/zaturn">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@kdqed/zaturn/badge" alt="Zaturn MCP server" />
+</a>
+
+## But I can just upload my data to ChatGPT and ask it to analyze right?
+
+Yes, but ChatGPT has an upload size limit of approximately 50MB for CSV files/spreadsheets, and uploading also takes time. Plus, it can't read data straight from your MySQL or PostgreSQL server. Zaturn can overcome all of these limitations, without moving your data anywhere. It simply equips your AI with SQL and visualization capabilities so AI can query your data directly, get the results, process them, and give you instant insights. With Zaturn, AI does not need to process your full dataset and keep it in its memory to answer your questions about the data.
+
+## Zaturn in Action
+
+https://github.com/user-attachments/assets/d42dc433-e5ec-4b3e-bef0-5cfc097396ab
 
 ## Features:
 
@@ -59,12 +74,6 @@ In addition to providing tabular and textual summaries, Zaturn can also generate
 More visualization capabilities are being added.
 
 
-## How Does Zaturn Work?
-
-The naivest way to have an LLM analyze your data is to upload a dataset with a prompt. But that won't get you far, because AI has context window limitations, and it can only go through a few thousand rows at the best. Also, LLM's are not great at doing math.
-
-Using an MCP like Zaturn will keep your data where it is, and enable AI to draft and run SQL queries on the data. The LLM now processes only the queries and results instead of your entire dataset.
-
 ## Installation & Setup
 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/#installation-methods)
 
@@ -149,9 +158,15 @@ Analyst:
 ```
 - A native notebook interface 
 
-If you have any specific requirements please feel free to raise an issue.
+## Support And Feedback
+
+[Raise an issue](https://github.com/kdqed/zaturn/issues) or [join the Discord](https://discord.gg/K8mECeVzpQ).
 
 
 ## Example Dataset Credits
 
 The [pokemon dataset compiled by Sarah Taha and PokéAPI](https://www.kaggle.com/datasets/sarahtaha/1025-pokemon) has been included under the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license for demonstration purposes.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=kdqed/zaturn&type=Date)](https://www.star-history.com/#kdqed/zaturn&Date)

{zaturn-0.1.2 → zaturn-0.1.4}/README.md

@@ -1,12 +1,28 @@
-<p align="center">
-  <img src="https://github.com/kdqed/zaturn/raw/main/brand/logo.png" width="128" height="128">
-</p>
+<h1>
+  <img src="https://github.com/kdqed/zaturn/raw/main/brand/logo.png" width="24" height="24">
+  <span>Zaturn: Your Co-Pilot For Data Analytics & Business Insights</span>
+</h1>
 
-# Zaturn: Your Co-Pilot For Data Analytics & BI
+Zaturn let's you analyze your data using AI chat; without needing you to write SQL/Python code or fiddling with aesthetically pleasing (but overwhelming) dashboards. 
+
+You can add Zaturn MCP to Claude Desktop (or any MCP client), connect your data sources, ask questions in natural language, and get instant insights with visualizations. With Zaturn, your AI can automatically understand the kind of data you have, query it, and give you useful pointers with a coherent narrative. You can ask specific questions like "Who is our most valuable customer?", or let AI explore your data with a question like "Here's all the data we have, give us some ideas for the next quarter."
+
+[![PyPI Downloads](https://static.pepy.tech/badge/zaturn)](https://pepy.tech/projects/zaturn) 
+
+[Join The Discord](https://discord.gg/K8mECeVzpQ)
 
-https://github.com/user-attachments/assets/d42dc433-e5ec-4b3e-bef0-5cfc097396ab
 
-Zaturn is an open source, AI-powered data analysis/BI tool that can connect to your data sources, run SQL queries on it, and give you useful insights. Think of it like vibe data analysis, in the spirit of vibe coding. Currently Zaturn is available as an MCP (Model Context Protocol) Server that can be integrated into your favorite MCP Client (Claude, Cursor, etc.) A full fledged notebook interface is on the roadmap.
+<a href="https://glama.ai/mcp/servers/@kdqed/zaturn">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@kdqed/zaturn/badge" alt="Zaturn MCP server" />
+</a>
+
+## But I can just upload my data to ChatGPT and ask it to analyze right?
+
+Yes, but ChatGPT has an upload size limit of approximately 50MB for CSV files/spreadsheets, and uploading also takes time. Plus, it can't read data straight from your MySQL or PostgreSQL server. Zaturn can overcome all of these limitations, without moving your data anywhere. It simply equips your AI with SQL and visualization capabilities so AI can query your data directly, get the results, process them, and give you instant insights. With Zaturn, AI does not need to process your full dataset and keep it in its memory to answer your questions about the data.
+
+## Zaturn in Action
+
+https://github.com/user-attachments/assets/d42dc433-e5ec-4b3e-bef0-5cfc097396ab
 
 ## Features:
 
@@ -32,12 +48,6 @@ In addition to providing tabular and textual summaries, Zaturn can also generate
 More visualization capabilities are being added.
 
 
-## How Does Zaturn Work?
-
-The naivest way to have an LLM analyze your data is to upload a dataset with a prompt. But that won't get you far, because AI has context window limitations, and it can only go through a few thousand rows at the best. Also, LLM's are not great at doing math.
-
-Using an MCP like Zaturn will keep your data where it is, and enable AI to draft and run SQL queries on the data. The LLM now processes only the queries and results instead of your entire dataset.
-
 ## Installation & Setup
 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/#installation-methods)
 
@@ -122,9 +132,15 @@ Analyst:
 ```
 - A native notebook interface 
 
-If you have any specific requirements please feel free to raise an issue.
+## Support And Feedback
+
+[Raise an issue](https://github.com/kdqed/zaturn/issues) or [join the Discord](https://discord.gg/K8mECeVzpQ).
 
 
 ## Example Dataset Credits
 
 The [pokemon dataset compiled by Sarah Taha and PokéAPI](https://www.kaggle.com/datasets/sarahtaha/1025-pokemon) has been included under the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license for demonstration purposes.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=kdqed/zaturn&type=Date)](https://www.star-history.com/#kdqed/zaturn&Date)

zaturn-0.1.4/debug_server.py

@@ -0,0 +1,4 @@
+from zaturn import mcp
+
+if __name__=="__main__":
+    mcp.run(transport='sse')

{zaturn-0.1.2 → zaturn-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zaturn"
-version = "0.1.2"
+version = "0.1.4"
 description = "AI Data Analysis MCP"
 authors = [
   {name = "Karthik Devan", email = "krtdvn@gmail.com"},
@@ -32,7 +32,6 @@ zaturn_mcp = "zaturn:main"
 [project.urls]
 Homepage = "https://github.com/kdqed/zaturn"
 Issues = "https://github.com/kdqed/zaturn/issues"
-CI = "https://github.com/kdqed/zaturn/actions"
 
 [build-system]
 requires = [
@@ -45,7 +44,7 @@ build-backend = "setuptools.build_meta"
 include-package-data = false
 
 [tool.setuptools.packages.find]
-exclude = ["docs*", "brand*"]
+exclude = ["docs*", "brand*", "debug*"]
 include = ["zaturn*"]
 
 [tool.setuptools.package-data]

{zaturn-0.1.2 → zaturn-0.1.4}/uv.lock

@@ -1329,7 +1329,7 @@ wheels = [
 
 [[package]]
 name = "zaturn"
-version = "0.1.0"
+version = "0.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },

{zaturn-0.1.2 → zaturn-0.1.4}/zaturn/core.py

@@ -20,15 +20,17 @@ def list_sources() -> str:
         
         result = "Available data sources:\n\n"
         for source in config.SOURCES:
-            result += f"- {source}\n"
+            tables = _list_tables(source)
+            if type(tables) is List:
+                tables = ', '.join(tables)
+            result += f"- {source}\nHas tables: {tables}\n"
     
         return result
     except Exception as e:
         return str(e)
 
 
-@mcp.tool()
-def list_tables(source_id: str):
+def _list_tables(source_id: str):
     """
     Lists names of all tables/datasets in a given data source.
     Use run_query with appropriate SQL query to determine table structure
@@ -67,6 +69,43 @@ def list_tables(source_id: str):
     except Exception as e:
         return str(e)
 
+@mcp.tool()
+def describe_table(source_id: str, table_name: str) -> str:
+    """
+    Lists columns and their types in the specified table of specified data source.
+
+    Args:
+        source_id: The data source
+        table_name: The table in the data source
+    """
+    try:
+        source = config.SOURCES.get(source_id)
+        if not source:
+            return f"Source {source_id} Not Found"
+
+        match source['type']:
+            case 'sqlite':
+                result = query_utils.execute_query(source,
+                    f"PRAGMA table_info({table_name});"
+                )
+                return result.to_markdown(index=False)
+                
+            case 'postgresql':
+                result = query_utils.execute_query(source,
+                    f"SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name = '{table_name}';"
+                )
+                return result.to_markdown(index=False)
+                
+            case "mysql" | "duckdb" | "csv" | "parquet":
+                result = query_utils.execute_query(source,
+                    f"DESCRIBE {table_name};"
+                )
+                return result.to_markdown(index=False)
+    
+    except Exception as e:
+        return str(e)
+            
+
 @mcp.tool()
 def run_query(source_id: str, query: str) -> str:
     """

{zaturn-0.1.2 → zaturn-0.1.4}/zaturn/visualizations.py

@@ -1,4 +1,5 @@
 from fastmcp import FastMCP, Image
+import math
 import matplotlib.pyplot as plt
 import os
 import seaborn as sns
@@ -7,6 +8,7 @@ from typing import Any, Union, Optional
 from zaturn import config, query_utils
 
 sns.set_theme()
+sns.set_style('ticks')
 
 mcp = FastMCP("Zaturn Visualizations")
 
@@ -14,7 +16,7 @@ mcp = FastMCP("Zaturn Visualizations")
 def _plot_to_image(plot) -> Union[str, Image]:
     figure = plot.get_figure()
     filepath = os.path.join(config.VISUALS_DIR, str(int(time.time())) + '.png')
-    figure.savefig(filepath)
+    figure.savefig(filepath, bbox_inches='tight')
     plt.clf()
     if config.RETURN_IMAGES:
         return Image(path=filepath)
@@ -22,6 +24,47 @@ def _plot_to_image(plot) -> Union[str, Image]:
         return filepath
 
 
+def _fix_x_labels(plot, labels):
+    max_label_length = max(list(labels.map(lambda x: len(str(x)))))
+
+    LABEL_HIDE_FACTOR = 1
+    if len(labels) > 20:
+        LABEL_HIDE_FACTOR = math.ceil(len(labels)/20)
+
+    labels_to_show = list(labels)
+    ticks = list(plot.get_xticks()) 
+    if LABEL_HIDE_FACTOR > 1:
+        ticks = ticks[::LABEL_HIDE_FACTOR]
+        labels_to_show = labels_to_show[::LABEL_HIDE_FACTOR]
+            
+    plot.set_xticks(ticks, labels_to_show)
+    cutoff = 2 # for rotation
+    
+    if max_label_length >= 12:
+        cutoff = 3
+    elif max_label_length >= 10:
+        cutoff = 4
+    elif max_label_length >= 8:
+        cutoff = 5
+    elif max_label_length >= 7:
+        cutoff = 5
+    elif max_label_length >= 6:
+        cutoff = 6
+    elif max_label_length >= 5:
+        cutoff = 7
+    elif max_label_length >= 4:
+        cutoff = 9
+    elif max_label_length >= 3:
+        cutoff = 13
+    else:
+        cutoff = 15
+    
+    if len(labels)>cutoff:
+        plot.set_xticklabels(plot.get_xticklabels(), rotation=-45, ha='left', va='top')
+    
+    return plot
+
+
 # Relationships
 
 @mcp.tool()
@@ -42,6 +85,7 @@ def scatter_plot(
     """
     df = query_utils.load_query(query_id)
     plot = sns.scatterplot(df, x=x, y=y, hue=hue)
+    plot = _fix_x_labels(plot, df[x])
     return _plot_to_image(plot)
 
 
@@ -62,6 +106,7 @@ def line_plot(
     """
     df = query_utils.load_query(query_id)
     plot = sns.lineplot(df, x=x, y=y, hue=hue)
+    plot = _fix_x_labels(plot, df[x])
     return _plot_to_image(plot)
 
 
@@ -108,6 +153,7 @@ def strip_plot(
     """
     df = query_utils.load_query(query_id)
     plot = sns.stripplot(df, x=x, y=y, hue=hue, legend=legend)
+    plot = _fix_x_labels(plot, df[x])
     return _plot_to_image(plot)
 
 
@@ -128,6 +174,7 @@ def box_plot(
     """
     df = query_utils.load_query(query_id)
     plot = sns.boxplot(df, x=x, y=y, hue=hue)
+    plot = _fix_x_labels(plot, df[x])
     return _plot_to_image(plot)
 
 
@@ -150,6 +197,7 @@ def bar_plot(
     """
     df = query_utils.load_query(query_id)
     plot = sns.barplot(df, x=x, y=y, hue=hue, orient=orient)
+    plot = _fix_x_labels(plot, df[x])
     return _plot_to_image(plot)
 
 

{zaturn-0.1.2 → zaturn-0.1.4/zaturn.egg-info}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: zaturn
-Version: 0.1.2
+Version: 0.1.4
 Summary: AI Data Analysis MCP
 Author-email: Karthik Devan <krtdvn@gmail.com>
 Maintainer-email: Karthik Devan <krtdvn@gmail.com>
 Project-URL: Homepage, https://github.com/kdqed/zaturn
 Project-URL: Issues, https://github.com/kdqed/zaturn/issues
-Project-URL: CI, https://github.com/kdqed/zaturn/actions
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -25,15 +24,31 @@ Requires-Dist: sqlalchemy>=2.0.40
 Requires-Dist: tabulate>=0.9.0
 Dynamic: license-file
 
-<p align="center">
-  <img src="https://github.com/kdqed/zaturn/raw/main/brand/logo.png" width="128" height="128">
-</p>
+<h1>
+  <img src="https://github.com/kdqed/zaturn/raw/main/brand/logo.png" width="24" height="24">
+  <span>Zaturn: Your Co-Pilot For Data Analytics & Business Insights</span>
+</h1>
 
-# Zaturn: Your Co-Pilot For Data Analytics & BI
+Zaturn let's you analyze your data using AI chat; without needing you to write SQL/Python code or fiddling with aesthetically pleasing (but overwhelming) dashboards. 
+
+You can add Zaturn MCP to Claude Desktop (or any MCP client), connect your data sources, ask questions in natural language, and get instant insights with visualizations. With Zaturn, your AI can automatically understand the kind of data you have, query it, and give you useful pointers with a coherent narrative. You can ask specific questions like "Who is our most valuable customer?", or let AI explore your data with a question like "Here's all the data we have, give us some ideas for the next quarter."
+
+[![PyPI Downloads](https://static.pepy.tech/badge/zaturn)](https://pepy.tech/projects/zaturn) 
+
+[Join The Discord](https://discord.gg/K8mECeVzpQ)
 
-https://github.com/user-attachments/assets/d42dc433-e5ec-4b3e-bef0-5cfc097396ab
 
-Zaturn is an open source, AI-powered data analysis/BI tool that can connect to your data sources, run SQL queries on it, and give you useful insights. Think of it like vibe data analysis, in the spirit of vibe coding. Currently Zaturn is available as an MCP (Model Context Protocol) Server that can be integrated into your favorite MCP Client (Claude, Cursor, etc.) A full fledged notebook interface is on the roadmap.
+<a href="https://glama.ai/mcp/servers/@kdqed/zaturn">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@kdqed/zaturn/badge" alt="Zaturn MCP server" />
+</a>
+
+## But I can just upload my data to ChatGPT and ask it to analyze right?
+
+Yes, but ChatGPT has an upload size limit of approximately 50MB for CSV files/spreadsheets, and uploading also takes time. Plus, it can't read data straight from your MySQL or PostgreSQL server. Zaturn can overcome all of these limitations, without moving your data anywhere. It simply equips your AI with SQL and visualization capabilities so AI can query your data directly, get the results, process them, and give you instant insights. With Zaturn, AI does not need to process your full dataset and keep it in its memory to answer your questions about the data.
+
+## Zaturn in Action
+
+https://github.com/user-attachments/assets/d42dc433-e5ec-4b3e-bef0-5cfc097396ab
 
 ## Features:
 
@@ -59,12 +74,6 @@ In addition to providing tabular and textual summaries, Zaturn can also generate
 More visualization capabilities are being added.
 
 
-## How Does Zaturn Work?
-
-The naivest way to have an LLM analyze your data is to upload a dataset with a prompt. But that won't get you far, because AI has context window limitations, and it can only go through a few thousand rows at the best. Also, LLM's are not great at doing math.
-
-Using an MCP like Zaturn will keep your data where it is, and enable AI to draft and run SQL queries on the data. The LLM now processes only the queries and results instead of your entire dataset.
-
 ## Installation & Setup
 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/#installation-methods)
 
@@ -149,9 +158,15 @@ Analyst:
 ```
 - A native notebook interface 
 
-If you have any specific requirements please feel free to raise an issue.
+## Support And Feedback
+
+[Raise an issue](https://github.com/kdqed/zaturn/issues) or [join the Discord](https://discord.gg/K8mECeVzpQ).
 
 
 ## Example Dataset Credits
 
 The [pokemon dataset compiled by Sarah Taha and PokéAPI](https://www.kaggle.com/datasets/sarahtaha/1025-pokemon) has been included under the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license for demonstration purposes.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=kdqed/zaturn&type=Date)](https://www.star-history.com/#kdqed/zaturn&Date)

{zaturn-0.1.2 → zaturn-0.1.4}/zaturn.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 .gitignore
 LICENSE
 README.md
+debug_server.py
 pyproject.toml
 uv.lock
 brand/logo.png