# pi-params

A [pi.dev](https://pi.dev) extension that lets you set per-provider, per-model parameter overrides (temperature, top_p, top_k, frequency_penalty, etc.) by hooking into Pi's `before_provider_request` event.

## How it works

1. You define parameter overrides in `.pi/params.toml`
2. pi-params tracks the current provider and model via the `model_select` event
3. Before each provider API request, it injects your overrides into the request payload
4. Overrides work with **any provider** — OpenAI, Anthropic, Google, OpenRouter, DeepSeek, etc.

## Quick start

1. Copy the example config:
   ```bash
   cp .pi/params.example.toml .pi/params.toml
   ```

2. Edit `.pi/params.toml` to your preferences

3. Load the extension:
   ```bash
   pi -e extensions/params.ts
   ```

4. Or add to your project's `.pi/settings.json` for automatic loading:
   ```json
   {
     "extensions": ["extensions/params.ts"]
   }
   ```

## Config format

```toml
# Global defaults — applies to ALL providers and models
["*"."*"]
temperature = 0.7
top_p = 0.9
max_tokens = 4096

# Provider-level defaults — applies to all models from this provider
["openai"."*"]
frequency_penalty = 0.0
presence_penalty = 0.0

# Per-model — applies only to this specific model on this provider
["openai"."gpt-4o"]
temperature = 0.5
max_tokens = 8192

# Cross-provider model wildcard — applies to this model on ANY provider
["*"."claude-sonnet-4-20250514"]
temperature = 0.25
```

### Merge behavior

Config entries are **merged** from least specific to most specific. Higher-specificity values override lower-specificity ones:

```
global (*/*)
  ↓
model wildcard (*/model)
  ↓
provider wildcard (provider/*)
  ↓
exact match (provider/model)
```

So if you set `temperature = 0.7` in `*/*` and `temperature = 0.3` in `anthropic/*`, all Anthropic models get `temperature = 0.3`.

## Slash commands

Use `/params` commands at runtime to adjust parameters without editing the config file. These **session overrides** take highest priority and are applied on top of your TOML config.

| Command | Description |
|---------|-------------|
| `/params` | Show current provider/model and all active overrides |
| `/params set <key> <value>` | Set a parameter override for this session |
| `/params unset <key>` | Remove a specific session override |
| `/params preset <name>` | Apply a named preset |
| `/params reset` | Clear all session overrides |

### Presets

| Preset | temperature | top_p | Other |
|--------|-------------|-------|-------|
| `creative` | 1.0 | 0.95 | — |
| `precise` | 0.1 | 0.1 | — |
| `balanced` | 0.5 | 0.8 | — |
| `code` | 0.2 | 0.5 | — |
| `brainstorm` | 1.2 | 0.95 | frequency_penalty 0.5 |
| `long` | — | — | max_tokens 16384 |

### Priority chain (highest wins)

```
TOML global defaults (*/*)
  ↓
TOML model wildcard (*/model)
  ↓
TOML provider wildcard (provider/*)
  ↓
TOML exact match (provider/model)
  ↓
Session overrides (/params commands)  ← highest priority
```

## Supported parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `temperature` | float (0.0–2.0) | Controls randomness. Lower = more deterministic. |
| `top_p` | float (0.0–1.0) | Nucleus sampling threshold. |
| `top_k` | integer | Top-k sampling (common with Anthropic, Google). |
| `frequency_penalty` | float (0.0–2.0) | Penalizes repeated tokens by frequency. |
| `presence_penalty` | float (0.0–2.0) | Penalizes tokens that have appeared. |
| `repetition_penalty` | float (0.0–2.0) | General repetition penalty. |
| `max_tokens` | integer | Maximum tokens in the response. |
| `stop` | string or string[] | Stop sequences. |

## Files

| File | Purpose |
|------|---------|
| `extensions/params.ts` | The extension itself |
| `.pi/params.toml` | Your active config (create from example) |
| `.pi/params.example.toml` | Example config with all providers and params |

## Requirements

- [pi.dev](https://pi.dev) CLI
- npm dependency: `smol-toml` (installed via `npm install` in this project)

## License

MIT