🔍 About This Code Showcase
These snippets show the heart of the build: a declarative toolset that is the agent's entire universe, and the governed gate that can execute nothing but those fixed, parameterized queries.
Synthetic-data generation and the conversational layer are omitted here for clarity. The full project is on GitHub.
🧾 The Toolset Is the Agent's Universe — tools.yaml
Each tool's SQL is fixed; the agent supplies only bound parameter values. There is deliberately no execute_sql, no list_tables, and no natural-language-to-SQL tool.
sources:
klinik-db:
kind: sqlite
database: ../data/klinik.db
tools:
list_inactive_patients:
kind: sqlite-sql
source: klinik-db
description: Lapsing / recall list. Returns name + last visit only.
parameters:
- name: since_date
type: string
description: Cut-off ISO date.
statement: |
SELECT p.name, MAX(cn.visit_date) AS last_visit
FROM patients p JOIN case_notes cn ON cn.patient_id = p.id
GROUP BY p.id
HAVING MAX(cn.visit_date) < :since_date
ORDER BY last_visit;
toolsets:
front_desk:
- condition_trend
- list_inactive_patients
- cluster_recent_symptoms
🔒 The Governed Gate — tool_runner.py
One component touches the database. It refuses any unknown tool, any unexpected parameter, and opens the connection read-only. There is no code path that runs caller-supplied SQL.
class GovernedToolset:
def __init__(self, toolset_name="front_desk"):
cfg = yaml.safe_load(open(TOOLS_YAML))
names = cfg["toolsets"][toolset_name]
self.loaded = {n: cfg["tools"][n] for n in names}
self.con = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
def run(self, name, **params):
if name not in self.loaded:
raise ValueError(
f"Tool '{name}' is not in this agent's toolset. "
f"No such capability exists — refused.")
spec = self.loaded[name]
self._check_params(name, spec, params)
if spec["kind"] == "sqlite-sql":
return [dict(r) for r in self.con.execute(spec["statement"], params)]
...
def _check_params(self, name, spec, params):
declared = {p["name"] for p in spec.get("parameters", [])}
unknown = set(params) - declared
if unknown:
raise ValueError(f"{name}: unknown parameter(s) {sorted(unknown)} — refused.")
🛡️ Proving It — guardrails_demo.py
Every test below is supposed to fail. Running the script confirms the four governance layers are real, not rhetorical.
expect_refused("Call a generic execute_sql tool",
lambda: ts.run("execute_sql", sql="SELECT * FROM patients"))
expect_refused("Inject an unexpected parameter",
lambda: ts.run("list_inactive_patients",
since_date="2025-06-01",
extra="'; DROP TABLE patients;--"))
def attempt_write():
ts.con.execute("DELETE FROM appointments WHERE status='no-show'")
expect_refused("Direct write on the read-only connection", attempt_write)