33 lines
1.6 KiB
Markdown
33 lines
1.6 KiB
Markdown
# 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`
|