---
name: sciatlas-researcher
description: Integration with SciAtlas — large-scale scientific knowledge graph (43M papers, 157M entities, 3B triplets). Install, configure, search, and generate literature reviews via Python SDK.
---

# SciAtlas Researcher

Интеграция с [SciAtlas](https://arxiv.org/abs/2605.22878) — hosted knowledge graph for automated scientific research.

## Установка (Mac без Xcode)

```bash
# Xcode/git отсутствует на этом Mac — pip install из git:// не работает
# Решение: скачать tarball и установить локально
curl -sL "https://github.com/zjunlp/SciAtlas/archive/main.tar.gz" -o /tmp/sciatlas.tar.gz
tar -xzf /tmp/sciatlas.tar.gz -C /tmp/
python3 -m pip install /tmp/SciAtlas-main/sciatlas
```

SciAtlas устанавливается в активный venv. На этой системе — Hermes venv (`~/.hermes/hermes-agent/.venv`), НЕ system Python.

**Важно:** `execute_code` sandbox не видит модуль. Только terminal() с полным путём:
```bash
~/.hermes/hermes-agent/.venv/bin/python3 -c "..."
```

## Регистрация API-токена

1. Открыть http://scinet.openkg.cn/register
2. Заполнить name, email → Send code
3. Проверить почту, ввести 6-значный код
4. Указать organization и use case
5. Нажать Create token
6. Сохранить токен (формат `scinet_xxx`, показывается один раз)

**Внимание:** на форме регистрации баг — поле `email_code` может получить email вместо кода. Если ошибка — перезаполнить, убедившись что фокус на поле кода.

## Настройка

```bash
export SCIATLAS_API_BASE_URL="http://scinet.openkg.cn"
export SCIATLAS_API_KEY="***"
export SCIATLAS_TIMEOUT=300
export SCIATLAS_RUNS_DIR=~/sciatlas_runs
```

Проверка:
```bash
sciatlas health
sciatlas config
```

## Использование Python SDK (рекомендуется вместо CLI)

CLI (`sciatlas search-papers`) стабильно таймаутится. Использовать Python SDK.

```python
import os
os.environ['SCIATLAS_API_BASE_URL'] = 'http://scinet.openkg.cn'
os.environ['SCIATLAS_API_KEY'] = '***'

from sciatlas import SciAtlasClient
client = SciAtlasClient(timeout=300)

# Проверка статуса
print(client.token_status())

# Поиск статей
result = client.search_papers(
    query='variational design engineering systems',
    keywords=[{'text': 'variational principles', 'score': 10}],
    top_k=5,
    retrieval_mode='hybrid',
)

for p in result['result']['sources']['kg']['papers']:
    print(f"[{p['rank']}] {p['title']} ({p['publication_year']}) — {p['score']}")
    print(f"    URL: {p['paper_url']}")
```

### One-liner для быстрого поиска

```bash
source ~/.sciatlas.env && ~/.hermes/hermes-agent/.venv/bin/python3 -c "
from sciatlas import SciAtlasClient
client = SciAtlasClient(timeout=300)
r = client.search_papers(query='<topic>', keywords=[{'text':'<kw>','score':10}], top_k=5)
for p in r['result']['sources']['kg']['papers']:
    print(f\"[{p['rank']}] {p['title']} ({p['publication_year']}) — {p['score']}\")
    print(f\"    {p['paper_url']}")
"
```

### Парсинг результата (структура response)

```python
# Полный путь:
result['result']['sources']['kg']['papers']  # список статей

# Поля каждой статьи:
p['title']              # название
p['publication_year']   # год
p['score']              # релевантность 0-1
p['paper_url']          # OpenAlex URL
p['cited_by_count']     # цитирования
p['paper']['has_abstract']  # есть ли абстракт
p['paper']['type']      # dissertation/article/etc
p['match_type']         # kg_graph / keyword / semantic
```

## Стратегия работы с нестабильным API

API `/v1/search` ненадёжен — частые таймауты >300с. Эвристики:
1. **Один keyword, top_k ≤ 5** — работает чаще всего
2. **Несколько keywords** — почти всегда таймаут. Вместо одного сложного запроса делать 2-3 простых (по одному keyword) и объединять результаты
3. Если запрос упал — retry c более простыми параметрами
4. Сохранять успешные результаты сразу

## API structure

Поисковый endpoint: `POST /v1/search`
- Body: `{"plan": {...}, "options": {...}}`
- `plan`: `query_text`, `source_type`, `keywords` (list of `{text, score}`), `titles`, `reference_titles`
- `options`: `top_k`, `retrieval_mode` (hybrid/semantic/keyword/title)

**Важно:** опции `top_keywords`, `max_titles`, `max_refs` — CLI-only, API не принимает (400 Bad Request).

## Проверка статуса токена

```bash
source ~/.sciatlas.env
curl -H "Authorization: Bearer $SCIAT...KEY" http://scinet.openkg.cn/v1/auth/token/status
```

Токен активен, дневной лимит 10000 запросов.

## Config file

Токен сохранён в `~/.sciatlas.env` (source-able):
```bash
source ~/.sciatlas.env && ~/.hermes/hermes-agent/.venv/bin/python3 -c "..."
```

## Известные проблемы

1. **CLI таймаутится** — используй Python SDK через venv python
2. **SDK таймаутится** — API нестабилен. Стратегия: несколько простых запросов вместо одного сложного
3. **execute_code не видит модуль** — sciatlas в Hermes venv. Только terminal() с полным путём
4. **`top_keywords`, `max_titles`, `max_refs`** — CLI-only, API не принимает (400)
5. **OpenAlex ключ не обязателен** — для базового поиска хватает SCIATLAS_API_KEY
6. **Регистрация под багом** — email_code может получить email вместо кода

## Референс: Agent Skills Spec

Формат скиллов следует [Agent Skills specification](https://agentskills.io/specification.md). YAML frontmatter с name/description, SKILL.md < 500 строк, references/ для деталей.

Референс по структуре — [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) (30k ⭐, 30+ скиллов, MIT).

## Доступные воркфлоу (CLI)

| Команда | Назначение |
|---------|-----------|
| `sciatlas search-papers` | Поиск статей |
| `sciatlas literature-review` | Обзор литературы |
| `sciatlas idea-grounding` | Привязка идеи к работам |
| `sciatlas idea-evaluate` | Оценка новизны |
| `sciatlas idea-generate` | Генерация идей |
| `sciatlas trend-report` | Анализ трендов |
| `sciatlas researcher-review` | Профиль исследователя |
| `sciatlas related-authors` | Поиск авторов |
