# Installation Guide

This guide covers all the ways to install and set up OCLAWMA.

## Table of Contents

- [Requirements](#requirements)
- [Install from PyPI](#install-from-pypi)
- [Install from Source](#install-from-source)
- [Development Installation](#development-installation)
- [Provider Setup](#provider-setup)
- [Verification](#verification)
- [Troubleshooting](#troubleshooting)

## Requirements

- Python 3.9 or higher
- pip (Python package installer)
- For local models: [Ollama](https://ollama.com)

## Install from PyPI

The simplest way to install OCLAWMA:

```bash
pip install oclawma
```

With optional development dependencies:

```bash
pip install oclawma[dev]
```

## Install from Source

For the latest development version:

```bash
# Clone the repository
git clone https://github.com/openclaw/oclawma.git
cd oclawma

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"
```

## Development Installation

For contributing to OCLAWMA:

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/oclawma.git
cd oclawma

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install with all dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pre-commit install
```

### Development Tools

The development installation includes:

- **pytest**: Testing framework
- **black**: Code formatting
- **ruff**: Fast Python linter
- **mypy**: Static type checking
- **pytest-cov**: Coverage reporting

## Provider Setup

### Ollama (Local Models)

1. Install Ollama from [ollama.com](https://ollama.com)

2. Pull a model:
   ```bash
   ollama pull qwen2.5:3b
   ```

3. Verify Ollama is running:
   ```bash
   ollama list
   ```

4. Run OCLAWMA:
   ```bash
   oclawma run
   ```

### Kimi (Cloud Provider)

1. Get your API key from [kimi.com](https://kimi.com)

2. Set the environment variable:
   ```bash
   export KIMI_API_KEY="your-api-key"
   ```

   Or add to your `~/.bashrc` or `~/.zshrc`:
   ```bash
   echo 'export KIMI_API_KEY="your-api-key"' >> ~/.bashrc
   ```

3. Run with Kimi provider:
   ```bash
   oclawma run --provider kimi --model k2.5
   ```

### Auto Provider (Recommended)

The auto provider uses Ollama locally with automatic fallback to Kimi for large contexts:

```bash
# Set both Ollama and Kimi credentials
export KIMI_API_KEY="your-api-key"

# Run with auto provider
oclawma run --provider auto
```

## Verification

Verify your installation:

```bash
# Check version
oclawma --version

# Show system status
oclawma status

# Run a test session
echo "Hello" | oclawma run
```

Expected output:
```
oclawma, version 0.1.0
System: OK
Provider: ollama
```

## Troubleshooting

### Ollama Connection Issues

**Problem**: `ConnectionError: Cannot connect to Ollama`

**Solution**:
```bash
# Check if Ollama is running
ollama serve

# Or start Ollama in the background
ollama serve &

# Verify connection
ollama list
```

### Kimi Authentication Errors

**Problem**: `AuthenticationError: Invalid API key`

**Solution**:
```bash
# Verify API key is set
echo $KIMI_API_KEY

# Set it again
export KIMI_API_KEY="your-api-key"

# Test with a simple request
oclawma run --provider kimi --model k2.5
```

### Python Version Issues

**Problem**: `requires-python: ">=3.9"`

**Solution**:
```bash
# Check Python version
python --version

# Install Python 3.9+ if needed
# On Ubuntu/Debian:
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-pip

# Use specific Python version
python3.10 -m pip install oclawma
```

### Permission Denied

**Problem**: `Permission denied when installing`

**Solution**:
```bash
# Use --user flag
pip install --user oclawma

# Or use a virtual environment
python -m venv venv
source venv/bin/activate
pip install oclawma
```

### Import Errors

**Problem**: `ModuleNotFoundError: No module named 'oclawma'`

**Solution**:
```bash
# Reinstall in development mode
pip uninstall oclawma
pip install -e ".[dev]"

# Verify installation
python -c "import oclawma; print(oclawma.__file__)"
```

## Next Steps

- Read the [Configuration Guide](configuration.md) for advanced settings
- Learn to [create skills](skill-development.md)
- Explore the [Architecture Overview](architecture.md)
