@toolbeltai/skills 0.1.0

package/sql-analyst/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: sql-analyst
+description: >
+  Text-to-SQL analyst powered by Toolbelt MCP. Toolbelt is a multi-modal data
+  platform combining SQL analytics, vector search, and real-time streaming.
+  Uploads a CSV, auto-generates schema context, then answers natural language
+  questions by generating and executing SQL. Use when an AI agent needs to analyze
+  tabular data without writing queries manually — upload, ask, get answers.
+license: MIT
+compatibility: >
+  Requires a Toolbelt account (provision free at https://toolbelt.ai) and an
+  MCP-compatible AI agent (Claude Code, Claude Desktop, or any client that
+  supports MCP server connections). MCP connection must be pre-established
+  before invocation.
+metadata:
+  author: toolbeltai
+  version: "1.0"
+  openclaw:
+    emoji: "📊"
+    homepage: "https://toolbelt.ai/docs/sql"
+    skillKey: "sql-analyst"
+---
+
+Upload tabular data and answer natural language questions about it using
+Toolbelt MCP tools. Work through each phase in order without prompting for
+user input. On unrecoverable error, emit a structured failure and halt.
+
+## When Not To Use
+
+- For unstructured text or documents — use `knowledge-graph` to extract entities and relationships.
+- For real-time or streaming data — use `streaming-analyst` instead.
+- For spatial data with lat/lon coordinates — use `geo-analyst` instead.
+
+## Invocation Parameters
+
+Extract these from the args string or conversation context before starting:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `namespace_id` | No | UUID of target namespace. Auto-select if omitted and only one exists; fail if ambiguous. |
+| `csv_content` | No | Raw CSV text to upload. Uses the embedded sample dataset if omitted. |
+| `asset_name` | No | Name for the uploaded table asset. Defaults to `sales-data`. |
+| `question` | No | Natural language question to ask about the data. Defaults to `What is the total sales amount by region?` |
+
+---
+
+## Default Sample Data
+
+If no `csv_content` is provided, use this sales dataset verbatim:
+
+```
+order_id,date,region,product,category,quantity,unit_price,amount,rep
+1001,2024-01-05,Northeast,Widget Pro,Hardware,12,49.99,599.88,Alice Chen
+1002,2024-01-08,Southeast,Gadget Basic,Software,5,29.99,149.95,Bob Martinez
+1003,2024-01-12,Midwest,Widget Pro,Hardware,8,49.99,399.92,Carol Singh
+1004,2024-01-15,West,Service Plan,Services,3,199.00,597.00,David Park
+1005,2024-01-19,Northeast,Gadget Basic,Software,20,29.99,599.80,Alice Chen
+1006,2024-01-22,West,Widget Pro,Hardware,6,49.99,299.94,Emma Lopez
+1007,2024-02-03,Southeast,Service Plan,Services,2,199.00,398.00,Bob Martinez
+1008,2024-02-07,Midwest,Gadget Plus,Software,15,79.99,1199.85,Frank Kim
+1009,2024-02-11,Northeast,Widget Pro,Hardware,10,49.99,499.90,Alice Chen
+1010,2024-02-14,West,Gadget Basic,Software,8,29.99,239.92,David Park
+1011,2024-02-18,Southeast,Gadget Plus,Software,4,79.99,319.96,Carol Singh
+1012,2024-02-21,Midwest,Service Plan,Services,1,199.00,199.00,Frank Kim
+1013,2024-03-02,Northeast,Service Plan,Services,5,199.00,995.00,Alice Chen
+1014,2024-03-06,West,Gadget Plus,Software,9,79.99,719.91,Emma Lopez
+1015,2024-03-10,Southeast,Widget Pro,Hardware,7,49.99,349.93,Bob Martinez
+1016,2024-03-14,Midwest,Gadget Basic,Software,11,29.99,329.89,Carol Singh
+1017,2024-03-18,Northeast,Gadget Plus,Software,6,79.99,479.94,David Park
+1018,2024-03-22,West,Service Plan,Services,4,199.00,796.00,Emma Lopez
+1019,2024-03-25,Southeast,Widget Pro,Hardware,3,49.99,149.97,Frank Kim
+1020,2024-03-28,Midwest,Widget Pro,Hardware,14,49.99,699.86,Carol Singh
+```
+
+Default `question`: `What is the total sales amount by region?`
+
+---
+
+## Phase 0: Verify Connection
+
+Call `get_semantic_names` (no arguments) immediately.
+
+- **If it succeeds:** proceed to Phase 1 using the returned namespaces.
+- **If it fails:** emit structured failure and halt.
+
+```
+FAILURE: Toolbelt MCP connection is not established.
+The MCP server must be connected before invoking this skill.
+See: https://toolbelt.ai/docs/mcp for setup instructions.
+```
+
+---
+
+## Phase 1: Resolve Namespace
+
+Use the namespaces returned from Phase 0.
+
+Resolution order:
+1. If `namespace_id` was provided as a parameter, use it directly.
+2. If only one namespace exists, use it.
+3. If multiple exist and no `namespace_id` was specified, emit structured failure and halt.
+
+```
+FAILURE: Multiple namespaces found and none specified.
+Available: [<list namespace display names and IDs>]
+Re-invoke with namespace_id=<uuid>.
+```
+
+Store the resolved `namespace_id` — pass it to every subsequent tool call.
+
+---
+
+## Phase 2: Upload CSV Data
+
+Resolve `csv_content` (use parameter value or default sample above).
+Resolve `asset_name` (use parameter value or default `sales-data`).
+
+Call `toolbelt_save`:
+
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "<asset_name>",
+  "file_name": "<asset_name>.csv",
+  "content": "<csv_content>",
+  "content_encoding": "text",
+  "data_format": "csv"
+}
+```
+
+Record the returned `asset_id`.
+
+---
+
+## Phase 3: Poll for Ingestion
+
+Call `toolbelt_jobs` with `{ "namespace_id": "<namespace_id>" }` every 10 seconds.
+
+Wait for the `ingest` job for this asset to reach `completed`.
+
+Typical duration: 15–60 seconds. Maximum wait: 3 minutes.
+
+If the job reaches `failed` or the timeout elapses, emit structured failure and halt:
+```
+FAILURE: CSV ingestion did not complete.
+Job status: <last observed status>
+```
+
+---
+
+## Phase 4: Get Schema Context
+
+Call `toolbelt_context` with `{ "namespace_id": "<namespace_id>" }`.
+
+Locate the table corresponding to the uploaded asset (match by `asset_name` or
+the table name returned from the save call). Record:
+- `table_name`: the SQL table name for this asset
+- `column_names`: list of columns in the table
+- `row_count`: number of rows if provided in context
+
+---
+
+## Phase 5: Ask a Natural Language Question
+
+Resolve `question` (use parameter value or default).
+
+Call `toolbelt_search`:
+
+```json
+{
+  "question": "<question>",
+  "namespace_id": "<namespace_id>",
+  "synthesize": true
+}
+```
+
+Parse the response to extract:
+- `answer`: the synthesized natural language answer
+- `sql_generated`: the SQL query that was generated and executed
+- `row_count`: number of rows returned by the SQL query
+- `sources`: any cited source tables or assets
+
+If `toolbelt_search` does not return SQL, try `toolbelt_sql` directly with a
+query you write from the schema context:
+
+```json
+{
+  "namespace_id": "<namespace_id>",
+  "query": "SELECT region, SUM(amount) AS total_amount FROM <table_name> GROUP BY region ORDER BY total_amount DESC"
+}
+```
+
+Record whichever path succeeded as `query_method` (`"search"` or `"direct_sql"`).
+
+---
+
+## Phase 6: Structured Output
+
+After all phases complete, emit a single structured result:
+
+```
+RESULT:
+  namespace_id: <uuid>
+  asset_name: <name of uploaded table>
+  table_name: <SQL table name>
+  row_count_ingested: <rows in the table>
+  phases_run: [0, 1, 2, 3, 4, 5]
+
+  question: "<question asked>"
+  query_method: "<'search' or 'direct_sql'>"
+  sql_generated: |
+    <SQL query that was generated or executed>
+  row_count: <number of rows returned by the query>
+  answer: |
+    <synthesized answer>
+  sources: [<cited tables or assets>]
+```
+
+---
+
+## Tool Reference
+
+| Phase | Tool(s) |
+|---|---|
+| 0. Verify connection | `get_semantic_names` |
+| 1. Resolve namespace | (from Phase 0 result) |
+| 2. Upload CSV document | `toolbelt_save` |
+| 3. Poll for ingestion | `toolbelt_jobs` |
+| 4. Get schema context | `toolbelt_context` |
+| 5. Ask question | `toolbelt_search`, `toolbelt_sql` (fallback) |
+| 6. Emit result | (structured output) |

package/streaming-analyst/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: streaming-analyst
+description: >
+  Real-time streaming analytics powered by Toolbelt MCP. Toolbelt is a
+  multi-modal data platform combining SQL analytics, vector search, and real-time
+  streaming. Connects a Kafka topic, runs windowed aggregation queries, and detects
+  anomalies using standard deviation. Falls back to simulated stream data when no
+  Kafka broker is provided. Use when an AI agent needs to analyze streaming data —
+  IoT sensors, event logs, security events, or fleet telemetry — without writing
+  infrastructure code.
+license: MIT
+compatibility: >
+  Requires a Toolbelt account (provision free at https://toolbelt.ai) and an
+  MCP-compatible AI agent (Claude Code, Claude Desktop, or any client that
+  supports MCP server connections). MCP connection must be pre-established
+  before invocation. Kafka parameters are optional — omit them to run with
+  simulated stream data.
+metadata:
+  author: toolbeltai
+  version: "1.0"
+  openclaw:
+    emoji: "📡"
+    homepage: "https://toolbelt.ai/docs/streaming"
+    skillKey: "streaming-analyst"
+---
+
+Connect a Kafka topic (or simulate one) and run real-time aggregation and
+anomaly detection using Toolbelt MCP tools. Work through each phase in order
+without prompting for user input. On unrecoverable error, emit a structured
+failure and halt.
+
+## When Not To Use
+
+- For static batch tabular data — use `sql-analyst` instead.
+- When real-time monitoring, windowed aggregation, or anomaly detection is not the goal.
+
+## Invocation Parameters
+
+Extract these from the args string or conversation context before starting:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `namespace_id` | No | UUID of target namespace. Auto-select if omitted and only one exists; fail if ambiguous. |
+| `kafka_broker` | No | Kafka broker URL (e.g. `kafka-broker:9092`). Omit to use simulated stream data. |
+| `kafka_topic` | No | Kafka topic name. Required if `kafka_broker` is provided. |
+| `kafka_schema` | No | SQL column schema (e.g. `sensor_id VARCHAR(64), ts TIMESTAMP, value DOUBLE`). Defaults to IoT schema below. |
+| `kafka_group_id` | No | Kafka consumer group ID. Omitted if not provided. |
+| `anomaly_threshold` | No | Standard deviation multiplier for anomaly detection. Defaults to `2.0`. |
+
+---
+
+## Default Simulated Stream Data
+
+When `kafka_broker` is not provided, upload this IoT sensor reading dataset as
+a relational asset to simulate a stream snapshot. It includes planted anomalies
+(readings > 2 standard deviations from mean) for detection validation.
+
+```
+sensor_id,ts,value,unit
+sensor-01,2024-03-01 00:00:00,72.3,celsius
+sensor-02,2024-03-01 00:00:00,71.8,celsius
+sensor-03,2024-03-01 00:00:00,70.5,celsius
+sensor-01,2024-03-01 00:01:00,72.6,celsius
+sensor-02,2024-03-01 00:01:00,72.1,celsius
+sensor-03,2024-03-01 00:01:00,71.0,celsius
+sensor-01,2024-03-01 00:02:00,73.0,celsius
+sensor-02,2024-03-01 00:02:00,71.5,celsius
+sensor-03,2024-03-01 00:02:00,70.8,celsius
+sensor-01,2024-03-01 00:03:00,72.8,celsius
+sensor-02,2024-03-01 00:03:00,98.7,celsius
+sensor-03,2024-03-01 00:03:00,71.2,celsius
+sensor-01,2024-03-01 00:04:00,73.1,celsius
+sensor-02,2024-03-01 00:04:00,72.4,celsius
+sensor-03,2024-03-01 00:04:00,45.1,celsius
+sensor-01,2024-03-01 00:05:00,72.5,celsius
+sensor-02,2024-03-01 00:05:00,72.0,celsius
+sensor-03,2024-03-01 00:05:00,71.5,celsius
+sensor-01,2024-03-01 00:06:00,72.9,celsius
+sensor-02,2024-03-01 00:06:00,71.7,celsius
+sensor-03,2024-03-01 00:06:00,70.9,celsius
+sensor-01,2024-03-01 00:07:00,126.4,celsius
+sensor-02,2024-03-01 00:07:00,72.3,celsius
+sensor-03,2024-03-01 00:07:00,71.8,celsius
+sensor-01,2024-03-01 00:08:00,73.2,celsius
+sensor-02,2024-03-01 00:08:00,71.9,celsius
+sensor-03,2024-03-01 00:08:00,71.3,celsius
+```
+
+The three anomalies in this dataset:
+- `sensor-02` at `00:03:00` — value `98.7` (spike high)
+- `sensor-03` at `00:04:00` — value `45.1` (drop low)
+- `sensor-01` at `00:07:00` — value `126.4` (extreme spike)
+
+Default `kafka_schema` (used if broker is provided without schema):
+```
+sensor_id VARCHAR(64), ts TIMESTAMP, value DOUBLE, unit VARCHAR(32)
+```
+
+---
+
+## Phase 0: Verify Connection
+
+Call `get_semantic_names` (no arguments) immediately.
+
+- **If it succeeds:** proceed to Phase 1 using the returned namespaces.
+- **If it fails:** emit structured failure and halt.
+
+```
+FAILURE: Toolbelt MCP connection is not established.
+The MCP server must be connected before invoking this skill.
+See: https://toolbelt.ai/docs/mcp for setup instructions.
+```
+
+---
+
+## Phase 1: Resolve Namespace
+
+Use the namespaces returned from Phase 0.
+
+Resolution order:
+1. If `namespace_id` was provided as a parameter, use it directly.
+2. If only one namespace exists, use it.
+3. If multiple exist and no `namespace_id` was specified, emit structured failure and halt.
+
+```
+FAILURE: Multiple namespaces found and none specified.
+Available: [<list namespace display names and IDs>]
+Re-invoke with namespace_id=<uuid>.
+```
+
+Store the resolved `namespace_id` — pass it to every subsequent tool call.
+
+---
+
+## Phase 2: Connect Stream Source
+
+**If `kafka_broker` is provided:**
+
+Call `toolbelt_connect`:
+```json
+{
+  "source_type": "kafka",
+  "namespace_id": "<namespace_id>",
+  "location": "KAFKA://<kafka_broker>",
+  "external_table_name": "<kafka_topic>",
+  "asset_name": "<kafka_topic>",
+  "kafka_column_definitions": "<kafka_schema or default schema>",
+  "kafka_subscribe": true,
+  "extra_options": { "kafka.group.id": "<kafka_group_id>" }
+}
+```
+
+Omit `extra_options` if `kafka_group_id` was not provided.
+
+Store the resulting table name as `stream_table`. Record `source_mode: "kafka"`.
+
+**If `kafka_broker` is not provided (simulated stream):**
+
+Upload the default sample data above as a document using `toolbelt_save`:
+
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "stream-readings",
+  "file_name": "stream-readings.csv",
+  "content": "<default sample data above>",
+  "content_encoding": "text",
+  "data_format": "csv"
+}
+```
+
+Record `source_mode: "simulated"`. Poll `toolbelt_jobs` every 10 seconds until
+the `ingest` job reaches `completed`. Maximum wait: 3 minutes.
+
+If the job reaches `failed` or the timeout elapses, emit structured failure and halt:
+```
+FAILURE: Stream data ingestion did not complete.
+Job status: <last observed status>
+```
+
+Call `toolbelt_context` to get the table name. Store as `stream_table`.
+
+---
+
+## Phase 3: Confirm Data Arrival
+
+Call `toolbelt_execute` to verify the stream table is queryable and report
+the initial row count:
+
+```sql
+SELECT COUNT(*) AS row_count FROM <stream_table>
+```
+
+If this fails, emit structured failure and halt:
+```
+FAILURE: Stream table is not queryable.
+Table: <stream_table>
+Error: <error message>
+```
+
+Record `initial_row_count`. For simulated streams this is the full dataset.
+For live Kafka streams, wait 30 seconds and poll again to observe growth:
+
+```sql
+SELECT COUNT(*) AS row_count FROM <stream_table>
+```
+
+Record `final_row_count`. If `final_row_count > initial_row_count`, set
+`data_is_growing: true`. For simulated mode, set `data_is_growing: "simulated"`.
+
+---
+
+## Phase 4: Aggregation Queries
+
+Run the following aggregation queries via `toolbelt_execute`. Substitute
+`<stream_table>` with the resolved table name throughout.
+
+### Query 1 — Per-sensor stats
+
+Compute mean, min, max, and reading count per sensor:
+
+```sql
+SELECT
+  sensor_id,
+  COUNT(*) AS reading_count,
+  ROUND(AVG(value), 2) AS avg_value,
+  ROUND(MIN(value), 2) AS min_value,
+  ROUND(MAX(value), 2) AS max_value
+FROM <stream_table>
+GROUP BY sensor_id
+ORDER BY sensor_id ASC
+```
+
+Record `per_sensor_rows` (number of rows returned).
+
+### Query 2 — 1-minute window aggregation
+
+Aggregate readings into 1-minute windows using timestamp truncation:
+
+```sql
+SELECT
+  sensor_id,
+  DATETIME(ts, 'start of minute') AS window_start,
+  COUNT(*) AS readings_in_window,
+  ROUND(AVG(value), 2) AS avg_value
+FROM <stream_table>
+GROUP BY sensor_id, DATETIME(ts, 'start of minute')
+ORDER BY window_start ASC, sensor_id ASC
+LIMIT 20
+```
+
+If the database does not support `DATETIME(ts, 'start of minute')`, fall back to:
+```sql
+SELECT
+  sensor_id,
+  ts,
+  value
+FROM <stream_table>
+ORDER BY ts ASC, sensor_id ASC
+LIMIT 20
+```
+
+Record `window_rows` (number of rows returned).
+
+---
+
+## Phase 5: Anomaly Detection
+
+Detect readings that deviate more than `anomaly_threshold` standard deviations
+from the per-sensor mean. Run via `toolbelt_execute`:
+
+```sql
+SELECT
+  r.sensor_id,
+  r.ts,
+  r.value,
+  ROUND(stats.avg_val, 2) AS sensor_mean,
+  ROUND(stats.std_val, 2) AS sensor_stddev,
+  ROUND(ABS(r.value - stats.avg_val) / NULLIF(stats.std_val, 0), 2) AS z_score
+FROM <stream_table> r
+JOIN (
+  SELECT
+    sensor_id,
+    AVG(value) AS avg_val,
+    STDDEV(value) AS std_val
+  FROM <stream_table>
+  GROUP BY sensor_id
+) stats ON r.sensor_id = stats.sensor_id
+WHERE ABS(r.value - stats.avg_val) > (<anomaly_threshold> * stats.std_val)
+ORDER BY z_score DESC
+```
+
+Substitute `<anomaly_threshold>` with the resolved value (default `2.0`).
+
+If `STDDEV` is not supported, substitute with the population standard deviation
+expression: `SQRT(AVG(value * value) - AVG(value) * AVG(value))`.
+
+Record:
+- `anomaly_count`: number of rows returned
+- `anomalies`: list of `{ sensor_id, ts, value, z_score }` for each row
+
+---
+
+## Phase 6: Structured Output
+
+Emit a single structured result after all phases complete:
+
+```
+RESULT:
+  namespace_id: <uuid>
+  stream_table: <table name>
+  source_mode: <"kafka" or "simulated">
+  phases_run: [0, 1, 2, 3, 4, 5]
+
+  data_arrival:
+    initial_row_count: <count>
+    final_row_count: <count>
+    data_is_growing: <true / false / "simulated">
+
+  aggregation:
+    per_sensor_rows: <count>
+    window_rows: <count>
+
+  anomaly_detection:
+    threshold_stddev: <anomaly_threshold>
+    anomaly_count: <count>
+    anomalies:
+      - sensor_id: <id>
+        ts: <timestamp>
+        value: <value>
+        z_score: <z_score>
+      ...
+```
+
+If any Phase 4–5 query fails, include `query_error: "<error>"` under that
+section and continue. Only halt on Phase 0–2 failures.
+
+---
+
+## Tool Reference
+
+| Phase | Tool(s) |
+|---|---|
+| 0. Verify connection | `get_semantic_names` |
+| 1. Resolve namespace | (from Phase 0 result) |
+| 2. Connect stream | `toolbelt_connect` (Kafka) or `toolbelt_save` + `toolbelt_jobs` + `toolbelt_context` (simulated) |
+| 3. Confirm data arrival | `toolbelt_execute` × 1–2 |
+| 4. Aggregation queries | `toolbelt_execute` × 2 |
+| 5. Anomaly detection | `toolbelt_execute` × 1 |
+| 6. Emit result | (structured output) |