# Execution Profile Definitions

Execution Profiles define **how** Scriptorium calls an LLM endpoint.

A profile file is YAML, typically stored under `profiles/`, for example `profiles/local-quality.yaml`.

## Complete Example

```yaml
id: local-quality
endpoint: http://localhost:8000/v1
model: gpt-4.1
temperature: 0.0
max_tokens: 1200
top_p: 1.0
timeout_seconds: 180
reasoning_effort: medium
api_key_env: SCRIPTORIUM_API_KEY
extra_params:
  provider: openrouter
  route: fallback
```

## Available Options

- `id` (required): Unique profile identifier used by `--profile` or prompt `default_profile`.
- `endpoint` (required): OpenAI-compatible base URL, usually ending in `/v1`.
- `model` (required): Model name to request at that endpoint.
- `temperature` (optional): Sampling temperature. Valid range is `0` to `2`.
- `max_tokens` (optional): Max completion tokens. Must be `>= 0`.
- `top_p` (optional): Nucleus sampling parameter. Valid range is `0` to `1`.
- `timeout_seconds` (optional): Request timeout in seconds. Must be `>= 0`.
- `reasoning_effort` (optional): Provider/model-specific reasoning level string.
- `api_key_env` (optional): Environment variable name that holds the API key.
- `extra_params` (optional): String key/value map for provider-specific parameters.

## Notes and Rules

- Raw API keys are not supported. Do **not** add `api_key` fields.
- Unknown YAML fields fail to load (strict decoding).
- If `api_key_env` is set, the environment variable must be present when the run executes.