> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrixllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Playground

> Iterate on prompts and compare model outputs interactively.

The Playground is an interactive UI inside the MetrixLLM dashboard where you can test prompts, compare models, and refine parameters without writing any code.

Because the Playground connects directly to your workspace's gateway, every test run uses your actual provider keys, respects your guardrails, and is logged in your Request Logs just like a real production request.

## Features

* **Multi-window comparison** — Run up to 4 side-by-side prompt windows
* **Multi-model support** — Test across OpenAI, Anthropic, Google, xAI, Groq, and Together
* **Streaming responses** — Watch tokens arrive in real time
* **Variables** — Use `{{variable}}` placeholders for parameterized prompts
* **Web search** — Enable MetrixLLM Search or native provider web search
* **Save and load prompts** — Persist configurations to your Prompt Registry
* **Code snippets** — Export any playground run as Python or cURL code
* **Run history** — Replay previous runs with full context

## Opening the Playground

Navigate to **Playground** in the left sidebar of your dashboard. The playground opens with a single window containing a default system message and an empty user message.

## Configuring a prompt

Each playground window has a configuration sidebar with these parameters:

| Parameter             | Range                        | Default         | Description                                        |
| --------------------- | ---------------------------- | --------------- | -------------------------------------------------- |
| **Model**             | All enabled workspace models | First available | The LLM to call                                    |
| **Temperature**       | 0 – 2                        | 0.7             | Higher = more creative, lower = more deterministic |
| **Max Tokens**        | 1 – 8192                     | 1024            | Maximum tokens in the completion                   |
| **Top P**             | 0 – 1                        | 1.0             | Nucleus sampling threshold                         |
| **Frequency Penalty** | -2 – 2                       | 0               | Penalize repeated tokens                           |

### Model selector

Click the model dropdown in the sidebar to search and select from all models enabled for your workspace. Models are grouped by provider (OpenAI, Anthropic, Google, etc.) and filtered based on your workspace's model access settings.

<Note>
  Models disabled by your workspace administrator will not appear in the selector. Contact your workspace owner to enable additional models.
</Note>

## Writing messages

The message editor supports multi-turn conversations with three role types:

* **System** — Sets the model's behavior and persona (typically one message at the top)
* **User** — The human's input to the model
* **Assistant** — Pre-filled assistant responses for few-shot prompting

Use the **+** button to add messages, the **trash** icon to remove them, and the **drag handles** to reorder.

### Using variables

Define reusable placeholders with double curly braces:

```
You are a {{role}} assistant. Answer questions about {{topic}} in a {{tone}} tone.
```

The Variables panel automatically detects all `{{variable}}` placeholders and provides input fields. Variables are replaced before the request is sent.

<Tip>
  Variables are great for A/B testing prompt phrasing — keep the structure the same and swap out tone, format, or context values.
</Tip>

## Running a prompt

Click **Run** in the sidebar (or **Run All** when using multiple windows) to send the request. The response streams in real time with a blinking cursor indicator.

### Response metadata

After completion, the response panel shows:

| Field             | Description                              |
| ----------------- | ---------------------------------------- |
| **Model**         | The exact model that answered            |
| **Tokens**        | Total tokens used (prompt + completion)  |
| **Latency**       | End-to-end response time in milliseconds |
| **Cost**          | Estimated USD cost of the call           |
| **Finish Reason** | `stop`, `length`, `tool_calls`, etc.     |

## Side-by-side comparison

Click **Split Window** to add another playground window (up to 4). Each window:

* Maintains independent messages, model selection, and parameters
* Can run simultaneously with **Run All**
* Inherits settings from the most recent window when split

This is useful for:

* Comparing the same prompt across different models
* Testing temperature variations side-by-side
* Evaluating system message phrasing options

## Web search

Enable web search to augment model responses with real-time information:

| Mode                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| **Off**               | No web search — pure model response                                            |
| **MetrixLLM Search**  | MetrixLLM retrieves and injects web results before the model processes them    |
| **Native (Provider)** | Uses the model provider's built-in web search tool (e.g., OpenAI's web search) |

### Search depth (MetrixLLM Search)

| Depth  | Queries | Results |
| ------ | ------- | ------- |
| Low    | 1       | 3       |
| Medium | 2       | 5       |
| High   | 3       | 8       |

## Saving prompts

Click **Save** to persist the current window's configuration (messages, model, temperature, max tokens) to your workspace's Prompt Registry.

<Steps>
  <Step title="Click Save">
    Click the **Save** button in the window header.
  </Step>

  <Step title="Name the prompt">
    Enter a descriptive name (e.g. "Customer Support - Friendly Tone").
  </Step>

  <Step title="Confirm">
    Click **Save**. The prompt is now available via the Prompt Registry API and can be loaded by your application using its `prompt_id`.
  </Step>
</Steps>

## Loading prompts

Click **Load** to browse and load previously saved prompts. Selecting a prompt replaces the current window's messages, model, and parameters with the saved values.

## Code snippets

Click **Code** to generate ready-to-use code for your current configuration:

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.metrixllm.com/v1",
      api_key="YOUR_KEY",
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
      ],
      temperature=0.7,
      max_tokens=1024,
      top_p=1,
  )

  print(response.choices[0].message.content)
  ```

  ```curl cURL theme={null}
  curl -X POST https://api.metrixllm.com/v1/chat/completions \
    -H "Authorization: Bearer YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
      ],
      "temperature": 0.7,
      "max_tokens": 1024,
      "top_p": 1
    }'
  ```
</CodeGroup>

<Note>
  The base URL points to your MetrixLLM gateway (`/v1`), not directly to the provider. This ensures all playground requests are logged and governed by your workspace routing rules.
</Note>

## Run history

The **History** panel tracks your recent runs (up to 50). Each entry shows:

* Model used
* Token count
* Latency
* Timestamp
* Preview of the response

Click any history entry to reload its full configuration (messages, model, parameters) into a new window.

## Replaying production requests

From the Request Logs, click **Replay in Playground** on any logged request to load its exact prompt, model, and parameters into the playground. This is useful for:

* Debugging failed or slow requests
* Iterating on prompts that underperformed in production
* Testing parameter changes against real request data

## State persistence

Playground state (windows, messages, parameters) is automatically saved to `localStorage` per workspace. When you return to the playground, your last configuration is restored.

Click **Reset** to clear all windows, history, and saved state.

## Best practices

* **Use variables for reusable templates** — Avoid duplicating prompts; parameterize with `{{variable}}`.
* **Compare at least 2 models** before promoting a prompt to production.
* **Check cost metadata** — A prompt that costs \$0.001 per call may be fine at 1K calls/day but expensive at 1M.
* **Save winning prompts immediately** — Use the Save button to persist to the Prompt Registry before moving on.
* **Use web search judiciously** — Native provider search adds latency; MetrixLLM Search is faster for simple lookups.

## Common pitfalls

<Warning>
  **Max tokens default is 1024.** If you expect long responses (e.g., document summarization), increase this value to avoid truncation.
</Warning>

* **Temperature 0 is not deterministic** across providers. For reproducibility, use temperature 0 and check `finish_reason`.
* **Variables with no value** remain as `{{name}}` in the request — ensure all detected variables have values before running.
* **Model name vs display name** — The model selector shows display names (e.g. "GPT-4o") but the API uses internal names (e.g. `gpt-4o`). Code snippets use the correct internal name.