matimo-postgres 0.1.0__tar.gz

matimo_postgres-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+**/node_modules/
+package-lock.json
+yarn.lock
+
+# Build output
+**/dist/
+*.tsbuildinfo
+
+# Python compiled / build
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+**/build/
+**/.eggs/
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.pytest_cache/
+
+# Test coverage
+**/coverage/
+**/.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+typescript/examples/mcp/matimo-tools/.matimo-approvals.json
+typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
+typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
+typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/matimo-health-check/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/moltbook-identity/SKILL.md
+typescript/packages/cli/.matimo/certs/server.crt
+typescript/packages/cli/.matimo/certs/server.key
+typescript/examples/mcp/.matimo/certs/server.crt
+typescript/examples/mcp/.matimo/certs/server.key

matimo_postgres-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: matimo-postgres
+Version: 0.1.0
+Summary: Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)
+License: MIT
+Keywords: agents,ai,matimo,postgres,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# 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
+

matimo_postgres-0.1.0/README.md

@@ -0,0 +1,107 @@
+# 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
+

matimo_postgres-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matimo-postgres"
+version = "0.1.0"
+description = "Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "tools", "agents", "matimo", "postgres"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "matimo-core>=0.1.0,<0.2.0",
+    "asyncpg>=0.29",
+]
+
+[project.entry-points."matimo.providers"]
+postgres = "matimo_postgres:get_tools_path"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matimo_postgres"]

matimo_postgres-0.1.0/src/matimo_postgres/__init__.py

@@ -0,0 +1,17 @@
+"""Matimo postgres provider — exposes the path to YAML tool definitions."""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+
+def get_tools_path() -> str:
+    """Return the absolute path to the bundled postgres tool definitions."""
+    try:
+        ref = importlib.resources.files("matimo_postgres") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+
+__all__ = ["get_tools_path"]

matimo_postgres-0.1.0/src/matimo_postgres/tools/execute-sql/definition.yaml

@@ -0,0 +1,59 @@
+name: postgres-execute-sql
+version: '1.0.0'
+description: Execute arbitrary SQL against a Postgres database. Supports both connection string and explicit env var configuration.
+
+parameters:
+  sql:
+    type: string
+    description: "SQL statement to execute. Use parameterized queries for safety (e.g. $1, $2)."
+    required: true
+  params:
+    type: array
+    description: "Optional array of parameters to pass to the query."
+    required: false
+  schema:
+    type: string
+    description: "Optional schema name to search for tables or qualify queries."
+    required: false
+
+execution:
+  type: function
+  # The function file path is resolved relative to this definition.yaml
+  code: ./execute-sql.py
+  timeout: 30000
+
+authentication:
+  type: custom
+  notes: |
+    The tool supports two authentication modes (choose either):
+    1. Connection string - set `MATIMO_POSTGRES_URL` to a full Postgres connection string (recommended).
+    2. Separate env vars - set `MATIMO_POSTGRES_HOST`, `MATIMO_POSTGRES_PORT`, `MATIMO_POSTGRES_USER`, `MATIMO_POSTGRES_PASSWORD`, `MATIMO_POSTGRES_DB`.
+  # Consumers should treat secrets as env variables. This custom auth type
+  # documents expected environment variables but does not enforce a single
+  # auth scheme - the executor reads either `MATIMO_POSTGRES_URL` or the
+  # individual env vars at runtime.
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+output_schema:
+  type: object
+  properties:
+    rows:
+      type: array
+      items:
+        type: object
+    rowCount:
+      type: number
+
+examples:
+  - name: Simple select
+    params:
+      sql: "SELECT id, name FROM users WHERE id = $1"
+      params: [1]
+
+  - name: Parameterless query
+    params:
+      sql: "SELECT count(*) as cnt FROM users"

matimo_postgres-0.1.0/src/matimo_postgres/tools/execute-sql/execute-sql.py

@@ -0,0 +1,93 @@
+"""
+execute-sql — Execute arbitrary SQL against a PostgreSQL database.
+Mirrors: typescript/packages/postgres/tools/execute-sql/execute-sql.ts
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import quote_plus
+
+from matimo.errors import ErrorCode, MatimoError
+
+
+async def run(params: dict[str, Any]) -> dict[str, Any]:
+    sql: str = params.get("sql", "").strip()
+    query_params: list | None = params.get("params")
+    schema: str | None = params.get("schema")
+
+    if not sql:
+        raise MatimoError(
+            "Missing SQL statement",
+            ErrorCode.EXECUTION_FAILED,
+            {"tool_name": "postgres-execute-sql"},
+        )
+
+    # Build connection string from MATIMO_POSTGRES_URL or separate env vars
+    connection_string = os.environ.get("MATIMO_POSTGRES_URL")
+
+    if not connection_string:
+        host = os.environ.get("MATIMO_POSTGRES_HOST")
+        port = os.environ.get("MATIMO_POSTGRES_PORT", "5432")
+        user = os.environ.get("MATIMO_POSTGRES_USER")
+        password = os.environ.get("MATIMO_POSTGRES_PASSWORD")
+        database = os.environ.get("MATIMO_POSTGRES_DB")
+
+        if host and user and password and database:
+            connection_string = (
+                f"postgresql://{quote_plus(user)}:{quote_plus(password)}@{host}:{port}/{database}"
+            )
+
+    if not connection_string:
+        raise MatimoError(
+            "Postgres connection information not provided. "
+            "Set MATIMO_POSTGRES_URL or MATIMO_POSTGRES_HOST/PORT/USER/PASSWORD/DB",
+            ErrorCode.EXECUTION_FAILED,
+            {"tool_name": "postgres-execute-sql"},
+        )
+
+    try:
+        import asyncpg  # type: ignore[import]
+    except ImportError:
+        raise MatimoError(
+            "asyncpg is required for the postgres tool. Install it with: pip install asyncpg",
+            ErrorCode.EXECUTION_FAILED,
+            {"tool_name": "postgres-execute-sql"},
+        ) from None
+
+    conn = None
+    try:
+        conn = await asyncpg.connect(connection_string)
+
+        # Set search_path if schema is specified
+        if schema:
+            await conn.execute(f"SET search_path TO {schema}")
+
+        rows = await conn.fetch(sql, *(query_params or []))
+        return {
+            "rows": [dict(row) for row in rows],
+            "row_count": len(rows),
+        }
+
+    except MatimoError:
+        raise
+    except Exception as exc:
+        msg = str(exc)
+        details: dict[str, Any] = {"original_message": msg}
+
+        if "Connection refused" in msg or "ECONNREFUSED" in msg:
+            details["hint"] = "Connection refused — is Postgres running at the configured host/port?"
+        elif "role" in msg and "does not exist" in msg:
+            details["hint"] = "Database user does not exist — check MATIMO_POSTGRES_USER env var"
+        elif "database" in msg and "does not exist" in msg:
+            details["hint"] = "Database does not exist — check MATIMO_POSTGRES_DB env var"
+
+        raise MatimoError(
+            f"Postgres query failed: {msg}",
+            ErrorCode.EXECUTION_FAILED,
+            {"tool_name": "postgres-execute-sql", "details": details},
+        ) from exc
+
+    finally:
+        if conn:
+            await conn.close()