Pi Runtime

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.

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

For multiple providers, resolve credentials per call:

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

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. 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:

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

See Custom Executors for the router-level behavior and Prompt Caching for cache keys, provider usage, and cache-aware routing.

Get Started

Build A Router

Advanced

Supply credentials

Connect it to a router

What is normalized

Retries and fallback

​Supply credentials

​Connect it to a router

​What is normalized

​Retries and fallback

Supply credentials

Connect it to a router

What is normalized

Retries and fallback