# OpenAI-Compatible API Contract

## Contract metadata

- id: `iop.openai-compatible-api`
- boundary: outer
- status: active
- source evidence:
  - `apps/edge/internal/openai/`
  - `packages/go/config/edge_types.go`
  - `configs/edge.yaml`

## Surface

Edge exposes model discovery, Chat Completions, Responses, and legacy Completions compatibility routes. A configured model route selects either normalized provider execution or an OpenAI-compatible provider tunnel.

## Request behavior

- `model` is the public route key. Edge resolves it to an internal provider adapter and target.
- Standard sampling, streaming, tools, tool choice, reasoning, and response-format fields remain top-level API fields.
- Caller metadata is an ordinary bounded string map. Edge does not interpret a metadata key as a local execution directory or process-control instruction.
- Provider-pool passthrough preserves supported provider-native OpenAI-compatible extension fields.
- Normalized execution preserves native tool calls through structured completion metadata. Text fallback is used only after a backend explicitly rejects native tools.
- Authentication failures, admission failures, provider errors, and streaming terminal errors use the compatible error envelope.

## Provider boundary

The API may invoke normalized inference or the provider tunnel. It must not start interactive host programs, reuse local process state, mutate a working directory, or expose host command execution. `session_id` is correlation metadata only.

## Verification

- `go test -count=1 ./apps/edge/internal/openai`
- `make test-e2e`