---
name: setup
description: Interactive configuration wizard for Ada. Use when the user says "setup", "configure", "settings", "set up my environment", or asks how to connect Zotero, Docker, Modal, API keys, Python environment, or any integration. Walks through each configuration step conversationally, letting the user skip what they don't need.
---

# Ada Setup Wizard

Walk the user through configuring Ada step by step. Present each section, let them configure or skip. Check current status before asking.

## How to run this

When the user triggers setup, present a summary of what can be configured, then go through each section. For each:
1. Check if it's already configured
2. Show current status
3. Ask if they want to configure/change it
4. If yes, guide them through it
5. If no, skip to next

## Sections

### 1. AI Model (required)

Check: `ada model list`

If no model is set:
- Run `ada model login <provider>` for OAuth providers (Anthropic, OpenAI, Google)
- Or ask for an API key and set it in `.env`

Guide:
```
Which AI provider do you use?
1. Anthropic (Claude) — recommended for research
2. OpenAI (GPT)
3. Google (Gemini)
4. Other (via OpenRouter)
```

### 2. Python Environment

Check: `which python3` and `python3 --version`

Options to present:
- **System Python** — use the default Python on the machine
- **Virtual environment** — create a `.venv` in the current project
- **Conda** — use an existing conda environment
- **uv** — use uv for fast Python package management

If they choose venv:
```bash
python3 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
```

If they choose uv:
```bash
pip install uv
uv venv .venv
source .venv/bin/activate
```

Store their preference by noting it in the conversation. Ada will use this for future Python execution.

### 3. Docker

Check: `docker --version`

If not installed, suggest:
- macOS: `brew install --cask docker`
- Linux: `curl -fsSL https://get.docker.com | sh`
- Windows: Download Docker Desktop

If installed, test it works:
```bash
docker run --rm hello-world
```

Explain: Docker is used for running untrusted code from papers safely. Optional but recommended for `/replicate` and `/autoresearch`.

### 4. AlphaXiv (paper search)

Check: Run `alpha status` via bash

If not logged in, guide them:
```bash
npx alpha login
```

Explain: AlphaXiv provides paper search, Q&A, code reading, and annotations. Free account.

### 5. Web Search (Tavily)

Check: `echo $TAVILY_API_KEY`

If not set:
- Get a key at https://tavily.com (free tier available)
- Add to `.env`: `TAVILY_API_KEY=your_key`

Explain: Enables web search for current events, products, and non-academic queries. Ada falls back to pi-web-access if unset.

### 6. Semantic Scholar

Check: `echo $S2_API_KEY`

If not set:
- Get a key at https://www.semanticscholar.org/product/api (free)
- Add to `.env`: `S2_API_KEY=your_key`
- Works without a key but with lower rate limits

Explain: Enables citation graph traversal and paper recommendations across 200M+ papers.

### 7. OpenAlex

Check: `echo $OPENALEX_API_KEY`

If not set:
- Get a key at https://openalex.org/users/me
- Add to `.env`: `OPENALEX_API_KEY=your_key`

Explain: Access to 240M+ scholarly works for bibliometric analysis and literature search.

### 8. Zotero (citation library)

Check: `echo $ZOTERO_API_KEY`

If not set:
- Get credentials at https://www.zotero.org/settings/keys
- Add to `.env`:
  ```
  ZOTERO_LIBRARY_ID=your_user_id
  ZOTERO_API_KEY=your_api_key
  ZOTERO_LIBRARY_TYPE=user
  ```

Explain: Connects Ada to your Zotero library for citation management, reference export, and bibliography generation.

### 9. Modal (cloud GPU)

Check: `echo $MODAL_TOKEN_ID`

If not set:
- Sign up at https://modal.com
- Run `pip install modal && modal setup`
- Add to `.env`:
  ```
  MODAL_TOKEN_ID=your_id
  MODAL_TOKEN_SECRET=your_secret
  ```

Explain: Runs heavy compute (ML training, simulations) on cloud GPUs. Only needed for `/replicate` with GPU workloads.

### 10. RunPod (persistent GPU)

Check: `echo $RUNPOD_API_KEY`

If not set:
- Sign up at https://runpod.io
- Add to `.env`: `RUNPOD_API_KEY=your_key`

Explain: Persistent GPU pods with SSH access. For long-running experiments that need dedicated hardware.

### 11. OpenRouter (AI image generation)

Check: `echo $OPENROUTER_API_KEY`

If not set:
- Get a key at https://openrouter.ai/keys
- Add to `.env`: `OPENROUTER_API_KEY=your_key`

Explain: Used by the scientific-schematics skill for AI-generated diagrams and figures. Also provides access to 100+ AI models as fallback.

### 12. LaTeX

Check: `which pdflatex`

If not installed:
- macOS: `brew install --cask mactex` (4GB, takes a few minutes)
- Linux: `sudo apt install texlive-full`
- Windows: Download MiKTeX from https://miktex.org

Explain: Required for generating papers, posters, and LaTeX documents. The `writing` and `latex-posters` skills need this.

### 13. Pandoc

Check: `which pandoc`

If not installed:
- macOS: `brew install pandoc`
- Linux: `sudo apt install pandoc`

Explain: Document conversion (markdown to PDF, DOCX, etc.) and the `/preview` command.

## After setup

Show a summary:
```
Ada Configuration Summary
─────────────────────────
Model:           anthropic/claude-opus-4-6 ✓
Python:          3.11 (venv) ✓
Docker:          24.0.7 ✓
AlphaXiv:        logged in ✓
Web Search:      Tavily ✓
Semantic Scholar: configured ✓
OpenAlex:        not configured ✗ (optional)
Zotero:          not configured ✗ (optional)
Modal:           not configured ✗ (optional)
RunPod:          not configured ✗ (optional)
OpenRouter:      not configured ✗ (optional)
LaTeX:           installed ✓
Pandoc:          installed ✓
```

Tell the user:
- "Your global config lives in `~/.ada/.env` — works from any folder."
- "To override for a specific project, add a `.env` in that project's directory."
- "You can re-run this anytime by typing 'setup' or 'configure my environment'."