sqlsaber 0.13.0__tar.gz → 0.15.0__tar.gz

{sqlsaber-0.13.0 → sqlsaber-0.15.0}/.github/workflows/claude-code-review.yml

@@ -17,14 +17,14 @@ jobs:
     #   github.event.pull_request.user.login == 'external-contributor' ||
     #   github.event.pull_request.user.login == 'new-developer' ||
     #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-    
+
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: read
       issues: read
       id-token: write
-    
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -39,7 +39,7 @@ jobs:
 
           # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
           # model: "claude-opus-4-20250514"
-          
+
           # Direct prompt for automated review (no @claude mention needed)
           direct_prompt: |
             Please review this pull request and provide feedback on:
@@ -48,12 +48,12 @@ jobs:
             - Performance considerations
             - Security concerns
             - Test coverage
-            
+
             Be constructive and helpful in your feedback.
 
           # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
           # use_sticky_comment: true
-          
+
           # Optional: Customize review based on file types
           # direct_prompt: |
           #   Review this PR focusing on:
@@ -61,18 +61,17 @@ jobs:
           #   - For API endpoints: Security, input validation, and error handling
           #   - For React components: Performance, accessibility, and best practices
           #   - For tests: Coverage, edge cases, and test quality
-          
+
           # Optional: Different prompts for different authors
           # direct_prompt: |
-          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' && 
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' &&
           #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
           #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
-          
+
           # Optional: Add specific tools for running tests or linting
           # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
-          
-          # Optional: Skip review for certain conditions
-          # if: |
-          #   !contains(github.event.pull_request.title, '[skip-review]') &&
-          #   !contains(github.event.pull_request.title, '[WIP]')
 
+        # Optional: Skip review for certain conditions
+        if: |
+          !contains(github.event.pull_request.title, '[skip-review]') &&
+          !contains(github.event.pull_request.title, '[WIP]')

sqlsaber-0.15.0/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel active CI runs for a PR before starting another run
+concurrency:
+  group: ${{ github.workflow}}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run tests
+        run: uv run python -m pytest

{sqlsaber-0.13.0 → sqlsaber-0.15.0}/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to SQLSaber will be documented in this file.
 
 ## [Unreleased]
 
+## [0.15.0] - 2025-08-18
+
+### Added
+
+- Tool abstraction system with centralized registry (new `Tool` base class, `ToolRegistry`, decorators)
+- Dynamic instruction generation system (`InstructionBuilder`)
+- Comprehensive test suite for the tools module
+
+### Changed
+
+- Refactored agents to use centralized tool registry instead of hardcoded tools
+- Enhanced MCP server with dynamic tool registration
+- Moved core SQL functionality to dedicated tool classes
+
+## [0.14.0] - 2025-08-01
+
+### Added
+
+- Local conversation storage between user and agent
+  - Store conversation history persistently
+  - Track messages with proper attribution
+- Added automated test execution in CI
+  - New GitHub Actions workflow for running tests
+  - Updated code review workflow
+
+### Fixed
+
+- Fixed CLI commands test suite (#11)
+
+### Changed
+
+- Removed schema caching from SchemaManager
+  - Simplified schema introspection by removing cache logic
+  - Direct database queries for schema information
+
 ## [0.13.0] - 2025-07-26
 
 ### Added

{sqlsaber-0.13.0 → sqlsaber-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlsaber
-Version: 0.13.0
+Version: 0.15.0
 Summary: SQLSaber - Agentic SQL assistant like Claude Code
 License-File: LICENSE
 Requires-Python: >=3.12

{sqlsaber-0.13.0 → sqlsaber-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlsaber"
-version = "0.13.0"
+version = "0.15.0"
 description = "SQLSaber - Agentic SQL assistant like Claude Code"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlsaber-0.13.0 → sqlsaber-0.15.0}/src/sqlsaber/agents/anthropic.py

@@ -21,6 +21,8 @@ from sqlsaber.config.settings import Config
 from sqlsaber.database.connection import BaseDatabaseConnection
 from sqlsaber.memory.manager import MemoryManager
 from sqlsaber.models.events import StreamEvent
+from sqlsaber.tools import tool_registry
+from sqlsaber.tools.instructions import InstructionBuilder
 
 
 class AnthropicSQLAgent(BaseSQLAgent):
@@ -51,89 +53,11 @@ class AnthropicSQLAgent(BaseSQLAgent):
         self._last_results = None
         self._last_query = None
 
-        # Define tools in the new format
-        self.tools: list[ToolDefinition] = [
-            ToolDefinition(
-                name="list_tables",
-                description="Get a list of all tables in the database with row counts. Use this first to discover available tables.",
-                input_schema={
-                    "type": "object",
-                    "properties": {},
-                    "required": [],
-                },
-            ),
-            ToolDefinition(
-                name="introspect_schema",
-                description="Introspect database schema to understand table structures.",
-                input_schema={
-                    "type": "object",
-                    "properties": {
-                        "table_pattern": {
-                            "type": "string",
-                            "description": "Optional pattern to filter tables (e.g., 'public.users', 'user%', '%order%')",
-                        }
-                    },
-                    "required": [],
-                },
-            ),
-            ToolDefinition(
-                name="execute_sql",
-                description="Execute a SQL query against the database.",
-                input_schema={
-                    "type": "object",
-                    "properties": {
-                        "query": {
-                            "type": "string",
-                            "description": "SQL query to execute",
-                        },
-                        "limit": {
-                            "type": "integer",
-                            "description": f"Maximum number of rows to return (default: {AnthropicSQLAgent.DEFAULT_SQL_LIMIT})",
-                            "default": AnthropicSQLAgent.DEFAULT_SQL_LIMIT,
-                        },
-                    },
-                    "required": ["query"],
-                },
-            ),
-            ToolDefinition(
-                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"],
-                },
-            ),
-        ]
+        # Get tool definitions from registry
+        self.tools: list[ToolDefinition] = tool_registry.get_tool_definitions()
+
+        # Initialize instruction builder
+        self.instruction_builder = InstructionBuilder(tool_registry)
 
         # Build system prompt with memories if available
         self.system_prompt = self._build_system_prompt()
@@ -157,31 +81,9 @@ class AnthropicSQLAgent(BaseSQLAgent):
     def _get_sql_assistant_instructions(self) -> str:
         """Get the detailed SQL assistant instructions."""
         db_type = self._get_database_type_name()
-        instructions = f"""You are also a helpful SQL assistant that helps users query their {db_type} database.
-
-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 - 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
-- Use table patterns like 'sample%' or '%experiment%' to filter related tables
-- Use proper JOIN syntax and avoid cartesian products
-- Include appropriate WHERE clauses to limit results
-- Explain what the query does in simple terms
-- Handle errors gracefully and suggest fixes
-- Be security conscious - use parameterized queries when needed
-"""
+
+        # Build dynamic instructions from available tools
+        instructions = self.instruction_builder.build_instructions(db_type=db_type)
 
         # Add memory context if database name is available
         if self.database_name:
@@ -189,7 +91,7 @@ Guidelines:
                 self.database_name
             )
             if memory_context.strip():
-                instructions += memory_context
+                instructions += "\n\n" + memory_context
 
         return instructions
 
@@ -199,16 +101,19 @@ Guidelines:
             return None
 
         memory = self.memory_manager.add_memory(self.database_name, content)
-        # Rebuild system prompt with new memory
+        # Rebuild system prompt with new memory (includes dynamic instructions)
         self.system_prompt = self._build_system_prompt()
         return memory.id
 
-    async def execute_sql(self, query: str, limit: int | None = None) -> str:
-        """Execute a SQL query against the database with streaming support."""
-        # Call parent implementation for core functionality
-        result = await super().execute_sql(query, limit)
+    async def _execute_sql_with_tracking(
+        self, query: str, limit: int | None = None
+    ) -> str:
+        """Execute SQL and track results for streaming."""
+        # Get the execute_sql tool and run it
+        tool = tool_registry.get_tool("execute_sql")
+        result = await tool.execute(query=query, limit=limit)
 
-        # Parse result to extract data for streaming (AnthropicSQLAgent specific)
+        # Parse result to extract data for streaming
         try:
             result_data = json.loads(result)
             if result_data.get("success") and "results" in result_data:
@@ -228,7 +133,14 @@ Guidelines:
         self, tool_name: str, tool_input: dict[str, Any]
     ) -> str:
         """Process a tool call and return the result."""
-        # Use parent implementation for core tools
+        # Special handling for execute_sql to track results
+        if tool_name == "execute_sql":
+            return await self._execute_sql_with_tracking(
+                tool_input.get("query", ""),
+                tool_input.get("limit", self.DEFAULT_SQL_LIMIT),
+            )
+
+        # Use parent implementation for all other tools
         return await super().process_tool_call(tool_name, tool_input)
 
     def _convert_user_message_to_message(
@@ -450,6 +362,16 @@ Guidelines:
         self._last_query = None
 
         try:
+            # Ensure conversation is active for persistence
+            await self._ensure_conversation()
+
+            # Store user message in conversation history and persistence
+            if use_history:
+                self.conversation_history.append(
+                    {"role": "user", "content": user_query}
+                )
+                await self._store_user_message(user_query)
+
             # Build messages with history if requested
             messages = []
             if use_history:
@@ -461,8 +383,9 @@ Guidelines:
                 instructions = self._get_sql_assistant_instructions()
                 messages.append(Message(MessageRole.USER, instructions))
 
-            # Add current user message
-            messages.append(Message(MessageRole.USER, user_query))
+            # Add current user message if not already in messages from history
+            if not use_history:
+                messages.append(Message(MessageRole.USER, user_query))
 
             # Create initial request and get response
             request = self._create_message_request(messages)
@@ -484,9 +407,12 @@ Guidelines:
                     return
 
                 # Add assistant's response to conversation
-                collected_content.append(
-                    {"role": "assistant", "content": response.content}
-                )
+                assistant_content = {"role": "assistant", "content": response.content}
+                collected_content.append(assistant_content)
+
+                # Store the assistant message immediately (not from collected_content)
+                if use_history:
+                    await self._store_assistant_message(response.content)
 
                 # Execute tools and get results
                 tool_results = []
@@ -499,9 +425,19 @@ Guidelines:
                         tool_results = event
 
                 # Continue conversation with tool results
-                collected_content.append({"role": "user", "content": tool_results})
+                tool_content = {"role": "user", "content": tool_results}
+                collected_content.append(tool_content)
+
+                # Store the tool message immediately and update history
                 if use_history:
-                    self.conversation_history.extend(collected_content)
+                    # Only add the NEW messages to history (not the accumulated ones)
+                    # collected_content has [assistant1, tool1, assistant2, tool2, ...]
+                    # We only want to add the last 2 items that were just added
+                    new_messages_for_history = collected_content[
+                        -2:
+                    ]  # Last assistant + tool pair
+                    self.conversation_history.extend(new_messages_for_history)
+                    await self._store_tool_message(tool_results)
 
                 if cancellation_token is not None and cancellation_token.is_set():
                     return
@@ -541,6 +477,10 @@ Guidelines:
                     {"role": "assistant", "content": response.content}
                 )
 
+                # Store final assistant message in persistence (only if not tool_use)
+                if response.stop_reason != "tool_use":
+                    await self._store_assistant_message(response.content)
+
         except asyncio.CancelledError:
             return
         except Exception as e:

sqlsaber-0.15.0/src/sqlsaber/agents/base.py

@@ -0,0 +1,187 @@
+"""Abstract base class for SQL agents."""
+
+import asyncio
+import json
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator
+
+from sqlsaber.conversation.manager import ConversationManager
+from sqlsaber.database.connection import (
+    BaseDatabaseConnection,
+    CSVConnection,
+    MySQLConnection,
+    PostgreSQLConnection,
+    SQLiteConnection,
+)
+from sqlsaber.database.schema import SchemaManager
+from sqlsaber.models.events import StreamEvent
+from sqlsaber.tools import SQLTool, tool_registry
+
+
+class BaseSQLAgent(ABC):
+    """Abstract base class for SQL agents."""
+
+    def __init__(self, db_connection: BaseDatabaseConnection):
+        self.db = db_connection
+        self.schema_manager = SchemaManager(db_connection)
+        self.conversation_history: list[dict[str, Any]] = []
+
+        # Conversation persistence
+        self._conv_manager = ConversationManager()
+        self._conversation_id: str | None = None
+        self._msg_index: int = 0
+
+        # Initialize SQL tools with database connection
+        self._init_tools()
+
+    @abstractmethod
+    async def query_stream(
+        self,
+        user_query: str,
+        use_history: bool = True,
+        cancellation_token: asyncio.Event | None = None,
+    ) -> AsyncIterator[StreamEvent]:
+        """Process a user query and stream responses.
+
+        Args:
+            user_query: The user's query to process
+            use_history: Whether to include conversation history
+            cancellation_token: Optional event to signal cancellation
+        """
+        pass
+
+    async def clear_history(self):
+        """Clear conversation history."""
+        # End current conversation in storage
+        await self._end_conversation()
+
+        # Clear in-memory history
+        self.conversation_history = []
+
+    def _get_database_type_name(self) -> str:
+        """Get the human-readable database type name."""
+        if isinstance(self.db, PostgreSQLConnection):
+            return "PostgreSQL"
+        elif isinstance(self.db, MySQLConnection):
+            return "MySQL"
+        elif isinstance(self.db, SQLiteConnection):
+            return "SQLite"
+        elif isinstance(self.db, CSVConnection):
+            return "SQLite"  # we convert csv to in-memory sqlite
+        else:
+            return "database"  # Fallback
+
+    def _init_tools(self) -> None:
+        """Initialize SQL tools with database connection."""
+        # Get all SQL tools and set their database connection
+        for tool_name in tool_registry.list_tools(category="sql"):
+            tool = tool_registry.get_tool(tool_name)
+            if isinstance(tool, SQLTool):
+                tool.set_connection(self.db)
+
+    async def process_tool_call(
+        self, tool_name: str, tool_input: dict[str, Any]
+    ) -> str:
+        """Process a tool call and return the result."""
+        try:
+            tool = tool_registry.get_tool(tool_name)
+            return await tool.execute(**tool_input)
+        except KeyError:
+            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+        except Exception as e:
+            return json.dumps(
+                {"error": f"Error executing tool '{tool_name}': {str(e)}"}
+            )
+
+    # Conversation persistence helpers
+
+    async def _ensure_conversation(self) -> None:
+        """Ensure a conversation is active for storing messages."""
+        if self._conversation_id is None:
+            db_name = getattr(self, "database_name", "unknown")
+            self._conversation_id = await self._conv_manager.start_conversation(db_name)
+            self._msg_index = 0
+
+    async def _store_user_message(self, content: str | dict[str, Any]) -> None:
+        """Store a user message in conversation history."""
+        if self._conversation_id is None:
+            return
+
+        await self._conv_manager.add_user_message(
+            self._conversation_id, content, self._msg_index
+        )
+        self._msg_index += 1
+
+    async def _store_assistant_message(
+        self, content: list[dict[str, Any]] | dict[str, Any]
+    ) -> None:
+        """Store an assistant message in conversation history."""
+        if self._conversation_id is None:
+            return
+
+        await self._conv_manager.add_assistant_message(
+            self._conversation_id, content, self._msg_index
+        )
+        self._msg_index += 1
+
+    async def _store_tool_message(
+        self, content: list[dict[str, Any]] | dict[str, Any]
+    ) -> None:
+        """Store a tool/system message in conversation history."""
+        if self._conversation_id is None:
+            return
+
+        await self._conv_manager.add_tool_message(
+            self._conversation_id, content, self._msg_index
+        )
+        self._msg_index += 1
+
+    async def _end_conversation(self) -> None:
+        """End the current conversation."""
+        if self._conversation_id:
+            await self._conv_manager.end_conversation(self._conversation_id)
+        self._conversation_id = None
+        self._msg_index = 0
+
+    async def restore_conversation(self, conversation_id: str) -> bool:
+        """Restore a conversation from storage to in-memory history.
+
+        Args:
+            conversation_id: ID of the conversation to restore
+
+        Returns:
+            True if successfully restored, False otherwise
+        """
+        success = await self._conv_manager.restore_conversation_to_agent(
+            conversation_id, self.conversation_history
+        )
+
+        if success:
+            # Set up for continuing this conversation
+            self._conversation_id = conversation_id
+            self._msg_index = len(self.conversation_history)
+
+        return success
+
+    async def list_conversations(self, limit: int = 50) -> list:
+        """List conversations for this agent's database.
+
+        Args:
+            limit: Maximum number of conversations to return
+
+        Returns:
+            List of conversation data
+        """
+        db_name = getattr(self, "database_name", None)
+        conversations = await self._conv_manager.list_conversations(db_name, limit)
+
+        return [
+            {
+                "id": conv.id,
+                "database_name": conv.database_name,
+                "started_at": conv.formatted_start_time(),
+                "ended_at": conv.formatted_end_time(),
+                "duration": conv.duration_seconds(),
+            }
+            for conv in conversations
+        ]

{sqlsaber-0.13.0 → sqlsaber-0.15.0}/src/sqlsaber/cli/interactive.py

@@ -136,11 +136,15 @@ class InteractiveSession:
                 if not user_query:
                     continue
 
-                if user_query in ["/exit", "/quit"]:
+                if (
+                    user_query in ["/exit", "/quit"]
+                    or user_query.startswith("/exit")
+                    or user_query.startswith("/quit")
+                ):
                     break
 
                 if user_query == "/clear":
-                    self.agent.clear_history()
+                    await self.agent.clear_history()
                     self.console.print("[green]Conversation history cleared.[/green]\n")
                     continue
 

sqlsaber-0.15.0/src/sqlsaber/conversation/__init__.py

@@ -0,0 +1,12 @@
+"""Conversation history storage for SQLSaber."""
+
+from .manager import ConversationManager
+from .models import Conversation, ConversationMessage
+from .storage import ConversationStorage
+
+__all__ = [
+    "Conversation",
+    "ConversationMessage",
+    "ConversationStorage",
+    "ConversationManager",
+]