sqlsaber 0.4.0__tar.gz → 0.5.0__tar.gz

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to SQLSaber will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Added support for plotting data from query results.
+  - The agent can decide if plotting will useful and create a plot with query results.
+- Small updates to system prompt
+
+## [0.4.1] - 2025-06-26
+
+### Added
+
+- Show connected database information at the start of a session
+- Update welcome message for clarity
+
 ## [0.4.0] - 2025-06-25
 
 ### Added

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlsaber
-Version: 0.4.0
+Version: 0.5.0
 Summary: SQLSaber - Agentic SQL assistant like Claude Code
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -16,6 +16,7 @@ Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: typer>=0.16.0
+Requires-Dist: uniplot>=0.21.2
 Description-Content-Type: text/markdown
 
 # SQLSaber
@@ -24,7 +25,28 @@ Description-Content-Type: text/markdown
 
 SQLSaber is an agentic SQL assistant. Think Claude Code but for SQL.
 
-Ask your questions in natural language and it will gather the right context and answer your query by writing SQL and analyzing the results.
+Ask your questions in natural language and it will gather the right context automatically and answer your query by writing SQL and analyzing the results.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Database Connection](#database-connection)
+  - [AI Model Configuration](#ai-model-configuration)
+  - [Memory Management](#memory-management)
+- [Usage](#usage)
+  - [Interactive Mode](#interactive-mode)
+  - [Single Query](#single-query)
+  - [Database Selection](#database-selection)
+- [Examples](#examples)
+- [MCP Server Integration](#mcp-server-integration)
+  - [Starting the MCP Server](#starting-the-mcp-server)
+  - [Configuring MCP Clients](#configuring-mcp-clients)
+  - [Available MCP Tools](#available-mcp-tools)
+- [How It Works](#how-it-works)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
@@ -39,16 +61,25 @@ Ask your questions in natural language and it will gather the right context and
 
 ## Installation
 
+### `uv`
+
 ```bash
 uv tool install sqlsaber
 ```
 
-or
+### `pipx`
 
 ```bash
 pipx install sqlsaber
 ```
 
+### `brew`
+
+```bash
+brew install uv
+uv tool install sqlsaber
+```
+
 ## Configuration
 
 ### Database Connection
@@ -151,7 +182,7 @@ SQLSaber includes an MCP (Model Context Protocol) server that allows AI agents l
 Run the MCP server using uvx:
 
 ```bash
-uvx saber-mcp
+uvx --from sqlsaber saber-mcp
 ```
 
 ### Configuring MCP Clients
@@ -161,12 +192,12 @@ uvx saber-mcp
 Add SQLSaber as an MCP server in Claude Code:
 
 ```bash
-claude mcp add -- uvx saber-mcp
+claude mcp add -- uvx --from sqlsaber saber-mcp
 ```
 
 #### Other MCP Clients
 
-For other MCP clients, configure them to run the command: `uvx saber-mcp`
+For other MCP clients, configure them to run the command: `uvx --from sqlsaber saber-mcp`
 
 ### Available MCP Tools
 

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/README.md

@@ -4,7 +4,28 @@
 
 SQLSaber is an agentic SQL assistant. Think Claude Code but for SQL.
 
-Ask your questions in natural language and it will gather the right context and answer your query by writing SQL and analyzing the results.
+Ask your questions in natural language and it will gather the right context automatically and answer your query by writing SQL and analyzing the results.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Database Connection](#database-connection)
+  - [AI Model Configuration](#ai-model-configuration)
+  - [Memory Management](#memory-management)
+- [Usage](#usage)
+  - [Interactive Mode](#interactive-mode)
+  - [Single Query](#single-query)
+  - [Database Selection](#database-selection)
+- [Examples](#examples)
+- [MCP Server Integration](#mcp-server-integration)
+  - [Starting the MCP Server](#starting-the-mcp-server)
+  - [Configuring MCP Clients](#configuring-mcp-clients)
+  - [Available MCP Tools](#available-mcp-tools)
+- [How It Works](#how-it-works)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
@@ -19,16 +40,25 @@ Ask your questions in natural language and it will gather the right context and
 
 ## Installation
 
+### `uv`
+
 ```bash
 uv tool install sqlsaber
 ```
 
-or
+### `pipx`
 
 ```bash
 pipx install sqlsaber
 ```
 
+### `brew`
+
+```bash
+brew install uv
+uv tool install sqlsaber
+```
+
 ## Configuration
 
 ### Database Connection
@@ -131,7 +161,7 @@ SQLSaber includes an MCP (Model Context Protocol) server that allows AI agents l
 Run the MCP server using uvx:
 
 ```bash
-uvx saber-mcp
+uvx --from sqlsaber saber-mcp
 ```
 
 ### Configuring MCP Clients
@@ -141,12 +171,12 @@ uvx saber-mcp
 Add SQLSaber as an MCP server in Claude Code:
 
 ```bash
-claude mcp add -- uvx saber-mcp
+claude mcp add -- uvx --from sqlsaber saber-mcp
 ```
 
 #### Other MCP Clients
 
-For other MCP clients, configure them to run the command: `uvx saber-mcp`
+For other MCP clients, configure them to run the command: `uvx --from sqlsaber saber-mcp`
 
 ### Available MCP Tools
 

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlsaber"
-version = "0.4.0"
+version = "0.5.0"
 description = "SQLSaber - Agentic SQL assistant like Claude Code"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -17,6 +17,7 @@ dependencies = [
     "aiosqlite>=0.21.0",
     "pandas>=2.0.0",
     "fastmcp>=2.9.0",
+    "uniplot>=0.21.2",
 ]
 
 [tool.uv]

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/agents/anthropic.py

@@ -82,6 +82,44 @@ class AnthropicSQLAgent(BaseSQLAgent):
                     "required": ["query"],
                 },
             },
+            {
+                "name": "plot_data",
+                "description": "Create a plot of query results.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "y_values": {
+                            "type": "array",
+                            "items": {"type": ["number", "null"]},
+                            "description": "Y-axis data points (required)",
+                        },
+                        "x_values": {
+                            "type": "array",
+                            "items": {"type": ["number", "null"]},
+                            "description": "X-axis data points (optional, will use indices if not provided)",
+                        },
+                        "plot_type": {
+                            "type": "string",
+                            "enum": ["line", "scatter", "histogram"],
+                            "description": "Type of plot to create (default: line)",
+                            "default": "line",
+                        },
+                        "title": {
+                            "type": "string",
+                            "description": "Title for the plot",
+                        },
+                        "x_label": {
+                            "type": "string",
+                            "description": "Label for X-axis",
+                        },
+                        "y_label": {
+                            "type": "string",
+                            "description": "Label for Y-axis",
+                        },
+                    },
+                    "required": ["y_values"],
+                },
+            },
         ]
 
         # Build system prompt with memories if available
@@ -96,13 +134,15 @@ Your responsibilities:
 1. Understand user's natural language requests, think and convert them to SQL
 2. Use the provided tools efficiently to explore database schema
 3. Generate appropriate SQL queries
-4. Execute queries safely (only SELECT queries unless explicitly allowed)
+4. Execute queries safely - queries that modify the database are not allowed
 5. Format and explain results clearly
+6. Create visualizations when requested or when they would be helpful
 
 IMPORTANT - Schema Discovery Strategy:
 1. ALWAYS start with 'list_tables' to see available tables and row counts
 2. Based on the user's query, identify which specific tables are relevant
 3. Use 'introspect_schema' with a table_pattern to get details ONLY for relevant tables
+4. Timestamp columns must be converted to text when you write queries
 
 Guidelines:
 - Use list_tables first, then introspect_schema for specific tables only
@@ -249,6 +289,15 @@ Guidelines:
                             "result": tool_result,
                         },
                     )
+                elif block["name"] == "plot_data":
+                    yield StreamEvent(
+                        "plot_result",
+                        {
+                            "tool_name": block["name"],
+                            "input": block["input"],
+                            "result": tool_result,
+                        },
+                    )
 
                 tool_results.append(build_tool_result_block(block["id"], tool_result))
 

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/agents/base.py

@@ -4,6 +4,8 @@ import json
 from abc import ABC, abstractmethod
 from typing import Any, AsyncIterator, Dict, List, Optional
 
+from uniplot import histogram, plot
+
 from sqlsaber.database.connection import (
     BaseDatabaseConnection,
     CSVConnection,
@@ -146,6 +148,15 @@ class BaseSQLAgent(ABC):
             return await self.execute_sql(
                 tool_input["query"], tool_input.get("limit", 100)
             )
+        elif tool_name == "plot_data":
+            return await self.plot_data(
+                y_values=tool_input["y_values"],
+                x_values=tool_input.get("x_values"),
+                plot_type=tool_input.get("plot_type", "line"),
+                title=tool_input.get("title"),
+                x_label=tool_input.get("x_label"),
+                y_label=tool_input.get("y_label"),
+            )
         else:
             return json.dumps({"error": f"Unknown tool: {tool_name}"})
 
@@ -182,3 +193,84 @@ class BaseSQLAgent(ABC):
         if query_upper.startswith("SELECT") and "LIMIT" not in query_upper:
             return f"{query.rstrip(';')} LIMIT {limit};"
         return query
+
+    async def plot_data(
+        self,
+        y_values: List[float],
+        x_values: Optional[List[float]] = None,
+        plot_type: str = "line",
+        title: Optional[str] = None,
+        x_label: Optional[str] = None,
+        y_label: Optional[str] = None,
+    ) -> str:
+        """Create a terminal plot using uniplot.
+
+        Args:
+            y_values: Y-axis data points
+            x_values: X-axis data points (optional)
+            plot_type: Type of plot - "line", "scatter", or "histogram"
+            title: Plot title
+            x_label: X-axis label
+            y_label: Y-axis label
+
+        Returns:
+            JSON string with success status and plot details
+        """
+        try:
+            # Validate inputs
+            if not y_values:
+                return json.dumps({"error": "No data provided for plotting"})
+
+            # Convert to floats if needed
+            try:
+                y_values = [float(v) if v is not None else None for v in y_values]
+                if x_values:
+                    x_values = [float(v) if v is not None else None for v in x_values]
+            except (ValueError, TypeError) as e:
+                return json.dumps({"error": f"Invalid data format: {str(e)}"})
+
+            # Create the plot
+            if plot_type == "histogram":
+                # For histogram, we only need y_values
+                histogram(
+                    y_values,
+                    title=title,
+                    bins=min(20, len(set(y_values))),  # Adaptive bin count
+                )
+                plot_info = {
+                    "type": "histogram",
+                    "data_points": len(y_values),
+                    "title": title or "Histogram",
+                }
+            elif plot_type in ["line", "scatter"]:
+                # For line/scatter plots
+                plot_kwargs = {
+                    "ys": y_values,
+                    "title": title,
+                    "lines": plot_type == "line",
+                }
+
+                if x_values:
+                    plot_kwargs["xs"] = x_values
+                if x_label:
+                    plot_kwargs["x_unit"] = x_label
+                if y_label:
+                    plot_kwargs["y_unit"] = y_label
+
+                plot(**plot_kwargs)
+
+                plot_info = {
+                    "type": plot_type,
+                    "data_points": len(y_values),
+                    "title": title or f"{plot_type.capitalize()} Plot",
+                    "has_x_values": x_values is not None,
+                }
+            else:
+                return json.dumps({"error": f"Unsupported plot type: {plot_type}"})
+
+            return json.dumps(
+                {"success": True, "plot_rendered": True, "plot_info": plot_info}
+            )
+
+        except Exception as e:
+            return json.dumps({"error": f"Error creating plot: {str(e)}"})

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/cli/commands.py

@@ -117,6 +117,9 @@ def query(
             if query_text:
                 # Single query mode with streaming
                 streaming_handler = StreamingQueryHandler(console)
+                console.print(
+                    f"[bold blue]Connected to:[/bold blue] {db_name} {agent._get_database_type_name()}\n"
+                )
                 await streaming_handler.execute_streaming_query(query_text, agent)
             else:
                 # Interactive mode

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/cli/display.py

@@ -205,3 +205,33 @@ class DisplayManager:
             self.show_error("Failed to parse schema data")
         except Exception as e:
             self.show_error(f"Error displaying schema information: {str(e)}")
+
+    def show_plot(self, plot_data: dict):
+        """Display plot information and status."""
+        try:
+            # Parse the result if it's a string
+            if isinstance(plot_data.get("result"), str):
+                result = json.loads(plot_data["result"])
+            else:
+                result = plot_data.get("result", {})
+
+            # Check if there was an error
+            if "error" in result:
+                self.show_error(f"Plot error: {result['error']}")
+                return
+
+            # If plot was successful, show plot info
+            if result.get("success") and result.get("plot_rendered"):
+                plot_info = result.get("plot_info", {})
+                self.console.print(
+                    f"\n[bold green]✓ Plot rendered:[/bold green] {plot_info.get('title', 'Plot')}"
+                )
+                self.console.print(
+                    f"[dim]  Type: {plot_info.get('type', 'unknown')}, "
+                    f"Data points: {plot_info.get('data_points', 0)}[/dim]"
+                )
+
+        except json.JSONDecodeError:
+            self.show_error("Failed to parse plot result")
+        except Exception as e:
+            self.show_error(f"Error displaying plot: {str(e)}")

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/cli/interactive.py

@@ -20,21 +20,24 @@ class InteractiveSession:
 
     def show_welcome_message(self):
         """Display welcome message for interactive mode."""
+        # Show database information
+        db_name = getattr(self.agent, "database_name", None) or "Unknown"
+        db_type = self.agent._get_database_type_name()
+
         self.console.print(
             Panel.fit(
                 "[bold green]SQLSaber - Use the agent Luke![/bold green]\n\n"
-                "Type your queries in natural language.\n\n"
-                "Press Esc-Enter or Meta-Enter to submit your query.\n\n"
-                "Type 'exit' or 'quit' to leave.",
+                "[bold]Your agentic SQL assistant.[/bold]\n\n\n"
+                "[dim]Use 'clear' to reset conversation, 'exit' or 'quit' to leave.[/dim]\n\n"
+                "[dim]Start a message with '#' to add something to agent's memory for this database.[/dim]",
                 border_style="green",
             )
         )
-
         self.console.print(
-            "[dim]Commands: 'clear' to reset conversation, 'exit' or 'quit' to leave[/dim]"
+            f"[bold blue]Connected to:[/bold blue] {db_name} ({db_type})\n"
         )
         self.console.print(
-            "[dim]Memory: Start a message with '#' to add it as a memory for this database[/dim]\n"
+            "[dim]Press Esc-Enter or Meta-Enter to submit your query.[/dim]\n"
         )
 
     async def run(self):

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/cli/streaming.py

@@ -63,6 +63,11 @@ class StreamingQueryHandler:
                         self.display.show_schema_info(event.data["result"])
                         has_content = True
 
+                elif event.type == "plot_result":
+                    # Handle plot results
+                    self.display.show_plot(event.data)
+                    has_content = True
+
                 elif event.type == "processing":
                     # Show status when processing tool results
                     if explanation_started:

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/src/sqlsaber/models/events.py

@@ -7,7 +7,7 @@ class StreamEvent:
     """Event emitted during streaming processing."""
 
     def __init__(self, event_type: str, data: Any = None):
-        # 'tool_use', 'text', 'query_result', 'error', 'processing'
+        # 'tool_use', 'text', 'query_result', 'plot_result', 'error', 'processing'
         self.type = event_type
         self.data = data
 

{sqlsaber-0.4.0 → sqlsaber-0.5.0}/uv.lock

@@ -774,6 +774,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ad/3f/11dd4cd4f39e05128bfd20138faea57bec56f9ffba6185d276e3107ba5b2/questionary-2.1.0-py3-none-any.whl", hash = "sha256:44174d237b68bc828e4878c763a9ad6790ee61990e0ae72927694ead57bab8ec", size = 36747 },
 ]
 
+[[package]]
+name = "readchar"
+version = "4.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/dd/f8/8657b8cbb4ebeabfbdf991ac40eca8a1d1bd012011bd44ad1ed10f5cb494/readchar-4.2.1.tar.gz", hash = "sha256:91ce3faf07688de14d800592951e5575e9c7a3213738ed01d394dcc949b79adb", size = 9685 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a9/10/e4b1e0e5b6b6745c8098c275b69bc9d73e9542d5c7da4f137542b499ed44/readchar-4.2.1-py3-none-any.whl", hash = "sha256:a769305cd3994bb5fa2764aa4073452dc105a4ec39068ffe6efd3c20c60acc77", size = 9350 },
+]
+
 [[package]]
 name = "rich"
 version = "14.0.0"
@@ -854,7 +863,7 @@ wheels = [
 
 [[package]]
 name = "sqlsaber"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiomysql" },
@@ -869,6 +878,7 @@ dependencies = [
     { name = "questionary" },
     { name = "rich" },
     { name = "typer" },
+    { name = "uniplot" },
 ]
 
 [package.dev-dependencies]
@@ -892,6 +902,7 @@ requires-dist = [
     { name = "questionary", specifier = ">=2.1.0" },
     { name = "rich", specifier = ">=13.7.0" },
     { name = "typer", specifier = ">=0.16.0" },
+    { name = "uniplot", specifier = ">=0.21.2" },
 ]
 
 [package.metadata.requires-dev]
@@ -971,6 +982,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/5c/23/c7abc0ca0a1526a0774eca151daeb8de62ec457e77262b66b359c3c7679e/tzdata-2025.2-py2.py3-none-any.whl", hash = "sha256:1a403fada01ff9221ca8044d701868fa132215d84beb92242d9acd2147f667a8", size = 347839 },
 ]
 
+[[package]]
+name = "uniplot"
+version = "0.21.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "numpy" },
+    { name = "readchar" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/87/65/b9db385152a5283c88f955710123c6539a7c79436d2de377b3449995b041/uniplot-0.21.2.tar.gz", hash = "sha256:fc350d6e0f2352822747a3426fef7f521d1b3973585ad2e2967c702dfc6e8440", size = 33412 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3a/0e/0b2e41841eb18017e7e125bc8294180d2597a4ca049641068f55355bcc69/uniplot-0.21.2-py3-none-any.whl", hash = "sha256:cae5875eac0d06fd75cbb7076ea3fa49565ef1d71140f0b9a39f7be96085536b", size = 36419 },
+]
+
 [[package]]
 name = "uvicorn"
 version = "0.34.3"