notebook-cell

You are helping the user add StackQL query cells to an existing Jupyter notebook that uses the pystackql magic extension.

Input: $@

Follow these steps in order.

Step 1 - Find the target notebook

Look for open or recently modified .ipynb files:

find . -name "*.ipynb" -not -path '*/.git/*' -not -path '*/.ipynb_checkpoints/*' 2>/dev/null

If multiple notebooks exist, check which ones already use pystackql:

grep -l "pystackql" *.ipynb 2>/dev/null

If there are multiple candidates, ask the user which notebook to add cells to.

If no notebook exists, suggest using /stackql-skills:notebook to create one first.

Step 2 - Read the existing notebook

Read the notebook to understand:

• Which magic extension is loaded (pystackql.magic or pystackql.magics)
• What providers have been pulled
• What Python variables are defined (these can be used in queries via $variable)
• How many cells exist (to determine insert position)
• What queries already exist (to avoid duplication)

Step 3 - Parse the request

Determine what the user wants:

• Raw SQL: the user provided a StackQL query directly
• Natural language: the user described what they want to query - generate the SQL
• --viz flag: what visualization to add (bar, line, table, or auto-detect)
• --no-display: suppress query output display

If the input is natural language, use the existing notebook context (pulled providers, variables) to generate the appropriate query. If needed, discover the schema:

stackql exec "DESCRIBE <provider>.<service>.<resource>;" --output json

Step 4 - Generate the cells

Cell conventions

Follow these rules for all notebook cells:

• One heading per cell, placed at the top
• No horizontal rules (---, ***, ___) or <hr/> tags
• Use spacing and headings to separate sections, not horizontal rules

Create 2-3 cells to insert:

Markdown cell

## <Section Title>

<Brief description of what this query does.>

Query cell

For single-line queries:

%stackql <QUERY>

For multi-line queries:

%%stackql
SELECT
    <fields>
FROM <provider>.<service>.<resource>
WHERE <params>

Options:

• Add --no-display to the %%stackql line if the flag was passed
• Add --csv-download if the user wants export capability

Use $variable substitution for any values that match Python variables already defined in the notebook.

Use $$ to escape literal dollar signs in JSON path expressions.

Visualization cell (if --viz or auto-detected)

Bar chart (--viz bar):

stackql_df.plot(kind='bar', x='<x_col>', y='<y_col>', title='<Title>');

Line chart (--viz line):

stackql_df.plot(kind='line', x='<x_col>', y='<y_col>', title='<Title>');

Table (--viz table):

stackql_df

Auto-detect: If the result likely has a categorical column and a numeric column, suggest a bar chart. If it has a date/time column and a numeric column, suggest a line chart. Otherwise, just display as a table.

Step 5 - Insert the cells

Use the NotebookEdit tool to insert the cells at the end of the notebook (or at a user-specified position).

Step 6 - Report

Briefly confirm what was added:

• The query that was inserted
• The visualization type (if any)
• Remind the user to run the cells in order
• Note that stackql_df will contain the query results as a pandas DataFrame