Asking the database in plain language

First the user asks what they need to know, written the way they would say it out loud. The model never touches the database: it picks from a closed catalogue of nine Python functions with typed signatures, and every one of them is executed in a terminal. “Which sales rep has the best euros-per-kilometre ratio” becomes a single call: the ranking function, the sales-rep dimension, the euros-per-kilometre metric.

Then every parameter is validated, before anything runs. Dimensions, metrics, filters and periods come from closed lists. If you ask for sales “by salesperson” and that is not one of the seven dimensions, the call fails and returns the seven that are valid. If you filter by a client called “restaurante” and three clients match, it refuses and names all three so you can pick. If you ask for kilometres per product, it explains that route metrics only make sense per sales rep. The model reads the error, corrects, and retries once.

There are seven dimensions (product, category, client, sales rep, region, channel and client type) and eight metrics (revenue, units, order count, average order value, kilometres, visits, euros per kilometre and euros per visit). Route metrics are only accepted per sales rep, because attributing kilometres to a product is meaningless, and the function says so.

The arithmetic is done by the code, not by the model. The function runs a parameterised query, and summing, averaging and dividing happen in Python over the rows the database returns. The answer in the chat is built from that result and nothing else, so the figure you read is exactly the one that came out of the calculation. Free text never reaches the database either: there is no SQL parameter, no expression field, no escape hatch. The model decides what to ask; it can never decide how to query.

Writes work the same way. “Raise the price of the 500 ml extra virgin to 12.50” goes through the update function, which only accepts a per-table whitelist of columns and returns the record before and after the change, so the edit is visible rather than asserted.

To finish, the answer arrives inside the chat as a table with the bars drawn on the line itself, and as an HTML report with its chart when one is asked for. Every call is appended to a log with its arguments, the number of rows it returned and the milliseconds it took, so “how did you do that?” is answered by reading that log rather than rebuilding it from memory.