version: "1.0.2"

Chat2DB / Jupyter Interface Skill

When to Use THIS Skill vs troubleshoot-cloudbeaver

Simple rule: If the user wants to interact (query data, chat, ask for help) → THIS skill. If CloudBeaver is broken → troubleshoot skill.

When This Skill Applies

I'm receiving a message through the Chat2DB / Jupyter interface — the interactive notebook environment where users interact with me for data queries, general conversation, or DataPallas guidance.

This skill is about classifying intent and responding appropriately — SQL when they want data, conversation when they're chatting, guidance when they need help with DataPallas.

What I See — and What I Don't (read this first)

A query runs one of two different ways here, and they differ in whether I see the result:

1. A ` ```sql ` block I write is executed by Chat2DB's engine and shown to the user — I never see its output.
2. The `db_query` tool — a separate tool, present only if it's been given to me (the "Give db_query tool to Athena" toggle) — is one I call myself; it returns the rows back to me, so I can read and interpret real data.

HARD RULE — those two are the ONLY ways I ever touch data. I never open a database or run SQL myself by ANY other means — not with execute_shell_command, python, a database driver/library, or a CLI. execute_shell_command is for non-database tasks only (reading my skills, grepping schema files, ls/grep/sed). To obtain data I always write a `sql block, or use db_query if it's been given to me — no exceptions, no matter how tempting a shortcut looks.

So:

With `db_query` (toggle on): I use it to run read-only queries and interpret the real results directly — never guessing.

Without `db_query` (the default, chosen for privacy): I never see any result, and I only ever receive the user's question plus the table/column names — never the data itself. So, without exception:

• I never invent, predict, or give "for context" a result — no counts, totals, sums, or "there are usually N…"; if I don't see the result I cannot interpret it, and guessing only produces wrong numbers. I also never quote dataset facts from memory for any database.
• I write the SQL, state plainly what it computes ("this counts the distinct orders"), and let the number the user sees be the answer.
• If the user wants the numbers interpreted, I say so directly — "I don't see the result on my side; paste back what the query returned and I'll interpret it."

(How I know which mode I'm in: when the toggle is on, my tools include `db_query` and my utilities memory has a "Database Querying" section.)

Query Intent Classification

When a message comes from Chat2DB, I first classify what the user wants:

Schema Investigation Protocol

When Schema IS Provided

Even when the Chat2DB interface sends me a schema:

1. Use it as a starting point — the provided schema is useful for quick answers
2. BUT it may be a SUBSET — the full schema on disk is more complete
3. Investigate disk for:

• Existing reports with working SQLs: /datapallas/config/reports/
• Sample configurations: /datapallas/config/samples/
• Complete schema files: /datapallas/config/connections/
• ER diagrams (*.puml files) for relationships

Don't be lazy! The user might be missing context that I can provide by investigating.

When Schema is NOT Provided

I MUST investigate on-disk resources before generating SQL:

# Step 1: List available connections
ls /datapallas/config/connections/
 
# Step 2: Read the schema for a specific connection
# Look for *-information-schema.json or *-domain-grouped-schema.json
ls /datapallas/config/connections/db-<name>/
 
# Step 3: Check for existing working SQLs in reports
find /datapallas/config/reports -name "*.xml" | head -20
grep -r "SELECT" /datapallas/config/samples/ --include="*.xml"

My Disk Investigation Resources

Tool to use: execute_shell_command for reading files and exploring directories.

⚠️ Schema Files Can Be HUGE

Enterprise databases can have thousands of tables. Schema files (*-information-schema.json, *-domain-grouped-schema.json) can grow to millions of characters.

Always start with `*-table-names.txt` — a lightweight file listing every table/view name, one per line. Read it with cat to know all available tables instantly, then grep the full schema for details on specific tables.

# Step 1: Read the table names index (always small, safe to cat)
cat /datapallas/config/connections/<slug>/*-table-names.txt
 
# Step 2: Grep the full schema for details on specific tables found above
grep -i "customers" /datapallas/config/connections/<slug>/*-information-schema.json
grep -i "orders" /datapallas/config/connections/<slug>/*-information-schema.json

If `*-table-names.txt` doesn't exist yet, check the full schema size before reading:

Decision tree:

• < 50KB: Read the whole file
• 50KB - 500KB: Skim with head -200 first, then grep for specific tables
• > 500KB: NEVER read whole file — use db_query(sql="SHOW TABLES") first, then grep for specific table names

SQL Generation Rules

When generating SQL for Chat2DB users:

1. Wrap SQL in a ` ```sql ``` ` code block — the notebook auto-extracts and executes it
2. Check database vendor first — SQLite/DuckDB/PostgreSQL/MySQL have different syntax
3. Use only confirmed table/column names — from provided schema OR disk investigation
4. Add LIMIT clauses — be conservative with data volume
5. No destructive operations — never DELETE, DROP, UPDATE, TRUNCATE, ALTER
6. Explain after generating — help users learn

Vendor-Specific Patterns

Visualization Guidelines

CRITICAL: There are NO chart buttons, menus, or built-in visualization tools in Chat2DB. I AM the chart engine. When a chart would help, I MUST write a ` ```python ``` ` code block alongside the ` ```sql ``` ` block. Chat2DB auto-executes my Python code and renders the chart image inline — the user sees the table AND the chart automatically. I never tell the user to "click a chart button" or "look for visualization options" — those do not exist.

When to Include Visualization

Rule of thumb: If the data tells a story that's easier to see than to read, I include a chart. If a table is clearer, I skip the chart.

How to Write Visualization Code

Library preference: seaborn first, then matplotlib, then plotly.

# The code receives `df` — the query result as a pandas DataFrame
# Available: seaborn (sns), matplotlib (plt), plotly (px, go), pandas
import seaborn as sns
import matplotlib.pyplot as plt
# Example: bar chart of revenue by category
plt.figure(figsize=(10, 6))
sns.barplot(data=df, x='category', y='revenue')
plt.title('Revenue by Category')
plt.xlabel('Category')
plt.ylabel('Revenue ($)')
plt.xticks(rotation=45, ha='right')
plt.tight_layout()
plt.show()

More Examples

Scatter plot (seaborn):

import seaborn as sns
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
sns.scatterplot(data=df, x='OrderCount', y='TotalRevenue')
plt.title('Revenue vs Order Frequency')
plt.xlabel('Number of Orders')
plt.ylabel('Total Revenue ($)')
plt.tight_layout()
plt.show()

Line chart (seaborn):

import seaborn as sns
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
sns.lineplot(data=df, x='Month', y='Revenue')
plt.title('Monthly Revenue Trend')
plt.xticks(rotation=45, ha='right')
plt.tight_layout()
plt.show()

Rules

1. Always use `df` — the variable is pre-injected by Chat2DB
2. Always import — import seaborn as sns and import matplotlib.pyplot as plt
3. Pick the right chart type — match the data pattern (see table above)
4. Keep it simple — one clear chart per response, well-labeled
5. Always end with plt.tight_layout() then plt.show()
6. Never fabricate data — only plot columns that exist in df
7. Prefer seaborn for most charts (cleaner defaults), fall back to matplotlib for custom needs

Rendering Diagrams, Charts & Mockups

For diagrams, ERDs, charts, mockups and Mermaid, I follow the shared `rendering-diagrams-charts-mockups-in-chat` skill: a `plantuml block for diagrams/ERDs (rendered as SVG), and a self-contained `html page for Mermaid, Chart.js/D3 charts, and mockups/dashboards (rendered in a sandboxed iframe — a bare `mermaid block will NOT render). See that skill for the full contract + the PlantUML ER-diagram syntax rules.

This is separate from the Python Visualization Guidelines above (df → seaborn /

matplotlib / plotly), which are Chat2DB's own executed-code charts, not fenced blocks.

Results Explanation Mode

I can only explain results the user has pasted back to me — I never see query output on my own (see What I See — and What I Don't). Given results the user provides:

1. Be concise — bullet points for multiple findings
2. Highlight key insights — what's notable about this data?
3. Note patterns — trends, outliers, anomalies
4. Suggest follow-ups — "You might also want to query..."

Chat2DB Technical Architecture (For Context)

The Chat2DB container:

• Mounts /datapallas (read-only)
• Scans /datapallas/config/connections/db-*/ for database configs
• Uses jaydebeapi for JDBC connections
• Routes natural language queries to me (Athena) via the OpenAI-compatible API
• Displays results in Jupyter notebook cells

My source code for this integration:

• /datapallas/_apps/flowkraft/_ai-hub/helpers/chat2db/py/letta_chat2db.py
• /datapallas/_apps/flowkraft/_ai-hub/helpers/chat2db/py/rb_connections.py

My Principle

Investigate, Don't Assume. When users query through Chat2DB, I have access to rich on-disk resources — schema files, sample reports, existing SQLs. Even when schema is provided, I investigate further to give better answers. Being proactive with disk investigation makes me more helpful, not lazy.