scientify 1.0.1 → 1.1.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAWlD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAsDtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAYlD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAuDtD"}

package/dist/index.js

@@ -1,8 +1,10 @@
 import { handleResearchStatus, handlePapers, handleIdeas, handleProjects, handleProjectSwitch, handleProjectDelete, } from "./src/commands.js";
 import { createArxivTool } from "./src/tools/arxiv-tool.js";
+import { createGithubSearchTool } from "./src/tools/github-search-tool.js";
 export default function register(api) {
-    // Register the arxiv tool
+    // Register tools
     api.registerTool(createArxivTool());
+    api.registerTool(createGithubSearchTool());
     // Register chat commands (bypass LLM)
     api.registerCommand({
         name: "research-status",

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAsB;IACrD,0BAA0B;IAC1B,GAAG,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC,CAAC;IAEpC,sCAAsC;IACtC,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,gEAAgE;QAC7E,WAAW,EAAE,KAAK;QAClB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,oBAAoB;KAC9B,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,0CAA0C;QACvD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,YAAY;KACtB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,WAAW;KACrB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,KAAK;QAClB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,oDAAoD;QACjE,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,IAAI,EAAE,yCAAyC;QAC5D,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAsB;IACrD,iBAAiB;IACjB,GAAG,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC,CAAC;IACpC,GAAG,CAAC,YAAY,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAE3C,sCAAsC;IACtC,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,gEAAgE;QAC7E,WAAW,EAAE,KAAK;QAClB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,oBAAoB;KAC9B,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,0CAA0C;QACvD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,YAAY;KACtB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,WAAW;KACrB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,KAAK;QAClB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,oDAAoD;QACjE,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,IAAI,EAAE,yCAAyC;QAC5D,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/src/tools/github-search-tool.d.ts

@@ -0,0 +1,22 @@
+export declare const GithubSearchToolSchema: import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    max_results: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare function createGithubSearchTool(): {
+    label: string;
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        query: import("@sinclair/typebox").TString;
+        max_results: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute: (_toolCallId: string, rawArgs: unknown) => Promise<{
+        type: "tool_result";
+        content: string;
+    }>;
+};
+//# sourceMappingURL=github-search-tool.d.ts.map

package/dist/src/tools/github-search-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-search-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/github-search-tool.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,sBAAsB;;;;;EAqBjC,CAAC;AAyCH,wBAAgB,sBAAsB;;;;;;;;;;2BAOL,MAAM,WAAW,OAAO;;;;EA4FxD"}

package/dist/src/tools/github-search-tool.js

@@ -0,0 +1,134 @@
+import { Type } from "@sinclair/typebox";
+const GITHUB_SEARCH_API = "https://api.github.com/search/repositories";
+const DEFAULT_MAX_RESULTS = 10;
+const MAX_RESULTS_LIMIT = 30;
+export const GithubSearchToolSchema = Type.Object({
+    query: Type.String({
+        description: "Search query for GitHub repositories (e.g. 'graph neural network recommendation').",
+    }),
+    max_results: Type.Optional(Type.Number({
+        description: "Maximum number of results (1-30). Default: 10.",
+        minimum: 1,
+        maximum: MAX_RESULTS_LIMIT,
+    })),
+    language: Type.Optional(Type.String({
+        description: "Filter by programming language (e.g. 'python', 'typescript').",
+    })),
+    sort: Type.Optional(Type.String({
+        description: 'Sort by: "stars" (default), "updated", or "best-match".',
+    })),
+});
+function readStringParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null) {
+        if (opts?.required) {
+            throw new Error(`Missing required parameter: ${key}`);
+        }
+        return undefined;
+    }
+    return String(value);
+}
+function readNumberParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null)
+        return undefined;
+    const num = Number(value);
+    if (isNaN(num))
+        return undefined;
+    return opts?.integer ? Math.floor(num) : num;
+}
+function resolveGithubToken() {
+    return ((process.env.GITHUB_TOKEN ?? "").trim() ||
+        (process.env.GH_TOKEN ?? "").trim() ||
+        (process.env.GITHUB_AI_TOKEN ?? "").trim() ||
+        undefined);
+}
+export function createGithubSearchTool() {
+    return {
+        label: "GitHub Search",
+        name: "github_search",
+        description: "Search GitHub repositories by keyword. Returns repo names, descriptions, star counts, and URLs. Reads GITHUB_TOKEN from environment for authentication.",
+        parameters: GithubSearchToolSchema,
+        execute: async (_toolCallId, rawArgs) => {
+            const params = rawArgs;
+            const query = readStringParam(params, "query", { required: true });
+            const maxResults = Math.min(readNumberParam(params, "max_results", { integer: true }) ?? DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT);
+            const language = readStringParam(params, "language");
+            const rawSort = readStringParam(params, "sort") ?? "stars";
+            // Build GitHub search query
+            let searchQuery = query;
+            if (language) {
+                searchQuery += ` language:${language}`;
+            }
+            const sort = rawSort === "best-match" ? undefined : rawSort;
+            const urlParams = new URLSearchParams({
+                q: searchQuery,
+                per_page: String(maxResults),
+                order: "desc",
+            });
+            if (sort) {
+                urlParams.set("sort", sort);
+            }
+            const url = `${GITHUB_SEARCH_API}?${urlParams.toString()}`;
+            const token = resolveGithubToken();
+            const headers = {
+                Accept: "application/vnd.github+json",
+                "User-Agent": "scientify-agent",
+            };
+            if (token) {
+                headers.Authorization = `Bearer ${token}`;
+            }
+            let response;
+            try {
+                response = await fetch(url, { headers });
+            }
+            catch (error) {
+                return {
+                    type: "tool_result",
+                    content: JSON.stringify({
+                        error: "network_error",
+                        message: `Failed to reach GitHub API: ${error instanceof Error ? error.message : String(error)}`,
+                    }),
+                };
+            }
+            if (response.status === 403) {
+                return {
+                    type: "tool_result",
+                    content: JSON.stringify({
+                        error: "rate_limited",
+                        message: "GitHub API rate limit exceeded. Set GITHUB_TOKEN environment variable for higher limits.",
+                    }),
+                };
+            }
+            if (!response.ok) {
+                return {
+                    type: "tool_result",
+                    content: JSON.stringify({
+                        error: "api_error",
+                        message: `GitHub API returned ${response.status}: ${response.statusText}`,
+                    }),
+                };
+            }
+            const data = (await response.json());
+            const repos = (data.items ?? []).map((repo) => ({
+                name: repo.full_name,
+                url: repo.html_url,
+                description: repo.description ?? "",
+                stars: repo.stargazers_count,
+                language: repo.language ?? "unknown",
+                updated: repo.updated_at,
+                topics: repo.topics ?? [],
+            }));
+            return {
+                type: "tool_result",
+                content: JSON.stringify({
+                    query,
+                    total_count: data.total_count ?? 0,
+                    returned: repos.length,
+                    repos,
+                }),
+            };
+        },
+    };
+}
+//# sourceMappingURL=github-search-tool.js.map

package/dist/src/tools/github-search-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-search-tool.js","sourceRoot":"","sources":["../../../src/tools/github-search-tool.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scientify",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Scientify - AI-powered research workflow automation for OpenClaw. Includes idea generation, literature review, research pipeline skills, and arxiv tool.",
   "type": "module",
   "main": "dist/index.js",

package/skills/idea-generation/references/idea-template.md

@@ -0,0 +1,217 @@
+# Idea Template
+
+Use this template for each idea in `~/.openclaw/workspace/ideas/`.
+
+---
+
+# Idea N: [Short Descriptive Title]
+
+## One-Line Summary
+
+[A single sentence that captures the core innovation. Should be understandable without context.]
+
+---
+
+## Challenges Addressed
+
+What problems in the current research landscape does this idea solve?
+
+- **[Challenge 1]**: [Brief description of the technical limitation]
+- **[Challenge 2]**: [Brief description of unsolved problem]
+- **[Challenge 3]**: [Brief description of key bottleneck]
+
+---
+
+## Existing Methods & Their Limitations
+
+| Method | Paper/Source | Strength | Weakness This Idea Addresses |
+|--------|--------------|----------|------------------------------|
+| [Method A] | [Citation] | [What it does well] | [Limitation] |
+| [Method B] | [Citation] | [What it does well] | [Limitation] |
+| [Method C] | [Citation] | [What it does well] | [Limitation] |
+
+---
+
+## Motivation
+
+### Why is this problem important?
+
+[Explain the significance of solving this problem. Who benefits? What applications are enabled?]
+
+### What gap does this fill?
+
+[Describe the specific research gap this idea addresses. Reference the limitations above.]
+
+### Potential impact
+
+[Quantify if possible: "Could improve X metric by Y%" or "Enables new application Z"]
+
+---
+
+## Proposed Method
+
+### Core Insight
+
+[2-3 sentences describing the key innovation. What is the "aha" moment?]
+
+### Technical Approach
+
+**Overview:**
+
+[1 paragraph high-level description]
+
+**Step-by-step methodology:**
+
+1. **[Step 1 Name]**: [Description]
+   - Input: [what this step takes]
+   - Output: [what this step produces]
+   - Key operation: [main computation]
+
+2. **[Step 2 Name]**: [Description]
+   - Input: ...
+   - Output: ...
+   - Key operation: ...
+
+3. **[Step 3 Name]**: [Description]
+   - ...
+
+### Mathematical Formulation
+
+**Problem Setup:**
+
+Let $X \in \mathbb{R}^{n \times d}$ denote [description]...
+
+**Core Equations:**
+
+```latex
+% Main loss function
+\mathcal{L} = \mathcal{L}_{task} + \lambda \mathcal{L}_{reg}
+
+% Where task loss is:
+\mathcal{L}_{task} = ...
+
+% And regularization term is:
+\mathcal{L}_{reg} = ...
+```
+
+**Key derivations (if applicable):**
+
+[Show important mathematical steps that justify the approach]
+
+### Architecture / Algorithm
+
+```
+Algorithm: [Name]
+Input: [inputs]
+Output: [outputs]
+
+1. Initialize [parameters]
+2. For each [iteration]:
+   a. Compute [something]
+   b. Update [something]
+3. Return [result]
+```
+
+Or for neural architectures:
+
+```
+[Input] → [Layer 1] → [Layer 2] → ... → [Output]
+         (dim: ...)   (dim: ...)         (dim: ...)
+```
+
+---
+
+## Expected Advantages
+
+Why should this approach work better than existing methods?
+
+- **[Advantage 1]**: [Explanation with reasoning]
+- **[Advantage 2]**: [Explanation with reasoning]
+- **[Advantage 3]**: [Explanation with reasoning]
+
+**Theoretical justification (if applicable):**
+
+[Brief argument for why this should work]
+
+---
+
+## Potential Challenges
+
+What could go wrong? How to mitigate?
+
+| Challenge | Risk Level | Mitigation Strategy |
+|-----------|------------|---------------------|
+| [Challenge 1] | High/Med/Low | [How to address] |
+| [Challenge 2] | High/Med/Low | [How to address] |
+| [Challenge 3] | High/Med/Low | [How to address] |
+
+---
+
+## Evaluation Plan
+
+### Datasets
+
+| Dataset | Task | Size | Why Chosen |
+|---------|------|------|------------|
+| [Dataset 1] | [Task] | [Size] | [Reason] |
+| [Dataset 2] | [Task] | [Size] | [Reason] |
+
+### Baselines
+
+| Method | Paper | Why Compare |
+|--------|-------|-------------|
+| [Baseline 1] | [Citation] | [Reason] |
+| [Baseline 2] | [Citation] | [Reason] |
+
+### Metrics
+
+| Metric | Description | Expected Improvement |
+|--------|-------------|---------------------|
+| [Metric 1] | [What it measures] | [X% over baseline] |
+| [Metric 2] | [What it measures] | [Y% over baseline] |
+
+### Ablation Studies
+
+What components to ablate to understand contribution?
+
+1. [Component 1]: Remove/replace to test [hypothesis]
+2. [Component 2]: Remove/replace to test [hypothesis]
+
+---
+
+## Scores
+
+| Criterion | Score (1-5) | Justification |
+|-----------|-------------|---------------|
+| **Novelty** | [X] | [Why this score] |
+| **Feasibility** | [X] | [Why this score] |
+| **Impact** | [X] | [Why this score] |
+| **Total** | [Sum] | |
+
+---
+
+## Implementation Notes
+
+### Recommended Libraries
+
+- [Library 1]: For [purpose]
+- [Library 2]: For [purpose]
+
+### Reference Code
+
+- [Repo 1](URL): [What to reference]
+- [Repo 2](URL): [What to reference]
+
+### Estimated Effort
+
+- Model implementation: [X days]
+- Data pipeline: [X days]
+- Training & evaluation: [X days]
+- Total: [X days]
+
+---
+
+## Related Ideas
+
+- **Idea [M]**: [How it relates - could be combined? alternative approach?]
+- **Future extension**: [What could come next after this idea]

package/skills/install-scientify/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: install-scientify
+description: "Install Scientify - AI-powered research workflow automation plugin. Adds skills for idea-generation, literature-review, research-pipeline, arxiv search, and workspace management commands."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔬",
+        "install":
+          [
+            {
+              "id": "scientify",
+              "kind": "node",
+              "package": "scientify",
+              "label": "Install Scientify plugin (npm)",
+            },
+          ],
+      },
+  }
+---
+
+# Install Scientify
+
+**Scientify** is an AI-powered research workflow automation plugin for OpenClaw.
+
+## What You Get
+
+### Skills (LLM-powered)
+
+| Skill | Description |
+|-------|-------------|
+| **idea-generation** | Generate innovative research ideas. Searches arXiv/GitHub, downloads papers, analyzes literature, outputs 5 ideas with citations. |
+| **research-pipeline** | End-to-end ML research workflow: idea → literature → survey → plan → implement → review → iterate. |
+| **literature-review** | Generate structured notes and synthesis from collected papers. |
+| **arxiv** | Search arXiv.org for papers and download .tex sources. |
+
+### Commands (Direct, no LLM)
+
+| Command | Description |
+|---------|-------------|
+| `/research-status` | Show workspace status |
+| `/papers` | List downloaded papers |
+| `/ideas` | List generated ideas |
+| `/projects` | List all projects |
+| `/project-switch <id>` | Switch project |
+| `/project-delete <id>` | Delete project |
+
+### Tool
+
+- **arxiv** - Search arXiv.org API with keyword search, date filtering, automatic .tex download
+
+## Installation
+
+Run:
+
+```bash
+npm install -g scientify
+```
+
+Or let OpenClaw install it automatically when you use this skill.
+
+Then add to your OpenClaw config:
+
+```json
+{
+  "plugins": ["scientify"]
+}
+```
+
+## Usage Examples
+
+### Generate Research Ideas
+
+```
+帮我调研 "长文档摘要" 领域，生成一些创新的研究想法
+```
+
+### Daily Literature Tracking
+
+```
+帮我设置一个定时任务，每天检查 arXiv 上关于 "transformer efficiency" 的新论文，发到飞书
+```
+
+### Check Workspace
+
+```
+/research-status
+```
+
+## Links
+
+- npm: https://www.npmjs.com/package/scientify
+- GitHub: https://github.com/tsingyuai/scientific
+- Author: tsingyuai

package/skills/literature-review/references/note-template.md

@@ -0,0 +1,134 @@
+# Paper Note Template
+
+Use this template for each paper in `~/.openclaw/workspace/literature/notes/`.
+
+---
+
+# [Paper Title]
+
+**ArXiv/DOI**: [id]
+**Authors**: [First Author et al.]
+**Year**: [YYYY]
+**Venue**: [Conference/Journal, or "arXiv preprint"]
+**PDF**: [local path or URL]
+
+---
+
+## TL;DR
+
+[1-2 sentences: What is the main contribution? What problem does it solve?]
+
+---
+
+## Problem Statement
+
+[What gap or challenge does this paper address? Why is it important?]
+
+---
+
+## Method
+
+### Core Idea
+
+[The key insight or innovation in 2-3 sentences]
+
+### Approach
+
+[Step-by-step description of the method]
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Key Equations
+
+```latex
+% Main loss function or formula
+L = ...
+```
+
+### Architecture / Algorithm
+
+[Describe the model architecture or algorithm structure]
+
+---
+
+## Experiments
+
+### Setup
+
+- **Datasets**: [list with brief description]
+- **Baselines**: [methods compared against]
+- **Metrics**: [evaluation metrics used]
+
+### Main Results
+
+| Method | Dataset | Metric | Score |
+|--------|---------|--------|-------|
+| Proposed | ... | ... | ... |
+| Baseline 1 | ... | ... | ... |
+
+### Ablation Studies
+
+[Key findings from ablation experiments]
+
+---
+
+## Analysis
+
+### Strengths
+
+- ✅ [Strength 1]
+- ✅ [Strength 2]
+- ✅ [Strength 3]
+
+### Weaknesses / Limitations
+
+- ⚠️ [Weakness 1]
+- ⚠️ [Weakness 2]
+
+### Questions / Unclear Points
+
+- ❓ [Question about the paper]
+
+---
+
+## Relevance
+
+### To My Research
+
+[How does this paper relate to what I'm working on?]
+
+### Key Takeaways
+
+1. [Actionable insight 1]
+2. [Actionable insight 2]
+
+### Ideas to Explore
+
+- [ ] [Idea inspired by this paper]
+- [ ] [Potential extension or combination]
+
+---
+
+## Key Quotes
+
+> "[Important quote 1]" — Section X
+
+> "[Important quote 2]" — Section Y
+
+---
+
+## References to Follow
+
+- [ ] **[Author et al., Year]**: [Title] — [Why interesting]
+- [ ] **[Author et al., Year]**: [Title] — [Why interesting]
+
+---
+
+## Meta
+
+- **Read on**: [date]
+- **Time spent**: [estimate]
+- **Rating**: [⭐⭐⭐⭐⭐ or 1-5]
+- **Would cite**: [Yes/No/Maybe]

package/skills/research-pipeline/SKILL.md

@@ -193,7 +193,7 @@ Execute:
 cd $WORKSPACE/project && pip install -r requirements.txt && python run.py --epochs 2
 ```
 
-If using GPU containers, ensure sandbox has `gpus` and `shmSize` configured.
+**Note:** GPU support requires external configuration. For GPU-accelerated training, consider using a dedicated ML environment or cloud instance.
 
 **Output:** `$WORKSPACE/project/` (code) + `$WORKSPACE/ml_res.md` (implementation report)
 

package/skills/research-pipeline/references/prompts/implement.md

@@ -0,0 +1,135 @@
+# Implementation Guide
+
+You are implementing an ML research project based on the plan in `workspace/plan_res.md`. The goal is a self-contained, runnable codebase in `workspace/project/`.
+
+## Core Principles
+
+### 1. Self-Contained Project
+
+ALL code must reside within `workspace/project/`. No direct imports from `workspace/repos/`. Reference code should be studied, understood, and rewritten to fit the project's architecture.
+
+When adapting reference code:
+
+- Understand the core logic and algorithm, not just copy the syntax.
+- Rewrite to fit consistent naming conventions and coding style.
+- Document the origin: add a comment like `# Adapted from repos/xyz/model/attention.py`.
+- Include all necessary utility functions — do not rely on external helpers.
+
+### 2. Follow the Plan Exactly
+
+Implement every component listed in `workspace/plan_res.md`:
+
+- Every atomic definition from the Model Plan becomes a class or module.
+- The dataset pipeline matches the Dataset Plan.
+- The loss function matches the Training Plan formula.
+- The evaluation matches the Testing Plan metrics.
+
+Do not skip components. Do not substitute simpler alternatives. If a component seems wrong, flag it rather than silently changing it.
+
+### 3. Real Data, Not Toy Data
+
+Use the actual datasets specified in the plan. If the dataset requires downloading, write the download logic. Never substitute with random data or tiny synthetic datasets for the implementation (the quick validation uses real data with 2 epochs, not fake data).
+
+## Project Structure
+
+```
+workspace/project/
+  model/
+    __init__.py
+    [component files matching Model Plan]
+  data/
+    __init__.py
+    dataset.py       # Dataset class
+    loader.py         # DataLoader configuration
+    preprocess.py     # Preprocessing logic
+  training/
+    __init__.py
+    trainer.py        # Training loop
+    loss.py           # Loss functions
+  testing/
+    __init__.py
+    evaluator.py      # Evaluation logic
+    metrics.py        # Metric implementations
+  utils/
+    __init__.py
+    [shared utilities]
+  run.py              # Main entry point
+  requirements.txt    # All dependencies with versions
+  README.md           # Brief description of the project
+```
+
+## Implementation Sequence
+
+Follow this order to catch issues early:
+
+1. **requirements.txt**: List all dependencies. Pin major versions.
+2. **Data pipeline**: Implement dataset loading first. Verify with a small print test.
+3. **Model architecture**: Implement each component. Verify shapes with dummy input.
+4. **Loss function**: Implement and verify with dummy predictions.
+5. **Training loop**: Wire everything together. Include logging.
+6. **Evaluation**: Implement metrics and test evaluation pipeline.
+7. **run.py**: Main entry point with argument parsing.
+
+After each step, run a quick sanity check before moving on.
+
+## Quick Validation Run
+
+The first run uses 2 epochs only:
+
+```bash
+cd workspace/project
+pip install -r requirements.txt
+python run.py --epochs 2
+```
+
+Expected outcomes:
+- No import errors or missing dependencies.
+- Loss decreases (even slightly) over 2 epochs.
+- No NaN or Inf in loss or gradients.
+- Evaluation metrics produce reasonable (not necessarily good) numbers.
+- Memory usage stays within limits.
+
+If the run fails, debug and fix before reporting. Common issues:
+- Shape mismatches: print tensor shapes at each step.
+- OOM: reduce batch size or model size for validation.
+- Data loading errors: verify file paths and formats.
+
+## Debugging Tips
+
+- Add `print(f"tensor.shape = {tensor.shape}")` at critical points during initial debugging.
+- Use `torch.autograd.set_detect_anomaly(True)` to catch gradient issues.
+- If training is unstable, check learning rate and gradient norms.
+- Remove debugging prints before the final version.
+
+## Implementation Report
+
+After the quick validation succeeds, write `workspace/ml_res.md`:
+
+```markdown
+# Implementation Report
+
+## Components Implemented
+- [List each module with brief description]
+
+## Quick Validation Results
+- Epochs: 2
+- Final training loss: [value]
+- Validation metrics: [values]
+- Runtime: [time]
+- GPU memory: [peak usage]
+
+## Deviations from Plan
+- [Any changes made and why]
+
+## Known Issues
+- [Any issues encountered]
+```
+
+## Rules
+
+1. Never import from `workspace/repos/` — adapt and rewrite instead.
+2. Never use toy/synthetic data — use real datasets from the plan.
+3. Never skip plan components — implement everything or flag the issue.
+4. Always validate with 2 epochs before declaring success.
+5. Always write `requirements.txt` with pinned versions.
+6. If you cannot resolve an issue after 3 attempts, document the problem and ask the user.

package/skills/research-pipeline/references/prompts/plan.md

@@ -0,0 +1,142 @@
+# Implementation Planning Guide
+
+You are creating a detailed, actionable implementation plan. This plan must be specific enough that the implementation step can follow it without ambiguity.
+
+## Prerequisites
+
+Before planning, you must have:
+
+- `workspace/task.json` — the research idea
+- `workspace/survey_res.md` — the literature survey with theory-to-code mappings
+- `workspace/prepare_res.md` — selected reference repositories
+
+Read ALL of these files thoroughly before writing the plan. Also browse the reference codebases in `workspace/repos/` to understand their structure and reusable components.
+
+## Plan Structure
+
+The plan has four mandatory sections. Write all four to `workspace/plan_res.md`.
+
+### 1. Dataset Plan
+
+```markdown
+## Dataset Plan
+
+### Data Source
+- Dataset name and where to obtain it
+- Size and format
+- Any preprocessing requirements
+
+### Data Loading Pipeline
+1. **Read**: How to load raw data (file format, library to use)
+2. **Preprocess**: Transformations, tokenization, normalization, feature extraction
+3. **DataLoader**: Batch construction, sampling strategy, collate function
+
+### Data Splits
+- Train/validation/test split ratios
+- Any special handling (e.g., cold-start users, temporal splits)
+```
+
+Refer to the reference codebases for data loading patterns. Cite specific files: "See `repos/xyz/data/loader.py` for the graph construction approach."
+
+### 2. Model Plan
+
+```markdown
+## Model Plan
+
+### Architecture Overview
+[High-level description of the model architecture]
+
+### Components (one per atomic definition)
+
+#### [Atomic Definition 1]
+- **Math**: $formula$
+- **Implementation**: Class name, input/output shapes, key methods
+- **Reference**: repos/xyz/model/attention.py, class MultiHeadAttention
+- **Adaptation notes**: [What to change from the reference]
+
+#### [Atomic Definition 2]
+...
+
+### Forward Pass
+[Step-by-step description of the forward pass, connecting all components]
+
+### Parameter Count Estimate
+[Rough estimate to sanity-check the architecture]
+```
+
+Every atomic definition from `survey_res.md` must appear as a component. If a definition doesn't map to a model component, explain why.
+
+### 3. Training Plan
+
+```markdown
+## Training Plan
+
+### Loss Function
+- Formula: $L = ...$
+- Components: [list each loss term and its purpose]
+- Reference: repos/xyz/training/loss.py
+
+### Optimizer
+- Algorithm: [Adam, AdamW, SGD, etc.]
+- Learning rate: [value] with [schedule: cosine, step, warmup, etc.]
+- Weight decay: [value]
+
+### Hyperparameters
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| Batch size | ... | ... |
+| Hidden dim | ... | ... |
+| Num layers | ... | ... |
+| Dropout | ... | ... |
+
+### Training Loop
+1. Forward pass
+2. Compute loss
+3. Backward pass
+4. Gradient clipping (if applicable)
+5. Optimizer step
+6. Logging (every N steps)
+7. Validation (every M epochs)
+
+### Quick Validation
+- Epochs: 2 (for initial validation)
+- Expected behavior: loss should decrease, no NaN/Inf
+
+### Full Training
+- Epochs: [value from reference papers]
+- Early stopping: [criteria]
+- Checkpoint: save best model by validation metric
+```
+
+### 4. Testing Plan
+
+```markdown
+## Testing Plan
+
+### Metrics
+- Primary: [e.g., NDCG@10, BLEU, F1]
+- Secondary: [e.g., Recall@20, Hit Rate]
+- Reference: repos/xyz/evaluation/metrics.py
+
+### Evaluation Protocol
+1. Load best checkpoint
+2. Run inference on test set
+3. Compute metrics
+4. Compare against baselines (from papers)
+
+### Baselines
+| Method | Metric | Value | Source |
+|--------|--------|-------|--------|
+| ... | ... | ... | [paper] |
+
+### Expected Results
+[Reasonable range for the proposed method based on paper claims]
+```
+
+## Quality Criteria
+
+- Every section must reference specific files from `workspace/repos/` where applicable.
+- Hyperparameter values should come from reference papers or standard practice, not guesses.
+- The plan must be implementable end-to-end without additional research.
+- If any information is missing (e.g., dataset not publicly available), flag it explicitly.
+- Do not over-engineer: plan what's needed for a solid implementation, not a production system.

package/skills/research-pipeline/references/prompts/review.md

@@ -0,0 +1,118 @@
+# Code Review Guide
+
+You are reviewing the implementation in `workspace/project/` to verify it correctly implements the research idea. This is a quality gate before full training.
+
+## Review Process
+
+### Phase 1: Verify Against Survey
+
+Read `workspace/survey_res.md` and extract the list of atomic definitions. For each atomic definition:
+
+1. Find the corresponding code in `workspace/project/`.
+2. Compare the code implementation against the mathematical formula.
+3. Check: does the code faithfully implement the math? Watch for:
+   - Missing terms in equations.
+   - Incorrect tensor operations (e.g., sum vs mean, wrong axis).
+   - Hardcoded values where parameters should be used.
+   - Simplifications that change the method's behavior.
+
+### Phase 2: Verify Against Plan
+
+Read `workspace/plan_res.md`. Check each section:
+
+**Dataset Plan:**
+- Is the correct dataset used (not a substitute)?
+- Does the preprocessing match the plan?
+- Is the DataLoader configured correctly (batch size, sampling)?
+
+**Model Plan:**
+- Are all components present?
+- Does the forward pass match the described architecture?
+- Are parameter counts reasonable?
+
+**Training Plan:**
+- Is the loss function correct (all terms present, correct weighting)?
+- Is the optimizer configured as planned?
+- Are hyperparameters matching?
+
+**Testing Plan:**
+- Are the correct metrics implemented?
+- Is the evaluation protocol correct?
+
+### Phase 3: Code Quality
+
+Check for implementation quality issues:
+
+- **Not a toy**: The implementation should be substantive, not a simplified stub.
+- **Correctness**: No obvious bugs (wrong indices, missing gradients, data leakage).
+- **Completeness**: All imports resolved, all functions implemented (no `pass` or `TODO`).
+- **Runnability**: The code should run end-to-end without errors.
+
+### Phase 4: Cross-Reference with Codebases
+
+If needed, compare against reference codebases in `workspace/repos/`:
+
+- Are key algorithmic patterns correctly adapted?
+- Were critical implementation details preserved during adaptation?
+
+## Review Output
+
+Write the review to `workspace/iterations/judge_vN.md` (increment N for each review iteration):
+
+```markdown
+# Review vN
+
+## Verdict: PASS / NEEDS_REVISION
+
+## Atomic Definition Checklist
+
+| Definition | Implemented | Correct | Notes |
+|-----------|-------------|---------|-------|
+| [def 1] | Yes/No | Yes/No | [details] |
+| [def 2] | Yes/No | Yes/No | [details] |
+| ... | ... | ... | ... |
+
+## Plan Compliance
+
+| Section | Status | Notes |
+|---------|--------|-------|
+| Dataset | OK / Issue | ... |
+| Model | OK / Issue | ... |
+| Training | OK / Issue | ... |
+| Testing | OK / Issue | ... |
+
+## Issues (if NEEDS_REVISION)
+
+### Issue 1: [Title]
+- **Location**: `project/model/attention.py`, line ~42
+- **Problem**: [Description of what's wrong]
+- **Expected**: [What the correct implementation should do]
+- **Suggestion**: [Specific fix]
+
+### Issue 2: [Title]
+...
+
+## Summary
+[Brief overall assessment: what's good, what needs work]
+```
+
+## Verdict Criteria
+
+**PASS** if:
+- All atomic definitions are implemented and correct.
+- All plan sections are satisfied.
+- Code runs end-to-end with decreasing loss.
+- No critical bugs.
+
+**NEEDS_REVISION** if:
+- Any atomic definition is missing or incorrectly implemented.
+- Any plan section has significant gaps.
+- Code has bugs that prevent correct execution.
+- Implementation is a toy/stub rather than a genuine attempt.
+
+## Iteration Rules
+
+- Each review is independent: re-evaluate everything, not just previously flagged issues.
+- Be specific in suggestions: cite file names, line numbers, and concrete fixes.
+- After 3 iterations of NEEDS_REVISION, escalate to the user with a summary of remaining issues.
+- Never approve code that doesn't run or produces NaN/Inf.

package/skills/research-pipeline/references/prompts/survey.md

@@ -0,0 +1,105 @@
+# Literature Survey Guide
+
+You are performing a literature survey to bridge theory and implementation. Your goal is to extract actionable knowledge from papers and codebases that will directly inform the implementation.
+
+## Process
+
+### Phase 1: Decompose the Idea
+
+Before reading any papers, break the research idea (from `task.json`) into **atomic academic definitions**. Each atomic definition must be:
+
+- A single, self-contained concept (e.g., "multi-head attention", "contrastive loss", "graph convolution").
+- Have clear mathematical foundations.
+- Be implementable as a code module.
+- Be traceable to specific papers.
+
+Write down your list of atomic definitions before proceeding. This ensures systematic coverage.
+
+### Phase 2: Paper Reading (per paper)
+
+For each paper in `workspace/papers/`:
+
+1. **Skim first**: Read title, abstract, introduction, and conclusion to understand the paper's scope.
+2. **Targeted reading**: For each atomic definition relevant to this paper, find:
+   - The formal definition (usually in a "Method" or "Approach" section).
+   - Mathematical formulas (equations, loss functions, update rules).
+   - Key theoretical claims or properties.
+3. **Search strategically**: Use keyword search within the .tex file. Look for `\begin{equation}`, `\mathcal`, `\text{loss}`, etc.
+
+### Phase 3: Code Reading (per repo)
+
+For each reference codebase in `workspace/repos/`:
+
+1. **Understand structure**: List the directory tree first.
+2. **Find implementations**: Map each mathematical formula to its code implementation:
+   - Model architecture classes → model definition formulas
+   - Loss function implementations → loss formulas
+   - Data processing pipelines → input/output specifications
+3. **Document the mapping**: For each formula, note the exact file, class, and function that implements it.
+
+### Phase 4: Write Notes
+
+For each paper, create `workspace/notes/paper_NNN.md` with this structure:
+
+```markdown
+# [Paper Title]
+ArXiv: [id] | Authors: [first author et al.]
+
+## Core Method
+[1-2 paragraph summary of the paper's main contribution]
+
+## Atomic Definitions Covered
+[List which atomic definitions from Phase 1 this paper addresses]
+
+## Math Formulas
+
+### [Definition Name 1]
+$$formula$$
+- Variables: [explain each variable]
+- Context: [when/where this is applied]
+
+### [Definition Name 2]
+...
+
+## Code Implementation
+
+### [Definition Name 1]
+- **Repo**: repos/[name]
+- **File**: path/to/file.py, class ClassName, method method_name
+- **Key logic**:
+```python
+# Excerpt of the most relevant 10-30 lines
+```
+- **Notes**: [any adaptations, simplifications, or deviations from the paper]
+
+## Key Insights
+- [Insight 1: anything surprising or important for implementation]
+- [Insight 2: ...]
+```
+
+### Phase 5: Synthesize
+
+After all papers are surveyed, write `workspace/survey_res.md`:
+
+```markdown
+# Literature Survey: [Research Idea]
+
+## Atomic Definitions
+[Complete list with brief descriptions]
+
+## Theory-to-Code Mapping
+[For each atomic definition: the formula, which papers define it, which repos implement it, and the recommended implementation approach]
+
+## Implementation Recommendations
+[Which reference implementations to adapt, potential pitfalls, suggested architecture]
+
+## Open Questions
+[Anything unclear that may need user input]
+```
+
+## Quality Criteria
+
+- Every atomic definition must appear in at least one paper note.
+- Every formula must have a corresponding code reference (or be flagged as "no reference found").
+- Do not skip papers. If a paper is not relevant, note why and move on.
+- Err on the side of extracting more detail rather than less. The implementation step depends on this survey.

package/skills/research-pipeline/references/workspace-spec.md

@@ -0,0 +1,81 @@
+# Workspace Directory Specification
+
+All research pipeline artifacts live in a `workspace/` directory. The location is either specified by the user or defaults to the current working directory plus `workspace/`.
+
+## Directory Layout
+
+```
+workspace/
+  task.json                 # Input: research task definition
+  search_results.md         # Step 2: arxiv + github search results
+  prepare_res.md            # Step 3: selected repos and rationale
+  survey_res.md             # Step 5: synthesized literature survey
+  plan_res.md               # Step 6: four-part implementation plan
+  ml_res.md                 # Step 7: implementation report
+  experiment_res.md         # Step 10: full training results
+
+  repos/                    # Step 3: cloned reference repositories
+    repo-name-1/
+    repo-name-2/
+
+  papers/                   # Step 4: downloaded paper sources
+    2401.12345.tex
+    2401.67890.tex
+
+  notes/                    # Step 5: per-paper survey notes
+    paper_001.md
+    paper_002.md
+
+  iterations/               # Steps 8-9: review history
+    judge_v1.md
+    judge_v2.md
+
+  project/                  # Step 7: implementation code
+    model/
+    data/
+    training/
+    testing/
+    utils/
+    run.py
+    requirements.txt
+```
+
+## Conventions
+
+### File Existence = Step Completion
+
+The research pipeline uses file existence as the checkpoint mechanism. Before executing any step, check whether its output file already exists. If it does, skip the step.
+
+This enables:
+- **Crash recovery**: resume from the last completed step.
+- **Incremental progress**: re-running the pipeline skips completed work.
+- **Transparency**: a human can inspect progress by listing the directory.
+
+### Naming Rules
+
+- Markdown files (`.md`) for human-readable outputs.
+- JSON files (`.json`) for structured data (task definition).
+- Paper notes use sequential numbering: `paper_001.md`, `paper_002.md`.
+- Review iterations use version numbering: `judge_v1.md`, `judge_v2.md`.
+
+### Immutability
+
+Once a step's output is written, do NOT modify it unless the user explicitly asks. If a step needs to be re-done, delete the output file first, then re-execute.
+
+Exception: `workspace/project/` is mutable during the implement-review-iterate loop (Steps 7-9).
+
+### task.json Schema
+
+```json
+{
+  "idea": "A 1-3 sentence description of the research idea",
+  "references": ["2401.12345", "paper title string"],
+  "domain": "recommendation systems",
+  "date_limit": "2024-01-01"
+}
+```
+
+- `idea` (required): The core research idea to implement.
+- `references` (optional): ArXiv IDs or paper titles as starting points.
+- `domain` (optional): Research domain for focused searching.
+- `date_limit` (optional): Only consider papers published after this date.