feat: add declarative database tool templates

[QueryPlanner]

Summary

Add a safe declarative database-tool system that lets Blacki define simple data tables and query/report templates without creating arbitrary executable code or mutating the core system prompt.

Priority

Medium

Level of Effort

Large

Problem

Some user-specific workflows need lightweight custom storage and retrieval beyond hardcoded tools. Letting the agent write Python tools, run arbitrary DDL, or edit its system prompt would be unsafe and hard to test. A safer model is to let the agent create constrained schemas and saved query templates that are validated by application code.

Proposed Approach

Add a declarative capability layer with allowlisted primitives:

• Create simple SQLite tables from validated schema definitions.
• Create saved query/report templates against those tables.
• Run saved templates through a generic tool.
• Store generated tool descriptions as metadata, not executable code.
• Keep custom instructions separate from the system prompt.

The agent should not be able to run arbitrary SQL, edit prompt.py, or write Python tool code.

Possible Tables

• custom_tables
• custom_table_columns
• saved_query_templates
• saved_tool_descriptions
• custom_instruction_overrides

Passing Criteria

• Unit tests prove invalid table names, column names, and SQL fragments are rejected.
• Unit tests prove only allowlisted SQLite types can be used.
• Unit tests prove saved query templates cannot execute arbitrary DDL/DML.
• Integration tests prove a table can be created, populated, queried, and reported through the generic tool.
• Prompt tests prove generated/custom instructions are loaded as bounded user context, not as system prompt replacement.
• uv run ruff format, uv run ruff check, uv run mypy ., and uv run pytest --cov=src pass.

Sources

• Current repository: https://github.com/QueryPlanner/blacki
• SQLite storage base: https://github.com/QueryPlanner/blacki/blob/main/src/blacki/storage/base.py
• SQLite connection setup: https://github.com/QueryPlanner/blacki/blob/main/src/blacki/storage/sqlite.py
• Tool registry: https://github.com/QueryPlanner/blacki/blob/main/src/blacki/registry.py
• Preference storage pattern: https://github.com/QueryPlanner/blacki/blob/main/src/blacki/utils/preferences.py
• Existing workout tools needing a more flexible model: https://github.com/QueryPlanner/blacki/blob/main/src/blacki/workouts/tools.py