Define v1alpha1 inference protocol configuration and Praxis filter mappings

Part of #8. Expand the v1alpha1 API design introduced in PR #5 by mapping AI inference API formats to their required Praxis filters and defining the configuration needed at the AIGateway level.

Assess the proposed inbound formats from MaaS

API	Endpoint	Status
OpenAI Chat Completions	/v1/chat/completions	Existing
OpenAI Embeddings	/v1/embeddings	Existing
Anthropic Messages	/v1/messages	Existing, with translation enabled
OpenAI Responses	/v1/responses	Proposed

against the required upstream formats. Distinguish existing controller integrations, capabilities available in Praxis, and planned or unsupported paths.

Deliverables

Document a mapping for each assessed client-facing/upstream format pair showing support status, required Praxis filter chain. Identify shared filters separately from format-specific requirements .
Identify the values required by each filter set, including connection information for storage or other dependencies: endpoints, credentials via Secret references. Record which values are required, optional, or defaulted.
Expand AIGateway.spec.protocols.llm in docs/design/api-v1alpha1.md with the identified fields for formats accepted into v1alpha1.
- Define omission and empty-stanza ({}) behavior, defaults, validation, and Secret reference semantics within the existing Tenant namespace constraints.
- Resolve when an empty stanza suffices and when configuration is mandatory.
- Specify required Secret keys and whether dependency credentials require Tenant authorization. Include examples and keep corresponding property names consistent in docs/design/api.md.

Acceptance criteria

Every assessed format pair has documented support status, dependencies, and configuration requirements, with a filter mapping for supported paths; unsupported combinations and translation limits are explicit.
Each required administrator-supplied value maps to a documented API field or an existing resource field, with examples sufficient to configure the filter set without exposing raw filter chains in the AIGateway API.
The mapping and API examples are checked against the relevant Praxis filter contracts and existing controller configuration at recorded revisions; remaining gaps, scope decisions, and deferred capabilities are explicit.

Out of scope

Implementing the generated filter chains, provisioning backing services, or adding new Praxis capabilities. Identifying a format or capability here does not automatically bring its implementation into v1alpha1 scope.

@derekhiggins

@derekhiggins @jland-redhat This is the list of inference APIs we are looking at. I have does this map to your expectations?

@leseb

@derekhiggins @jland-redhat This is the list of inference APIs we are looking at. I have does this map to your expectations?

To be able to have parity with what OGX provided we'd also need the following

API	Endpoint	Status
OpenAI Conversations	/v1/conversations	Existing in Praxis (managed, shares the Responses state store)
OpenAI Files	/v1/files	Passthrough today; native API proposed (ai#494)
OpenAI Vector Stores	/v1/vector_stores	Passthrough today; native API proposed (ai#485)

cc @leseb @eoinfennessy

@derekhiggins

@derekhiggins I have added these to the list now.

@derekhiggins

To help visualise for Files and VectorStores

@derekhiggins What is the intention with these storage APIs. Do you expose openAI files and openAI vector to the client directly. So would they potentially need to be represented as

apiVersion: aigateway.praxis.io/v1alpha1
kind: Files
metadata:
  name: research-files
  namespace: research
spec:
  tenantRef:
    name: research

  connection:
    secretRef:
      name: files-connection

  governance:
    authorization:
      cel: >-
        has(claim.groups) && "research-file-users" in claim.groups
---
apiVersion: aigateway.praxis.io/v1alpha1
kind: VectorStores
metadata:
  name: research-vectors
  namespace: research
spec:
  tenantRef:
    name: research

  connection:
    secretRef:
      name: vector-store-connection

  embeddingModelRef:
    name: research-embedding

  chunking:
    maxTokens: 800
    overlap: 400

  governance:
    authorization:
      cel: >-
        has(claim.groups) && "research-search-users" in claim.groups

Resource	Responsibility
AIGateway	Enable API surfaces and authenticate callers
Model	Publish a model, select its providers and authorize access
Files	Configure file storage and authorize file operations
VectorStores	Configure vector storage/ingestion and authorize store operations

If we use secret types to hint at the contents we can have s3, PostgreSQL etc

@guicassolato

Note will prob add the Files and Vector Store API as part of the next API iteration rather than this one, but good to map it out and understand the need. cc @guicassolato

@derekhiggins What is the intention with these storage APIs. Do you expose openAI files and openAI vector to the client directly. So would they potentially need to be represented as

Yup, files and vector API would be exposed to the client (something like what you have above should work)

Additional endpoints we are planning to support in the near future

API	Endpoint	Transport	Status
Text-to-Speech	/v1/audio/speech	JSON	Proposed – JSON request, audio response
Image Generations	/v1/images/generations	JSON	Proposed
Rerank	/v1/rerank	JSON	Proposed
Audio Transcriptions	/v1/audio/transcriptions	Multipart	Proposed – blocked on ext_proc support
Image Edits	/v1/images/edits	Multipart	Proposed – blocked on ext_proc support
OCR	TBD	Multipart	Proposed – no shipped runtime yet
Vision	/v1/chat/completions	JSON	Existing – image content in messages

Navigation Menu

Repository navigation

Define v1alpha1 inference protocol configuration and Praxis filter mappings #9

Deliverables

Acceptance criteria

Out of scope

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Define v1alpha1 inference protocol configuration and Praxis filter mappings #9

Description

Deliverables

Acceptance criteria

Out of scope

Activity

maleck13 commented on Nov 10, 2026

derekhiggins commented on Nov 10, 2026

maleck13 commented on Nov 10, 2026

maleck13 commented on Nov 10, 2026

maleck13 commented on Nov 10, 2026

derekhiggins commented on Nov 10, 2026

jland-redhat commented on Nov 12, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions