FietSQL × Ollama Playbook

This companion README focuses on the Ollama distribution of the fietSQL model (cowolff/fietSQL). It walks through building prompts with this package, handing them to Ollama, and validating the returned SQL before you run it anywhere else.

Prerequisites

Python ≥ 3.8 with this package installed:
```
pip install fietSQL
```
Ollama installed locally – see https://ollama.com/download
Pull the model once so it is cached:
```
ollama pull cowolff/fietSQL
```
Ollama Python client for talking to the local daemon:
```
pip install ollama
```

Step 1 – Describe your schema and question

SCHEMA = """
CREATE TABLE customers (
    id INTEGER PRIMARY KEY,
    name TEXT,
    city TEXT
);

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    customer_id INTEGER,
    total NUMERIC
);
"""

QUESTION = "Which city has the highest total sales?"

Keep the schema close to the real database (column names, aliases, relationships). The higher the fidelity, the better the SQL the model can synthesize.

Step 2 – Build the fietSQL chat prompt

from fietSQL import build_prompt

prompt = build_prompt(schema=SCHEMA, question=QUESTION)
print(prompt)

build_prompt produces the <|im_start|>/<|im_end|> meta format that fietSQL expects. If you need few-shot examples, concatenate them onto the returned string before calling Ollama.

Step 3 – Send the prompt through the Ollama Python library

import ollama
from fietSQL import build_prompt

prompt = build_prompt(schema=SCHEMA, question=QUESTION)

response = ollama.generate(
    model="cowolff/fietSQL",
    prompt=prompt,
    stream=False,
)
sql = response["response"].strip()

ollama.generate talks directly to your local Ollama daemon and returns the model output as a Python dict. The SQL is typically in response["response"]; adjust parsing if you enable streaming or include multiple turns.

Step 4 – Verify the SQL before execution

from fietSQL import evaluate_executability

report = evaluate_executability(SCHEMA, sql)
if report.is_executable:
    print("Looks good!", report.details)
else:
    print("SQL failed fast:", report.details)
    print("Missing tables:", report.missing_tables)
    print("Missing columns:", report.missing_columns)

evaluate_executability spins up an in-memory SQLite database with your DDL, runs the query, and captures missing-table/column hints to help you refine your prompt or schema description.

End-to-end sample script

#!/usr/bin/env python3
import ollama
from fietSQL import build_prompt, evaluate_executability

SCHEMA = """
CREATE TABLE customers (
    id INTEGER PRIMARY KEY,
    name TEXT,
    city TEXT
);

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    customer_id INTEGER,
    total NUMERIC
);
"""
QUESTION = "Which city has the highest total sales?"

prompt = build_prompt(SCHEMA, QUESTION)
response = ollama.generate(
    model="cowolff/fietSQL",
    prompt=prompt,
    stream=False,
)
sql = response["response"].strip()
print("\nGenerated SQL:\n", sql)

report = evaluate_executability(SCHEMA, sql)
print("\nExecutability:", report.is_executable)
print(report.details)

Save this as run_ollama.py, make it executable, and iterate on your schema/questions. Because everything stays local, turnaround time is fast.

Troubleshooting

Symptom	Likely cause	Fix
`ollama: command not found`	Ollama daemon isn’t installed or not on PATH.	Install Ollama and restart your shell.
`ModuleNotFoundError: No module named 'ollama'`	Python client not installed in current environment.	Run `pip install ollama` inside your virtual env.
Model responds with prose instead of SQL	Prompt missing clear instruction.	Ensure you use `build_prompt` or add “Write the SQL query” to your prompt manually.
`evaluate_executability` reports missing tables	Schema lacks the referenced table names.	Add the relevant CREATE TABLE statements to your schema string.

Helpful commands

# Refresh the local model cache
ollama pull cowolff/fietSQL

# Test a prompt quickly
echo "<prompt>" | ollama run cowolff/fietSQL

# Run the unit tests for the helper library
python -m pytest

Models

Readme