matimo-postgres 0.1.2__tar.gz → 0.1.3__tar.gz

{matimo_postgres-0.1.2 → matimo_postgres-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: matimo-postgres
-Version: 0.1.2
+Version: 0.1.3
 Summary: Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)
 License: MIT
 Keywords: agents,ai,matimo,postgres,tools
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 
 # matimo-postgres
 
-> PostgreSQL tools for [Matimo](https://matimo.dev) — execute SQL queries safely with policy-gated approval.
+> PostgreSQL tools for [Matimo](https://matimo.dev) - execute SQL queries safely with policy-gated approval.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-postgres)](https://pypi.org/project/matimo-postgres/)
 [![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
@@ -34,9 +34,12 @@ pip install matimo matimo-postgres
 
 | Tool | Description |
 |------|-------------|
-| `execute-sql` | Execute a SQL query against a PostgreSQL database |
+| `postgres-execute-sql` | Execute a SQL query against a PostgreSQL database |
 
-The `execute-sql` tool is marked `requires_approval: true` — destructive operations (INSERT, UPDATE, DELETE, DROP) trigger HITL approval by default.
+The tool does not set `requires_approval` itself - if you want destructive operations
+(INSERT, UPDATE, DELETE, DROP) to require human approval, gate them yourself via a
+[policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) or a custom
+`PolicyEngine`.
 
 ---
 
@@ -44,19 +47,15 @@ The `execute-sql` tool is marked `requires_approval: true` — destructive opera
 
 ```python
 import asyncio
-from matimo import Matimo, InitOptions
+from matimo import Matimo
 from matimo_postgres import get_tools_path
 
 async def main():
-    # Auto-approve for read-only usage (CI/CD)
-    matimo = await Matimo.init(
-        get_tools_path(),
-        InitOptions(on_hitl=lambda req: {'approved': True, 'reason': 'auto'}),
-    )
+    matimo = await Matimo.init(get_tools_path())
 
     # Run a SELECT query
-    result = await matimo.execute('execute-sql', {
-        'query': 'SELECT id, name FROM users LIMIT 10',
+    result = await matimo.execute('postgres-execute-sql', {
+        'sql': 'SELECT id, name FROM users LIMIT 10',
     })
     print(result)
 
@@ -65,20 +64,20 @@ asyncio.run(main())
 
 ### With Interactive Approval (Recommended for Writes)
 
+If you've configured a policy that quarantines this tool for HITL review, provide an
+`on_hitl` callback:
+
 ```python
 async def ask_user(request) -> dict:
-    print(f"\nSQL requires approval:\n{request.params.get('query')}")
+    print(f"\nSQL requires approval:\n{request.params.get('sql')}")
     answer = input("Run this query? [y/n]: ").strip()
     return {'approved': answer == 'y', 'reason': 'user reviewed'}
 
-matimo = await Matimo.init(
-    get_tools_path(),
-    InitOptions(on_hitl=ask_user),
-)
+matimo = await Matimo.init(get_tools_path(), on_hitl=ask_user)
 
-# This will prompt before executing
-await matimo.execute('execute-sql', {
-    'query': 'DELETE FROM sessions WHERE expired_at < NOW()',
+# This will prompt before executing, if quarantined by your policy
+await matimo.execute('postgres-execute-sql', {
+    'sql': 'DELETE FROM sessions WHERE expired_at < NOW()',
 })
 ```
 
@@ -87,21 +86,21 @@ await matimo.execute('execute-sql', {
 ## Authentication
 
 ```bash
-export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+export MATIMO_POSTGRES_URL="postgresql://user:password@localhost:5432/mydb"
 # or individual params
-export POSTGRES_HOST="localhost"
-export POSTGRES_PORT="5432"
-export POSTGRES_DB="mydb"
-export POSTGRES_USER="myuser"
-export POSTGRES_PASSWORD="mypassword"
+export MATIMO_POSTGRES_HOST="localhost"
+export MATIMO_POSTGRES_PORT="5432"
+export MATIMO_POSTGRES_DB="mydb"
+export MATIMO_POSTGRES_USER="myuser"
+export MATIMO_POSTGRES_PASSWORD="mypassword"
 ```
 
 ---
 
 ## Security Notes
 
-- All SQL queries go through Matimo's **content validator** — SSRF and injection patterns are detected
-- The tool has `requires_approval: true` — writes trigger approval by default
+- All SQL queries go through Matimo's **content validator** - SSRF and injection patterns are detected
+- The tool itself does not require approval - use a policy file if you want writes gated
 - Use a **read-only database user** for agent workloads when possible
 - Consider a [policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
 

matimo_postgres-0.1.3/README.md

@@ -0,0 +1,106 @@
+# matimo-postgres
+
+> PostgreSQL tools for [Matimo](https://matimo.dev) - execute SQL queries safely with policy-gated approval.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-postgres)](https://pypi.org/project/matimo-postgres/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-postgres
+```
+
+---
+
+## Available Tools (1 Tool)
+
+| Tool | Description |
+|------|-------------|
+| `postgres-execute-sql` | Execute a SQL query against a PostgreSQL database |
+
+The tool does not set `requires_approval` itself - if you want destructive operations
+(INSERT, UPDATE, DELETE, DROP) to require human approval, gate them yourself via a
+[policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) or a custom
+`PolicyEngine`.
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_postgres import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Run a SELECT query
+    result = await matimo.execute('postgres-execute-sql', {
+        'sql': 'SELECT id, name FROM users LIMIT 10',
+    })
+    print(result)
+
+asyncio.run(main())
+```
+
+### With Interactive Approval (Recommended for Writes)
+
+If you've configured a policy that quarantines this tool for HITL review, provide an
+`on_hitl` callback:
+
+```python
+async def ask_user(request) -> dict:
+    print(f"\nSQL requires approval:\n{request.params.get('sql')}")
+    answer = input("Run this query? [y/n]: ").strip()
+    return {'approved': answer == 'y', 'reason': 'user reviewed'}
+
+matimo = await Matimo.init(get_tools_path(), on_hitl=ask_user)
+
+# This will prompt before executing, if quarantined by your policy
+await matimo.execute('postgres-execute-sql', {
+    'sql': 'DELETE FROM sessions WHERE expired_at < NOW()',
+})
+```
+
+---
+
+## Authentication
+
+```bash
+export MATIMO_POSTGRES_URL="postgresql://user:password@localhost:5432/mydb"
+# or individual params
+export MATIMO_POSTGRES_HOST="localhost"
+export MATIMO_POSTGRES_PORT="5432"
+export MATIMO_POSTGRES_DB="mydb"
+export MATIMO_POSTGRES_USER="myuser"
+export MATIMO_POSTGRES_PASSWORD="mypassword"
+```
+
+---
+
+## Security Notes
+
+- All SQL queries go through Matimo's **content validator** - SSRF and injection patterns are detected
+- The tool itself does not require approval - use a policy file if you want writes gated
+- Use a **read-only database user** for agent workloads when possible
+- Consider a [policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
+
+---
+
+## Documentation
+
+- [Approval System](https://matimo.dev/docs/api-reference/APPROVAL-SYSTEM)
+- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/postgres)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-postgres/
+- **GitHub:** https://github.com/tallclub/matimo
+

{matimo_postgres-0.1.2 → matimo_postgres-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-postgres"
-version = "0.1.2"
+version = "0.1.3"
 description = "Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)"
 readme = "README.md"
 license = { text = "MIT" }

matimo_postgres-0.1.2/README.md

@@ -1,107 +0,0 @@
-# matimo-postgres
-
-> PostgreSQL tools for [Matimo](https://matimo.dev) — execute SQL queries safely with policy-gated approval.
-
-[![PyPI](https://img.shields.io/pypi/v/matimo-postgres)](https://pypi.org/project/matimo-postgres/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
-
----
-
-## Installation
-
-```bash
-pip install matimo matimo-postgres
-```
-
----
-
-## Available Tools (1 Tool)
-
-| Tool | Description |
-|------|-------------|
-| `execute-sql` | Execute a SQL query against a PostgreSQL database |
-
-The `execute-sql` tool is marked `requires_approval: true` — destructive operations (INSERT, UPDATE, DELETE, DROP) trigger HITL approval by default.
-
----
-
-## Quick Start
-
-```python
-import asyncio
-from matimo import Matimo, InitOptions
-from matimo_postgres import get_tools_path
-
-async def main():
-    # Auto-approve for read-only usage (CI/CD)
-    matimo = await Matimo.init(
-        get_tools_path(),
-        InitOptions(on_hitl=lambda req: {'approved': True, 'reason': 'auto'}),
-    )
-
-    # Run a SELECT query
-    result = await matimo.execute('execute-sql', {
-        'query': 'SELECT id, name FROM users LIMIT 10',
-    })
-    print(result)
-
-asyncio.run(main())
-```
-
-### With Interactive Approval (Recommended for Writes)
-
-```python
-async def ask_user(request) -> dict:
-    print(f"\nSQL requires approval:\n{request.params.get('query')}")
-    answer = input("Run this query? [y/n]: ").strip()
-    return {'approved': answer == 'y', 'reason': 'user reviewed'}
-
-matimo = await Matimo.init(
-    get_tools_path(),
-    InitOptions(on_hitl=ask_user),
-)
-
-# This will prompt before executing
-await matimo.execute('execute-sql', {
-    'query': 'DELETE FROM sessions WHERE expired_at < NOW()',
-})
-```
-
----
-
-## Authentication
-
-```bash
-export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
-# or individual params
-export POSTGRES_HOST="localhost"
-export POSTGRES_PORT="5432"
-export POSTGRES_DB="mydb"
-export POSTGRES_USER="myuser"
-export POSTGRES_PASSWORD="mypassword"
-```
-
----
-
-## Security Notes
-
-- All SQL queries go through Matimo's **content validator** — SSRF and injection patterns are detected
-- The tool has `requires_approval: true` — writes trigger approval by default
-- Use a **read-only database user** for agent workloads when possible
-- Consider a [policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
-
----
-
-## Documentation
-
-- [Approval System](https://matimo.dev/docs/api-reference/APPROVAL-SYSTEM)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
-- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/postgres)
-
----
-
-## Links
-
-- **PyPI:** https://pypi.org/project/matimo-postgres/
-- **GitHub:** https://github.com/tallclub/matimo
-