@wentorai/research-plugins 1.0.0 → 1.2.0

package/skills/tools/code-exec/overleaf-cli-guide/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: overleaf-cli-guide
+description: "Sync and manage Overleaf LaTeX projects from the command line"
+metadata:
+  openclaw:
+    emoji: "terminal"
+    category: "tools"
+    subcategory: "code-exec"
+    keywords: ["Overleaf", "LaTeX", "CLI", "sync", "git", "collaboration", "academic writing"]
+    source: "https://github.com/overleaf/overleaf"
+---
+
+# Overleaf CLI Guide
+
+Sync, manage, and automate Overleaf LaTeX projects from the command line. Work in your preferred local editor while keeping Overleaf as the collaboration and compilation hub for your research team.
+
+## Overview
+
+Overleaf is the dominant online LaTeX editor in academia, used by millions of researchers for collaborative paper writing. However, many researchers prefer local editors (VS Code, Neovim, Emacs) for their superior editing capabilities, version control integration, and ability to run custom scripts. The Overleaf CLI bridge enables a hybrid workflow: edit locally with full tooling, then sync changes to Overleaf for collaboration and compilation.
+
+This skill covers three approaches to Overleaf CLI integration: Overleaf's built-in Git bridge (available on paid plans), the open-source `overleaf-sync` tool (works with free plans), and direct API interaction. Each approach has different trade-offs in terms of cost, features, and reliability.
+
+Beyond simple sync, this guide covers automation workflows that are particularly valuable for research: automated bibliography updates from reference managers, figure regeneration from data analysis scripts, CI-based PDF compilation, and multi-author merge conflict resolution.
+
+## Overleaf Git Bridge
+
+Overleaf Server Pro and paid plans include a Git bridge that exposes each project as a Git repository.
+
+### Setup
+
+```bash
+# Clone your Overleaf project (requires paid plan)
+git clone https://git.overleaf.com/YOUR_PROJECT_ID my-paper
+cd my-paper
+
+# The remote is already configured
+git remote -v
+# origin  https://git.overleaf.com/YOUR_PROJECT_ID (fetch)
+# origin  https://git.overleaf.com/YOUR_PROJECT_ID (push)
+```
+
+### Daily Workflow
+
+```bash
+# Pull latest changes from collaborators
+git pull origin master
+
+# Edit locally in your preferred editor
+vim main.tex
+
+# Push changes back to Overleaf
+git add -A
+git commit -m "Revise methodology section"
+git push origin master
+```
+
+### Conflict Resolution
+
+When collaborators edit the same section simultaneously:
+
+```bash
+git pull origin master
+# If conflicts occur:
+# 1. Open conflicted files
+# 2. Resolve LaTeX merge conflicts (look for <<<<<<< markers)
+# 3. Verify the document compiles
+git add -A
+git commit -m "Resolve merge conflict in results section"
+git push origin master
+```
+
+## Open-Source Sync Tools
+
+### overleaf-sync (Python)
+
+For free Overleaf accounts without Git bridge access:
+
+```bash
+# Install
+pip install overleaf-sync
+
+# Login (stores credentials securely)
+ols login
+
+# List your projects
+ols list
+
+# Download a project
+ols download "My Research Paper" --path ./my-paper
+
+# Upload local changes
+ols upload ./my-paper --project "My Research Paper"
+
+# Two-way sync (pull then push)
+ols sync ./my-paper --project "My Research Paper"
+```
+
+### Automated Sync Script
+
+```bash
+#!/bin/bash
+# sync-overleaf.sh - Run periodically or before/after editing sessions
+
+PROJECT_DIR="$1"
+PROJECT_NAME="$2"
+
+echo "Pulling latest from Overleaf..."
+ols download "$PROJECT_NAME" --path "$PROJECT_DIR" --skip-existing
+
+echo "Compiling locally to verify..."
+cd "$PROJECT_DIR"
+latexmk -pdf -interaction=nonstopmode main.tex
+
+if [ $? -eq 0 ]; then
+    echo "Compilation successful. Pushing to Overleaf..."
+    ols upload "$PROJECT_DIR" --project "$PROJECT_NAME"
+else
+    echo "Compilation failed. Fix errors before syncing."
+    exit 1
+fi
+```
+
+## Automation Workflows
+
+### Auto-Update Bibliography from Zotero
+
+```python
+import subprocess
+from pathlib import Path
+
+def sync_bibliography(zotero_lib_id, bib_file, project_dir):
+    """Export Zotero library and sync to Overleaf project."""
+    # Export from Zotero using Better BibTeX
+    subprocess.run([
+        "curl", "-s",
+        f"http://localhost:23119/better-bibtex/export/library?/"
+        f"{zotero_lib_id}/library.biblatex",
+        "-o", str(Path(project_dir) / bib_file)
+    ])
+    print(f"Updated {bib_file} from Zotero library {zotero_lib_id}")
+```
+
+### Auto-Regenerate Figures from Data
+
+```python
+import subprocess
+from pathlib import Path
+
+def regenerate_figures(scripts_dir, figures_dir):
+    """Run all figure generation scripts and update outputs."""
+    scripts = sorted(Path(scripts_dir).glob("fig_*.py"))
+    for script in scripts:
+        print(f"Running {script.name}...")
+        subprocess.run(["python", str(script)], cwd=figures_dir)
+
+    print(f"Regenerated {len(scripts)} figures in {figures_dir}")
+```
+
+### CI/CD PDF Compilation
+
+```yaml
+# .github/workflows/compile-paper.yml
+name: Compile LaTeX Paper
+on:
+  push:
+    branches: [main]
+    paths: ['**.tex', '**.bib', '**.sty']
+
+jobs:
+  compile:
+    runs-on: ubuntu-latest
+    container:
+      image: texlive/texlive:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Compile PDF
+        run: |
+          latexmk -pdf -interaction=nonstopmode main.tex
+      - name: Upload PDF
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper-pdf
+          path: main.pdf
+      - name: Check for warnings
+        run: |
+          grep -i "warning" main.log | grep -v "Font" || true
+```
+
+## Project Organization
+
+Recommended directory structure for CLI-managed Overleaf projects:
+
+```
+my-paper/
+  main.tex              # Main document
+  sections/
+    01-introduction.tex
+    02-related-work.tex
+    03-methodology.tex
+    04-results.tex
+    05-discussion.tex
+    06-conclusion.tex
+  figures/
+    fig1-architecture.pdf
+    fig2-results.pdf
+  tables/
+    tab1-comparison.tex
+  references.bib
+  custom.sty            # Custom LaTeX macros
+  scripts/              # Not synced to Overleaf
+    fig_architecture.py
+    fig_results.py
+    sync.sh
+  .gitignore
+```
+
+### .gitignore for LaTeX Projects
+
+```gitignore
+# LaTeX build artifacts
+*.aux
+*.bbl
+*.blg
+*.fdb_latexmk
+*.fls
+*.log
+*.out
+*.synctex.gz
+*.toc
+
+# Local scripts (don't sync to Overleaf)
+scripts/
+
+# OS files
+.DS_Store
+```
+
+## Editor Integration
+
+### VS Code
+
+Install the "LaTeX Workshop" extension and configure local compilation:
+
+```json
+{
+  "latex-workshop.latex.tools": [
+    {
+      "name": "latexmk",
+      "command": "latexmk",
+      "args": ["-pdf", "-interaction=nonstopmode", "%DOC%"]
+    }
+  ]
+}
+```
+
+### Neovim with VimTeX
+
+```lua
+-- init.lua
+vim.g.vimtex_compiler_method = 'latexmk'
+vim.g.vimtex_view_method = 'skim'  -- macOS
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Git push rejected | Pull first, resolve conflicts, then push |
+| Sync tool authentication error | Re-run login, check 2FA settings |
+| Compilation differs locally vs Overleaf | Match TeX Live versions; Overleaf uses TeX Live 2024 |
+| Binary files (images) cause large diffs | Use `.gitattributes` to mark as binary |
+| Overleaf rate limiting | Add delays between API calls, use Git bridge if available |
+
+## References
+
+- Overleaf Git bridge documentation: https://www.overleaf.com/learn/how-to/Git_integration
+- overleaf-sync: https://github.com/moritzgloeckl/overleaf-sync
+- LaTeX Workshop (VS Code): https://github.com/James-Yu/LaTeX-Workshop
+- latexmk documentation: https://mg.readthedocs.io/latexmk.html

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

@@ -0,0 +1,149 @@
+---
+name: clawphd-guide
+description: "Agent for converting papers to diagrams, posters, and videos"
+metadata:
+  openclaw:
+    emoji: "🎬"
+    category: "tools"
+    subcategory: "diagram"
+    keywords: ["paper visualization", "poster generation", "research video", "diagram agent", "visual abstract", "presentation"]
+    source: "https://github.com/ZhihaoAIRobotic/ClawPhD"
+---
+
+# ClawPhD Guide
+
+## Overview
+
+ClawPhD is an AI agent that converts research papers into visual formats — architecture diagrams, research posters, visual abstracts, and video presentations. It reads paper PDFs, extracts key concepts and results, and generates publication-ready visual materials. Useful for conference presentations, social media dissemination, and research communication.
+
+## Features
+
+```
+Paper PDF / LaTeX
+      ↓
+  Content Extraction Agent
+  ├── Key contributions
+  ├── Architecture / method
+  ├── Results tables and figures
+  └── Abstract and conclusions
+      ↓
+  Visual Generation Agent
+  ├── Architecture diagram (SVG/PNG)
+  ├── Research poster (A0 PDF)
+  ├── Visual abstract (social media)
+  ├── Slide deck (Beamer/PPTX)
+  └── Video narration (MP4)
+```
+
+## Usage
+
+```python
+from clawphd import ClawPhD
+
+agent = ClawPhD(llm_provider="anthropic")
+
+# Generate architecture diagram
+diagram = agent.generate_diagram(
+    paper="paper.pdf",
+    style="clean",       # clean, detailed, minimal
+    format="svg",
+    focus="method",      # method, pipeline, architecture
+)
+diagram.save("architecture.svg")
+
+# Generate research poster
+poster = agent.generate_poster(
+    paper="paper.pdf",
+    template="academic",   # academic, conference, minimal
+    size="A0",
+    color_scheme="blue",
+)
+poster.save("poster.pdf")
+
+# Generate visual abstract
+abstract = agent.generate_visual_abstract(
+    paper="paper.pdf",
+    format="png",
+    dimensions=(1200, 630),  # Twitter/LinkedIn optimal
+)
+abstract.save("visual_abstract.png")
+```
+
+## Diagram Styles
+
+```python
+# Architecture diagram
+diagram = agent.generate_diagram(
+    paper="paper.pdf",
+    style="clean",
+    components={
+        "show_data_flow": True,
+        "show_dimensions": True,
+        "show_loss_functions": False,
+        "annotation_level": "medium",
+    },
+)
+
+# Pipeline diagram
+pipeline = agent.generate_diagram(
+    paper="paper.pdf",
+    focus="pipeline",
+    layout="horizontal",  # horizontal, vertical, circular
+)
+
+# Comparison diagram
+comparison = agent.generate_comparison(
+    papers=["paper_a.pdf", "paper_b.pdf"],
+    aspects=["architecture", "performance", "complexity"],
+)
+```
+
+## Poster Generation
+
+```python
+# Conference poster with full customization
+poster = agent.generate_poster(
+    paper="paper.pdf",
+    template="neurips",
+    sections=[
+        "title_block",
+        "motivation",
+        "method",
+        "key_results",
+        "conclusions",
+        "qr_code",
+    ],
+    style={
+        "font_family": "Helvetica",
+        "heading_color": "#2563EB",
+        "background": "#FFFFFF",
+        "columns": 3,
+    },
+)
+```
+
+## Slide Generation
+
+```python
+# Generate presentation slides
+slides = agent.generate_slides(
+    paper="paper.pdf",
+    format="beamer",     # beamer, pptx, reveal_js
+    num_slides=15,
+    include_speaker_notes=True,
+    style="metropolis",  # Beamer theme
+)
+slides.save("presentation.tex")
+```
+
+## Use Cases
+
+1. **Conference posters**: Generate posters from papers
+2. **Social media**: Visual abstracts for paper promotion
+3. **Presentations**: Quick slide decks from papers
+4. **Architecture diagrams**: Clean method visualizations
+5. **Teaching**: Visual explanations of research papers
+
+## References
+
+- [ClawPhD GitHub](https://github.com/ZhihaoAIRobotic/ClawPhD)

package/skills/tools/diagram/code-flow-visualizer/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: code-flow-visualizer
+description: "Convert Python, JavaScript, and TypeScript functions into Mermaid flowcharts"
+metadata:
+  openclaw:
+    emoji: "flow"
+    category: "tools"
+    subcategory: "diagram"
+    keywords: ["code visualization", "flowchart", "Mermaid", "Python", "control flow", "AST"]
+    source: "https://github.com/mermaid-js/mermaid"
+---
+
+# Code Flow Visualizer
+
+Convert Python, JavaScript, and TypeScript functions into Mermaid flowcharts by analyzing control flow structures. This skill helps researchers document and understand complex algorithmic logic, data processing pipelines, and experimental workflows embedded in code.
+
+## Overview
+
+Research code often contains intricate control flow: nested conditionals for data filtering, loops over experimental conditions, error handling for API calls, and branching logic for different analysis paths. Understanding this flow is critical for reproducibility, code review, and documentation, yet reading nested code can be cognitively demanding.
+
+This skill translates source code into visual Mermaid flowcharts by parsing control flow structures (if/else, for/while loops, try/catch, match/switch, return statements) and mapping them to flowchart nodes and edges. The resulting diagrams serve as documentation supplements in README files, lab notebooks, and paper appendices.
+
+The approach works by performing a lightweight static analysis of the code's abstract syntax tree (AST). Each control structure maps to a specific flowchart pattern: conditionals become diamond decision nodes, loops become cycles with back-edges, function calls become subroutine nodes, and return statements become terminal nodes.
+
+## Conversion Rules
+
+### Control Flow Mapping
+
+| Code Structure | Flowchart Element | Mermaid Shape |
+|---------------|-------------------|---------------|
+| Function entry | Start node | `([Function Name])` |
+| Assignment / expression | Process node | `[statement]` |
+| `if` / `else if` | Decision diamond | `{condition?}` |
+| `for` / `while` loop | Decision + back-edge | `{loop condition?}` with cycle |
+| `try` / `catch` | Process + error path | `[try block]` with dashed error edge |
+| `return` / `yield` | Terminal / output node | `([return value])` |
+| Function call | Subroutine node | `[[function_name()]]` |
+| `match` / `switch` | Multi-branch decision | `{value?}` with labeled edges |
+
+### Python Example
+
+**Input code:**
+
+```python
+def process_papers(papers, min_citations=10):
+    results = []
+    for paper in papers:
+        if paper.year < 2015:
+            continue
+        if paper.citation_count < min_citations:
+            continue
+        try:
+            abstract = fetch_abstract(paper.doi)
+            embeddings = compute_embeddings(abstract)
+            results.append({"paper": paper, "embedding": embeddings})
+        except APIError:
+            log_error(paper.doi)
+    return results
+```
+
+**Output flowchart:**
+
+```mermaid
+flowchart TD
+    Start(["process_papers(papers, min_citations=10)"]) --> Init["results = [ ]"]
+    Init --> Loop{"For each paper in papers?"}
+    Loop -->|Done| Return(["Return results"])
+    Loop -->|Next paper| YearCheck{"paper.year < 2015?"}
+    YearCheck -->|Yes| Loop
+    YearCheck -->|No| CitCheck{"citation_count < min_citations?"}
+    CitCheck -->|Yes| Loop
+    CitCheck -->|No| TryBlock["abstract = fetch_abstract(paper.doi)"]
+    TryBlock --> Embed["embeddings = compute_embeddings(abstract)"]
+    Embed --> Append["results.append(...)"]
+    Append --> Loop
+    TryBlock -.->|APIError| LogErr["log_error(paper.doi)"]
+    LogErr --> Loop
+```
+
+### JavaScript / TypeScript Example
+
+**Input code:**
+
+```typescript
+async function searchPapers(query: string, maxResults: number = 50): Promise<Paper[]> {
+    const cached = await cache.get(query);
+    if (cached) return cached;
+
+    const results: Paper[] = [];
+    let offset = 0;
+
+    while (results.length < maxResults) {
+        const batch = await api.search(query, offset, 10);
+        if (batch.length === 0) break;
+
+        for (const paper of batch) {
+            if (paper.isRetracted) continue;
+            results.push(paper);
+        }
+        offset += 10;
+    }
+
+    await cache.set(query, results);
+    return results;
+}
+```
+
+**Output flowchart:**
+
+```mermaid
+flowchart TD
+    Start(["searchPapers(query, maxResults=50)"]) --> Cache["cached = await cache.get(query)"]
+    Cache --> CacheHit{"cached exists?"}
+    CacheHit -->|Yes| ReturnCached(["Return cached"])
+    CacheHit -->|No| InitResults["results = [ ], offset = 0"]
+    InitResults --> WhileLoop{"results.length < maxResults?"}
+    WhileLoop -->|No| SaveCache["await cache.set(query, results)"]
+    WhileLoop -->|Yes| Fetch["batch = await api.search(query, offset, 10)"]
+    Fetch --> EmptyCheck{"batch.length === 0?"}
+    EmptyCheck -->|Yes| SaveCache
+    EmptyCheck -->|No| ForLoop{"For each paper in batch?"}
+    ForLoop -->|Done| IncOffset["offset += 10"]
+    IncOffset --> WhileLoop
+    ForLoop -->|Next| Retracted{"paper.isRetracted?"}
+    Retracted -->|Yes| ForLoop
+    Retracted -->|No| Push["results.push(paper)"]
+    Push --> ForLoop
+    SaveCache --> Return(["Return results"])
+```
+
+## Handling Complex Patterns
+
+### Nested Conditionals
+
+Deeply nested if/else chains are flattened into a decision tree. Each branch is labeled with its condition, and nodes at the same depth are arranged vertically for readability.
+
+### Recursive Functions
+
+Recursive calls are shown as subroutine nodes with a self-referencing edge back to the function start node. A note annotation indicates the recursion base case.
+
+### Generator Functions (yield)
+
+Python generators use `yield` as intermediate output nodes (shown as parallelogram shapes). The flowchart shows the suspension point and resumption path.
+
+### Error Handling Chains
+
+Multiple `except` clauses create parallel error paths from the `try` block, each labeled with the exception type. `finally` blocks are shown as a converging node that all paths pass through.
+
+## Styling for Documentation
+
+### Academic Paper Style
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#f8f9fa',
+    'primaryBorderColor': '#212529',
+    'primaryTextColor': '#212529',
+    'lineColor': '#495057',
+    'fontFamily': 'Times New Roman, serif',
+    'fontSize': '14px'
+  }
+}}%%
+flowchart TD
+    A["Step 1"] --> B{"Decision"} --> C["Step 2"]
+```
+
+### Export for LaTeX
+
+```bash
+# Render Mermaid to PDF for LaTeX inclusion
+mmdc -i flowchart.mmd -o flowchart.pdf -t neutral -b transparent
+```
+
+```latex
+\begin{figure}[h]
+    \centering
+    \includegraphics[width=0.8\textwidth]{flowchart.pdf}
+    \caption{Control flow of the data processing pipeline.}
+    \label{fig:flowchart}
+\end{figure}
+```
+
+## Limitations and Best Practices
+
+1. **Scope**: Works best for functions under 100 lines. For larger codebases, visualize individual functions or extract key subroutines.
+2. **Dynamic dispatch**: Cannot trace through dynamic method resolution or callback chains. Show these as labeled subroutine nodes.
+3. **Concurrency**: Async/await is shown sequentially. Concurrent branches (e.g., `Promise.all`) are noted but not fully modeled.
+4. **Simplification**: Omit trivial assignments and logging statements to keep diagrams focused on control flow.
+
+## References
+
+- Mermaid flowchart syntax: https://mermaid.js.org/syntax/flowchart.html
+- Python AST module: https://docs.python.org/3/library/ast.html
+- TypeScript Compiler API: https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API
+- Code2Flow (related tool): https://github.com/scottrogowski/code2flow