| name | aminer-deep-search |
| version | 1.0.0 |
| author | AMiner |
| contact | report@aminer.cn |
| description | Activate this skill when the user wants deep, multi-round academic paper collection for a survey or literature review using AMiner data and a ReAct-style LLM controller. Use this skill for broad topic exploration, survey bibliography construction, automatic keyword search plus backward-reference snowballing, and collecting hundreds of candidate papers with AMiner IDs and titles. This skill calls an OpenAI-compatible chat model to decide tool calls, and uses AMiner keyword search plus paper reference APIs as tools. It is not intended for simple single-paper lookup or lightweight recommendations; use aminer-free-academic or aminer-daily-paper for those simpler tasks.
|
| metadata | {"openclaw":{"requires":{"bins":["python3"],"env":["AMINER_API_KEY"]},"primaryEnv":"AMINER_API_KEY"}} |
AMiner Deep Search
ReAct-style survey paper collection using OpenAI-compatible model calls and AMiner search/reference APIs.
Use this skill when the user asks to collect papers for a research topic, build a large literature list, run citation snowballing, or prepare survey references.
What This Skill Does
The framework runs an LLM-controlled loop with these tools:
search: AMiner keyword search, returning up to 20 papers per query.get_reference: AMiner backward-reference expansion for selected seed papers.add_to_paper_set: deduplicated paper collection by AMiner paper ID.END: terminate and output [{"id": "...", "title": "..."}, ...].
The controller prompt asks the model to expand queries, prioritize high-quality seed papers, use reference snowballing, and terminate within 50 rounds. The target collection size is 400+ papers when AMiner results support it; it must not fabricate papers.
Required Environment Variables
Check the AMiner key before running:
[ -z "${AMINER_API_KEY:-}" ] && echo "AMINER_API_KEY missing" || echo "AMINER_API_KEY exists"
If AMINER_API_KEY is missing, stop and ask the user to provide or set it. Never print the key. The code does not contain a built-in AMiner token.
LLM Configuration
The LLM can use OpenClaw-provided settings or a user-provided OpenAI-compatible endpoint. The skill reads the following environment variables (the underscore-style names are recommended; the dotted legacy names are still accepted for backward compatibility):
LLM_API_KEY (legacy: llm.api_key): LLM API key. Check at runtime and prompt if neither OpenClaw nor the user supplies a key.LLM_BASE_URL (legacy: llm.base_url): LLM base URL. Optional when OpenClaw provides a default; otherwise pass --base-url.LLM_MODEL (legacy: llm.model): LLM model name. Required unless --models is passed.
Underscore-style names are recommended because POSIX shells (bash/zsh) do not allow . in variable names, so export llm.api_key=... will fail with not a valid identifier. Use the underscore names with export, or fall back to env "llm.api_key=..." python ... for the legacy names.
Before running, check whether an LLM key is available:
if [ -z "${LLM_API_KEY:-$(printenv 'llm.api_key')}" ]; then
echo "LLM API key missing"
else
echo "LLM API key exists"
fi
If no LLM key is available, stop and ask the user to set LLM_API_KEY (or legacy llm.api_key), or pass --api-key. Never print the key. Do not hard-code provider-specific tokens or base URLs in this skill.
Check whether an LLM model is available:
[ -z "${LLM_MODEL:-$(printenv 'llm.model')}" ] && echo "LLM model missing" || echo "LLM model exists"
If no LLM model is available, ask the user to set LLM_MODEL (or legacy llm.model), or pass --models. There is no provider-specific default model list.
Quick setup examples
export LLM_API_KEY="sk-xxx"
export LLM_BASE_URL="https://api.deepseek.com/v1"
export LLM_MODEL="deepseek-chat"
export AMINER_API_KEY="xxx"
python3 react_agent.py --topic "your research topic"
env "llm.api_key=sk-xxx" \
"llm.base_url=https://api.deepseek.com/v1" \
"llm.model=deepseek-chat" \
"AMINER_API_KEY=xxx" \
python3 react_agent.py --topic "your research topic"
Environment Setup
From this skill directory, install dependencies into the Python environment used by python3:
python3 -m pip install -r requirements.txt
If you prefer an isolated conda environment, create and activate one first, then install the dependencies:
CONDA_PKGS_DIRS="$(pwd)/.conda_pkgs" conda create -p "$(pwd)/.conda" python=3.11 pip -y
conda activate "$(pwd)/.conda"
PIP_CACHE_DIR="$(pwd)/.pip_cache" python3 -m pip install -r requirements.txt
Any compatible Python 3 environment may run the script as long as it has openai and requests.
Execution
Run the main collector from this skill directory:
python3 react_agent.py \
--topic "<research topic>" \
--timeout 300 \
--max-tool-calls 20 \
--max-rounds 50
Useful options:
--api-key: LLM API key. Defaults to LLM_API_KEY (legacy: llm.api_key).--base-url: LLM base URL. Defaults to LLM_BASE_URL (legacy: llm.base_url).--models: model fallback list. Required unless LLM_MODEL (legacy: llm.model) is configured.--timeout: per-model-call timeout in seconds. Default is 300.--target-size: desired final paper count. Default is 400.--include-abstracts: include abstracts in the final saved JSON when available.
The script prints the final JSON list and saves a copy under outputs/.
Operating Rules
- Use this skill only for deep collection workflows. For one-off lookup or normal AMiner Q&A, route to the simpler AMiner skills.
- Do not expose
LLM_API_KEY (legacy llm.api_key) or AMINER_API_KEY.
- Keep model/tool-call budgets under control; default
--max-tool-calls 20 and --max-rounds 50.
- If AMiner returns too few papers, report the actual collected count instead of inventing missing papers.
- If a run is likely to be expensive or long, tell the user the planned topic, model, timeout, max tool calls, and output location before starting.
File Map
react_agent.py: ReAct loop and CLI.api_client.py: OpenAI-compatible client with model fallback.prompt.py: paper-collection system prompt.search.py: AMiner keyword search and paper detail normalization.citation.py: AMiner reference expansion.paper_set.py: deduplicated collection and final JSON output.
