sqlsaber 0.20.0__tar.gz → 0.22.0__tar.gz

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlsaber
-Version: 0.20.0
+Version: 0.22.0
 Summary: SQLsaber - Open-source agentic SQL assistant
 License-File: LICENSE
 Requires-Python: >=3.12

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/docs/src/content/docs/changelog.md

@@ -7,6 +7,23 @@ All notable changes to SQLsaber will be documented here.
 
 ### Unreleased
 
+### v0.22.0 - 2025-09-15
+
+#### Added
+
+- Query timeout protection to prevent runaway queries
+  - 30-second timeout applied to all database operations by default
+  - Both client-side and server-side timeout enforcement where supported (PostgreSQL, MySQL)
+  - Per-query timeout override parameter for edge cases
+  - Automatic rollback of transactions when queries timeout
+
+### v0.21.0 - 2025-09-15
+
+#### Changed
+
+- Use Responses API for OpenAI models
+- Stream markdown while streaming response from models
+
 ---
 
 ### v0.20.0 - 2025-09-10

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/docs/src/content/docs/guides/getting-started.mdx

@@ -3,8 +3,7 @@ title: Getting Started
 description: Your first steps with SQLsaber
 ---
 
-import { Aside } from '@astrojs/starlight/components';
-
+import { Aside } from "@astrojs/starlight/components";
 
 Welcome to SQLsaber! This guide will walk you through setting up SQLsaber and running your first query.
 
@@ -27,15 +26,18 @@ saber auth setup
 ```
 
 This will prompt you to:
+
 - Choose a provider (We recommend Anthropic)
 - Enter your API key
 
 <Aside type="tip">
-If you have a Claude Pro or Max subscription, you can use it with SQLsaber. It is one of the most cost-effective options.
+  If you have a Claude Pro or Max subscription, you can use it with SQLsaber. It
+  is one of the most cost-effective options.
 </Aside>
 
 <Aside type="note">
-    If you choose a provider other than Anthropic, please select the appropriate model for the provider by running `saber models set`.
+  If you choose a provider other than Anthropic, please select the appropriate
+  model for the provider by running `saber models set`.
 </Aside>
 
 #### 2. Add Your Database
@@ -47,10 +49,11 @@ saber db add my-database
 ```
 
 This interactive command will ask you for:
+
 - Database type
-    - PostgreSQL
-    - MySQL
-    - SQLite
+  - PostgreSQL
+  - MySQL
+  - SQLite
 - Connection details (host, port, database name, username)
 - SSL configuration (if needed)
 
@@ -63,6 +66,7 @@ curl -L -o legislators.db https://github.com/SarthakJariwala/sqlsaber/raw/refs/h
 # Add it to SQLsaber
 saber db add legislators --type sqlite --database ./legislators.db
 ```
+
 </Aside>
 
 #### 3. Your First Query
@@ -82,14 +86,15 @@ Try asking a question:
 ```
 
 SQLsaber will:
+
 1. Analyze your database schema
 2. Generate appropriate SQL
 3. Execute the query
 4. Present the results and analysis
 
 <script
-  src="https://asciinema.org/a/739273.js"
-  id="asciicast-739273"
+  src="https://asciinema.org/a/739399.js"
+  id="asciicast-739399"
   async="true"
 ></script>
 
@@ -142,18 +147,21 @@ Now that you have SQLsaber running, explore these features:
 #### Common Issues
 
 **"No database connections configured"**
+
 ```bash
 saber db list  # Check configured databases
 saber db add my-db  # Add a new database
 ```
 
 **"Authentication not configured"**
+
 ```bash
 saber auth status  # Check auth status
 saber auth setup   # Set up authentication
 ```
 
 **"Database connection failed"**
+
 ```bash
 saber db test my-database  # Test the connection
 ```

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/docs/src/content/docs/guides/queries.mdx

@@ -3,7 +3,7 @@ title: Running Queries
 description: Learn different ways to query your data with SQLsaber
 ---
 
-import { Aside } from '@astrojs/starlight/components';
+import { Aside } from "@astrojs/starlight/components";
 
 SQLsaber offers multiple ways to query your database using natural language. This guide covers all the different query modes and their use cases.
 
@@ -16,8 +16,8 @@ saber
 ```
 
 <script
-  src="https://asciinema.org/a/739273.js"
-  id="asciicast-739273"
+  src="https://asciinema.org/a/739399.js"
+  id="asciicast-739399"
   async="true"
 ></script>
 
@@ -30,6 +30,7 @@ saber "How many orders were placed last week?"
 ```
 
 Useful for:
+
 - Shell scripting
 - Quick checks
 - Automated reporting
@@ -50,6 +51,7 @@ curl -s https://api.example.com/query | saber
 ```
 
 Useful for:
+
 - Shell scripting
 - Batch processing
 - Integration with other tools
@@ -82,6 +84,7 @@ Type `@` followed by a table name to get autocomplete suggestions:
 ```
 
 Supports schema-aware completions:
+
 ```
 > @pub[TAB] → @public.customers
 ```

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/docs/src/content/docs/index.mdx

@@ -25,8 +25,8 @@ import {
 } from "@astrojs/starlight/components";
 
 <script
-  src="https://asciinema.org/a/739273.js"
-  id="asciicast-739273"
+  src="https://asciinema.org/a/739399.js"
+  id="asciicast-739399"
   async="true"
 ></script>
 

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlsaber"
-version = "0.20.0"
+version = "0.22.0"
 description = "SQLsaber - Open-source agentic SQL assistant"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/src/sqlsaber/agents/pydantic_ai_agent.py

@@ -8,6 +8,7 @@ import httpx
 from pydantic_ai import Agent, RunContext
 from pydantic_ai.models.anthropic import AnthropicModel
 from pydantic_ai.models.google import GoogleModel
+from pydantic_ai.models.openai import OpenAIResponsesModel
 from pydantic_ai.providers.anthropic import AnthropicProvider
 from pydantic_ai.providers.google import GoogleProvider
 
@@ -79,6 +80,10 @@ def build_sqlsaber_agent(
         provider_obj = AnthropicProvider(api_key="placeholder", http_client=http_client)
         model_obj = AnthropicModel(model_name_only, provider=provider_obj)
         agent = Agent(model_obj, name="sqlsaber")
+    elif provider == "openai":
+        # Use OpenAI Responses Model for structured output capabilities
+        model_obj = OpenAIResponsesModel(model_name_only)
+        agent = Agent(model_obj, name="sqlsaber")
     else:
         agent = Agent(cfg.model_name, name="sqlsaber")
 

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/src/sqlsaber/cli/display.py

@@ -1,12 +1,167 @@
-"""Display utilities for the CLI interface."""
+"""Display utilities for the CLI interface.
+
+All rendering occurs on the event loop thread.
+Streaming segments use Live Markdown; transient status and SQL blocks are also
+rendered with Live.
+"""
 
 import json
+from typing import Sequence, Type
 
-from rich.console import Console
-from rich.markdown import Markdown
+from pydantic_ai.messages import ModelResponsePart, TextPart
+from rich.columns import Columns
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.live import Live
+from rich.markdown import CodeBlock, Markdown
 from rich.panel import Panel
+from rich.spinner import Spinner
 from rich.syntax import Syntax
 from rich.table import Table
+from rich.text import Text
+
+
+class _SimpleCodeBlock(CodeBlock):
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        code = str(self.text).rstrip()
+        yield Syntax(
+            code,
+            self.lexer_name,
+            theme=self.theme,
+            background_color="default",
+            word_wrap=True,
+        )
+
+
+class LiveMarkdownRenderer:
+    """Handles Live markdown rendering with segment separation.
+
+    Supports different segment kinds: 'assistant', 'thinking', 'sql'.
+    Adds visible paragraph breaks between segments and renders code fences
+    with nicer formatting.
+    """
+
+    _patched_fences = False
+
+    def __init__(self, console: Console):
+        self.console = console
+        self._live: Live | None = None
+        self._status_live: Live | None = None
+        self._buffer: str = ""
+        self._current_kind: Type[ModelResponsePart] | None = None
+
+    def prepare_code_blocks(self) -> None:
+        """Patch rich Markdown fence rendering once for nicer code blocks."""
+        if LiveMarkdownRenderer._patched_fences:
+            return
+        # Guard with class check to avoid re-patching if already applied
+        if Markdown.elements.get("fence") is not _SimpleCodeBlock:
+            Markdown.elements["fence"] = _SimpleCodeBlock
+        LiveMarkdownRenderer._patched_fences = True
+
+    def ensure_segment(self, kind: Type[ModelResponsePart]) -> None:
+        """
+        Ensure a markdown Live segment is active for the given kind.
+
+        When switching kinds, end the previous segment and add a paragraph break.
+        """
+        # If a transient status is showing, clear it first (no paragraph break)
+        if self._status_live is not None:
+            self.end_status()
+        if self._live is not None and self._current_kind == kind:
+            return
+        if self._live is not None:
+            self.end()
+            self.paragraph_break()
+
+        self._start()
+        self._current_kind = kind
+
+    def append(self, text: str | None) -> None:
+        """Append text to the current markdown segment and refresh."""
+        if not text:
+            return
+        if self._live is None:
+            # default to assistant if no segment was ensured
+            self.ensure_segment(TextPart)
+
+        self._buffer += text
+        self._live.update(Markdown(self._buffer))
+
+    def end(self) -> None:
+        """Finalize and stop the current Live segment, if any."""
+        if self._live is None:
+            return
+        if self._buffer:
+            self._live.update(Markdown(self._buffer))
+        self._live.stop()
+        self._live = None
+        self._buffer = ""
+        self._current_kind = None
+
+    def end_if_active(self) -> None:
+        self.end()
+
+    def paragraph_break(self) -> None:
+        self.console.print()
+
+    def start_sql_block(self, sql: str) -> None:
+        """Render a SQL block using a transient Live markdown segment."""
+        if not sql or not isinstance(sql, str) or not sql.strip():
+            return
+        # Separate from surrounding content
+        self.end_if_active()
+        self.paragraph_break()
+        self._buffer = f"```sql\n{sql}\n```"
+        # Use context manager to auto-stop and persist final render
+        with Live(
+            Markdown(self._buffer),
+            console=self.console,
+            vertical_overflow="visible",
+            refresh_per_second=12,
+        ):
+            pass
+
+    def start_status(self, message: str = "Crunching data...") -> None:
+        """Show a transient status line with a spinner until streaming starts."""
+        if self._status_live is not None:
+            # Update existing status text
+            self._status_live.update(self._status_renderable(message))
+            return
+        live = Live(
+            self._status_renderable(message),
+            console=self.console,
+            transient=True,  # disappear when stopped
+            refresh_per_second=12,
+        )
+        self._status_live = live
+        live.start()
+
+    def end_status(self) -> None:
+        live = self._status_live
+        if live is None:
+            return
+        live.stop()
+        self._status_live = None
+
+    def _status_renderable(self, message: str):
+        spinner = Spinner("dots", style="yellow")
+        text = Text(f" {message}", style="yellow")
+        return Columns([spinner, text], expand=False)
+
+    def _start(self, initial_markdown: str = "") -> None:
+        if self._live is not None:
+            self.end()
+        self._buffer = initial_markdown or ""
+        live = Live(
+            Markdown(self._buffer),
+            console=self.console,
+            vertical_overflow="visible",
+            refresh_per_second=12,
+        )
+        self._live = live
+        live.start()
 
 
 class DisplayManager:
@@ -14,10 +169,11 @@ class DisplayManager:
 
     def __init__(self, console: Console):
         self.console = console
+        self.live = LiveMarkdownRenderer(console)
 
     def _create_table(
         self,
-        columns: list,
+        columns: Sequence[str | dict[str, str]],
         header_style: str = "bold blue",
         title: str | None = None,
     ) -> Table:
@@ -34,17 +190,24 @@ class DisplayManager:
 
     def show_tool_executing(self, tool_name: str, tool_input: dict):
         """Display tool execution details."""
-        self.console.print(f"\n[yellow]🔧 Using tool: {tool_name}[/yellow]")
+        # Normalized leading blank line before tool headers
+        self.show_newline()
         if tool_name == "list_tables":
-            self.console.print("[dim]  → Discovering available tables[/dim]")
+            self.console.print(
+                "[dim bold]:gear: Discovering available tables[/dim bold]"
+            )
         elif tool_name == "introspect_schema":
             pattern = tool_input.get("table_pattern", "all tables")
-            self.console.print(f"[dim]  → Examining schema for: {pattern}[/dim]")
+            self.console.print(
+                f"[dim bold]:gear: Examining schema for: {pattern}[/dim bold]"
+            )
         elif tool_name == "execute_sql":
+            # For streaming, we render SQL via LiveMarkdownRenderer; keep Syntax
+            # rendering for threads show/resume. Controlled by include_sql flag.
             query = tool_input.get("query", "")
-            self.console.print("\n[bold green]Executing SQL:[/bold green]")
+            self.console.print("[dim bold]:gear: Executing SQL:[/dim bold]")
             self.show_newline()
-            syntax = Syntax(query, "sql")
+            syntax = Syntax(query, "sql", background_color="default", word_wrap=True)
             self.console.print(syntax)
 
     def show_text_stream(self, text: str):
@@ -99,10 +262,12 @@ class DisplayManager:
         """Display a newline for spacing."""
         self.console.print()
 
-    def show_table_list(self, tables_data: str):
+    def show_table_list(self, tables_data: str | dict):
         """Display the results from list_tables tool."""
         try:
-            data = json.loads(tables_data)
+            data = (
+                json.loads(tables_data) if isinstance(tables_data, str) else tables_data
+            )
 
             # Handle error case
             if "error" in data:
@@ -143,10 +308,12 @@ class DisplayManager:
         except Exception as e:
             self.show_error(f"Error displaying table list: {str(e)}")
 
-    def show_schema_info(self, schema_data: str):
+    def show_schema_info(self, schema_data: str | dict):
         """Display the results from introspect_schema tool."""
         try:
-            data = json.loads(schema_data)
+            data = (
+                json.loads(schema_data) if isinstance(schema_data, str) else schema_data
+            )
 
             # Handle error case
             if "error" in data:

{sqlsaber-0.20.0 → sqlsaber-0.22.0}/src/sqlsaber/cli/interactive.py

@@ -2,6 +2,7 @@
 
 import asyncio
 from pathlib import Path
+from textwrap import dedent
 
 import platformdirs
 from prompt_toolkit import PromptSession
@@ -10,6 +11,7 @@ from prompt_toolkit.patch_stdout import patch_stdout
 from prompt_toolkit.styles import Style
 from pydantic_ai import Agent
 from rich.console import Console
+from rich.markdown import Markdown
 from rich.panel import Panel
 
 from sqlsaber.cli.completers import (
@@ -102,14 +104,14 @@ class InteractiveSession:
                 )
             )
             self.console.print(
-                "\n",
-                "[dim] > Use '/clear' to reset conversation",
-                "[dim] > Use 'Ctrl+D', '/exit' or '/quit' to leave[/dim]",
-                "[dim] > Use 'Ctrl+C' to interrupt and return to prompt\n\n",
-                "[dim] > Start message with '#' to add something to agent's memory for this database",
-                "[dim] > Type '@' to get table name completions",
-                "[dim] > Press 'Esc-Enter' or 'Meta-Enter' to submit your question",
-                sep="\n",
+                Markdown(
+                    dedent("""
+                    - Use `/` for slash commands
+                    - Type `@` to get table name completions
+                    - Start message with `#` to add something to agent's memory
+                    - Use `Ctrl+C` to interrupt and `Ctrl+D` to exit
+                    """)
+                )
             )
 
         self.console.print(

sqlsaber-0.22.0/src/sqlsaber/cli/streaming.py

@@ -0,0 +1,176 @@
+"""Streaming query handling for the CLI (pydantic-ai based).
+
+This module uses DisplayManager's LiveMarkdownRenderer to stream Markdown
+incrementally as the agent outputs tokens. Tool calls and results are
+rendered via DisplayManager helpers.
+"""
+
+import asyncio
+import json
+from functools import singledispatchmethod
+from typing import AsyncIterable
+
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.messages import (
+    AgentStreamEvent,
+    FunctionToolCallEvent,
+    FunctionToolResultEvent,
+    PartDeltaEvent,
+    PartStartEvent,
+    TextPart,
+    TextPartDelta,
+    ThinkingPart,
+    ThinkingPartDelta,
+)
+from rich.console import Console
+
+from sqlsaber.cli.display import DisplayManager
+
+
+class StreamingQueryHandler:
+    """
+    Handles streaming query execution and display using pydantic-ai events.
+
+    Uses DisplayManager.live to render Markdown incrementally as text streams in.
+    """
+
+    def __init__(self, console: Console):
+        self.console = console
+        self.display = DisplayManager(console)
+
+    async def _event_stream_handler(
+        self, ctx: RunContext, event_stream: AsyncIterable[AgentStreamEvent]
+    ) -> None:
+        """
+        Handle pydantic-ai streaming events and update Live Markdown via DisplayManager.
+        """
+
+        async for event in event_stream:
+            await self.on_event(event, ctx)
+
+    # --- Event routing via singledispatchmethod ---------------------------------------
+    @singledispatchmethod
+    async def on_event(
+        self, event: AgentStreamEvent, ctx: RunContext
+    ) -> None:  # default
+        return
+
+    @on_event.register
+    async def _(self, event: PartStartEvent, ctx: RunContext) -> None:
+        if isinstance(event.part, TextPart):
+            self.display.live.ensure_segment(TextPart)
+            self.display.live.append(event.part.content)
+        elif isinstance(event.part, ThinkingPart):
+            self.display.live.ensure_segment(ThinkingPart)
+            self.display.live.append(event.part.content)
+
+    @on_event.register
+    async def _(self, event: PartDeltaEvent, ctx: RunContext) -> None:
+        d = event.delta
+        if isinstance(d, TextPartDelta):
+            delta = d.content_delta or ""
+            if delta:
+                self.display.live.ensure_segment(TextPart)
+                self.display.live.append(delta)
+        elif isinstance(d, ThinkingPartDelta):
+            delta = d.content_delta or ""
+            if delta:
+                self.display.live.ensure_segment(ThinkingPart)
+                self.display.live.append(delta)
+
+    @on_event.register
+    async def _(self, event: FunctionToolCallEvent, ctx: RunContext) -> None:
+        # Clear any status/markdown Live so tool output sits between
+        self.display.live.end_status()
+        self.display.live.end_if_active()
+        args = event.part.args_as_dict()
+
+        # Special handling: display SQL via Live as markdown code block
+        if event.part.tool_name == "execute_sql":
+            query = args.get("query") or ""
+            if isinstance(query, str) and query.strip():
+                self.display.live.start_sql_block(query)
+        else:
+            self.display.show_tool_executing(event.part.tool_name, args)
+
+    @on_event.register
+    async def _(self, event: FunctionToolResultEvent, ctx: RunContext) -> None:
+        # Route tool result to appropriate display
+        tool_name = event.result.tool_name
+        content = event.result.content
+        if tool_name == "list_tables":
+            self.display.show_table_list(content)
+        elif tool_name == "introspect_schema":
+            self.display.show_schema_info(content)
+        elif tool_name == "execute_sql":
+            data = {}
+            if isinstance(content, str):
+                try:
+                    data = json.loads(content)
+                except (json.JSONDecodeError, TypeError) as exc:
+                    try:
+                        self.console.log(f"Malformed execute_sql result: {exc}")
+                    except Exception:
+                        pass
+            elif isinstance(content, dict):
+                data = content
+            if isinstance(data, dict) and data.get("success") and data.get("results"):
+                self.display.show_query_results(data["results"])  # type: ignore[arg-type]
+        # Add a blank line after tool output to separate from next segment
+        self.display.show_newline()
+        # Show status while agent sends a follow-up request to the model
+        self.display.live.start_status("Crunching data...")
+
+    async def execute_streaming_query(
+        self,
+        user_query: str,
+        agent: Agent,
+        cancellation_token: asyncio.Event | None = None,
+        message_history: list | None = None,
+    ):
+        # Prepare nicer code block rendering for Markdown
+        self.display.live.prepare_code_blocks()
+        try:
+            # If Anthropic OAuth, inject SQLsaber instructions before the first user prompt
+            prepared_prompt: str | list[str] = user_query
+            is_oauth = bool(getattr(agent, "_sqlsaber_is_oauth", False))
+            no_history = not message_history
+            if is_oauth and no_history:
+                ib = getattr(agent, "_sqlsaber_instruction_builder", None)
+                mm = getattr(agent, "_sqlsaber_memory_manager", None)
+                db_type = getattr(agent, "_sqlsaber_db_type", "database")
+                db_name = getattr(agent, "_sqlsaber_database_name", None)
+                instructions = (
+                    ib.build_instructions(db_type=db_type) if ib is not None else ""
+                )
+                mem = (
+                    mm.format_memories_for_prompt(db_name)
+                    if (mm is not None and db_name)
+                    else ""
+                )
+                parts = [p for p in (instructions, mem) if p and str(p).strip()]
+                if parts:
+                    injected = "\n\n".join(parts)
+                    prepared_prompt = [injected, user_query]
+
+            # Show a transient status until events start streaming
+            self.display.live.start_status("Crunching data...")
+
+            # Run the agent with our event stream handler
+            run = await agent.run(
+                prepared_prompt,
+                message_history=message_history,
+                event_stream_handler=self._event_stream_handler,
+            )
+            return run
+        except asyncio.CancelledError:
+            # Show interruption message outside of Live
+            self.display.show_newline()
+            self.console.print("[yellow]Query interrupted[/yellow]")
+            return None
+        finally:
+            # End any active status and live markdown segments
+            try:
+                self.display.live.end_status()
+            finally:
+                self.display.live.end_if_active()