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

# Variants

> Documentation for working with model variants

Variants are edits to a model that allow you to modify model behavior by adjusting feature activations and defining conditional behaviors.

## Creating Variants

### Basic Usage

Create a variant by instantiating the `Variant` class with a base model:

<CodeGroup name="Basic Usage">
  ```python Code theme={null}
  from goodfire import Variant

  # Create a variant from a base model
  variant = Variant("meta-llama/Llama-3.1-8B-Instruct")
  print(variant)
  ```

  ```output Output theme={null}
  Variant(
     base_model=meta-llama/Llama-3.1-8B-Instruct,
     edits={
     }
  )
  ```
</CodeGroup>

## Adding features to a variant

<CodeGroup name="Creating Variants">
  ```python Adding features to a variant theme={null}
  from goodfire import Variant

  # Create a variant from a base model
  variant = Variant("meta-llama/Llama-3.1-8B-Instruct")

  # Search for a feature to modify
  feature = client.features.search("formal writing style", model=variant, top_k=1)[0]

  # Set feature modifications
  variant.set(feature, 0.5)  # Value typically between -1 and 1
  ```

  ```output Edited variant theme={null}
  Variant(
     base_model=meta-llama/Llama-3.1-8B-Instruct,
     edits={
        Feature("Formal business and technical writing style"): 0.5,
     }
  )
  ```
</CodeGroup>

## Conditional Controls

You can create variants that respond dynamically to feature activations:

<CodeGroup name="Conditional Controls">
  ```python Conditional Controls theme={null}
  # First get some features to work with
  whale_feature = client.features.search("whales", model=variant, top_k=1)[0]
  pirate_feature = client.features.search("pirate speech", model=variant, top_k=1)[0]

  # Activate pirate features when whale features are detected
  variant.set_when(whale_feature > 0.75, {
      pirate_feature: 0.5
  })

  # Abort generation if certain features are too strong
  variant.abort_when(whale_feature > 0.9)

  # Custom handler when condition is met
  def my_handler(context):
      print(f"Whale feature activated with strength: {context.activations[whale_feature]}")

  ```
</CodeGroup>

## Methods

### set()

Set feature modifications. This method is overloaded to handle different input types.

**Signatures:**

```python theme={null}
def set(self, feature: Feature | FeatureGroup, value: float)
def set(self, edits: dict[Feature, float] | FeatureEdits)
```

**Parameters:**

<ResponseField name="feature" type="Feature | FeatureGroup">
  Single feature or feature group to modify. Required when using the first signature.
</ResponseField>

<ResponseField name="value" type="float">
  Modification value (typically between -1 and 1). Required when using the first signature.
</ResponseField>

<ResponseField name="edits" type="dict[Feature, float] | FeatureEdits">
  Dictionary of features and their values, or a FeatureEdits object. Required when using the second signature.
</ResponseField>

**Examples:**

```python theme={null}
# Single feature modification
formal_feature = client.features.search("formal writing style", model=variant, top_k=1)[0]
variant.set(formal_feature, 0.5)

# Multiple features at once using dict
casual_feature = client.features.search("casual writing style", model=variant, top_k=1)[0]
variant.set({
    formal_feature: 0.5,
    casual_feature: -0.3
})

# Using FeatureEdits object
edits = client.features.AutoSteer("be funny", model=variant)
variant.set(edits)
```

### set\_when()

Define conditional feature modifications.

**Parameters:**

<ResponseField name="condition" type="ConditionalGroup" required>
  Condition that triggers the modifications
</ResponseField>

<ResponseField name="values" type="dict[Feature, float] | FeatureEdits" required>
  Feature modifications to apply when condition is met
</ResponseField>

**Example:**

```python set_when example theme={null}
whale_feature = client.features.search("whales", model=variant, top_k=1)[0]
pirate_feature = client.features.search("pirate speech", model=variant, top_k=1)[0]
# Activate pirate features when whale features are detected
variant.set_when(whale_feature > 0.3, {
    pirate_feature: 0.5
})
```

### abort\_when()

Abort generation when a condition is met.

**Parameters:**

<ResponseField name="condition" type="ConditionalGroup" required>
  Condition that triggers the abort
</ResponseField>

**Example:**

```python Abort example theme={null}
inappropriate_feature = client.features.search("inappropriate content", model=variant, top_k=1)[0]
# Abort if inappropriate content is detected
variant.abort_when(inappropriate_feature > 0.8)

try:
    response = client.chat.completions.create(
        messages=[{"role": "user", "content": "..."}],
        model=variant,
        stream=False
    )
except goodfire.exceptions.InferenceAbortedException:
    print("Aborted because of inappropriate content")

print(variant)
```

### reset()

Remove all feature modifications.

**Example:**

```python Reset variant theme={null}
variant.reset()
```

### clear()

Remove modifications for specific features.

**Parameters:**

<ResponseField name="feature" type="Feature | FeatureGroup" required>
  Feature(s) to clear modifications for
</ResponseField>

**Example:**

```python Clear particular feature theme={null}
variant.clear(feature)
```

## Serialization

Variants can be serialized to and from JSON:

```python Storing and loading variants theme={null}
# Save variant to JSON
variant_json = variant.json()

# Load variant from JSON
loaded_variant = Variant.from_json(variant_json)
```

## Using with OpenAI SDK

Variants are compatible with the OpenAI SDK:

```python Using with OpenAI SDK theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GOODFIRE_API_KEY",
    base_url="https://api.goodfire.ai/api/inference/v1"
)

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model=variant.base_model,
    extra_body={"controller": variant.controller.json()}
)
```

## Classes

### VariantMetaData

Metadata about a model variant.

**Properties:**

<ResponseField name="name" type="str">
  Name of the variant
</ResponseField>

<ResponseField name="base_model" type="str">
  Base model identifier
</ResponseField>

<ResponseField name="id" type="str">
  Unique identifier for the variant
</ResponseField>