### Install Zaturn

Source: https://context7.com/kdqed/zaturn/llms.txt

Install Zaturn using pip or uv.

```bash
pip install zaturn
```

```bash
uv add zaturn
```

--------------------------------

### Launch Zaturn Studio

Source: https://context7.com/kdqed/zaturn/llms.txt

Start the Zaturn Studio web interface, which runs a Flask development server on http://localhost:6066.

```bash
zaturn_studio
```

--------------------------------

### Claude Desktop MCP Configuration

Source: https://context7.com/kdqed/zaturn/llms.txt

Example JSON configuration for setting up Zaturn as an MCP server in Claude Desktop.

```json
{
  "mcpServers": {
    "zaturn": {
      "command": "zaturn_mcp",
      "args": [
        "postgresql://user:password@localhost:5432/mydb",
        "/path/to/data.csv"
      ]
    }
  }
}
```

--------------------------------

### Launch `zaturn_mcp` with CLI data sources

Source: https://context7.com/kdqed/zaturn/llms.txt

Launch the MCP server with various data sources specified as command-line arguments. Supports SQLite, PostgreSQL, MySQL, SQL Server, ClickHouse, DuckDB, CSV, Parquet, and BigQuery. Multiple sources can be provided, or no arguments to use the demo dataset.

```bash
zaturn_mcp sqlite:///path/to/mydata.db
```

```bash
zaturn_mcp postgresql://user:password@localhost:5432/mydb
```

```bash
zaturn_mcp mysql://user:password@localhost:3306/mydb
```

```bash
zaturn_mcp mssql://user:password@localhost:1433/mydb
```

```bash
zaturn_mcp clickhouse://user:password@localhost:8123/mydb
```

```bash
zaturn_mcp /path/to/analytics.duckdb
```

```bash
zaturn_mcp /path/to/sales_data.csv
```

```bash
zaturn_mcp /path/to/events.parquet
```

```bash
zaturn_mcp bigquery://my-gcp-project/my_dataset
```

```bash
zaturn_mcp sqlite:///inventory.db postgresql://user:pass@host/analytics /data/logs.csv
```

```bash
zaturn_mcp
```

--------------------------------

### List Data Sources with `Core` Tool

Source: https://context7.com/kdqed/zaturn/llms.txt

Use the `list_data_sources` method from the `Core` class to list registered data sources and their tables. Requires a dictionary of sources and their configurations.

```python
from zaturn.tools.core import Core

sources = {
    "sales-csv": {"source_type": "csv", "url": "/data/sales.csv"},
    "warehouse-postgresql": {
        "source_type": "postgresql",
        "url": "postgresql://user:pass@localhost:5432/warehouse"
    },
}

core = Core(sources)
result = core.list_data_sources()
print(result)
```

--------------------------------

### Configure Persistent Sources via File

Source: https://context7.com/kdqed/zaturn/llms.txt

Configure persistent data sources by creating a `sources.txt` file. The file path is platform-dependent. Sources in this file take priority over CLI arguments.

```bash
cat > ~/.local/share/zaturn/zaturn/sources.txt <<EOF
postgresql://analyst:secret@db.example.com:5432/warehouse
/home/analyst/exports/daily_sales.csv
EOF
```

```bash
zaturn_mcp
```

--------------------------------

### Initialize ZaturnAgent for AI Data Analysis

Source: https://context7.com/kdqed/zaturn/llms.txt

Instantiate `ZaturnAgent` to leverage an OpenAI-compatible provider with integrated Zaturn tools. Configure endpoint, API key, model, tools, and optional reasoning effort and system prompt.

```python
from zaturn.studio.agent_wrapper import ZaturnAgent
from zaturn.tools import ZaturnTools

sources = {
    "sales-sqlite": {
        "source_type": "sqlite",
        "url": "sqlite:///sales.db"
    }
}

agent = ZaturnAgent(
    endpoint="https://api.openai.com/v1",
    api_key="sk-...",
    model_name="gpt-4o",
    tools=ZaturnTools(sources).tools,
    image_input=True,          # set True if model supports image inputs
    reasoning_effort="medium", # 'low' | 'medium' | 'high' | 'none'
    system_prompt="You are a helpful data analysis assistant.",
)

# Single-turn query
messages = agent.run("What are the top 5 products by revenue this quarter?")

# Multi-turn follow-up (pass previous messages as history)
messages = agent.run(
    prompt="Show that as a bar chart",
    message_history=messages,
)
```

--------------------------------

### Execute BigQuery Query

Source: https://context7.com/kdqed/zaturn/llms.txt

Connects to a BigQuery dataset using a service account and executes a SQL query. The service account path should be configured.

```python
source = {"source_type": "bigquery", "url": "bigquery://my-project/my_dataset"}
df = execute_query(source, "SELECT * FROM `my_table` LIMIT 50")
```

--------------------------------

### Describe Table Schema with `Core` Tool

Source: https://context7.com/kdqed/zaturn/llms.txt

Use the `describe_table` method from the `Core` class to retrieve column names and data types for a specific table within a source. The output is formatted as a Markdown table.

```python
from zaturn.tools.core import Core

sources = {
    "mydb-sqlite": {
        "source_type": "sqlite",
        "url": "sqlite:///mydb.sqlite"
    }
}

core = Core(sources)
result = core.describe_table(source_id="mydb-sqlite", table_name="orders")
print(result)
```

--------------------------------

### Execute ClickHouse Query

Source: https://context7.com/kdqed/zaturn/llms.txt

Connects to a ClickHouse database and executes a SQL query. Ensure read-only credentials are provided.

```python
source = {"source_type": "clickhouse", "url": "clickhouse://user:pass@host:8123/db"}
df = execute_query(source, "SELECT * FROM access_log LIMIT 100")
```

--------------------------------

### Generate Histogram with histogram

Source: https://context7.com/kdqed/zaturn/llms.txt

Renders a histogram from query results. Supports binning with `nbins` and multi-dimension coloring for stacked histograms.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "logs-duckdb": {
        "source_type": "duckdb",
        "url": "/data/analytics.duckdb"
    }
}

viz = Visualizations(sources)

image = viz.histogram(
    source_id="logs-duckdb",
    query="SELECT response_time_ms, endpoint FROM request_logs WHERE status = 200",
    column="response_time_ms",
    color="endpoint",   # optional: stacked histogram per endpoint
    nbins=50,           # optional: number of bins
)
```

--------------------------------

### Display DataFrame Head and Data Types

Source: https://context7.com/kdqed/zaturn/llms.txt

Prints the first few rows and the data types of a Pandas DataFrame. This is useful for inspecting query results.

```python
print(df.head())
print(df.dtypes)
```

--------------------------------

### Execute SQL Query with `execute_query`

Source: https://context7.com/kdqed/zaturn/llms.txt

Use `execute_query` for direct SQL execution against various data sources, returning results as a pandas DataFrame. Supports SQLite, PostgreSQL, CSV, and Parquet via DuckDB.

```python
from zaturn.tools.query_utils import execute_query

# SQLite (PRAGMA query_only = ON)
source = {"source_type": "sqlite", "url": "sqlite:///mydb.sqlite"}
df = execute_query(source, "SELECT * FROM customers LIMIT 10")

# PostgreSQL (SERIALIZABLE + postgresql_readonly=True)
source = {"source_type": "postgresql", "url": "postgresql://user:pass@host/db"}
df = execute_query(source, "SELECT product_id, SUM(qty) FROM line_items GROUP BY 1")

# CSV via DuckDB in-memory (use 'CSV' as table name)
source = {"source_type": "csv", "url": "/data/transactions.csv"}
df = execute_query(source, "SELECT customer_id, SUM(amount) FROM CSV GROUP BY customer_id")

# Parquet via DuckDB in-memory (use 'PARQUET' as table name)
source = {"source_type": "parquet", "url": "/data/events.parquet"}
df = execute_query(source, "SELECT date_trunc('day', ts) AS day, COUNT(*) FROM PARQUET GROUP BY 1")
```

--------------------------------

### Execute Read-Only SQL Query with run_query

Source: https://context7.com/kdqed/zaturn/llms.txt

Use `run_query` to execute read-only SQL queries against Parquet or PostgreSQL sources. For Parquet, use 'PARQUET' as the table name. Results are returned as a Markdown table.

```python
from zaturn.tools.core import Core

sources = {
    "events-parquet": {
        "source_type": "parquet",
        "url": "/data/events.parquet"
    },
    "app-postgresql": {
        "source_type": "postgresql",
        "url": "postgresql://readonly_user:pass@localhost:5432/appdb"
    },
}

core = Core(sources)

# Query a Parquet file using DuckDB SQL syntax, table name must be 'PARQUET'
result = core.run_query(
    source_id="events-parquet",
    query="SELECT event_type, COUNT(*) AS cnt FROM PARQUET GROUP BY event_type ORDER BY cnt DESC LIMIT 5"
)
print(result)
# | event_type   |   cnt |
# |:-------------|------:|
# | page_view    | 48302 |
# | click        | 21045 |
# | signup       |  3201 |
# | purchase     |  1892 |
# | logout       |   744 |

# Query PostgreSQL
result = core.run_query(
    source_id="app-postgresql",
    query="SELECT date_trunc('month', created_at) AS month, SUM(total_amount) AS revenue FROM orders GROUP BY 1 ORDER BY 1 DESC LIMIT 3"
)
print(result)
```

--------------------------------

### Generate Bar Chart with bar_plot

Source: https://context7.com/kdqed/zaturn/llms.txt

Creates a bar chart, supporting vertical ('v') and horizontal ('h') orientations. Use the `color` parameter for stacked bars.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "inventory-sqlite": {
        "source_type": "sqlite",
        "url": "sqlite:///inventory.db"
    }
}

viz = Visualizations(sources)

# Horizontal bar chart
image = viz.bar_plot(
    source_id="inventory-sqlite",
    query="SELECT category, SUM(units_sold) AS total_sold FROM products GROUP BY category ORDER BY total_sold DESC",
    x="total_sold",
    y="category",
    orientation="h",
)

# Vertical stacked bar chart
image = viz.bar_plot(
    source_id="inventory-sqlite",
    query="SELECT month, region, SUM(revenue) AS revenue FROM sales GROUP BY 1,2",
    x="month",
    y="revenue",
    color="region",
    orientation="v",
)
```

--------------------------------

### Generate Density Heatmap from SQL Query

Source: https://context7.com/kdqed/zaturn/llms.txt

Use `density_heatmap` to visualize data concentration across two numeric dimensions using a 2D histogram. Specify source ID, query, and columns for x and y axes, with optional bin counts.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "telemetry-parquet": {
        "source_type": "parquet",
        "url": "/data/telemetry.parquet"
    }
}

viz = Visualizations(sources)

image = viz.density_heatmap(
    source_id="telemetry-parquet",
    query="SELECT cpu_usage, memory_usage FROM PARQUET WHERE timestamp >= '2024-06-01'",
    column_x="cpu_usage",
    column_y="memory_usage",
    nbins_x=30,   # optional
    nbins_y=30,   # optional
)
```

--------------------------------

### Generate Line Plot with line_plot

Source: https://context7.com/kdqed/zaturn/llms.txt

Creates a line chart, ideal for time-series data. Use the optional `color` column to draw multiple colored lines per category. Renders results as a PNG image.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "sales-postgresql": {
        "source_type": "postgresql",
        "url": "postgresql://user:pass@localhost:5432/sales"
    }
}

viz = Visualizations(sources)

image = viz.line_plot(
    source_id="sales-postgresql",
    query="""
        SELECT date_trunc('week', order_date)::date AS week,
               region,
               SUM(revenue) AS total_revenue
        FROM orders
        WHERE order_date >= '2024-01-01'
        GROUP BY 1, 2
        ORDER BY 1
    """,
    x="week",
    y="total_revenue",
    color="region",   # draws one line per region
)
```

--------------------------------

### Generate Scatter Plot with scatter_plot

Source: https://context7.com/kdqed/zaturn/llms.txt

Renders query results as a scatter plot PNG. Maps a third column to point color using the optional `color` parameter. Returns an MCP `ImageContent` object.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "pokemon-csv": {
        "source_type": "csv",
        "url": "/path/to/all_pokemon_data.csv"
    }
}

viz = Visualizations(sources)

image = viz.scatter_plot(
    source_id="pokemon-csv",
    query="SELECT attack, defense, type1 FROM CSV WHERE legendary = false",
    x="attack",
    y="defense",
    color="type1",   # optional: color points by Pokémon type
)
# image.type == 'image'
# image.mimeType == 'image/png'
# image.data  -> base64-encoded PNG string
```

--------------------------------

### Generate Box Plot from SQL Query

Source: https://context7.com/kdqed/zaturn/llms.txt

Use `box_plot` to visualize distribution statistics from a SQL query. Requires specifying the source ID, SQL query, and columns for x, y, and optional color.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "hr-mysql": {
        "source_type": "mysql",
        "url": "mysql+pymysql://user:pass@localhost:3306/hr"
    }
}

viz = Visualizations(sources)

image = viz.box_plot(
    source_id="hr-mysql",
    query="SELECT department, salary FROM employees WHERE employment_status = 'active'",
    x="department",
    y="salary",
    color="department",   # optional
)
```

--------------------------------

### Generate Polar Scatter and Line Plots

Source: https://context7.com/kdqed/zaturn/llms.txt

Use `polar_scatter` for individual points or `polar_line` for closed lines in polar coordinates, suitable for cyclic data. Specify source ID, query, and columns for radius (r) and angle (theta), with optional color.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "wind-csv": {"source_type": "csv", "url": "/data/wind_readings.csv"}
}

viz = Visualizations(sources)

# Polar scatter
image = viz.polar_scatter(
    source_id="wind-csv",
    query="SELECT wind_speed, wind_direction, station FROM CSV",
    r="wind_speed",
    theta="wind_direction",
    color="station",   # optional
)

# Polar line (closed)
image = viz.polar_line(
    source_id="wind-csv",
    query="SELECT AVG(wind_speed) AS avg_speed, wind_direction FROM CSV GROUP BY wind_direction ORDER BY wind_direction",
    r="avg_speed",
    theta="wind_direction",
)
```

--------------------------------

### Conditional Chat Rendering Logic

Source: https://github.com/kdqed/zaturn/blob/main/zaturn/studio/templates/chat.html

This Jinja2 template code iterates through chat messages and their parts, rendering different components based on the 'part_kind' and 'kind' attributes. It handles system prompts, user prompts, AI responses, and tool returns. A fallback displays the entire chat object as JSON if the schema version is less than 1.

```html
{% if chat.get('schema_version', 0) >= 1 %} {% for message in chat['messages'] %} {% for part in message['parts'] %} {% if part['part_kind']=='system-prompt' %} {% include('chat_metadata.html') %} {% elif part['part_kind']=='user-prompt' %} {% include('user_message.html') %} {% elif part['part_kind']=='text' and message['kind']=='response' %} {% include('ai_message.html') %} {% elif part['part_kind']=='tool-return' %} {% include('function_call.html') %} {% endif %} {% endfor %} {% endfor %} {% include('icons/arrow-right.svg') %} {% include('loader.html') %} {% else %} {{chat | tojson(indent=2)}} {% endif %}
```

--------------------------------

### Generate Strip Plot from SQL Query

Source: https://context7.com/kdqed/zaturn/llms.txt

Use `strip_plot` to display individual data points from a SQL query. Useful for showing the full distribution and spread. Specify source ID, query, and columns for x, y, and color.

```python
from zaturn.tools.visualizations import Visualizations

sources = {
    "experiments-csv": {
        "source_type": "csv",
        "url": "/data/ab_test_results.csv"
    }
}

viz = Visualizations(sources)

image = viz.strip_plot(
    source_id="experiments-csv",
    query="SELECT variant, conversion_rate FROM CSV",
    x="variant",
    y="conversion_rate",
    color="variant",
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.