Runtime context

A RuntimeContext is the ambient configuration a program runs under. It carries the active language model, the adapter, any callbacks, and execution settings like thread count. Programs read it implicitly through a given, so you configure once and every program in scope picks it up.

Setting it

There are three ways to install a context:

• RuntimeEnvironment.configure(ctx) sets the default of the process. Only the first thread that calls it can call it again.
• RuntimeEnvironment.withSettings(ctx) { ... } installs a context just for the duration of a block.
• RuntimeEnvironment.withInstalled(ctx) { ... } does the same, and it gives the block the context as a given.

The Quickstart shows the full wiring of a model and adapter into a context.

Scoped overrides

withSettings is the tool for changing one setting temporarily. Here a question is answered under the default model, then again under a different model, scoped to a block:

def askWithOverride(question: String, overrideModel: String)(using
    ctx: RuntimeContext
): Either[DspyError, (String, String)] =
  for
    base   <- ask(question) // current/global LM
    other  <- OpenAiLanguageModel.fromEnv(overrideModel)
    scoped <- RuntimeEnvironment.withSettings(ctx.copy(lm = Some(other))) {
                given RuntimeContext = RuntimeEnvironment.current
                ask(question)
              }
  yield (base, scoped)

The override applies only inside the block; outside it, the original context is unchanged. The same pattern swaps the adapter, adds callbacks, or changes any other context field. The trace and the history that the block adds stay after the block, as with DSPy's dspy.context.

A field that a context does not set is None, and it comes from the installed context. A set value wins, also an empty one: callbacks = Some(Vector.empty) turns off the callbacks for the block, as dspy.context(callbacks=[]) does.

What the context carries

Field	Purpose
lm	The active language model.
adapter	The active adapter.
callbacks	Handlers for the observability event stream.
trackUsage	Whether the usage trackers get the token usage. Some(false) turns them off. The usage of a program result stays.

Next: Observability.