pi-openai-instructions-provider

A pi provider package for OpenAI-compatible Responses APIs that keeps the standard /v1/responses transport, but rewrites the request payload to:

• send the system prompt through instructions
• remove the duplicated system/developer prompt from input
• send a stable prompt_cache_key

This is useful for OpenAI-compatible providers where prompt caching works better when the stable prefix is carried in instructions instead of repeated inside input.

What It Registers

After installation, pi gets a new provider:

• provider: openai-instructions
• api: openai-instructions-responses

The provider wraps pi-ai's built-in openai-responses implementation and only rewrites the payload before it is sent.

Install

pi install /absolute/path/to/extensions-package/pi-openai-instructions-provider

Or publish it to npm and install it with:

pi install npm:pi-openai-instructions-provider

Required Environment Variables

By default, the provider reads:

OPENAI_API_KEY=...

If your upstream uses a different environment variable name, set:

PI_OPENAI_INSTRUCTIONS_API_KEY_ENV=MY_PROVIDER_API_KEY
MY_PROVIDER_API_KEY=...

Optional Environment Variables

Base URL

Defaults to the standard OpenAI endpoint:

PI_OPENAI_INSTRUCTIONS_BASE_URL=https://api.openai.com/v1

Examples:

PI_OPENAI_INSTRUCTIONS_BASE_URL=https://your-gateway.example.com/v1
PI_OPENAI_INSTRUCTIONS_BASE_URL=https://your-gateway.example.com/openai/v1

Model Allowlist

By default, the package exposes a curated set of built-in OpenAI Responses models. Override the list with a comma-separated allowlist:

PI_OPENAI_INSTRUCTIONS_MODELS=gpt-4.1,gpt-4.1-mini,gpt-5.5,o4-mini

Prompt Cache Key Strategy

Supported modes:

• stable (default)
• session
• input

PI_OPENAI_INSTRUCTIONS_CACHE_KEY_MODE=stable

Behavior:

• stable: hash of provider + model + baseUrl + instructions + tools fingerprint
• session: uses sessionId
• input: hash of the rewritten input

You can also change the prefix:

PI_OPENAI_INSTRUCTIONS_CACHE_KEY_PREFIX=my-team

Debug Logging

PI_OPENAI_INSTRUCTIONS_DEBUG=true

This prints the final prompt_cache_key to stderr for inspection.

Usage

After installation, select the provider's model in pi:

openai-instructions/gpt-4.1
openai-instructions/gpt-5.5
openai-instructions/o4-mini

Notes

• This package is for standard OpenAI-compatible Responses APIs.
• It intentionally does not use Codex-specific transport, OAuth, JWT-derived headers, or /codex/responses routing.
• It is designed to stay close to pi-ai's built-in openai-responses behavior while only changing the payload shape relevant to caching.