---
name: tsinghua-fib-lab/easypaper-setup-environment
source: https://app.decimal.ai/s/tsinghua-fib-lab-easypaper-setup-environment@1/SKILL.md
source_sha256: c0484a9f4915
---

Use this skill when the plugin is first installed or when environment setup is needed.

## Setup Workflow

### 1. Check Python Environment

- Detect if `uv` is available (preferred) or `python`/`python3`
- If `uv` is available, use it to create an isolated virtual environment
- If not, check for `venv` or `virtualenv` and create a virtual environment
- Environment should be created in a project-local directory (e.g., `.venv` or `.easypaper-env`)

### 2. Install EasyPaper Package

- If `uv` is available:
  ```bash
  uv venv .easypaper-env
  source .easypaper-env/bin/activate  # or .easypaper-env/Scripts/activate on Windows
  uv pip install -e .  # if in repo root
  # OR
  uv pip install easypaper[server]  # if installing from PyPI
  ```
- If using standard Python:
  ```bash
  python -m venv .easypaper-env
  source .easypaper-env/bin/activate
  pip install -e .  # or pip install easypaper[server]
  ```

### 3. Check LaTeX Installation

- Check for LaTeX distribution:
  - On macOS: Check for `pdflatex` command, suggest `brew install --cask mactex` or `brew install basictex`
  - On Linux: Check for `pdflatex`, suggest `sudo apt-get install texlive-full` or `texlive-base`
  - On Windows: Check for `pdflatex`, suggest installing MiKTeX or TeX Live
- Verify installation by running: `pdflatex --version`
- If not installed, provide clear installation instructions for the user's OS

### 4. Create or Validate Configuration

- Check for an existing EasyPaper YAML config in this order:
  - User-provided path in the conversation
  - `AGENT_CONFIG_PATH`
  - `./easypaper_config.yaml`
  - `./configs/openrouter.yaml`
  - `./configs/example.yaml`
- If no usable config exists, create `./easypaper_config.yaml` from the bundled
  sibling template file `config.example.yaml`.
- The bundled `config.example.yaml` must stay byte-for-byte synchronized with
  the repository source template `configs/example.yaml`; do not hand-write a
  partial config in this skill.
- After creating the file, ask the user for the required LLM API key/provider
  value and replace only the placeholder values they explicitly provide
  (for example `YOUR_OPENROUTER_KEY`). Do not invent credentials.
- Keep the generated config path explicit for later SDK calls, either by using
  `EasyPaper(config_path="<absolute path to easypaper_config.yaml>")` or by
  setting `AGENT_CONFIG_PATH` for commands that call `load_config()`.
- The template enables the skills system. Users do not need a local `./skills`
  folder: EasyPaper loads packaged built-in skills first, then overlays user
  skills from `skills_dir` when that directory exists.

### 5. Verify Setup

- Test EasyPaper import: `python -c "import easypaper; from easypaper import EasyPaper, PaperMetaData; print('EasyPaper imported successfully')"`
- Test LaTeX: `pdflatex --version`
- Test config parsing when a config path exists:
  `python -c "from easypaper import EasyPaper; EasyPaper(config_path='easypaper_config.yaml'); print('EasyPaper config loaded successfully')"`

### 6. Create Environment Activation Script

Create a helper script (`.easypaper-activate.sh` or `.easypaper-activate.bat`) that:
- Activates the virtual environment
- Sets up PATH if needed
- Provides instructions for using EasyPaper as Python SDK
- Exports `AGENT_CONFIG_PATH` to the generated config path when practical

## Error Handling

- If Python version < 3.11, inform user and suggest upgrade
- If package installation fails, show error and suggest manual installation
- If LaTeX is missing, provide OS-specific installation commands
- If the config template file is missing from the installed skill directory,
  report the plugin installation as incomplete and ask the user to reinstall
  the EasyPaper Claude Code plugin.
- Always verify each step before proceeding to the next

## Post-Setup Instructions

After successful setup, inform the user:
1. Environment is ready in `.easypaper-env`
2. To activate: `source .easypaper-env/bin/activate` (or equivalent for Windows)
3. EasyPaper can now be used directly as a Python SDK: `from easypaper import EasyPaper, PaperMetaData`
4. The environment is isolated and won't affect system Python
5. The active config file path, normally `./easypaper_config.yaml`