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

# Pi Runtime

> Execute catalog models with Dari's built-in provider adapter.

`createPiRuntime()` is the first-party executor built on `@mupt-ai/pi-ai`. It turns the framework's normalized request into a provider call and converts the result back into the framework completion or stream contract.

The runtime uses Pi's model catalog. Supported providers and APIs depend on the catalog version installed with the package.

## Supply credentials

The host supplies credentials; the framework does not read environment variables.

```ts theme={null}
const pi = await createPiRuntime({
  apiKey: process.env.OPENAI_API_KEY!,
});
```

For multiple providers, resolve credentials per call:

```ts theme={null}
const pi = await createPiRuntime({
  apiKey: async ({ provider, model, api, purpose }) => {
    const key = await loadKey({ provider, model, api, purpose });
    if (!key) throw new Error(`No credential for ${provider}`);
    return key;
  },
  timeoutMs: 120_000,
  maxRetries: 2,
});
```

The resolver receives `provider`, `model`, `api`, and `purpose` (`execution` or `selector`). Keep credentials in your application; never put them in model declarations or requests.

## Connect it to a router

```ts theme={null}
const router = createRouter({
  executor: pi,
  models: [
    pi.model("openai/gpt-5.4-mini"),
    pi.model("openai/gpt-5.4"),
  ],
  policy: ({ candidates }) => ({
    model: candidates[0]!.id,
    reason: "Use the first eligible model.",
  }),
});
```

`executor: pi` is the default for model declarations that do not name an executor. Models can override it with `executor: "other"` and a matching `executors` entry.

## What is normalized

The runtime supports the framework's portable messages, images, tools, tool results, reasoning, hosted web-search items, generation controls, response formats, prompt-cache correlation, streaming, and cancellation. Provider APIs do not all support every feature. Unsupported combinations fail as request or configuration errors instead of being silently dropped; see [Protocols And Streaming](/framework/protocols-and-streaming).

Pi may adapt `json_object` to a permissive schema on providers without native JSON-object mode. Remote image URLs are not accepted by the shared image contract; download them in your host or use a custom executor.

## Retries and fallback

`maxRetries` controls retries for the same model inside Pi. Cross-model fallback is configured on `createRouter`, not on the runtime:

```ts theme={null}
const router = createRouter({
  models,
  policy,
  executor: pi,
  fallback: { enabled: true, requiresDifferentProvider: true },
});
```

See [Custom Executors](/framework/custom-executors#fallback) for the router-level behavior and [Prompt Caching](/framework/prompt-caching) for cache keys, provider usage, and cache-aware routing.