Skip to content

Personal AI, On Personal Devices

Python

feat: add knowledge_sql tool for read-only SQL aggregation queries

Jon Saad-Falcon5ea5df93d492
diff --git a/src/openjarvis/tools/knowledge_sql.py b/src/openjarvis/tools/knowledge_sql.py
new file mode 100644
index 00000000..15001de9
--- /dev/null
+++ b/src/openjarvis/tools/knowledge_sql.py
@@ -0,0 +1,130 @@
+"""KnowledgeSQLTool — read-only SQL queries against the KnowledgeStore.
+
+Allows agents to run SELECT queries for aggregation, counting, ranking,
+and filtering operations that BM25 search cannot handle.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Any, Optional
+
+from openjarvis.connectors.store import KnowledgeStore
+from openjarvis.core.registry import ToolRegistry
+from openjarvis.core.types import ToolResult
+from openjarvis.tools._stubs import BaseTool, ToolSpec
+
+_MAX_ROWS = 50
+
+_SCHEMA_DESCRIPTION = (
+ "Table: knowledge_chunks\n"
+ "Columns: id, content, source, doc_type, doc_id, title, author, "
+ "participants, timestamp, thread_id, url, metadata, chunk_index"
+)
+
+
[email protected]("knowledge_sql")
+class KnowledgeSQLTool(BaseTool):
+ """Run read-only SQL against the knowledge store for aggregation queries."""
+
+ tool_id = "knowledge_sql"
+
+ def __init__(self, store: Optional[KnowledgeStore] = None) -> None:
+ self._store = store
+
+ @property
+ def spec(self) -> ToolSpec:
+ return ToolSpec(
+ name="knowledge_sql",
+ description=(
+ "Run a read-only SQL SELECT query against the knowledge_chunks table. "
+ "Use for counting, ranking, aggregation, and filtering. "
+ f"{_SCHEMA_DESCRIPTION}"
+ ),
+ parameters={
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": (
+ "SQL SELECT query. Only SELECT statements allowed. "
+ "Example: SELECT author, COUNT(*) as n "
+ "FROM knowledge_chunks "
+ "WHERE source='imessage' GROUP BY author "
+ "ORDER BY n DESC LIMIT 10"
+ ),
+ },
+ },
+ "required": ["query"],
+ },
+ category="knowledge",
+ )
+
+ def execute(self, **params: Any) -> ToolResult:
+ if self._store is None:
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content="No knowledge store configured.",
+ success=False,
+ )
+
+ query: str = params.get("query", "").strip()
+ if not query:
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content="No query provided.",
+ success=False,
+ )
+
+ normalized = query.lstrip().upper()
+ if not normalized.startswith("SELECT"):
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content="Only SELECT queries are allowed (read-only).",
+ success=False,
+ )
+
+ _FORBIDDEN = ("DROP", "DELETE", "INSERT", "UPDATE", "ALTER", "CREATE", "ATTACH")
+ for forbidden in _FORBIDDEN:
+ if forbidden in normalized:
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content=(
+ f"Query contains forbidden keyword: {forbidden}."
+ " Only SELECT queries allowed."
+ ),
+ success=False,
+ )
+
+ try:
+ rows = self._store._conn.execute(query).fetchmany(_MAX_ROWS)
+ except sqlite3.OperationalError as exc:
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content=f"SQL error: {exc}",
+ success=False,
+ )
+
+ if not rows:
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content="Query returned no results.",
+ success=True,
+ metadata={"num_rows": 0},
+ )
+
+ columns = rows[0].keys()
+ lines = [" | ".join(columns)]
+ lines.append(" | ".join("---" for _ in columns))
+ for row in rows:
+ lines.append(" | ".join(str(row[c]) for c in columns))
+
+ return ToolResult(
+ tool_name="knowledge_sql",
+ content="\n".join(lines),
+ success=True,
+ metadata={"num_rows": len(rows)},
+ )
+
+
+__all__ = ["KnowledgeSQLTool"]
diff --git a/tests/tools/test_knowledge_sql.py b/tests/tools/test_knowledge_sql.py
new file mode 100644
index 00000000..c2be20b9
--- /dev/null
+++ b/tests/tools/test_knowledge_sql.py
@@ -0,0 +1,77 @@
+"""Tests for KnowledgeSQLTool."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from openjarvis.connectors.store import KnowledgeStore
+from openjarvis.core.registry import ToolRegistry
+
+
+def store(tmp_path: Path) -> KnowledgeStore:
+ ks = KnowledgeStore(str(tmp_path / "test.db"))
+ ks.store("Hello from Alice", source="imessage", author="Alice", doc_type="message")
+ ks.store("Hello from Alice again", source="imessage", author="Alice", doc_type="message")
+ ks.store("Meeting notes Q1", source="granola", author="Bob", doc_type="document")
+ ks.store("Email about Spain trip", source="gmail", author="Carol", doc_type="email")
+ return ks
+
+
+def test_select_count(store: KnowledgeStore) -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ tool = KnowledgeSQLTool(store=store)
+ result = tool.execute(query="SELECT COUNT(*) as total FROM knowledge_chunks")
+ assert result.success
+ assert "4" in result.content
+
+
+def test_group_by_author(store: KnowledgeStore) -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ tool = KnowledgeSQLTool(store=store)
+ result = tool.execute(
+ query="SELECT author, COUNT(*) as n FROM knowledge_chunks GROUP BY author ORDER BY n DESC"
+ )
+ assert result.success
+ assert "Alice" in result.content
+ assert "2" in result.content
+
+
+def test_rejects_non_select(store: KnowledgeStore) -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ tool = KnowledgeSQLTool(store=store)
+ result = tool.execute(query="DELETE FROM knowledge_chunks")
+ assert not result.success
+ assert "read-only" in result.content.lower() or "SELECT" in result.content
+
+
+def test_rejects_drop(store: KnowledgeStore) -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ tool = KnowledgeSQLTool(store=store)
+ result = tool.execute(query="DROP TABLE knowledge_chunks")
+ assert not result.success
+
+
+def test_handles_bad_sql(store: KnowledgeStore) -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ tool = KnowledgeSQLTool(store=store)
+ result = tool.execute(query="SELECT * FROM nonexistent_table")
+ assert not result.success
+
+
+def test_filter_by_source(store: KnowledgeStore) -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ tool = KnowledgeSQLTool(store=store)
+ result = tool.execute(
+ query="SELECT title, author FROM knowledge_chunks WHERE source = 'gmail'"
+ )
+ assert result.success
+ assert "Carol" in result.content
+
+
+def test_registered() -> None:
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ ToolRegistry.register_value("knowledge_sql", KnowledgeSQLTool)
+ assert ToolRegistry.contains("knowledge_sql")