​

Quickstart

Ember is a hosted API/SDK that lets you shape AI model behavior by directly controlling a model’s internal units of computation, or “features”. With Ember, you can modify features to precisely control model outputs, or use them as building blocks for tasks like classification.

In this quickstart, you’ll learn how to:

• Find features that matter for your specific needs
• Edit features to create model variants
• Discover which features are active in your data
• Save and load your model variants

!pip install goodfire

You can get an API key through our platform

GOODFIRE_API_KEY = "{YOUR_API_KEY}"

​

Initialize the SDK

import goodfire
client = goodfire.Client(api_key=GOODFIRE_API_KEY)
# Instantiate a model variant. 
variant = goodfire.Variant("meta-llama/Llama-3.3-70B-Instruct")

Our sampling API is OpenAI compatible, making it easy to integrate.

​

Editing features to create model variants

​

How to find relevant features for edits

There are three ways to find features you may want to modify:

• Auto Steer: Simply describe what you want, and let the API automatically select and adjust feature weights

• Feature Search: Find features using semantic search

• Contrastive Search: Identify relevant features by comparing two different datasets

Let’s explore each method in detail.

variant.reset()

​

(Advanced) Conditional logic for feature edits

You can establish relationships between different features (or feature groups) using conditional interventions.

First, let’s reset the variant and pick out the funny feature

Now, let’s find a features where the model is talking like a pirate

Now, let’s set up behaviour so that when the model is talking like a pirate, it will be funny.

Well I don’t know if I laughed at that, and maybe the model isn’t very good at pirate jokes, so let’s set up behaviour to stop generating if the pirate features are too strong.

# Abort if pirate features are too strong
variant.abort_when(pirate_features > 0.75)

try:
    response = client.chat.completions.create(
        messages=[{"role": "user", "content": "Tell me about pirates."}],
        model=variant
    )
except goodfire.exceptions.InferenceAbortedException:
    print("Generation aborted due to too much pirate content")

If you aren’t sure of the features you want to condition on, use AutoConditional with a specified prompt to get back an automatically generated condition.

# Generate auto conditional based on a description. This will automatically
# choose the relevant features and conditional weight
conditional = goodfire.conditional.AutoConditional(
    "pirates",
    client=client,
    model="meta-llama/Llama-3.3-70B-Instruct",
    num_features_to_use=5
)

# Apply feature edits when condition is met
variant.set_when(conditional, {
    joke_features[0]: 0.5,
    joke_features[1]: 0.5
})

​

Discover which features are active in your data

​

Working with a conversation context

You can inspect what features are activating in a given conversation with the inspect API, which returns a context object.

Say you want to understand what model features are important when the model tells a joke. You can pass in the same joke conversation dataset to the inspect endpoint.

From the context object, you can access a lookup object which can be used to look at the set of feature labels in the context.

You can select the top k activating features in the context, ranked by activation strength. There are features related to jokes and tongue twisters, among other syntactical features.

You can also inspect individual tokens level feature activations. Let’s see what features are active at the punchline token.

​

(Advanced) Look at next token logits

​

Get feature activation vectors for machine learning tasks

To run a machine learning pipeline at the feature level (for instance, for humor detection) you can directly export features using client.features.activations to get a matrix or retrieve a sparse vector for a specific FeatureGroup.

​

Inspecting specific features

There may be specific features whose activation patterns you’re interested in exploring. In this case, you can specify features such as humor_features and pass that into the features argument of inspect.

Now, let’s see if these features are activating in the joke conversation.

Now you can retrieve the top k activating humor features in the context. This might be a more interesting set of features for downstream tasks.

​

Save and load your model variants

You can serialize a variant to JSON format for saving.

And load a variant from JSON format.

Now, let’s generate a response with the loaded variant.

​

Using OpenAI SDK

You can also work directly with the OpenAI SDK for inference since our endpoint is fully compatible.

!pip install openai --quiet

from openai import OpenAI

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

response = oai_client.chat.completions.create(
    messages=[
        {"role": "user", "content": "who is this"},
    ],
    model=variant.base_model,
    extra_body={"controller": variant.controller.json()},
)

response.choices[0].message.content