@wentorai/research-plugins 1.0.0 → 1.2.0

package/skills/tools/diagram/excalidraw-diagram-guide/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: excalidraw-diagram-guide
+description: "Generate hand-drawn style Excalidraw diagrams from text descriptions"
+metadata:
+  openclaw:
+    emoji: "sketch"
+    category: "tools"
+    subcategory: "diagram"
+    keywords: ["Excalidraw", "diagram", "whiteboard", "hand-drawn", "sketch", "visual"]
+    source: "https://github.com/excalidraw/excalidraw"
+---
+
+# Excalidraw Diagram Guide
+
+Generate hand-drawn style diagrams, wireframes, and visual explanations using Excalidraw's open-source whiteboard format. This skill enables researchers to create informal yet informative sketches for brainstorming sessions, presentations, and collaborative workshops.
+
+## Overview
+
+Excalidraw is an open-source virtual whiteboard tool that produces diagrams with a distinctive hand-drawn aesthetic. Unlike formal diagramming tools such as PlantUML or Visio, Excalidraw prioritizes approachability and rapid ideation. Its output looks intentionally informal, which makes it well-suited for early-stage research brainstorming, teaching materials, and conference posters where a polished UML diagram would feel overly rigid.
+
+The tool stores diagrams in a JSON-based `.excalidraw` format, making them fully version-controllable and programmatically generatable. Researchers can describe what they need in natural language, and this skill translates those descriptions into valid Excalidraw scene files that can be opened in the Excalidraw editor or embedded directly into web pages.
+
+Excalidraw supports real-time collaboration, end-to-end encryption for shared sessions, and export to PNG and SVG. The hand-drawn style is achieved through a custom rendering engine that applies subtle randomization to stroke paths, giving each element a natural, sketched appearance.
+
+## Creating Diagrams from Descriptions
+
+The Excalidraw JSON format consists of an array of elements, each with a type (rectangle, ellipse, arrow, text, line, diamond), position coordinates, dimensions, and style properties.
+
+### Basic Element Structure
+
+```json
+{
+  "type": "rectangle",
+  "x": 100,
+  "y": 200,
+  "width": 200,
+  "height": 80,
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "#a5d8ff",
+  "fillStyle": "hachure",
+  "strokeWidth": 1,
+  "roughness": 1,
+  "roundness": { "type": 3 }
+}
+```
+
+### Key Properties
+
+| Property | Values | Description |
+|----------|--------|-------------|
+| `fillStyle` | `hachure`, `cross-hatch`, `solid` | Fill pattern style |
+| `roughness` | `0`, `1`, `2` | Hand-drawn roughness level |
+| `strokeWidth` | `1`, `2`, `4` | Line thickness |
+| `strokeStyle` | `solid`, `dashed`, `dotted` | Line style |
+| `roundness` | `null`, `{ "type": 3 }` | Corner rounding |
+
+### Common Academic Color Palette
+
+```
+Primary:   #1971c2 (blue)    Background: #a5d8ff
+Accent:    #e03131 (red)     Background: #ffc9c9
+Success:   #2f9e44 (green)   Background: #b2f2bb
+Warning:   #f08c00 (orange)  Background: #ffec99
+Neutral:   #495057 (gray)    Background: #dee2e6
+```
+
+## Research Workflow Diagrams
+
+### Methodology Flowchart
+
+Describe a research pipeline and generate the corresponding layout:
+
+```
+Input: "Create a flowchart showing: Literature Review -> Research Questions ->
+        Hypothesis Formation -> Study Design -> Data Collection -> Analysis ->
+        Results -> Discussion -> Publication"
+```
+
+Each step becomes a rounded rectangle connected by arrows. Decision points (e.g., "Results Significant?") use diamond shapes with branching arrows.
+
+### System Architecture Sketches
+
+For software or experimental system diagrams, use grouped rectangles with labeled connections:
+
+```
+Input: "Draw a system architecture with three layers:
+        Frontend (React dashboard),
+        Backend (FastAPI + PostgreSQL),
+        External (Semantic Scholar API, CrossRef API)"
+```
+
+The output places each layer as a dashed-border container with internal component boxes and inter-layer arrows.
+
+## Embedding and Export
+
+### Export Options
+
+- **PNG**: Best for slides and documents. Use `exportScale: 2` for high-DPI output.
+- **SVG**: Ideal for papers and web embedding. Scales without quality loss.
+- **JSON**: Native format for version control and programmatic manipulation.
+
+### Web Embedding
+
+```html
+<iframe
+  src="https://excalidraw.com/#json=YOUR_ENCODED_DATA"
+  width="800"
+  height="600"
+  style="border: none;">
+</iframe>
+```
+
+### Programmatic Generation (Python)
+
+```python
+import json
+
+def create_box(text, x, y, width=200, height=80, color="#a5d8ff"):
+    return [
+        {
+            "type": "rectangle",
+            "x": x, "y": y,
+            "width": width, "height": height,
+            "backgroundColor": color,
+            "fillStyle": "hachure",
+            "roughness": 1,
+            "strokeWidth": 1
+        },
+        {
+            "type": "text",
+            "x": x + 10, "y": y + 25,
+            "text": text,
+            "fontSize": 16
+        }
+    ]
+
+scene = {
+    "type": "excalidraw",
+    "version": 2,
+    "elements": create_box("Literature Review", 100, 100)
+                + create_box("Data Analysis", 100, 250)
+}
+
+with open("research_flow.excalidraw", "w") as f:
+    json.dump(scene, f, indent=2)
+```
+
+## Collaboration Features
+
+Excalidraw supports live collaboration through shared session links. Each participant sees real-time cursor positions and edits. Sessions can be encrypted end-to-end using the built-in encryption feature, which is important when sketching unpublished research ideas.
+
+For research teams, the recommended workflow is:
+
+1. Create a shared session for the brainstorming phase
+2. Export the final sketch as `.excalidraw` JSON and commit to the project repository
+3. Generate high-resolution PNG/SVG exports for inclusion in papers or presentations
+
+## Integration with Research Tools
+
+- **Obsidian**: The Excalidraw plugin enables whiteboard sketching directly in research notes
+- **Notion**: Embed via iframe or exported SVG
+- **LaTeX**: Export as SVG, include with `\includesvg{}` (requires `svg` package)
+- **Jupyter**: Display exported PNG inline using `IPython.display.Image`
+- **VS Code**: Official Excalidraw extension for editing `.excalidraw` files in the IDE
+
+## References
+
+- Excalidraw open-source repository: https://github.com/excalidraw/excalidraw
+- Excalidraw libraries (pre-made shapes): https://libraries.excalidraw.com
+- Excalidraw file format specification: https://docs.excalidraw.com

package/skills/tools/diagram/json-data-visualizer/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: json-data-visualizer
+description: "Guide to JSON Crack for visualizing complex JSON data structures"
+metadata:
+  openclaw:
+    emoji: "🌳"
+    category: "tools"
+    subcategory: "diagram"
+    keywords: ["JSON visualization", "data structure diagram", "tree visualization", "API response viewer", "schema explorer"]
+    source: "https://github.com/AykutSarac/jsoncrack.com"
+---
+
+# JSON Crack Data Visualizer Guide
+
+## Overview
+
+JSON Crack (formerly JSON Visio) is an open-source data visualization tool with over 43K stars on GitHub that transforms JSON, YAML, XML, TOML, and CSV data into interactive graph diagrams. Instead of reading raw nested data structures, researchers can instantly see the hierarchical relationships, nested objects, and array structures as a navigable node-link diagram rendered on an infinite canvas.
+
+For academic researchers, JSON Crack is particularly valuable when working with complex API responses, configuration files, experimental metadata schemas, and nested data exports. Bioinformatics researchers dealing with deeply nested gene ontology JSON files, social scientists working with survey platform API responses, and computational researchers inspecting machine learning model configuration files all benefit from being able to see their data structures visually rather than scrolling through thousands of lines of text.
+
+The tool is available as a hosted web application at jsoncrack.com, as a self-hosted Docker deployment for institutional use, and as an embeddable React component that can be integrated into custom research tools. It also provides an API for programmatic access, making it suitable for integration into data processing pipelines.
+
+## Getting Started
+
+### Web Application Usage
+
+The fastest way to use JSON Crack is through the web interface. Paste or upload JSON data and the visualization renders immediately.
+
+### Self-Hosted Deployment for Research Labs
+
+```bash
+# Clone the repository
+git clone https://github.com/AykutSarac/jsoncrack.com.git
+cd jsoncrack.com
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Or build and serve for production
+npm run build
+npm start
+```
+
+### Docker Deployment
+
+```bash
+# Run with Docker
+docker run -d -p 8888:8080 \
+  --name json-crack \
+  --restart unless-stopped \
+  jsoncrack/jsoncrack
+
+# Access at http://localhost:8888
+```
+
+### Docker Compose for Lab Infrastructure
+
+```yaml
+version: "3.8"
+services:
+  json-crack:
+    image: jsoncrack/jsoncrack
+    container_name: json-crack
+    ports:
+      - "8888:8080"
+    restart: unless-stopped
+```
+
+## Visualizing Research Data Structures
+
+### Experimental Metadata Schema
+
+Researchers frequently work with complex nested JSON structures for experimental metadata. JSON Crack makes these immediately readable.
+
+```json
+{
+  "experiment": {
+    "id": "EXP-2026-0142",
+    "title": "Effect of Temperature on Protein Folding Kinetics",
+    "principal_investigator": {
+      "name": "Dr. Jane Smith",
+      "orcid": "0000-0002-1234-5678",
+      "affiliation": "Department of Biochemistry"
+    },
+    "protocol": {
+      "version": "3.2",
+      "steps": [
+        {
+          "order": 1,
+          "name": "Sample Preparation",
+          "duration_minutes": 120,
+          "equipment": ["centrifuge", "spectrophotometer"],
+          "parameters": {
+            "temperature_celsius": 25,
+            "buffer_ph": 7.4,
+            "concentration_mm": 0.5
+          }
+        },
+        {
+          "order": 2,
+          "name": "Thermal Denaturation",
+          "duration_minutes": 180,
+          "temperature_range": {
+            "start": 25,
+            "end": 95,
+            "step": 1,
+            "unit": "celsius"
+          }
+        },
+        {
+          "order": 3,
+          "name": "Data Acquisition",
+          "instrument": "circular_dichroism_spectrometer",
+          "wavelength_range_nm": [190, 260]
+        }
+      ]
+    },
+    "samples": [
+      {
+        "id": "S001",
+        "condition": "wild_type",
+        "replicates": 3,
+        "measurements": {
+          "tm_celsius": 68.2,
+          "delta_h_kcal": -45.3,
+          "r_squared": 0.997
+        }
+      }
+    ]
+  }
+}
+```
+
+When loaded into JSON Crack, this structure displays as an interactive tree diagram where each nested object becomes a card node, arrays show their elements as connected child nodes, and researchers can click to expand or collapse sections for focused exploration.
+
+### API Response Inspection
+
+When working with research APIs (PubMed, CrossRef, OpenAlex, etc.), responses are often deeply nested. JSON Crack helps researchers understand the response schema before writing parsing code.
+
+```python
+import requests
+import json
+
+# Fetch metadata from CrossRef API
+response = requests.get(
+    "https://api.crossref.org/works/10.1038/nature12373"
+)
+data = response.json()
+
+# Save for visualization in JSON Crack
+with open("crossref_response.json", "w") as f:
+    json.dump(data, f, indent=2)
+
+# Open crossref_response.json in JSON Crack to explore the schema
+# This reveals the nested structure of author arrays, funding info,
+# reference lists, and license metadata
+```
+
+## Embedding in Research Applications
+
+JSON Crack provides a React component that can be embedded in custom research tools.
+
+### React Component Integration
+
+```tsx
+import { JsonCrackEmbed } from "jsoncrack-react";
+import { useState } from "react";
+
+function DataSchemaViewer({ experimentData }) {
+  const [jsonContent, setJsonContent] = useState(
+    JSON.stringify(experimentData, null, 2)
+  );
+
+  return (
+    <div style={{ width: "100%", height: "600px" }}>
+      <h3>Experiment Data Schema</h3>
+      <JsonCrackEmbed
+        json={jsonContent}
+        style={{ width: "100%", height: "100%" }}
+      />
+    </div>
+  );
+}
+```
+
+### Embedding via iframe
+
+```html
+<iframe
+  src="https://jsoncrack.internal.lab/widget"
+  width="100%"
+  height="600"
+  style="border: 1px solid #e5e7eb; border-radius: 8px;"
+></iframe>
+```
+
+## Supported Data Formats
+
+JSON Crack handles multiple data serialization formats commonly used in research.
+
+### JSON
+
+The primary format. Supports nested objects, arrays, primitives, and null values. JSON Schema validation is available to verify data conforms to expected structures.
+
+### YAML
+
+Common in configuration files for research software, CI/CD pipelines, and computational workflow definitions (e.g., Snakemake, Nextflow configs).
+
+```yaml
+pipeline:
+  name: rnaseq-analysis
+  steps:
+    - name: quality-control
+      tool: fastqc
+      input: raw_reads/*.fastq.gz
+    - name: trimming
+      tool: trimmomatic
+      parameters:
+        min_length: 36
+        quality_threshold: 20
+    - name: alignment
+      tool: star
+      genome_index: /ref/hg38
+```
+
+### CSV
+
+Tabular data from experiments and surveys can be visualized to understand column relationships and data types.
+
+### TOML
+
+Used in Python project configuration (pyproject.toml), Rust cargo files, and various research tool configurations.
+
+## Practical Research Workflows
+
+### Schema Documentation
+
+Use JSON Crack to generate visual documentation of your lab's data schemas. Export the visualization as an image for inclusion in lab manuals, onboarding documents, or data management plans.
+
+### API Development
+
+When building research APIs with FastAPI or Flask, use JSON Crack to visualize and verify your API response structures during development.
+
+### Data Validation
+
+Before processing large datasets, visualize a sample record in JSON Crack to verify the structure matches expectations. This is faster than writing validation code for initial inspection.
+
+### Comparing Data Versions
+
+When data schemas evolve between experiment versions, visualize both versions side-by-side to identify structural differences and plan migration logic.
+
+## Keyboard Shortcuts and Tips
+
+- **Ctrl+Shift+D** - Toggle dark/light mode
+- **Ctrl+Shift+F** - Format/prettify the input data
+- **Ctrl+Shift+C** - Compact the input data
+- **Mouse wheel** - Zoom in/out on the diagram
+- **Click and drag** - Pan the canvas
+- **Click a node** - Highlight the path from root to that node
+- **Search** - Find specific keys or values in the graph
+
+## References
+
+- JSON Crack website: https://jsoncrack.com
+- JSON Crack GitHub: https://github.com/AykutSarac/jsoncrack.com
+- JSON Crack React embed: https://www.npmjs.com/package/jsoncrack-react
+- JSON Crack VS Code extension: available in VS Code Marketplace

package/skills/tools/diagram/kroki-diagram-api/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: kroki-diagram-api
+description: "Generate diagrams from text via Kroki's multi-format rendering API"
+metadata:
+  openclaw:
+    emoji: "📐"
+    category: "tools"
+    subcategory: "diagram"
+    keywords: ["Kroki", "diagram generation", "text-to-diagram", "Graphviz", "PlantUML", "Mermaid"]
+    source: "https://kroki.io/"
+---
+
+# Kroki Diagram API
+
+## Overview
+
+Kroki provides a unified HTTP API to render 20+ text-based diagram formats into images (SVG, PNG, PDF). It supports Mermaid, PlantUML, Graphviz, D2, BPMN, and more — all through a single endpoint. Self-hostable or use the free public instance. No authentication required. Ideal for generating research figures, architecture diagrams, and flowcharts programmatically.
+
+## API Usage
+
+### GET Request (URL-encoded)
+
+```bash
+# Graphviz DOT diagram
+curl "https://kroki.io/graphviz/svg/digraph{A->B->C}" -o diagram.svg
+
+# Mermaid diagram (base64-encoded)
+echo "graph TD; A-->B; B-->C;" | base64 | \
+  curl "https://kroki.io/mermaid/svg/$(cat -)" -o diagram.svg
+```
+
+### POST Request (Recommended)
+
+```bash
+# PlantUML sequence diagram
+curl -X POST "https://kroki.io/plantuml/svg" \
+  -H "Content-Type: text/plain" \
+  -d '@startuml
+Alice -> Bob: Hello
+Bob --> Alice: Hi!
+@enduml' -o sequence.svg
+
+# Mermaid flowchart
+curl -X POST "https://kroki.io/mermaid/svg" \
+  -H "Content-Type: text/plain" \
+  -d 'graph TD
+    A[Data Collection] --> B[Preprocessing]
+    B --> C[Model Training]
+    C --> D[Evaluation]
+    D -->|Good| E[Deploy]
+    D -->|Bad| B' -o flowchart.svg
+
+# Graphviz
+curl -X POST "https://kroki.io/graphviz/svg" \
+  -H "Content-Type: text/plain" \
+  -d 'digraph {
+    rankdir=LR
+    "Raw Data" -> "Feature Extraction" -> "Model" -> "Prediction"
+  }' -o pipeline.svg
+
+# D2 diagram
+curl -X POST "https://kroki.io/d2/svg" \
+  -H "Content-Type: text/plain" \
+  -d 'Client -> API: Request
+API -> Database: Query
+Database -> API: Results
+API -> Client: Response' -o d2.svg
+```
+
+### URL Format
+
+```
+https://kroki.io/{diagram_type}/{output_format}/{encoded_source}
+
+# Or POST to:
+https://kroki.io/{diagram_type}/{output_format}
+```
+
+### Supported Diagram Types
+
+| Type | Keyword | Best for |
+|------|---------|----------|
+| Mermaid | `mermaid` | Flowcharts, sequences, Gantt |
+| PlantUML | `plantuml` | UML, sequences, class diagrams |
+| Graphviz | `graphviz` | Network graphs, DAGs |
+| D2 | `d2` | Modern text-to-diagram |
+| Ditaa | `ditaa` | ASCII art diagrams |
+| BlockDiag | `blockdiag` | Block diagrams |
+| Nomnoml | `nomnoml` | UML-like diagrams |
+| WaveDrom | `wavedrom` | Digital timing diagrams |
+| Vega | `vega` | Data visualizations |
+| Vega-Lite | `vegalite` | Simplified data viz |
+| C4 PlantUML | `c4plantuml` | C4 architecture |
+| BPMN | `bpmn` | Business processes |
+| Bytefield | `bytefield` | Protocol/byte diagrams |
+| Excalidraw | `excalidraw` | Hand-drawn style |
+
+### Output Formats
+
+| Format | Extension | Use case |
+|--------|-----------|----------|
+| SVG | `/svg` | Web, scalable |
+| PNG | `/png` | Documents, slides |
+| PDF | `/pdf` | Papers, print |
+| JPEG | `/jpeg` | Compatibility |
+
+## Python Usage
+
+```python
+import requests
+import base64
+import zlib
+
+
+KROKI_URL = "https://kroki.io"
+
+
+def render_diagram(source: str, diagram_type: str = "mermaid",
+                   output_format: str = "svg") -> bytes:
+    """Render a text diagram to image via Kroki."""
+    resp = requests.post(
+        f"{KROKI_URL}/{diagram_type}/{output_format}",
+        headers={"Content-Type": "text/plain"},
+        data=source,
+    )
+    resp.raise_for_status()
+    return resp.content
+
+
+def save_diagram(source: str, output_path: str,
+                 diagram_type: str = "mermaid",
+                 output_format: str = "svg"):
+    """Render and save a diagram to file."""
+    content = render_diagram(source, diagram_type, output_format)
+    with open(output_path, "wb") as f:
+        f.write(content)
+
+
+def render_research_pipeline(steps: list) -> bytes:
+    """Create a research pipeline flowchart."""
+    nodes = []
+    for i, step in enumerate(steps):
+        node_id = chr(65 + i)
+        nodes.append(f"    {node_id}[{step}]")
+        if i > 0:
+            prev_id = chr(65 + i - 1)
+            nodes.append(f"    {prev_id} --> {node_id}")
+
+    mermaid = "graph TD\n" + "\n".join(nodes)
+    return render_diagram(mermaid, "mermaid", "svg")
+
+
+# Example: create a research workflow diagram
+workflow = """graph TD
+    A[Literature Review] --> B[Hypothesis]
+    B --> C[Data Collection]
+    C --> D[Statistical Analysis]
+    D --> E{Significant?}
+    E -->|Yes| F[Write Paper]
+    E -->|No| G[Revise Hypothesis]
+    G --> B
+    F --> H[Peer Review]"""
+
+save_diagram(workflow, "research_workflow.svg", "mermaid")
+
+# Example: Graphviz citation network
+citation_graph = """digraph {
+    rankdir=BT
+    node [shape=box, style=rounded]
+    "Vaswani 2017" -> "BERT 2018"
+    "Vaswani 2017" -> "GPT 2018"
+    "BERT 2018" -> "RoBERTa 2019"
+    "GPT 2018" -> "GPT-2 2019"
+    "GPT-2 2019" -> "GPT-3 2020"
+}"""
+save_diagram(citation_graph, "citations.svg", "graphviz")
+
+# Example: research pipeline helper
+pipeline_svg = render_research_pipeline([
+    "Raw Data", "Cleaning", "Feature Engineering",
+    "Model Training", "Evaluation", "Deployment"
+])
+```
+
+## Self-Hosting
+
+```bash
+# Run Kroki locally via Docker
+docker run -d -p 8000:8000 yuzutech/kroki
+
+# Then use http://localhost:8000 instead of https://kroki.io
+```
+
+## References
+
+- [Kroki](https://kroki.io/)
+- [Kroki Documentation](https://docs.kroki.io/)
+- [Kroki GitHub](https://github.com/yuzutech/kroki)