SkillOpt/docs/guide/installation.md

Installation

Requirements

• Python ≥ 3.10
• For research training/evaluation, access to at least one configured model backend (hosted API, local server, or an installed execution CLI)
• The SkillOpt-Sleep mock backend needs no credentials

Choose an Install

PyPI

Use PyPI for the Python packages and installed commands:

python -m pip install skillopt
skillopt-sleep --help

This installs skillopt-train, skillopt-eval, and skillopt-sleep. The wheel does not include the repository's benchmark configs, data materializers, agent-integration shells/MCP servers, or development tests; use a source checkout for those files.

!!! important "PyPI versus main" These docs track the latest main. The current PyPI release is 0.2.0. The generic research openai_compatible backend, SkillOpt-Sleep handoff, Sleep support for non-Azure OpenAI-compatible endpoints, and the Sleep --preferences flag landed after that release and require a source install from main until the next release.

Source checkout

git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
python -m pip install -e .

Use the source checkout for paper reproduction, built-in benchmark configs, and contributions.

Optional Dependencies

Install extras for specific benchmarks or backends:

=== "ALFWorld"

```bash
python -m pip install -e ".[alfworld]"
```

=== "Claude agent SDK (optional)"

```bash
python -m pip install -e ".[claude]"
```

This extra does not install the `claude` executable. The research
`claude_chat` backend launches `claude -p`, so install and authenticate the
Claude Code CLI separately. The SDK extra is only needed when selecting an
SDK-backed Claude Code exec path.

=== "Qwen (Local)"

```bash
python -m pip install -e ".[qwen]"
```

=== "SearchQA data"

```bash
python -m pip install -e ".[searchqa]"
```

=== "WebUI"

```bash
python -m pip install -e ".[webui]"
```

=== "Development"

```bash
python -m pip install -e ".[dev]"
```

=== "All"

```bash
python -m pip install -e ".[alfworld,claude,qwen,searchqa,webui,docs,dev]"
```

Environment Variables

From a source checkout, copy the template and fill in only the backend you will use:

cp .env.example .env

SkillOpt does not automatically load .env; export it into the current shell before running commands:

set -a
source .env
set +a

For Azure OpenAI with API-key authentication, the minimum settings are:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-12-01-preview
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_AUTH_MODE=api_key

Use AZURE_OPENAI_AUTH_MODE=azure_cli for Azure CLI credentials, or managed_identity with an optional AZURE_OPENAI_MANAGED_IDENTITY_CLIENT_ID.

The research claude_chat backend is a Claude Code CLI adapter, not a direct Anthropic API client. Install and authenticate claude, and set CLAUDE_CLI_BIN only if the executable is not available as claude on PATH. ANTHROPIC_API_KEY is one authentication option the CLI may consume.

OpenAI-compatible servers have three distinct entry points:

1. The research engine's generic openai_compatible backend uses OPENAI_COMPATIBLE_BASE_URL, OPENAI_COMPATIBLE_API_KEY, and OPENAI_COMPATIBLE_MODEL.
2. The research openai_chat backend can use AZURE_OPENAI_AUTH_MODE=openai_compatible with AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY.
3. SkillOpt-Sleep uses the same Azure-family variables as item 2 with skillopt-sleep run --backend azure_openai.

For research train/eval commands, model.optimizer and model.target in the YAML config are applied after backend initialization. They override model-name environment variables such as OPENAI_COMPATIBLE_MODEL and QWEN_CHAT_MODEL; set both role models explicitly when selecting those backends.

!!! tip You only need to configure the backend you plan to use. See Configuration for exact backend names and role-specific overrides.

Verify Installation

python -c "import skillopt; print('SkillOpt ready!')"
skillopt-train --help
skillopt-eval --help
skillopt-sleep --help

Next Steps

→ Run your first experiment