zaturn 0.1.0__py3-none-any.whl

zaturn/__init__.py

@@ -0,0 +1,14 @@
+from fastmcp import FastMCP
+from zaturn import core, visualizations
+
+# Mount modules and make MCP
+mcp = FastMCP("Zaturn MCP")
+mcp.mount("core", core.mcp)
+mcp.mount("visualizations", visualizations.mcp)
+
+def main():
+    mcp.run()
+
+
+if __name__=="__main__":
+    main()

zaturn/config.py

@@ -0,0 +1,88 @@
+import argparse
+import os
+import platformdirs
+import sys
+
+# Basic Setup
+USER_DATA_DIR = platformdirs.user_data_dir('zaturn', 'zaturn')
+USER_CONFIG_DIR = platformdirs.user_config_dir('zaturn', 'zaturn')
+QUERIES_DIR = os.path.join(USER_DATA_DIR, 'queries')
+VISUALS_DIR = os.path.join(USER_DATA_DIR, 'visuals')
+SOURCES_FILE = os.path.join(USER_CONFIG_DIR, 'sources.txt')
+
+os.makedirs(USER_CONFIG_DIR, exist_ok=True)
+os.makedirs(QUERIES_DIR, exist_ok=True)
+os.makedirs(VISUALS_DIR, exist_ok=True)
+
+# Parse command line args
+parser = argparse.ArgumentParser(
+    description="Zaturn: A read-only BI tool for analyzing various data sources"
+)
+parser.add_argument('--noimg', action='store_const', 
+    const=True, default=False, 
+    help='Return image file paths instead of images for visuals. Use when MCP client cannot render images.',
+)
+parser.add_argument('sources', nargs=argparse.REMAINDER, default=[], 
+    help='Data source (can be specified multiple times). Can be SQLite, MySQL, PostgreSQL connection string, or a path to CSV, Parquet, or DuckDB file.'
+)
+args = parser.parse_args()
+
+# Read and parse sources
+source_list = []
+if os.path.exists(SOURCES_FILE):
+    with open(SOURCES_FILE) as f:
+        source_list = [line.strip('\n') for line in f.readlines() if line.strip('\n')]
+
+if not source_list:
+    source_list = args.sources
+
+if not source_list:
+    source_list = [os.path.join(os.getcwd(), 'example_data', 'all_pokemon_data.csv')]
+    print("No data sources provided. Loading example dataset for demonstration.")
+    print(f"\nTo load your datasets, add them to {SOURCES_FILE} (one source URL or full file path per line)")
+    print("\nOr use command line args to specify data sources:")
+    print("uv run --directory /path/to/zaturn mcp_server.py sqlite:///path/to/mydata.db")
+    print(f"\nNOTE: Sources in command line args will be ignored if sources are found in {SOURCES_FILE}")
+    
+SOURCES = {}
+for s in source_list:
+    source = s.lower()
+    if source.startswith('sqlite://'):
+        source_type = 'sqlite'
+        source_name = source.split('/')[-1].split('?')[0].split('.db')[0]
+    elif source.startswith('postgresql://'):
+        source_type = 'postgresql'
+        source_name = source.split('/')[-1].split('?')[0]
+    elif source.startswith("mysql+pymysql://"):
+        source_type = 'mysql'
+        source_name = source.split('/')[-1].split('?')[0]
+    elif source.endswith(".duckdb"):
+        source_type = "duckdb"
+        source_name = source.split('/')[-1].split('.')[0]
+    elif source.endswith(".csv"):
+        source_type = "csv"
+        source_name = source.split('/')[-1].split('.')[0]
+    elif source.endswith(".parquet"):
+        source_type = "parquet"
+        source_name = source.split('/')[-1].split('.')[0]
+    else:
+        continue
+
+    source_id = f'{source_name}-{source_type}'
+    if source_id in SOURCES:
+        i = 2
+        while True:
+            source_id = f'{source_name}{i}-{source_type}'
+            if source_id not in SOURCES:
+                break
+            i += 1
+
+    SOURCES[source_id] = {'url': s, 'type': source_type}
+
+
+# Other Settings
+RETURN_IMAGES = not args.noimg
+print(SOURCES)
+
+
+

zaturn/core.py

@@ -0,0 +1,101 @@
+from fastmcp import FastMCP
+import os
+from typing import Any, List, Union
+from zaturn import config, query_utils
+
+mcp = FastMCP("Zaturn Core")
+
+
+@mcp.tool()
+def list_sources() -> str:
+    """
+    List all available data sources.
+    Returns a list of unique source_ids to be used for other queries.
+    Source type is included in the source_id string.
+    While drafting SQL queries use appropriate syntax as per source type.
+    """
+    try:
+        if not config.SOURCES:
+            return "No data sources available. Add sources using the command line parameters."
+        
+        result = "Available data sources:\n\n"
+        for source in config.SOURCES:
+            result += f"- {source}\n"
+    
+        return result
+    except Exception as e:
+        return str(e)
+
+
+@mcp.tool()
+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
+    
+    Args:
+        source_id: The data source to list tables from
+    """
+    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,
+                    "SELECT name FROM sqlite_schema WHERE type ='table' AND name NOT LIKE 'sqlite_%';"
+                )
+                return result['name'].to_list()
+
+            case "postgresql":
+                result = query_utils.execute_query(source,
+                    "SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname != 'pg_catalog' AND schemaname != 'information_schema';"
+                )
+                return result['tablename'].to_list()
+
+            case "mysql":
+                result = query_utils.execute_query(source, "SHOW TABLES")
+                for col in list(result):
+                    if col.startswith("Tables_in_"):
+                        return result[col].to_list()
+                
+            case "duckdb" | "csv" | "parquet":
+                result = query_utils.execute_query(source, "SHOW TABLES")
+                return result['name'].to_list()
+
+    except Exception as e:
+        return str(e)
+
+@mcp.tool()
+def run_query(source_id: str, query: str) -> str:
+    """
+    Run query against specified source
+    For both csv and parquet sources, use DuckDB SQL syntax
+    Use 'CSV' as the table name for csv sources.
+    Use 'PARQUET' as the table name for parquet sources.
+
+    This will return a query_id, which can be referenced while calling other Zaturn tools.
+    Args:
+        source_id: The data source to run the query on
+        query: SQL query to run on the data source
+    """
+    try:
+        source = config.SOURCES.get(source_id)
+        if not source:
+            return f"Source {source_id} Not Found"
+            
+        df = query_utils.execute_query(source, query)
+        query_id = query_utils.save_query(df)
+        return query_id
+    except Exception as e:
+        return str(e)
+
+
+@mcp.tool()
+def show_query_result(query_id) -> str:
+    """
+    Show stored result for query_id in markdown table format
+    """
+    df = query_utils.load_query(query_id)
+    return df.to_markdown(index=False)

zaturn/query_utils.py

@@ -0,0 +1,80 @@
+import duckdb
+import numpy as np
+import os
+import pandas as pd
+import sqlalchemy
+from sqlalchemy.orm import Session
+import time
+from typing import List
+from zaturn import config
+
+
+def execute_query(source: dict, query: str):
+    """Run the query using the appropriate engine and read only config"""
+    url = source['url']
+    
+    match source['type']:
+        case "sqlite":
+            if "mode=ro" in url:
+                pass
+            elif '?' in url:
+                url += '&mode=ro'
+            else:
+                url += '?mode=ro'
+            with sqlalchemy.create_engine(url).connect() as conn:
+                result = conn.execute(sqlalchemy.text(query))
+                return pd.DataFrame(result)
+
+        case "mysql":
+            engine = sqlalchemy.create_engine(url)
+            with Session(engine) as session:
+                session.autoflush = False
+                session.autocommit = False
+                session.flush = lambda *args: None
+                result = session.execute(sqlalchemy.text(query))
+                return pd.DataFrame(result)
+
+        case "postgresql":
+            engine = sqlalchemy.create_engine(url)
+            with engine.connect() as conn:
+                conn = conn.execution_options(
+                    isolation_level="SERIALIZABLE",
+                    postgresql_readonly=True,
+                    postgresql_deferrable=True,
+                )
+                with conn.begin():
+                    result = conn.execute(sqlalchemy.text(query))
+                    return pd.DataFrame(result)
+
+        case "duckdb":
+            conn = duckdb.connect(url, read_only=True)
+            return conn.execute(query).df()
+
+        case "csv":
+            conn = duckdb.connect(database=':memory:')
+            conn.execute(f"CREATE VIEW CSV AS SELECT * FROM read_csv('{url}')")
+            return conn.execute(query).df()
+
+        case "parquet":
+            conn = duckdb.connect(database=':memory:')
+            conn.execute(f"CREATE VIEW PARQUET AS SELECT * FROM read_parquet('{url}')")
+            return conn.execute(query).df()
+        
+        case _:
+            raise Exception("Unsupported Source")
+
+
+def save_query(df: pd.DataFrame):
+    """Save query results to disk and return a unique reference id"""
+    query_id = 'q' + str(int(time.time()))
+    filepath = os.path.join(config.QUERIES_DIR, f'{query_id}.parquet')
+    df.replace({np.nan: None}).to_parquet(filepath, engine='pyarrow', index=False)
+    return query_id
+
+
+def load_query(query_id: str):
+    """Load query results from disk using unique reference id"""
+    filepath = os.path.join(config.QUERIES_DIR, f'{query_id}.parquet')
+    df = pd.read_parquet(filepath, engine='pyarrow').replace({np.nan: None})
+    df.reset_index(drop=True, inplace=True)
+    return df

zaturn/visualizations.py

@@ -0,0 +1,155 @@
+from fastmcp import FastMCP, Image
+import matplotlib.pyplot as plt
+import os
+import seaborn as sns
+import time
+from typing import Any, Union, Optional
+from zaturn import config, query_utils
+
+sns.set_theme()
+
+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)
+    plt.clf()
+    if config.RETURN_IMAGES:
+        return Image(path=filepath)
+    else:
+        return filepath
+
+
+# Relationships
+
+@mcp.tool()
+def scatter_plot(
+    query_id: str,
+    x: str,
+    y: str,
+    hue: str = None
+    ):
+    """
+    Make a scatter plot with the dataframe obtained from running SQL Query against source
+    If this returns an image, display it. If it returns a file path, mention it.
+    Args:
+        query_id: Previously run query to use for plotting
+        x: Column name from SQL result to use for x-axis
+        y: Column name from SQL result to use for y-axis
+        hue: Optional String; Column name from SQL result to use for coloring the points  
+    """
+    df = query_utils.load_query(query_id)
+    plot = sns.scatterplot(df, x=x, y=y, hue=hue)
+    return _plot_to_image(plot)
+
+
+@mcp.tool()
+def line_plot(
+    query_id: str,
+    x: str,
+    y: str,
+    hue: str = None
+    ):
+    """
+    Make a line plot with the dataframe obtained from running SQL Query against source
+    Args:
+        query_id: Previously run query to use for plotting
+        x: Column name from SQL result to use for x-axis
+        y: Column name from SQL result to use for y-axis
+        hue: Optional; column name from SQL result to use for drawing multiple colored lines
+    """
+    df = query_utils.load_query(query_id)
+    plot = sns.lineplot(df, x=x, y=y, hue=hue)
+    return _plot_to_image(plot)
+
+
+# Distributions
+
+@mcp.tool()
+def histogram(
+    query_id: str,
+    column: str,
+    hue: str = None,
+    bins: int = None
+    ):
+    """
+    Make a histogram with a column of the dataframe obtained from running SQL Query against source
+    Args:
+        query_id: Previously run query to use for plotting
+        column: Column name from SQL result to use for the histogram
+        hue: Optional; column name from SQL result to use for drawing multiple colored histograms
+        bins: Optional; number of bins
+    """
+    df = query_utils.load_query(query_id)
+    plot = sns.histplot(df, x=column, hue=hue, bins=bins)
+    return _plot_to_image(plot)
+
+
+# Categorical
+
+@mcp.tool()
+def strip_plot(
+    query_id: str,
+    x: str,
+    y: str = None,
+    hue: str = None,
+    legend: bool = False
+    ):
+    """
+    Make a strip plot with the dataframe obtained from running SQL Query against source
+    Args:
+        query_id: Previously run query to use for plotting
+        x: Column name from SQL result to use for x axis
+        y: Optional; column name from SQL result to use for y axis
+        hue: Optional; column name from SQL result to use for coloring the points
+        legend: Whether to draw a legend for the hue
+    """
+    df = query_utils.load_query(query_id)
+    plot = sns.stripplot(df, x=x, y=y, hue=hue, legend=legend)
+    return _plot_to_image(plot)
+
+
+@mcp.tool()
+def box_plot(
+    query_id: str,
+    x: str,
+    y: str = None,
+    hue: str = None
+    ):
+    """
+    Make a box plot with the dataframe obtained from running SQL Query against source
+    Args:
+        query_id: Previously run query to use for plotting
+        x: Column name from SQL result to use for x axis
+        y: Optional; column name from SQL result to use for y axis
+        hue: Optional column name from SQL result to use for coloring the points
+    """
+    df = query_utils.load_query(query_id)
+    plot = sns.boxplot(df, x=x, y=y, hue=hue)
+    return _plot_to_image(plot)
+
+
+@mcp.tool()
+def bar_plot(
+    query_id: str,
+    x: str,
+    y: str = None,
+    hue: str = None,
+    orient: str = 'v'
+    ):
+    """
+    Make a bar plot with the dataframe obtained from running SQL Query against source
+    Args:
+        query_id: Previously run query to use for plotting
+        x: Column name from SQL result to use for x axis
+        y: Optional; column name from SQL result to use for y axis
+        hue: Optional column name from SQL result to use for coloring the bars
+        orient: Orientation of the box plot, use 'v' for vertical and 'h' for horizontal
+    """
+    df = query_utils.load_query(query_id)
+    plot = sns.barplot(df, x=x, y=y, hue=hue, orient=orient)
+    return _plot_to_image(plot)
+
+

zaturn-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: zaturn
+Version: 0.1.0
+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: Changelog, https://github.com/kdqed/zaturn/releases
+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
+Requires-Dist: cryptography>=44.0.2
+Requires-Dist: duckdb>=1.2.1
+Requires-Dist: fastmcp>=0.4.1
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: platformdirs>=4.3.7
+Requires-Dist: psycopg2-binary>=2.9.10
+Requires-Dist: pyarrow>=19.0.1
+Requires-Dist: pymysql>=1.1.1
+Requires-Dist: python-lsp-server>=1.12.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: sqlalchemy>=2.0.40
+Requires-Dist: tabulate>=0.9.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="brand/logo.png" width="128" height="128">
+</p>
+
+# Zaturn: Your Co-Pilot For Data Analytics & BI
+
+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.
+
+## Features:
+
+### Multiple Data Sources 
+Zaturn can currently connect to the following data sources: 
+- SQL Databases: PostgreSQL, SQLite, DuckDB, MySQL
+- Files: CSV, Parquet
+
+Connectors for more data sources are being added.
+
+### Visualizations
+In addition to providing tabular and textual summaries, Zaturn can also generate the following image visualizations
+
+- Scatter and Line Plots
+- Histograms
+- Strip and Box Plots
+- Bar Plots
+
+> NOTE: The visuals will be shown only if your MCP client supports image rendering (e.g. Claude Desktop)
+> 
+> If you MCP client does not support images (e.g. Cursor) add the `--noimg` argument in the MCP config. Then the plots will be stored as files and the file location will be returned. You can view the plots with your file browser.
+
+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)
+
+2. Clone/Download this repository:
+```bash
+$ git clone https://github.com/kdqed/zaturn.git
+```
+
+3. Add to MCP config, with data sources:
+```json
+"mcpServers": {
+  "zaturn": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--directory",
+      "/path/to/downloaded/folder",
+      "mcp_server.py",
+      "mysql+pymysql://username:password@host:3306/dbname",
+      "postgresql://username:password@host:port/dbname",
+      "sqlite:////full/path/to/sample_dbs/northwind.db",
+      "/full/path/to/sample_dbs/titanic.parquet",
+      "/full/path/to/sample_dbs/ny_aq.csv",
+      "/full/path/to/sample_dbs/duckdb_sample.duckdb"
+    ]
+  },
+}
+```
+
+If your MCP client does not support images, add the `--noimg` flag after `mcp_server.py`:
+```json
+...
+      "mcp_server.py",
+      "--noimg",
+      "mysql+pymysql://username:password@host:3306/dbname",
+...
+```
+
+
+4. Set a system prompt if your LLM/IDE allows you to:
+```
+You are a helpful data analysis assistant. Use only the tool provided data sources to process user inputs. Do not use external sources or your own knowledge base.
+```
+
+5. Ask a question and watch the magic:
+```
+User: List the top 5 customers by revenue for Northwind
+AI: 
+[04/08/25 15:16:47] INFO     Processing request of type ListToolsRequest                                     server.py:534
+[04/08/25 15:16:51] INFO     Processing request of type CallToolRequest                                      server.py:534
+[04/08/25 15:16:53] INFO     Processing request of type CallToolRequest                                      server.py:534
+[04/08/25 15:16:55] INFO     Processing request of type CallToolRequest                                      server.py:534
+The top 5 customers by revenue for Northwind are:
+
+1. B's Beverages with a revenue of $6,154,115.34
+2. Hungry Coyote Import Store** with a revenue of $5,698,023.67
+3. Rancho grande with a revenue of $5,559,110.08
+4. Gourmet Lanchonetes with a revenue of $5,552,597.90
+5. Ana Trujillo Emparedados y helados with a revenue of $5,534,356.6
+```
+
+## Roadmap
+
+- Support for more data source types
+- More data visualizations
+- Predictive analysis and forecasting, e.g.:
+```
+Based on the revenue of the last 3 months, forecast next month's revenue.
+```
+- Generate Presentations & PDFs
+```
+Manager: 
+  I need a presentation to show the boss. Can you do it by EOD?
+Analyst: 
+  EOD?! Are you still in the 2010s? 
+  I can get it done right now. Actually, you can do it right now.
+  You know what? The boss can do it right now.
+```
+- A native notebook interface 
+
+If you have any specific requirements please feel free to raise an issue.
+
+
+## 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.

zaturn-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+zaturn/__init__.py,sha256=v4t5fkRuIJFE-SBxCa5pBjZv0EoC0eWK75nU9iaa7Rg,267
+zaturn/config.py,sha256=t11_sJxTsliTGpImveqmgjXWTDeijK8VMqqTPygEY7E,3154
+zaturn/core.py,sha256=sn2oliWVDqhYSAwSe5VbhNamaKAsnlrT3oc6uzffzs4,3267
+zaturn/query_utils.py,sha256=zyQjcRnPKGHZdf0XHzQeMxHw9vieZIwXhBbVGP87ml4,2801
+zaturn/visualizations.py,sha256=Dj08msgZ_DIMEVvJIlybT3cIA3GNkcXVOa9TJsHK2yo,4551
+zaturn-0.1.0.dist-info/licenses/LICENSE,sha256=mZSuFlbEBZGl0-8ULRMLdRDbhau5hrWRNQOjytYeaug,1070
+zaturn-0.1.0.dist-info/METADATA,sha256=_NI82YYMcGMc1Jz2OH6XmGwsoLUVpPB5zxvu0d1mCjM,5831
+zaturn-0.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+zaturn-0.1.0.dist-info/entry_points.txt,sha256=N1UZC2zvod92_Brs4A2xZiAnt-iGLBNryglXfwhxfj4,43
+zaturn-0.1.0.dist-info/top_level.txt,sha256=KLUnwQwVZkfd5YCnnqR35MOOs8KLhanPGelvmRo2MVA,7
+zaturn-0.1.0.dist-info/RECORD,,

zaturn-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zaturn-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zaturn_mcp = zaturn:main

zaturn-0.1.0.dist-info/licenses/LICENSE

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

zaturn-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zaturn