# Profiles

Profiles are named LLM configurations that define how you connect to AI providers. Each profile specifies the provider, model, API key, and parameters like temperature and max tokens.

## Why Profiles

Profiles let you switch between different AI setups without editing config files:

```bash
kollab --profile work    # Enterprise Azure OpenAI
kollab --profile local   # Ollama on your machine
kollab --profile cheap   # Gemini Flash for quick tasks
```

## Environment Variable Pattern

Create profiles entirely from environment variables using the pattern:

```bash
KOLLABOR_{NAME}_{FIELD}=value
```

When an env var like `OPENAI_API_KEY` is set, you can reference it with:
```bash
export KOLLABOR_WORK_PROVIDER=openai
export KOLLABOR_WORK_API_KEY=$OPENAI_API_KEY
kollab --profile work
```

### Disabling Auto-Detection

Auto-detection is not implemented. Set profiles manually via env vars or config.

## The 'auto' Provider

Set `provider` to `auto` to let Kollabor pick the best available provider based on your API keys:

```bash
KOLLABOR_MYPROFILE_PROVIDER=auto
KOLLABOR_MYPROFILE_API_KEY=sk-ant-...
```

Detection order:
1. Anthropic (keys starting with `sk-ant-`)
2. OpenAI (keys starting with `sk-`)
3. Falls back to OpenAI if unknown format

## Profile Command

The `/profile` command (aliases: `/prof`, `/llm`) manages profiles interactively:

```
/profile list                    # List all profiles with details
/profile set <name>              # Switch active profile
/profile create                  # Create new profile (interactive wizard)
```

note: `show` and `delete` subcommands are not implemented.

### Creating Profiles Interactively

```
/profile create
```

Prompts you for:
1. Profile name (e.g., `work-azure`)
2. Provider (auto, openai, anthropic, azure_openai, gemini, openrouter, custom)
3. API key (masked input, shown as `sk-...-xyz`)
4. Model name
5. Temperature (0.0-2.0)
6. Max tokens
7. Base URL (for custom providers)
8. Organization ID (OpenAI only)

After basic setup, you can configure advanced settings:
- Description
- Timeout (milliseconds, 0 = no timeout)
- Tool calling support
- Streaming enabled

## Environment Variable Pattern

Create profiles entirely from environment variables using the pattern:

```bash
KOLLABOR_{NAME}_{FIELD}=value
```

### Valid Fields

| Field | Description | Example |
|-------|-------------|---------|
| `PROVIDER` | Provider type | `anthropic`, `openai`, `custom`, `azure_openai`, `gemini`, `openai_responses`, `openrouter` |
| `MODEL` | Model identifier | `claude-opus-4-6`, `gpt-4` |
| `API_KEY` | Authentication key | `sk-ant-...` |
| `BASE_URL` | Custom endpoint | `http://localhost:11434/v1` |
| `TEMPERATURE` | Sampling randomness | `0.7` (0.0-2.0) |
| `MAX_TOKENS` | Response length limit | `4096` |
| `TIMEOUT` | Request timeout | `30000` (milliseconds, 0 = none) |
| `TOP_P` | Nucleus sampling | `0.9` (0.0-1.0) |
| `STREAMING` | Stream responses | `true` / `false` |
| `SUPPORTS_TOOLS` | Enable tool calling | `true` / `false` |

### Examples

#### Anthropic Claude (work)
```bash
export KOLLABOR_WORK_PROVIDER=anthropic
export KOLLABOR_WORK_API_KEY=sk-ant-...
export KOLLABOR_WORK_MODEL=claude-opus-4-6
export KOLLABOR_WORK_TEMPERATURE=0.5

kollab --profile work
```

#### Local Ollama
```bash
export KOLLABOR_LOCAL_PROVIDER=custom
export KOLLABOR_LOCAL_BASE_URL=http://localhost:11434/v1
export KOLLABOR_LOCAL_MODEL=llama3.3
export KOLLABOR_LOCAL_API_KEY=  # Empty for local

kollab --profile local
```

#### Azure OpenAI (enterprise)
```bash
export KOLLABOR_ENTERPRISE_PROVIDER=azure_openai
export KOLLABOR_ENTERPRISE_API_KEY=...
export KOLLABOR_ENTERPRISE_MODEL=gpt-5.2
export KOLLABOR_ENTERPRISE_BASE_URL=https://your-resource.openai.azure.com
export KOLLABOR_ENTERPRISE_API_VERSION=2025-01-01-preview

kollab --profile enterprise
```

### Global Overrides

Set `KOLLABOR_{FIELD}` (without profile name) to override any active profile:

```bash
export KOLLABOR_MODEL=claude-opus-4-6   # Overrides model for all profiles
export KOLLABOR_TEMPERATURE=0.3        # Overrides temperature
```

## Profile Priority

Values resolve in this order (highest to lowest):

1. `KOLLABOR_{PROFILE_NAME}_{FIELD}` - Profile-specific env var
2. `KOLLABOR_{FIELD}` - Global env var override
3. Config file value (`config.json`)
4. Default value

Example for model field with profile named `work`:
1. `KOLLABOR_WORK_MODEL` (checked first)
2. `KOLLABOR_MODEL` (checked second)
3. `config.json` work.profile.model
4. Default model for provider

## Saving Profiles

### Save to Global Config
```bash
/profile create
# ... fill in wizard ...
kollab --profile work    # Profile saved to ~/.kollabor-cli/config.json
```

### Save to Project Config
```bash
/profile create --local
# Profile saved to .kollabor-cli/config.json (project-specific)
```

### Store API Key in Config

By default, API keys from env vars are used at runtime. To store directly in config:

```json
{
  "kollabor": {
    "llm": {
      "profiles": {
        "work": {
          "provider": "anthropic",
          "model": "claude-opus-4-6",
          "api_key": "sk-ant-...",
          "temperature": 0.5
        }
      }
    }
  }
}
```

Stored keys take precedence over env vars for that profile.

## OpenAI OAuth

Use your ChatGPT Plus/Pro subscription without an API key:

```bash
kollab --login openai
```

### Setup

In ChatGPT web:
1. Go to Settings > Security (or Data Controls)
2. Enable "Device code authorization"

### How It Works

1. CLI displays a verification code
2. Browser opens to `auth.openai.com/codex/device`
3. Enter the code to authorize
4. Tokens stored at `~/.kollabor-cli/oauth/openai_tokens.json`

The `openai_responses` provider is auto-configured after login. No profile creation needed.

### Token Management

- Tokens expire in ~8 days
- Auto-refresh on expiry
- Re-run `kollab --login openai` if refresh fails

## Switching Profiles at Runtime

Use `/profile set` to switch without restarting:

```
/profile set local
```

Profile switch takes effect immediately for the next message.

## Complete Example: Three Profiles

Set up work, local, and cheap profiles:

```bash
# ~/.zshrc or ~/.bashrc

# Work: Claude Opus for complex tasks
export KOLLABOR_WORK_PROVIDER=anthropic
export KOLLABOR_WORK_API_KEY=sk-ant-...
export KOLLABOR_WORK_MODEL=claude-opus-4-6
export KOLLABOR_WORK_MAX_TOKENS=8192

# Local: Ollama for privacy
export KOLLABOR_LOCAL_PROVIDER=custom
export KOLLABOR_LOCAL_BASE_URL=http://localhost:11434/v1
export KOLLABOR_LOCAL_MODEL=llama3.3

# Cheap: Gemini Flash for quick tasks
export KOLLABOR_CHEAP_PROVIDER=gemini
export KOLLABOR_CHEAP_API_KEY=...
export KOLLABOR_CHEAP_MODEL=gemini-3-flash
export KOLLABOR_CHEAP_MAX_TOKENS=1024
```

Usage:
```bash
kollab --profile work    # Deep reasoning
kollab --profile local   # Private, offline
kollab --profile cheap   # Quick, low-cost
```

## Configuration Structure

Profiles are stored in `config.json`:

```json
{
  "kollabor": {
    "llm": {
      "profiles": {
        "my-profile": {
          "provider": "anthropic",
          "model": "claude-opus-4-6",
          "api_key": "",
          "base_url": "",
          "temperature": 0.7,
          "max_tokens": 4096,
          "timeout": 0,
          "top_p": null,
          "streaming": true,
          "supports_tools": true,
          "description": "My custom profile"
        }
      },
      "active_profile": "my-profile"
    }
  }
}
```

For full config file details, see [configuration.md](../configuration.md).

## Provider-Specific Details

Each provider has unique configuration options. See [providers.md](../providers.md) for:

- API endpoints
- Supported models
- Provider-specific fields (Azure endpoint, OpenRouter headers)
- OAuth setup
- Custom endpoint configuration
