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.pynew file mode 100644index 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.pynew file mode 100644index 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")