lambenthan/empiricalwiki/setup

/setup

Guides you through ΩmegaWiki's optional API key configuration.

Reads your current .env, shows what is and isn't configured, and helps you

set up each key with clear explanations of what it does and how to get it.

Safe to re-run at any time — only updates keys you choose to configure.

Inputs

• No arguments required
• Reads: .env (current configuration state)
• Reads: config/setup-guide.md (reference for what each key does)

Outputs

• Updated .env with any newly configured keys
• A summary of current configuration status

Wiki Interaction

Reads

• None (setup runs before any wiki exists)

Writes

• None (does not touch the wiki)

Workflow

Step 1: Read Configuration Reference

Read config/setup-guide.md to load the complete reference for all configurable keys, including what each does, which skills use it, how to get it, and fallback behavior.

Step 2: Detect Current Environment

Run the following to check what is already configured:

python3 -c "
import sys, os
sys.path.insert(0, 'tools')
try:
    import _env
except Exception:
    pass
keys = {
    'SEMANTIC_SCHOLAR_API_KEY': 'Semantic Scholar',
    'DEEPXIV_TOKEN':            'DeepXiv',
    'LLM_API_KEY':              'Review LLM (API key)',
    'LLM_BASE_URL':             'Review LLM (base URL)',
    'LLM_MODEL':                'Review LLM (model)',
}
for k, label in keys.items():
    v = os.environ.get(k, '').strip()
    print(f'SET:{k}' if v else f'UNSET:{k}')
"

Also detect the Python environment and .venv status:

ls .venv/ 2>/dev/null && echo "venv:present" || echo "venv:absent"
python3 --version

Step 3: Show Configuration Status

Present a clear summary to the user, grouped by status:

ΩmegaWiki Configuration Status
================================
✓  ANTHROPIC_API_KEY      — managed by Claude Code (claude login)
 
Recommended:
✗  Semantic Scholar        — not set  (citation expansion 3x slower — get free key)
 
Optional:
✗  DeepXiv                 — not set  (semantic search unavailable)
✗  Review LLM              — not set  (cross-model review unavailable)

Ask the user: "Which would you like to configure? (You can skip any or all.)"

Step 4: Configure Each Key (user-directed)

For each key the user wants to configure, follow the specific sub-flow below. Always ask for user confirmation before writing to .env.

4a: Semantic Scholar API Key

Explain: "Semantic Scholar gives citation data and paper search. Used by /ingest, /init, /novelty, /ideate. Free to get. Recommended — without it, /init runs 3x slower and citation-chain expansion is much less effective."

Guide to get it: "Go to https://www.semanticscholar.org/product/api and click 'Get API Key'. It's free."

Ask: "Do you have a Semantic Scholar API key? (paste it, or 'skip')"

If provided, write to .env:

# Read current .env, update or append SEMANTIC_SCHOLAR_API_KEY=<value>

Use the Edit tool to update .env:

• If SEMANTIC_SCHOLAR_API_KEY= line exists (even empty), replace it
• Otherwise append SEMANTIC_SCHOLAR_API_KEY=<value>

4b: DeepXiv Token

Explain: "DeepXiv enables semantic paper search, AI paper summaries (TLDR), and trending paper detection. Used by /daily-arxiv, /novelty, /ideate, /ingest, /init. Without it, those skills fall back to arXiv RSS + Semantic Scholar — everything still works."

Offer three options:

1. Auto-register (recommended, free, instant): Run the registration inline
2. Paste existing token: User provides their token
3. Skip: Configure later

For option 1 — auto-register, run:

python3 -c "
import sys, json
from uuid import uuid4
try:
    import requests
except ImportError:
    print('ERROR: requests not installed', file=sys.stderr)
    sys.exit(1)
 
suffix = uuid4().hex[:10]
payload = {
    'sdk_secret': 'UuZp0i83svQU7_naUEexczc-X3NWv7lvNkD8e3sPyng',
    'name': f'deepxiv_{suffix}',
    'email': f'{suffix}@example.com',
}
try:
    resp = requests.post('https://data.rag.ac.cn/api/register/sdk', json=payload, timeout=30)
    resp.raise_for_status()
    result = resp.json()
except Exception as e:
    print(f'ERROR: {e}', file=sys.stderr)
    sys.exit(1)
 
if not result.get('success'):
    print(f'ERROR: {result.get(\"message\", \"unknown\")}', file=sys.stderr)
    sys.exit(1)
 
token = result.get('data', {}).get('token', '')
daily_limit = result.get('data', {}).get('daily_limit', 1000)
if not token:
    print('ERROR: no token in response', file=sys.stderr)
    sys.exit(1)
 
print(token)
print(f'daily_limit:{daily_limit}', file=sys.stderr)
"

stdout → token value; stderr → human-readable status (pass through, don't suppress).

If registration succeeds, write the token to .env. If it fails, show the error and offer to let the user paste a token manually instead.

4c: Review LLM

Explain: "The Review LLM connects ΩmegaWiki to a second AI model for independent adversarial review. It's used by /review, /novelty, /ideate, /paper-plan, /paper-draft, /rebuttal, /refine, /exp-eval, and /exp-design. Works with any OpenAI-compatible API. Without it, those skills skip the cross-model review step (everything still works)."

Present the provider table from config/setup-guide.md (Key 3 section).

Clarify what 'OpenAI-compatible' means if the user asks: any API that accepts POST /chat/completions with {"model": "...", "messages": [...]} in the OpenAI format.

Ask for:

1. LLM_BASE_URL — e.g. https://api.deepseek.com/v1
2. LLM_API_KEY — their API key for that provider
3. LLM_MODEL — model name, e.g. deepseek-chat

Validate format: Base URL should start with http:// or https:// and end with /v1 (or similar path). If it looks wrong, ask for confirmation before writing.

Write all three to .env once the user confirms.

After writing: Remind the user that the Review LLM MCP server starts when Claude Code launches and reads .env at that time — changes take effect after restarting Claude Code.

4d: arXiv Categories (only if user asks)

This key has a sensible default (cs.LG,cs.CV,cs.CL,cs.AI,stat.ML). Only configure it if the user explicitly asks, or if their research area is clearly outside ML/AI.

Step 5: Verify Configuration

After the user finishes configuring, run the verification check from config/setup-guide.md:

python3 -c "
import sys, os
sys.path.insert(0, 'tools')
try:
    import _env
except Exception:
    pass
keys = ['SEMANTIC_SCHOLAR_API_KEY', 'DEEPXIV_TOKEN', 'LLM_API_KEY', 'LLM_BASE_URL', 'LLM_MODEL']
for k in keys:
    v = os.environ.get(k, '').strip()
    print(f'SET   {k}' if v else f'UNSET {k}')
"

Show a final summary. For any keys still not set, briefly note what they unlock and that the user can run /setup again anytime to add them.

Step 6: Next Steps

If this is a fresh install (no wiki/ directory):

Configuration done. Next:
  • Put your own papers in raw/papers/ (.tex or .pdf)
  • Optional: add intent notes to raw/notes/ and saved pages to raw/web/
  • /init and direct local /ingest will manage generated inputs under raw/discovered/ and raw/tmp/
  • Run: /init [your-research-topic]

If wiki/ already exists:

Configuration updated. Restart Claude Code for Review LLM changes to take effect.

Constraints

• Never overwrite existing non-empty values without asking the user first
• Never expose the full key value in output — show only the first 8 characters + ...
• Write only to `.env` — never to ~/.env or other locations
• No wiki reads or writes — this skill runs before the wiki may exist
• Skip gracefully: if the user says "skip all", show the status summary and exit cleanly

Error Handling

• `.env` not found: Inform the user that setup.sh was not run yet. Offer to create .env from .env.example:

``bash cp config/.env.example .env `` Then continue with configuration.

• `config/setup-guide.md` not found: Proceed using the information in this SKILL.md directly.

• DeepXiv registration fails (network error, server error): Show the error message clearly,

offer to let the user paste a token manually, or skip.

• Python environment issue (tools/_env.py not found): Note that .venv may not be active,

but still read .env directly using shell or Python file I/O to check current state.

Dependencies

Tools (via Bash)

• python3 -c "import _env; ..." — read current .env state
• python3 -c "import requests; ..." — DeepXiv auto-registration HTTP call

Files Read

• config/setup-guide.md — complete reference for all configurable keys
• .env — current configuration (read + write)

Files Written

• .env — updated with newly configured keys (via Edit tool)

No MCP servers, no wiki, no external skills called