@toolbeltai/skills 0.1.0

package/geo-analyst/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: geo-analyst
+description: >
+  GPU-accelerated geospatial analytics powered by Toolbelt MCP. Toolbelt is a
+  multi-modal data platform combining SQL analytics, vector search, and real-time
+  streaming. Uploads lat/lon sensor data, runs geospatial SQL queries (distance,
+  point-in-polygon, track creation), and emits structured results. Use when an AI
+  agent needs to analyze spatial data, compute distances, test point containment,
+  or build movement tracks 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.
+metadata:
+  author: toolbeltai
+  version: "1.0"
+  openclaw:
+    emoji: "🌍"
+    homepage: "https://toolbelt.ai/docs/geospatial"
+    skillKey: "geo-analyst"
+---
+
+Execute GPU-accelerated geospatial analytics end-to-end using Toolbelt MCP tools.
+Work through each phase in order. Extract all required inputs from task parameters
+or invocation context — do not prompt for user input. Progress through phases
+without confirmation. On unrecoverable error, emit a structured failure and halt.
+
+## When Not To Use
+
+- For tabular data without lat/lon coordinates — use `sql-analyst` instead.
+- For unstructured text or documents — use `knowledge-graph` 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 with id, name, lat, lon columns. Uses default Tampa Bay sample if omitted. |
+| `asset_name` | No | Name for the uploaded sensor table. Defaults to `sensor-locations`. |
+| `zone_wkt` | No | WKT polygon for point-in-polygon query. Uses default Tampa downtown zone if omitted. |
+
+---
+
+## Default Sample Data
+
+If no `csv_content` is provided, use this Tampa Bay area sensor dataset:
+
+```
+id,name,lat,lon
+1,Sensor A,27.9506,-82.4572
+2,Sensor B,27.9659,-82.4398
+3,Sensor C,27.9881,-82.5014
+4,Sensor D,27.9344,-82.5181
+5,Sensor E,28.0080,-82.4271
+6,Sensor F,27.9196,-82.3943
+7,Sensor G,27.8772,-82.5236
+8,Sensor H,28.0346,-82.4850
+9,Sensor I,27.9712,-82.5489
+10,Sensor J,27.9050,-82.4127
+```
+
+Default `zone_wkt` (downtown Tampa bounding polygon):
+```
+POLYGON((-82.4650 27.9400, -82.4350 27.9400, -82.4350 27.9700, -82.4650 27.9700, -82.4650 27.9400))
+```
+
+---
+
+## 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 Sensor Data
+
+Upload the CSV as a document using `toolbelt_save`:
+
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "<asset_name or 'sensor-locations'>",
+  "file_name": "sensor-locations.csv",
+  "content": "<csv_content or default sample data above>",
+  "content_encoding": "text",
+  "data_format": "csv"
+}
+```
+
+### Poll for ingestion
+
+Call `toolbelt_jobs` with `{ "namespace_id": "<namespace_id>" }` every 10 seconds.
+
+Wait for the `ingest` job 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: Sensor data ingestion did not complete.
+Job status: <last observed status>
+```
+
+After completion, call `toolbelt_context` to retrieve the table name for the
+uploaded asset. Store it as `sensor_table` for use in Phase 3.
+
+---
+
+## Phase 3: Run Geospatial Queries
+
+Run all three queries using `toolbelt_execute`. Pass `namespace_id` and `query`
+for each call. Collect results.
+
+**Note:** `ST_DISTANCE`, `ST_CONTAINS`, and `ST_MAKELINE` are Kinetica-native geospatial
+functions available through Toolbelt's GPU-accelerated query engine. They are not standard
+SQL and will not work against other databases.
+
+### Query 1 — Pairwise Distance
+
+`ST_DISTANCE(lat1, lon1, lat2, lon2)` → meters between two WGS-84 points.
+
+```sql
+SELECT
+  a.name AS sensor_a,
+  b.name AS sensor_b,
+  ROUND(ST_DISTANCE(a.lat, a.lon, b.lat, b.lon)) AS distance_m
+FROM <sensor_table> a
+JOIN <sensor_table> b ON a.id < b.id
+ORDER BY distance_m ASC
+LIMIT 10
+```
+
+Record: `distance_query_rows` (number of rows returned), `closest_pair` (sensor_a and sensor_b from the first row), `min_distance_m`.
+
+### Query 2 — Point-in-Polygon
+
+`ST_CONTAINS(wkt_polygon, lat, lon)` → 1 if point is inside the polygon.
+
+```sql
+SELECT
+  id,
+  name,
+  lat,
+  lon,
+  ST_CONTAINS('<zone_wkt>', lat, lon) AS in_zone
+FROM <sensor_table>
+WHERE ST_CONTAINS('<zone_wkt>', lat, lon) = 1
+```
+
+Substitute `<zone_wkt>` with the provided or default WKT string.
+
+Record: `in_zone_count` (number of sensors inside the polygon), `in_zone_sensors` (list of names).
+
+### Query 3 — Track Line
+
+`ST_MAKELINE(lat, lon ORDER BY id)` → linestring connecting all points in sequence.
+
+```sql
+SELECT
+  ST_ASTEXT(ST_MAKELINE(lat, lon ORDER BY id ASC)) AS track_wkt,
+  COUNT(*) AS point_count
+FROM <sensor_table>
+```
+
+Record: `track_point_count`, `track_wkt_excerpt` (first 120 chars of the WKT).
+
+---
+
+## Phase 4: Structured Output
+
+After all queries complete, emit a single structured result:
+
+```
+RESULT:
+  namespace_id: <uuid>
+  sensor_table: <table name>
+  phases_run: [0, 1, 2, 3]
+  row_count: <total rows in sensor table>
+
+  distance_query:
+    rows_returned: <distance_query_rows>
+    closest_pair: "<sensor_a> → <sensor_b>"
+    min_distance_m: <min_distance_m>
+
+  point_in_polygon:
+    zone_wkt: "<zone_wkt used>"
+    in_zone_count: <count>
+    in_zone_sensors: [<names>]
+
+  track:
+    point_count: <track_point_count>
+    track_wkt_excerpt: "<first 120 chars>"
+```
+
+If any query fails, include `query_error: "<error>"` under that query's section
+and continue with remaining queries. 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. Upload sensor data | `toolbelt_save`, `toolbelt_jobs`, `toolbelt_context` |
+| 3. Run geospatial queries | `toolbelt_execute` × 3 |
+| 4. Emit result | (structured output) |

package/knowledge-graph/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: knowledge-graph
+description: >
+  Automatically extract entities and relationships from any document and explore
+  the results as a knowledge graph — no schema or ontology required. Toolbelt is
+  a multi-modal data platform combining SQL analytics, vector search, and
+  real-time streaming. Upload a document, then surface entities, relationship
+  types, and hidden connections via graph queries. Use when an AI agent needs to
+  turn unstructured text into structured, navigable knowledge without writing any
+  extraction 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.
+metadata:
+  author: toolbeltai
+  version: "1.0"
+  openclaw:
+    emoji: "🕸️"
+    homepage: "https://toolbelt.ai/docs/knowledge-graph"
+    skillKey: "knowledge-graph"
+---
+
+Extract a knowledge graph from a document and explore it autonomously 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 structured tabular data (CSV, SQL tables) — use `sql-analyst` instead.
+- When entity and relationship extraction is not needed — use `sql-analyst` or `streaming-analyst` for the appropriate data type.
+
+## 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. |
+| `document_content` | No | Raw text to upload. Uses the embedded sample document if omitted. |
+| `document_name` | No | Name for the document asset. Defaults to `kg-sample-doc`. |
+| `cypher_query` | No | Custom Cypher query to run in Phase 5. Uses default discovery query if omitted. |
+
+---
+
+## Default Sample Document
+
+If no `document_content` is provided, use the following text verbatim:
+
+```
+NovaTech Industries: Company Overview
+
+NovaTech Industries was founded in 2018 by Dr. Elena Vasquez and Marcus Okafor
+in Austin, Texas. The company specializes in next-generation industrial automation
+hardware and AI-driven process control systems.
+
+Dr. Elena Vasquez, Chief Executive Officer, previously led R&D at Siemens Energy
+before co-founding NovaTech. Marcus Okafor, Chief Technology Officer, holds three
+patents in embedded sensor design and was a principal engineer at Honeywell
+Automation prior to joining the venture.
+
+NovaTech's flagship product, the Sentinel-X200, is an industrial sensor array
+that monitors temperature, vibration, and chemical composition simultaneously.
+The Sentinel-X200 is manufactured at NovaTech's production facility in San
+Antonio, Texas, and has been deployed at over 140 client sites worldwide. Key
+clients include Pacific Rim Petrochemicals in Singapore, Northern Grid Energy
+in Oslo, Norway, and Delta Fabrication Group in Detroit, Michigan.
+
+In 2021, NovaTech acquired Axon Micro Systems, a startup based in Boulder,
+Colorado, founded by Dr. Priya Nair. Axon Micro specialized in MEMS-based
+pressure sensors. Following the acquisition, Dr. Nair joined NovaTech as VP
+of Sensor Innovation and relocated to the Austin headquarters.
+
+NovaTech's second product line, the Argus Platform, provides real-time analytics
+for industrial IoT deployments. The Argus Platform integrates directly with the
+Sentinel-X200 and supports connectivity to Siemens SCADA systems, Rockwell
+Automation ControlLogix PLCs, and ABB Ability industrial cloud. The Argus Platform
+is sold as a subscription service and is managed from NovaTech's cloud operations
+center in Phoenix, Arizona.
+
+The company raised a $45 million Series B in 2022, led by Meridian Growth Capital
+and co-invested by Cascade Ventures. The funding round was used to expand the
+San Antonio manufacturing facility and open a European sales office in Frankfurt,
+Germany, led by regional director Thomas Brandt.
+
+NovaTech employs 320 people across its Austin headquarters, San Antonio plant,
+Phoenix operations center, and Frankfurt office. The company reported $62 million
+in revenue for fiscal year 2023, with 40% of revenue from international markets.
+
+Key partnerships include a joint development agreement with MIT's Advanced
+Materials Lab, overseen by Professor Alan Chen, to develop next-generation
+ceramic sensor substrates. NovaTech also holds a preferred supplier agreement
+with Broadcom for embedded processing chips used in the Sentinel-X200.
+
+In 2024, NovaTech announced the Sentinel-X300, the next-generation successor to
+the X200, featuring AI-based anomaly detection co-developed with researchers at
+UT Austin. The X300 is scheduled for commercial release in Q3 2025 and will be
+manufactured at a new facility in Round Rock, Texas.
+```
+
+---
+
+## 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.
+Never use the display name as the ID.
+
+---
+
+## Phase 2: Upload Document
+
+Resolve `document_content` (use parameter value or default sample above).
+Resolve `document_name` (use parameter value or default `kg-sample-doc`).
+
+Call `toolbelt_save`:
+
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "<document_name>",
+  "file_name": "document.txt",
+  "content": "<document_content>",
+  "content_encoding": "text"
+}
+```
+
+Record the returned `asset_id` for reference.
+
+---
+
+## Phase 3: Poll for Entity Extraction
+
+Call `toolbelt_jobs` with `{ "namespace_id": "<namespace_id>" }` every 10 seconds.
+
+Both job stages must reach `completed`:
+- `ingest` — document parsed and stored
+- `semantic` — embeddings generated and GLiNER entity extraction complete
+
+Typical duration: 30–120 seconds. Maximum wait: 5 minutes.
+
+If either job reaches `failed` or the timeout elapses, emit structured failure and halt:
+```
+FAILURE: Entity extraction did not complete.
+Job status: <last observed status for ingest and semantic jobs>
+```
+
+Do not proceed to Phase 4 until **both** jobs are `completed`. The knowledge
+graph is only available after the `semantic` job finishes — this is when GLiNER
+runs and populates entity nodes and relationship edges.
+
+---
+
+## Phase 4: Check Graph Readiness
+
+Call `toolbelt_jobs` with `{ "namespace_id": "<namespace_id>" }` and inspect the
+job list for a `kg-rebuild` (or `graph_build` / `graph`) job entry.
+
+**If a `kg-rebuild` job is found and `completed`:** set `graph_ready = true`.
+
+**If a `kg-rebuild` job is found and `running`:** poll every 10 seconds, up to
+2 minutes. If it completes in that window, set `graph_ready = true`. If it
+times out, set `graph_ready = false` and emit the warning below.
+
+**If no `kg-rebuild` job is found, or it is in `failed` / `pending` state:**
+set `graph_ready = false` and emit this non-fatal warning — do NOT halt:
+
+```
+WARNING: kg-rebuild job has not run or did not complete for this namespace.
+The Kinetica knowledge graph is unavailable.
+Entity and relationship data will be surfaced from the vector/embedding store instead.
+```
+
+Proceed to Phase 5 regardless of `graph_ready`.
+
+---
+
+## Phase 5: Surface Entities
+
+### Path A — Graph describe (when `graph_ready = true`)
+
+Call `toolbelt_graph` with `operation: "describe"`:
+
+```json
+{
+  "operation": "describe",
+  "namespace_id": "<namespace_id>"
+}
+```
+
+Parse the response to extract:
+- `graph_name`: the name of the knowledge graph (required for Phase 6 Cypher)
+- `entity_count`: total number of entity nodes extracted
+- `relationship_count`: total number of relationship edges extracted
+- `entity_types`: list of distinct entity type labels (e.g. PERSON, ORG, LOCATION, PRODUCT)
+- `sample_entities`: up to 5 example entity names from the response
+
+Store `graph_name` — it is required as a parameter and as the prefix in every Cypher query.
+
+If `toolbelt_graph describe` fails or returns no graphs despite `graph_ready = true`,
+reset `graph_ready = false` and continue with Path B.
+
+### Path B — Vector store entity search (when `graph_ready = false`)
+
+Run the following four `toolbelt_search` calls against the namespace to surface
+entity mentions extracted during the `semantic` job:
+
+```json
+{ "namespace_id": "<namespace_id>", "query": "people and persons mentioned" }
+{ "namespace_id": "<namespace_id>", "query": "organizations and companies" }
+{ "namespace_id": "<namespace_id>", "query": "locations cities and places" }
+{ "namespace_id": "<namespace_id>", "query": "products technologies and systems" }
+```
+
+From the combined results, collect:
+- `entity_types`: the categories queried that returned results (`PERSON`, `ORG`, `LOCATION`, `PRODUCT`)
+- `sample_entities`: up to 5 representative names surfaced across the results
+- `entity_count`: approximate — set to the total number of distinct names found
+- `relationship_count`: set to `null` (not available via this path)
+- `graph_name`: set to `null`
+
+Note in the RESULT that counts are approximate and sourced from vector search.
+
+---
+
+## Phase 6: Explore Connections
+
+### Path A — Cypher query (when `graph_ready = true` and `graph_name` is set)
+
+**Important:** Kinetica Cypher requires the query to begin with
+`GRAPH <graph_name> MATCH ...`. The `graph_name` must come from the Phase 5
+`describe` response.
+
+Attempt:
+
+```json
+{
+  "operation": "query",
+  "namespace_id": "<namespace_id>",
+  "graph_name": "<graph_name>",
+  "query": "GRAPH <graph_name> MATCH (a)-[r]->(b) RETURN a.name AS source, label(a) AS source_type, type(r) AS relationship, b.name AS target, label(b) AS target_type ORDER BY source LIMIT 25"
+}
+```
+
+If the Cypher query succeeds, record:
+- `relationship_rows`: rows returned (first 10)
+- `result_count`: total rows
+- `query_method`: `"cypher"`
+
+If Approach A fails (HTTP 5xx or zero rows), extract relationship edges from the
+Phase 5 `describe` response (`relationships` or `edges` arrays) and record:
+- `relationship_rows`: tuples extracted from `describe` (first 10)
+- `result_count`: total relationships from Phase 5 `relationship_count`
+- `query_method`: `"describe_fallback"`
+
+### Path B — Vector relationship search (when `graph_ready = false`)
+
+Run the following `toolbelt_search` calls to surface relationship-rich passages:
+
+```json
+{ "namespace_id": "<namespace_id>", "query": "founded by acquired partnership agreement" }
+{ "namespace_id": "<namespace_id>", "query": "works for reports to leads manages" }
+{ "namespace_id": "<namespace_id>", "query": "located in based in headquartered" }
+```
+
+From the combined results, extract the most informative relationship snippets.
+Present them as plain-language connection summaries (not structured tuples) and record:
+- `relationship_rows`: up to 10 plain-language relationship summaries
+- `result_count`: number of summaries
+- `query_method`: `"vector_search"`
+
+---
+
+## Phase 7: Structured Output
+
+After all phases complete, emit a single structured result:
+
+```
+RESULT:
+  namespace_id: <uuid>
+  document_name: <document name uploaded>
+  phases_run: [0, 1, 2, 3, 4, 5, 6]
+  graph_ready: <true | false>
+
+  knowledge_graph:
+    entity_count: <integer, or "~N (approximate)" if vector path>
+    relationship_count: <integer, or null if vector path>
+    entity_types: [<list of type labels>]
+    sample_entities: [<up to 5 entity names>]
+
+  connections:
+    query_method: "<cypher | describe_fallback | vector_search>"
+    query_used: "<query executed or 'toolbelt_search (relationship queries)' if vector path>"
+    result_count: <integer>
+    rows:
+      - source: "<name>" relationship: "<type>" target: "<name>"   # graph paths
+      - "<plain-language relationship summary>"                     # vector path
+      ... (up to 10 rows)
+```
+
+If `graph_ready` was `false`, include a note:
+```
+  note: "kg-rebuild job was not available; entity and relationship data sourced from vector/embedding store. Re-run after kg-rebuild completes for full graph traversal."
+```
+
+If Phase 5 or 6 produced partial data (e.g., counts present but no rows), include
+what is available and note the gap. Only halt on Phase 0–3 failures.
+
+---
+
+## Tool Reference
+
+| Phase | Tool(s) |
+|---|---|
+| 0. Verify connection | `get_semantic_names` |
+| 1. Resolve namespace | (from Phase 0 result) |
+| 2. Upload document | `toolbelt_save` |
+| 3. Poll for extraction | `toolbelt_jobs` (ingest + semantic) |
+| 4. Check graph readiness | `toolbelt_jobs` (kg-rebuild; sets `graph_ready` flag) |
+| 5A. Describe entities (graph path) | `toolbelt_graph` (operation: describe) |
+| 5B. Surface entities (vector path) | `toolbelt_search` (4 entity-type queries) |
+| 6A. Explore connections (graph path) | `toolbelt_graph` (operation: query), fallback to describe |
+| 6B. Explore connections (vector path) | `toolbelt_search` (3 relationship queries) |
+| 7. Emit result | (structured output) |