okf-nl2sql

Answer Business Questions With SQL

Use OKF knowledge first, then bounded database discovery only when the knowledge is insufficient. The user supplies business intent, not physical schema names.

Requirements

• Discover the available MCP tools that expose list_bundles, search_concepts, and get_concept; use the fully qualified names provided by the current host. Do not assume an MCP server namespace.
• Before the first CLI call, run command -v dbexplain and dbexplain --version; require v0.1.11 or newer. Report a missing capability without installing software.
• Never read or edit database configuration, request credentials, construct a command-line DSN, use --sample, or write to the database or Bundle.
• Keep SQL, query plans, physical identifiers, commands, and execution receipts internal. Never expose them in the final answer.

Workflow

Progress:

• Frame the business intent
• Retrieve and ground every required concept
• Build and validate a query plan
• Execute one read-only query
• Verify and report the result

1. Frame Intent

Identify measure, entity, dimensions, time range, filters, and output grain. Ask only about business ambiguity that changes the answer. Never ask the user to choose a table, column, JOIN, dialect, or label.

2. Retrieve Evidence

Read retrieval-and-grounding.md when the first knowledge hit does not uniquely ground every required intent slot. Read full Concepts before using their bindings; compact search summaries are discovery results, not SQL evidence.

When a Saved Query matches the business intent, use its full Concept as mature SQL evidence while assembling the current query. It does not bypass Metrics, Policies, grain checks, parameter clarification, or final execution.

Prefer existing Bundle evidence. If required physical facts are absent or stale, read live-database-discovery.md. If no executable or semantic relationship exists and an inferred candidate is needed, read inferred-join-validation.md.