aiservershell

README

AI Server Shell

AI Server Shell is a Go framework for exposing application-defined AI behavior through SDK-compatible server protocols. The shell owns routing, validation, authentication hooks, HTTP/SSE/WebSocket lifecycle, and OpenAI-shaped errors; your backend owns models, agents, tools, memory, persistence, and business logic.

Milestone 1 freezes the OpenAI handler to 182 paths and 288 operations from openai/openai-openapi commit 2186421dca0cca7c1e67caa7739005e8b1ccc4dd, plus the Realtime and Responses WebSocket unions in official Node SDK v7.4.0. Anthropic and Gemini handlers are future work and will consume the same protocol-neutral backend.Services registry.

Tested SDKs

The compatibility suite pins and tests exact client versions. Add one row for each SDK version and language as coverage expands; an unlisted version is not an automatic compatibility claim.

Protocol	Language	SDK	Tested version
OpenAI	JavaScript / TypeScript	openai-node	7.4.0

Use it

Implement the public backend contract, inject one object for every capability or selected objects for individual capabilities, then construct a normal http.Handler:

services, err := backend.NewServices(
    backend.WithHandler(app),
    backend.WithRealtime(app),
    backend.WithResponsesWebSocket(app),
)
if err != nil {
    log.Fatal(err)
}

handler, err := openai.NewHandler(services)
if err != nil {
    log.Fatal(err)
}
log.Fatal(http.ListenAndServe(":8080", handler))

backend.Handler receives a canonical capability, stable operation ID, metadata, path/query parameters, and bounded JSON or opaque bytes. A missing capability returns a stable OpenAI-shaped 501; it is not silently simulated. Bidirectional sessions implement backend.SessionBackend and backend.Session.

The optional root aggregate mounts already-constructed protocol handlers and does not introduce another backend contract:

shell, err := aiservershell.New(
    aiservershell.WithHandler("/v1/", handler),
)

The application owns the listener. During graceful shutdown, stop the http.Server and call shell.Shutdown(ctx); the latter prevents new protocol upgrades, cancels active OpenAI WebSocket sessions, and waits for them to exit. Unary HTTP and SSE calls follow their request contexts.

See examples/minimal, docs/backend-contract.md, and docs/openai-compatibility.md.

Validate it

make verify

# Opt-in live, read-only differential check. Requires OPENAI_API_KEY.
OPENAI_COMPAT_PROFILE=safe make compatibility-safe

make verify regenerates the frozen profile, rejects drift, runs unit/race/vet, installs the pinned official SDK, and drives it through real local listeners. The local suite requires no network credential. Live tests keep the incoming Shell credential separate from the upstream key and never forward it.

Compatibility boundary

The committed route and event inventories are reproducible coverage inputs, not a promise to adopt later upstream changes automatically. Unknown fields inside known events are preserved. Unknown routes are 404; frozen routes with missing backend capabilities are 501. Current limitations and live evidence are stated in docs/openai-compatibility.md.

Licensed under the Apache License 2.0.

Documentation

Overview

Package aiservershell provides a pluggable server-side shell for exposing OpenAI-compatible APIs from application-defined Go services.

Protocol handlers are independently constructed from the shared, protocol-neutral backend.Services registry. The root Server is only an optional http.Handler aggregate; applications may serve a protocol handler directly.

Index

• type Server
  • func New(options ...ServerOption) (*Server, error)
  • func (s *Server) ServeHTTP(writer http.ResponseWriter, request *http.Request)
  • func (s *Server) Shutdown(ctx context.Context) error
• type ServerOption
  • func WithHandler(pattern string, handler http.Handler) ServerOption

Types

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is an optional aggregate for independently constructed protocol handlers. It implements http.Handler and does not own network listeners.

func New

func New(options ...ServerOption) (*Server, error)

New constructs an aggregate Server.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(writer http.ResponseWriter, request *http.Request)

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown asks mounted handlers with active protocol sessions to stop and waits for them to finish. Listener shutdown remains owned by the application's http.Server; callers normally invoke both with the same context.

type ServerOption

type ServerOption func(*serverConfig) error

ServerOption configures an aggregate Server.

func WithHandler

func WithHandler(pattern string, handler http.Handler) ServerOption

WithHandler mounts one independently constructed protocol handler. Pattern follows http.ServeMux syntax.