strands-sql 0.1.4__tar.gz → 0.1.7__tar.gz

{strands_sql-0.1.4 → strands_sql-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strands-sql
-Version: 0.1.4
+Version: 0.1.7
 Summary: General-purpose SQL tool for Strands agents — supports PostgreSQL, MySQL, and SQLite.
 Project-URL: Homepage, https://github.com/NithiN-1808/strands-sql
 Project-URL: Repository, https://github.com/NithiN-1808/strands-sql
@@ -211,7 +211,6 @@ Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
 Description-Content-Type: text/markdown
 
 # strands-sql
-
 [![PyPI](https://img.shields.io/pypi/v/strands-sql)](https://pypi.org/project/strands-sql/)
 [![Python](https://img.shields.io/pypi/pyversions/strands-sql)](https://pypi.org/project/strands-sql/)
 
@@ -232,25 +231,46 @@ pip install "strands-sql[mysql]"
 
 ## Quick Start
 
-```python
-from strands import Agent
-from strands_sql import sql_database
+### Direct Usage
 
-agent = Agent(tools=[sql_database])
+```python
+from strands_sql import run_sql_database
 
 # Discover the schema
-agent.tool.sql_database(action="schema_summary")
+run_sql_database(
+    action="schema_summary",
+    connection_string="sqlite:///./local.db"
+)
 
 # Describe a specific table
-agent.tool.sql_database(action="describe_table", table="users")
+run_sql_database(
+    action="describe_table",
+    table="users",
+    connection_string="sqlite:///./local.db"
+)
 
 # Run a query (returns a markdown table by default)
-agent.tool.sql_database(
+run_sql_database(
     action="query",
     sql="SELECT * FROM orders WHERE amount > 100 LIMIT 20",
+    connection_string="sqlite:///./local.db"
 )
 ```
 
+### With a Strands Agent
+
+```python
+from strands import Agent
+from strands_sql import sql_database
+
+agent = Agent(tools=[sql_database])
+
+# The agent decides when and how to invoke the tool
+agent("List all tables in my database")
+agent("Show me all orders above 100")
+agent("How many users are there?")
+```
+
 ## Configuration
 
 ### Connection String
@@ -262,7 +282,7 @@ export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
 ```
 
 ```python
-agent.tool.sql_database(
+run_sql_database(
     action="list_tables",
     connection_string="sqlite:///./local.db",
 )
@@ -281,9 +301,10 @@ agent.tool.sql_database(
 ## Safety Options
 
 ```python
-agent.tool.sql_database(
+run_sql_database(
     action="query",
     sql="SELECT * FROM users",
+    connection_string="sqlite:///./local.db",
     read_only=True,                      # Default: True — blocks INSERT/UPDATE/DELETE
     max_rows=500,                        # Default: 500 — caps result size
     timeout=30,                          # Default: 30s — kills hung queries
@@ -297,6 +318,7 @@ agent.tool.sql_database(
 | `read_only` | `True` | Blocks all write queries |
 | `max_rows` | `500` | Maximum rows returned by `query` |
 | `timeout` | `30` | Query timeout in seconds (1–300) |
+| `output_format` | `markdown` | Output format: `markdown` or `json` |
 | `allowed_tables` | `None` | Allowlist — only these tables are accessible |
 | `blocked_tables` | `None` | Blocklist — these tables are never accessible |
 
@@ -304,10 +326,33 @@ agent.tool.sql_database(
 
 ```python
 # Markdown table (default — great for LLMs)
-agent.tool.sql_database(action="query", sql="SELECT * FROM users", output_format="markdown")
+run_sql_database(
+    action="query",
+    sql="SELECT * FROM users",
+    connection_string="sqlite:///./local.db",
+    output_format="markdown"
+)
 
 # JSON array
-agent.tool.sql_database(action="query", sql="SELECT * FROM users", output_format="json")
+run_sql_database(
+    action="query",
+    sql="SELECT * FROM users",
+    connection_string="sqlite:///./local.db",
+    output_format="json"
+)
+```
+
+## Execute (Write Queries)
+
+Write queries are blocked by default. To enable:
+
+```python
+run_sql_database(
+    action="execute",
+    sql="INSERT INTO users (name, age) VALUES ('Eve', 22)",
+    connection_string="sqlite:///./local.db",
+    read_only=False
+)
 ```
 
 ## Development

{strands_sql-0.1.4 → strands_sql-0.1.7}/README.md

@@ -1,5 +1,4 @@
 # strands-sql
-
 [![PyPI](https://img.shields.io/pypi/v/strands-sql)](https://pypi.org/project/strands-sql/)
 [![Python](https://img.shields.io/pypi/pyversions/strands-sql)](https://pypi.org/project/strands-sql/)
 
@@ -20,25 +19,46 @@ pip install "strands-sql[mysql]"
 
 ## Quick Start
 
-```python
-from strands import Agent
-from strands_sql import sql_database
+### Direct Usage
 
-agent = Agent(tools=[sql_database])
+```python
+from strands_sql import run_sql_database
 
 # Discover the schema
-agent.tool.sql_database(action="schema_summary")
+run_sql_database(
+    action="schema_summary",
+    connection_string="sqlite:///./local.db"
+)
 
 # Describe a specific table
-agent.tool.sql_database(action="describe_table", table="users")
+run_sql_database(
+    action="describe_table",
+    table="users",
+    connection_string="sqlite:///./local.db"
+)
 
 # Run a query (returns a markdown table by default)
-agent.tool.sql_database(
+run_sql_database(
     action="query",
     sql="SELECT * FROM orders WHERE amount > 100 LIMIT 20",
+    connection_string="sqlite:///./local.db"
 )
 ```
 
+### With a Strands Agent
+
+```python
+from strands import Agent
+from strands_sql import sql_database
+
+agent = Agent(tools=[sql_database])
+
+# The agent decides when and how to invoke the tool
+agent("List all tables in my database")
+agent("Show me all orders above 100")
+agent("How many users are there?")
+```
+
 ## Configuration
 
 ### Connection String
@@ -50,7 +70,7 @@ export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
 ```
 
 ```python
-agent.tool.sql_database(
+run_sql_database(
     action="list_tables",
     connection_string="sqlite:///./local.db",
 )
@@ -69,9 +89,10 @@ agent.tool.sql_database(
 ## Safety Options
 
 ```python
-agent.tool.sql_database(
+run_sql_database(
     action="query",
     sql="SELECT * FROM users",
+    connection_string="sqlite:///./local.db",
     read_only=True,                      # Default: True — blocks INSERT/UPDATE/DELETE
     max_rows=500,                        # Default: 500 — caps result size
     timeout=30,                          # Default: 30s — kills hung queries
@@ -85,6 +106,7 @@ agent.tool.sql_database(
 | `read_only` | `True` | Blocks all write queries |
 | `max_rows` | `500` | Maximum rows returned by `query` |
 | `timeout` | `30` | Query timeout in seconds (1–300) |
+| `output_format` | `markdown` | Output format: `markdown` or `json` |
 | `allowed_tables` | `None` | Allowlist — only these tables are accessible |
 | `blocked_tables` | `None` | Blocklist — these tables are never accessible |
 
@@ -92,10 +114,33 @@ agent.tool.sql_database(
 
 ```python
 # Markdown table (default — great for LLMs)
-agent.tool.sql_database(action="query", sql="SELECT * FROM users", output_format="markdown")
+run_sql_database(
+    action="query",
+    sql="SELECT * FROM users",
+    connection_string="sqlite:///./local.db",
+    output_format="markdown"
+)
 
 # JSON array
-agent.tool.sql_database(action="query", sql="SELECT * FROM users", output_format="json")
+run_sql_database(
+    action="query",
+    sql="SELECT * FROM users",
+    connection_string="sqlite:///./local.db",
+    output_format="json"
+)
+```
+
+## Execute (Write Queries)
+
+Write queries are blocked by default. To enable:
+
+```python
+run_sql_database(
+    action="execute",
+    sql="INSERT INTO users (name, age) VALUES ('Eve', 22)",
+    connection_string="sqlite:///./local.db",
+    read_only=False
+)
 ```
 
 ## Development

{strands_sql-0.1.4 → strands_sql-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strands-sql"
-version = "0.1.4"
+version = "0.1.7"
 description = "General-purpose SQL tool for Strands agents — supports PostgreSQL, MySQL, and SQLite."
 readme = "README.md"
 license = { file = "LICENSE" }

{strands_sql-0.1.4 → strands_sql-0.1.7}/setup_template.py

@@ -114,7 +114,7 @@ def select_components() -> list[str]:
 
 def replace_in_file(filepath: str, replacements: dict[str, str]) -> None:
     """Replace all occurrences in a file."""
-    with open(filepath, "r", encoding="utf-8") as f:
+    with open(filepath, encoding="utf-8") as f:
         content = f.read()
 
     for old, new in replacements.items():

strands_sql-0.1.7/src/strands_sql/__init__.py

@@ -0,0 +1,5 @@
+"""strands-sql — General-purpose SQL tool for Strands agents."""
+
+from .sql_database import get_tool, run_sql_database, sql_database
+
+__all__ = ["sql_database", "get_tool", "run_sql_database"]

{strands_sql-0.1.4 → strands_sql-0.1.7}/src/strands_sql/sql_database.py

@@ -479,4 +479,26 @@ def sql_database(tool: ToolUse, **kwargs: Any) -> ToolResult:
         "content": [{"text": result}],
     }
 sql_database.TOOL_SPEC = TOOL_SPEC # type: ignore[attr-defined]
-sql_database.tool_spec = TOOL_SPEC  # type: ignore[attr-defined]
+sql_database.tool_spec = TOOL_SPEC  # type: ignore[attr-defined]
+
+def get_tool():
+    """Return a properly registered Strands Tool."""
+    from strands.tools import Tool
+
+    return Tool.from_function(
+        func=sql_database,
+        name=TOOL_SPEC["name"],
+        description=TOOL_SPEC["description"],
+        input_schema=TOOL_SPEC["inputSchema"]["json"],
+    )
+
+
+def run_sql_database(**kwargs):
+    """Direct usage without needing ToolUse format."""
+    result = sql_database(
+        tool={
+            "toolUseId": "direct",
+            "input": kwargs,
+        }
+    )
+    return result["content"][0]["text"]

strands_sql-0.1.4/src/strands_sql/__init__.py

@@ -1,5 +0,0 @@
-"""strands-sql — General-purpose SQL tool for Strands agents."""
-
-from .sql_database import TOOL_SPEC, sql_database
-
-__all__ = ["sql_database", "TOOL_SPEC"]