The client API described in OpenAPI, and both APIs in Swagger UI
CI / test (push) Failing after 6m12s
CI / test (push) Failing after 6m12s
/v1/openapi.json is the API clients use — OpenAI's endpoints, Anthropic's, and what llmgw adds — in OpenAPI 3.1, generated from internal/clientapi's route table by the generator the admin API's document comes from, now told each document's title, server, token and error. A test reads the router's mux.HandleFunc calls and refuses a route described and not mounted, or mounted and not described. Asked for before there is a key, so it needs none. /docs/api shows it in Swagger UI 5.33.1 (Apache 2.0, served from the gateway as the page's policy requires): Authorize takes a key, Try it out sends to this gateway. Staff are offered the admin API's document too, from /docs/api/admin.json, which nobody else is given. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
41601bc5ef
commit
fd3c7bda32
26 files changed
+3956
-48
No files matched your search
@@ -0,0 +1,479 @@
|
||||
// Package clientapi describes the API clients use, the one on :8080 — OpenAI's
|
||||
// shape and what llmgw adds to it — for its OpenAPI document.
|
||||
//
|
||||
// The types here are the bodies as they go over the wire, written for the
|
||||
// document: the handlers read a request's routing fields and pass the rest
|
||||
// to the engine as it came, so a request may carry more than is listed, and
|
||||
// an engine's answer may say more than is listed. The route table is checked
|
||||
// against the router's own by a test, so an endpoint cannot be added without
|
||||
// being described.
|
||||
package clientapi
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// Error is every refusal: OpenAI's shape.
|
||||
type Error struct {
|
||||
Error ErrorBody `json:"error"`
|
||||
}
|
||||
|
||||
// ErrorBody says why.
|
||||
type ErrorBody struct {
|
||||
Message string `json:"message"`
|
||||
// Type is invalid_request_error, server_error, rate_limit_exceeded …
|
||||
Type string `json:"type"`
|
||||
// Code, where there is one a client branches on: model_not_found,
|
||||
// content_policy_violation, job_not_found, system_stopped.
|
||||
Code *string `json:"code"`
|
||||
}
|
||||
|
||||
// ChatMessage is one turn.
|
||||
type ChatMessage struct {
|
||||
// Role is system, user, assistant or tool.
|
||||
Role string `json:"role"`
|
||||
// Content is a string, or a list of parts: text, and image_url for a
|
||||
// model with vision.
|
||||
Content json.RawMessage `json:"content"`
|
||||
Name string `json:"name,omitempty"`
|
||||
ToolCalls json.RawMessage `json:"tool_calls,omitempty"`
|
||||
ToolCallID string `json:"tool_call_id,omitempty"`
|
||||
}
|
||||
|
||||
// StreamOptions asks for usage in the last chunk of a stream.
|
||||
type StreamOptions struct {
|
||||
IncludeUsage bool `json:"include_usage"`
|
||||
}
|
||||
|
||||
// ChatCompletionRequest is a chat turn asked of a model.
|
||||
type ChatCompletionRequest struct {
|
||||
// Model is a model's name or alias, or an adapter's name.
|
||||
Model string `json:"model"`
|
||||
Messages []ChatMessage `json:"messages"`
|
||||
// Stream answers as server-sent events.
|
||||
Stream bool `json:"stream,omitempty"`
|
||||
StreamOptions *StreamOptions `json:"stream_options,omitempty"`
|
||||
MaxTokens int `json:"max_tokens,omitempty"`
|
||||
MaxCompletionTokens int `json:"max_completion_tokens,omitempty"`
|
||||
Temperature *float64 `json:"temperature,omitempty"`
|
||||
TopP *float64 `json:"top_p,omitempty"`
|
||||
Seed *int64 `json:"seed,omitempty"`
|
||||
// Stop is a string or a list of them.
|
||||
Stop json.RawMessage `json:"stop,omitempty"`
|
||||
Tools json.RawMessage `json:"tools,omitempty"`
|
||||
ToolChoice json.RawMessage `json:"tool_choice,omitempty"`
|
||||
ResponseFormat json.RawMessage `json:"response_format,omitempty"`
|
||||
// User is the client's own name for whoever it serves, kept with the
|
||||
// usage.
|
||||
User string `json:"user,omitempty"`
|
||||
// Metadata are tags kept with the usage, never sent to the engine.
|
||||
Metadata map[string]string `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// Usage is what a request used.
|
||||
type Usage struct {
|
||||
PromptTokens int `json:"prompt_tokens"`
|
||||
CompletionTokens int `json:"completion_tokens"`
|
||||
TotalTokens int `json:"total_tokens"`
|
||||
}
|
||||
|
||||
// ChatChoice is one answer.
|
||||
type ChatChoice struct {
|
||||
Index int `json:"index"`
|
||||
Message ChatMessage `json:"message"`
|
||||
// FinishReason is stop, length or tool_calls.
|
||||
FinishReason string `json:"finish_reason"`
|
||||
}
|
||||
|
||||
// ChatCompletion is a model's answer.
|
||||
type ChatCompletion struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Created int64 `json:"created"`
|
||||
Model string `json:"model"`
|
||||
Choices []ChatChoice `json:"choices"`
|
||||
Usage Usage `json:"usage"`
|
||||
}
|
||||
|
||||
// CompletionRequest is a prompt to continue.
|
||||
type CompletionRequest struct {
|
||||
Model string `json:"model"`
|
||||
// Prompt is a string or a list of them.
|
||||
Prompt json.RawMessage `json:"prompt"`
|
||||
MaxTokens int `json:"max_tokens,omitempty"`
|
||||
Temperature *float64 `json:"temperature,omitempty"`
|
||||
Stream bool `json:"stream,omitempty"`
|
||||
Stop json.RawMessage `json:"stop,omitempty"`
|
||||
Seed *int64 `json:"seed,omitempty"`
|
||||
}
|
||||
|
||||
// CompletionChoice is one continuation.
|
||||
type CompletionChoice struct {
|
||||
Index int `json:"index"`
|
||||
Text string `json:"text"`
|
||||
FinishReason string `json:"finish_reason"`
|
||||
}
|
||||
|
||||
// Completion is a continued prompt.
|
||||
type Completion struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Created int64 `json:"created"`
|
||||
Model string `json:"model"`
|
||||
Choices []CompletionChoice `json:"choices"`
|
||||
Usage Usage `json:"usage"`
|
||||
}
|
||||
|
||||
// EmbeddingRequest asks for vectors.
|
||||
type EmbeddingRequest struct {
|
||||
Model string `json:"model"`
|
||||
// Input is a string or a list of them; each is embedded on its own, and
|
||||
// the longest must fit the model's context.
|
||||
Input json.RawMessage `json:"input"`
|
||||
EncodingFormat string `json:"encoding_format,omitempty"`
|
||||
Dimensions int `json:"dimensions,omitempty"`
|
||||
}
|
||||
|
||||
// Embedding is one input's vector.
|
||||
type Embedding struct {
|
||||
Object string `json:"object"`
|
||||
Index int `json:"index"`
|
||||
Embedding []float64 `json:"embedding"`
|
||||
}
|
||||
|
||||
// EmbeddingList is every input's vector.
|
||||
type EmbeddingList struct {
|
||||
Object string `json:"object"`
|
||||
Data []Embedding `json:"data"`
|
||||
Model string `json:"model"`
|
||||
Usage Usage `json:"usage"`
|
||||
}
|
||||
|
||||
// RerankRequest orders documents by a query, for a reranker vLLM serves.
|
||||
type RerankRequest struct {
|
||||
Model string `json:"model"`
|
||||
Query string `json:"query"`
|
||||
Documents []string `json:"documents"`
|
||||
TopN int `json:"top_n,omitempty"`
|
||||
}
|
||||
|
||||
// ScoreRequest scores pairs of texts, for a scorer vLLM serves.
|
||||
type ScoreRequest struct {
|
||||
Model string `json:"model"`
|
||||
// TextA and TextB are strings or lists of them.
|
||||
TextA json.RawMessage `json:"text_1"`
|
||||
TextB json.RawMessage `json:"text_2"`
|
||||
}
|
||||
|
||||
// TranscriptionForm is speech to text, sent as a form.
|
||||
type TranscriptionForm struct {
|
||||
// File is the audio.
|
||||
File []byte `json:"file"`
|
||||
Model string `json:"model"`
|
||||
Language string `json:"language,omitempty"`
|
||||
Prompt string `json:"prompt,omitempty"`
|
||||
ResponseFormat string `json:"response_format,omitempty"`
|
||||
Temperature float64 `json:"temperature,omitempty"`
|
||||
}
|
||||
|
||||
// Transcription is the text.
|
||||
type Transcription struct {
|
||||
Text string `json:"text"`
|
||||
}
|
||||
|
||||
// ImageRequest asks for pictures, of a model that makes them.
|
||||
type ImageRequest struct {
|
||||
Model string `json:"model"`
|
||||
Prompt string `json:"prompt"`
|
||||
// N is how many, at most 4.
|
||||
N int `json:"n,omitempty"`
|
||||
// Size is WIDTHxHEIGHT, each a multiple of 16 from 256 to 2048.
|
||||
Size string `json:"size,omitempty"`
|
||||
// ResponseFormat is b64_json, the only one offered.
|
||||
ResponseFormat string `json:"response_format,omitempty"`
|
||||
Seed *int64 `json:"seed,omitempty"`
|
||||
Steps int `json:"steps,omitempty"`
|
||||
NegativePrompt string `json:"negative_prompt,omitempty"`
|
||||
Guidance *float64 `json:"guidance,omitempty"`
|
||||
}
|
||||
|
||||
// Image is one picture.
|
||||
type Image struct {
|
||||
B64JSON string `json:"b64_json"`
|
||||
}
|
||||
|
||||
// ImagesResponse is the pictures made; x-llmgw-seed says the seed.
|
||||
type ImagesResponse struct {
|
||||
Created int64 `json:"created"`
|
||||
Data []Image `json:"data"`
|
||||
}
|
||||
|
||||
// ModerationRequest asks the guardrails' judge.
|
||||
type ModerationRequest struct {
|
||||
// Input is a string or up to 32 of them.
|
||||
Input json.RawMessage `json:"input"`
|
||||
Model string `json:"model,omitempty"`
|
||||
}
|
||||
|
||||
// ModerationResult is one input's verdict.
|
||||
type ModerationResult struct {
|
||||
Flagged bool `json:"flagged"`
|
||||
Categories map[string]bool `json:"categories"`
|
||||
CategoryScores map[string]float64 `json:"category_scores"`
|
||||
}
|
||||
|
||||
// ModerationResponse is every input's verdict.
|
||||
type ModerationResponse struct {
|
||||
ID string `json:"id"`
|
||||
Model string `json:"model"`
|
||||
Results []ModerationResult `json:"results"`
|
||||
}
|
||||
|
||||
// ResponsesRequest is OpenAI's Responses API, translated to chat completions.
|
||||
type ResponsesRequest struct {
|
||||
Model string `json:"model"`
|
||||
// Input is a string or a list of items: messages, function calls and
|
||||
// their outputs.
|
||||
Input json.RawMessage `json:"input"`
|
||||
Instructions string `json:"instructions,omitempty"`
|
||||
Stream bool `json:"stream,omitempty"`
|
||||
Tools json.RawMessage `json:"tools,omitempty"`
|
||||
// Text carries format: a JSON schema the answer follows.
|
||||
Text json.RawMessage `json:"text,omitempty"`
|
||||
MaxOutputTokens int `json:"max_output_tokens,omitempty"`
|
||||
}
|
||||
|
||||
// MessagesRequest is Anthropic's Messages API, translated to chat completions.
|
||||
type MessagesRequest struct {
|
||||
Model string `json:"model"`
|
||||
Messages json.RawMessage `json:"messages"`
|
||||
System json.RawMessage `json:"system,omitempty"`
|
||||
MaxTokens int `json:"max_tokens"`
|
||||
Stream bool `json:"stream,omitempty"`
|
||||
Tools json.RawMessage `json:"tools,omitempty"`
|
||||
}
|
||||
|
||||
// TokenCount is how many tokens a Messages request would be.
|
||||
type TokenCount struct {
|
||||
InputTokens int `json:"input_tokens"`
|
||||
}
|
||||
|
||||
// License is the terms what a model makes comes under.
|
||||
type License struct {
|
||||
Name string `json:"name"`
|
||||
URL string `json:"url,omitempty"`
|
||||
Notice string `json:"notice,omitempty"`
|
||||
}
|
||||
|
||||
// ModelInfo is a model a key may use.
|
||||
type ModelInfo struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Created int64 `json:"created"`
|
||||
OwnedBy string `json:"owned_by"`
|
||||
// ContextLength and MaxOutputTokens, where the catalog says.
|
||||
ContextLength int `json:"context_length,omitempty"`
|
||||
MaxOutputTokens int `json:"max_output_tokens,omitempty"`
|
||||
Description string `json:"description,omitempty"`
|
||||
// Capabilities: tools, vision, embeddings, images, meshes.
|
||||
Capabilities map[string]bool `json:"capabilities"`
|
||||
License *License `json:"license,omitempty"`
|
||||
}
|
||||
|
||||
// ModelList is the models a key may use.
|
||||
type ModelList struct {
|
||||
Object string `json:"object"`
|
||||
Data []ModelInfo `json:"data"`
|
||||
}
|
||||
|
||||
// FileForm is a file uploaded, as a form.
|
||||
type FileForm struct {
|
||||
File []byte `json:"file"`
|
||||
// Purpose is batch for a batch's input.
|
||||
Purpose string `json:"purpose"`
|
||||
}
|
||||
|
||||
// File is a file kept: a batch's input or output, a job's result.
|
||||
type File struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Bytes int64 `json:"bytes"`
|
||||
CreatedAt int64 `json:"created_at"`
|
||||
Filename string `json:"filename"`
|
||||
// Purpose is batch, batch_output or job_output.
|
||||
Purpose string `json:"purpose"`
|
||||
Status string `json:"status"`
|
||||
ExpiresAt int64 `json:"expires_at,omitempty"`
|
||||
}
|
||||
|
||||
// FileList is the caller's files.
|
||||
type FileList struct {
|
||||
Object string `json:"object"`
|
||||
Data []File `json:"data"`
|
||||
}
|
||||
|
||||
// Deleted says a thing is gone.
|
||||
type Deleted struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Deleted bool `json:"deleted"`
|
||||
}
|
||||
|
||||
// BatchRequest runs a file of requests, at the lowest priority.
|
||||
type BatchRequest struct {
|
||||
InputFileID string `json:"input_file_id"`
|
||||
// Endpoint is /v1/chat/completions, /v1/completions or /v1/embeddings.
|
||||
Endpoint string `json:"endpoint"`
|
||||
// CompletionWindow is 24h.
|
||||
CompletionWindow string `json:"completion_window"`
|
||||
Metadata map[string]string `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// RequestCounts is how a batch's lines went.
|
||||
type RequestCounts struct {
|
||||
Total int `json:"total"`
|
||||
Completed int `json:"completed"`
|
||||
Failed int `json:"failed"`
|
||||
}
|
||||
|
||||
// Batch is a batch and how far it is.
|
||||
type Batch struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Endpoint string `json:"endpoint"`
|
||||
InputFileID string `json:"input_file_id"`
|
||||
CompletionWindow string `json:"completion_window"`
|
||||
Status string `json:"status"`
|
||||
OutputFileID *string `json:"output_file_id"`
|
||||
ErrorFileID *string `json:"error_file_id"`
|
||||
CreatedAt int64 `json:"created_at"`
|
||||
InProgressAt *int64 `json:"in_progress_at"`
|
||||
ExpiresAt *int64 `json:"expires_at"`
|
||||
FinalizingAt *int64 `json:"finalizing_at"`
|
||||
CompletedAt *int64 `json:"completed_at"`
|
||||
FailedAt *int64 `json:"failed_at"`
|
||||
ExpiredAt *int64 `json:"expired_at"`
|
||||
CancellingAt *int64 `json:"cancelling_at"`
|
||||
CancelledAt *int64 `json:"cancelled_at"`
|
||||
RequestCounts RequestCounts `json:"request_counts"`
|
||||
Errors json.RawMessage `json:"errors"`
|
||||
Metadata json.RawMessage `json:"metadata"`
|
||||
}
|
||||
|
||||
// BatchList is the caller's batches.
|
||||
type BatchList struct {
|
||||
Object string `json:"object"`
|
||||
Data []Batch `json:"data"`
|
||||
HasMore bool `json:"has_more"`
|
||||
}
|
||||
|
||||
// MeshRequest asks for a 3D model from a picture, of a model that makes
|
||||
// them: a job.
|
||||
type MeshRequest struct {
|
||||
Model string `json:"model"`
|
||||
// Image is the picture, base64 or a data URL: PNG, JPEG or WebP, one
|
||||
// object on a plain background.
|
||||
Image string `json:"image"`
|
||||
Seed *int64 `json:"seed,omitempty"`
|
||||
Steps int `json:"steps,omitempty"`
|
||||
// Resolution is the model's grid, a multiple of 32 from 64 to 2048.
|
||||
Resolution int `json:"resolution,omitempty"`
|
||||
}
|
||||
|
||||
// JobProgress is how far along a job is.
|
||||
type JobProgress struct {
|
||||
// State is queued, running, done or failed.
|
||||
State string `json:"state"`
|
||||
// Ahead is how many wait before it, while queued.
|
||||
Ahead int `json:"ahead,omitempty"`
|
||||
NodeClass string `json:"node_class,omitempty"`
|
||||
Step int `json:"step,omitempty"`
|
||||
Steps int `json:"steps,omitempty"`
|
||||
Percent int `json:"percent,omitempty"`
|
||||
}
|
||||
|
||||
// JobUsage is what a finished job used.
|
||||
type JobUsage struct {
|
||||
PromptTokens int64 `json:"prompt_tokens"`
|
||||
CompletionTokens int64 `json:"completion_tokens"`
|
||||
Images int64 `json:"images"`
|
||||
Meshes int64 `json:"meshes"`
|
||||
}
|
||||
|
||||
// Job is a 3D model asked for: its status, progress and, when done, the
|
||||
// file its result is in.
|
||||
type Job struct {
|
||||
ID string `json:"id"`
|
||||
Object string `json:"object"`
|
||||
Endpoint string `json:"endpoint"`
|
||||
Model string `json:"model"`
|
||||
// Status is queued, running, cancelling, completed, failed, cancelled
|
||||
// or expired.
|
||||
Status string `json:"status"`
|
||||
Progress *JobProgress `json:"progress"`
|
||||
OutputFileID *string `json:"output_file_id"`
|
||||
ContentType *string `json:"content_type"`
|
||||
Error *ErrorBody `json:"error"`
|
||||
CreatedAt int64 `json:"created_at"`
|
||||
StartedAt *int64 `json:"started_at"`
|
||||
FinishedAt *int64 `json:"finished_at"`
|
||||
ExpiresAt *int64 `json:"expires_at"`
|
||||
Usage *JobUsage `json:"usage"`
|
||||
License *License `json:"license,omitempty"`
|
||||
}
|
||||
|
||||
// JobList is the caller's jobs.
|
||||
type JobList struct {
|
||||
Object string `json:"object"`
|
||||
Data []Job `json:"data"`
|
||||
HasMore bool `json:"has_more"`
|
||||
FirstID *string `json:"first_id"`
|
||||
LastID *string `json:"last_id"`
|
||||
}
|
||||
|
||||
// MemoryWrite is a note kept for the caller's project.
|
||||
type MemoryWrite struct {
|
||||
Text string `json:"text"`
|
||||
Tags []string `json:"tags,omitempty"`
|
||||
}
|
||||
|
||||
// MemoryNote is a note kept.
|
||||
type MemoryNote struct {
|
||||
Key string `json:"key"`
|
||||
Text string `json:"text"`
|
||||
Tags []string `json:"tags"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
}
|
||||
|
||||
// MemoryList is the project's notes.
|
||||
type MemoryList struct {
|
||||
Object string `json:"object"`
|
||||
Data []MemoryNote `json:"data"`
|
||||
}
|
||||
|
||||
// Me is the caller as the gateway sees it: its key, place and limits.
|
||||
type Me struct {
|
||||
Authenticated bool `json:"authenticated"`
|
||||
KeyID string `json:"key_id,omitempty"`
|
||||
Key string `json:"key,omitempty"`
|
||||
Project string `json:"project,omitempty"`
|
||||
Team string `json:"team,omitempty"`
|
||||
Organization string `json:"organization,omitempty"`
|
||||
// Limits and Usage are what applies and what has been used of it.
|
||||
Limits json.RawMessage `json:"limits,omitempty"`
|
||||
Usage json.RawMessage `json:"usage,omitempty"`
|
||||
}
|
||||
|
||||
// MCPRequest is a JSON-RPC 2.0 call to the gateway's MCP server: its tools
|
||||
// are the memory notes.
|
||||
type MCPRequest struct {
|
||||
JSONRPC string `json:"jsonrpc"`
|
||||
ID json.RawMessage `json:"id"`
|
||||
Method string `json:"method"`
|
||||
Params json.RawMessage `json:"params,omitempty"`
|
||||
}
|
||||
|
||||
// KBDeleted says a document left a collection.
|
||||
type KBDeleted struct {
|
||||
Name string `json:"name"`
|
||||
Deleted bool `json:"deleted"`
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
package clientapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/router"
|
||||
)
|
||||
|
||||
type (
|
||||
// Route and Param are the admin API's, which one generator reads.
|
||||
Route = adminapi.Route
|
||||
Param = adminapi.Param
|
||||
)
|
||||
|
||||
// PathParams describes the parameters in Routes' paths.
|
||||
var PathParams = map[string]string{
|
||||
"files/{id}": "The file's ID, file-….",
|
||||
"batches/{id}": "The batch's ID, batch_….",
|
||||
"generations/{id}": "The job's ID, job_….",
|
||||
"threads/{id}": "The conversation's ID, as sent in x-llmgw-thread.",
|
||||
"memory/{key}": "The note's key, chosen by the caller.",
|
||||
"collections/{id}": "The collection's ID, its name when that is unique, or ORG/NAME.",
|
||||
}
|
||||
|
||||
// any is a body whose shape is the engine's or the provider's own.
|
||||
var anyJSON = json.RawMessage{}
|
||||
|
||||
// Routes is every endpoint the client API serves, but /health, /ready and
|
||||
// /leader, which are a load balancer's and need no key.
|
||||
var Routes = []Route{
|
||||
{Method: "POST", Path: "/v1/chat/completions", Summary: "A chat turn",
|
||||
Description: "A model's name, an alias, or an adapter's name. Fields not listed go to the engine as sent. " +
|
||||
"With a knowledge base, x-llmgw-knowledge names the collections to answer from; x-llmgw-thread continues a stored conversation.",
|
||||
Request: ChatCompletionRequest{}, Response: ChatCompletion{}, Stream: true},
|
||||
{Method: "POST", Path: "/v1/completions", Summary: "A prompt continued",
|
||||
Request: CompletionRequest{}, Response: Completion{}, Stream: true},
|
||||
{Method: "POST", Path: "/v1/embeddings", Summary: "Vectors for texts",
|
||||
Request: EmbeddingRequest{}, Response: EmbeddingList{}},
|
||||
{Method: "POST", Path: "/v1/rerank", Summary: "Documents ordered by a query, for a reranker vLLM serves",
|
||||
Request: RerankRequest{}, Response: anyJSON},
|
||||
{Method: "POST", Path: "/v1/score", Summary: "Pairs of texts scored, for a scorer vLLM serves",
|
||||
Request: ScoreRequest{}, Response: anyJSON},
|
||||
{Method: "POST", Path: "/v1/audio/transcriptions", Summary: "Speech to text",
|
||||
Request: TranscriptionForm{}, Form: true, Response: Transcription{}},
|
||||
{Method: "POST", Path: "/v1/audio/translations", Summary: "Speech to English text",
|
||||
Request: TranscriptionForm{}, Form: true, Response: Transcription{}},
|
||||
{Method: "POST", Path: "/v1/images/generations", Summary: "Pictures, of a model that makes them",
|
||||
Description: "Made by ComfyUI. Pictures come back as b64_json and are kept nowhere; x-llmgw-seed says the seed.",
|
||||
Request: ImageRequest{}, Response: ImagesResponse{}},
|
||||
{Method: "POST", Path: "/v1/3d/generations", Summary: "A 3D model from a picture, as a job",
|
||||
Description: "Answered 202 with the job; ask after it until it is completed, then download output_file_id from /v1/files.",
|
||||
Request: MeshRequest{}, Response: Job{}, Status: 202},
|
||||
{Method: "GET", Path: "/v1/3d/generations", Summary: "The caller's 3D jobs, newest first",
|
||||
Query: []Param{
|
||||
{Name: "limit", Type: "integer", Description: "The most jobs to answer with, at most 100; 20 when absent."},
|
||||
{Name: "after", Description: "A job's ID: those asked for before it."},
|
||||
},
|
||||
Response: JobList{}},
|
||||
{Method: "GET", Path: "/v1/3d/generations/{id}", Summary: "A 3D job: its status, progress and result", Response: Job{}},
|
||||
{Method: "POST", Path: "/v1/3d/generations/{id}/cancel", Summary: "Stop a 3D job, in the engine's queue too", Response: Job{}},
|
||||
{Method: "POST", Path: "/v1/moderations", Summary: "Texts judged by the guardrails' judge model",
|
||||
Request: ModerationRequest{}, Response: ModerationResponse{}},
|
||||
{Method: "POST", Path: "/v1/responses", Summary: "OpenAI's Responses API, for Codex and the like",
|
||||
Request: ResponsesRequest{}, Response: anyJSON, Stream: true},
|
||||
{Method: "POST", Path: "/v1/messages", Summary: "Anthropic's Messages API, for Claude Code and Anthropic's SDKs",
|
||||
Description: "The key is sent as x-api-key or as a bearer token.",
|
||||
Request: MessagesRequest{}, Response: anyJSON, Stream: true},
|
||||
{Method: "POST", Path: "/v1/messages/count_tokens", Summary: "How many tokens a Messages request would be",
|
||||
Request: MessagesRequest{}, Response: TokenCount{}},
|
||||
{Method: "GET", Path: "/v1/models", Summary: "The models the key may use", Response: ModelList{}},
|
||||
{Method: "POST", Path: "/v1/files", Summary: "Upload a file: a batch's input",
|
||||
Request: FileForm{}, Form: true, Response: File{}},
|
||||
{Method: "GET", Path: "/v1/files", Summary: "The caller's files",
|
||||
Query: []Param{{Name: "purpose", Description: "Only files of this purpose: batch, batch_output, job_output."}},
|
||||
Response: FileList{}},
|
||||
{Method: "GET", Path: "/v1/files/{id}", Summary: "A file", Response: File{}},
|
||||
{Method: "GET", Path: "/v1/files/{id}/content", Summary: "A file's content",
|
||||
Binary: "application/octet-stream"},
|
||||
{Method: "DELETE", Path: "/v1/files/{id}", Summary: "Delete a file", Response: Deleted{}},
|
||||
{Method: "POST", Path: "/v1/batches", Summary: "Run a file of requests at the lowest priority",
|
||||
Request: BatchRequest{}, Response: Batch{}},
|
||||
{Method: "GET", Path: "/v1/batches", Summary: "The caller's batches",
|
||||
Query: []Param{
|
||||
{Name: "limit", Type: "integer", Description: "The most batches to answer with; 20 when absent."},
|
||||
{Name: "after", Description: "A batch's ID: those made before it."},
|
||||
},
|
||||
Response: BatchList{}},
|
||||
{Method: "GET", Path: "/v1/batches/{id}", Summary: "A batch and how far it is", Response: Batch{}},
|
||||
{Method: "POST", Path: "/v1/batches/{id}/cancel", Summary: "Stop a batch", Response: Batch{}},
|
||||
{Method: "DELETE", Path: "/v1/threads/{id}", Summary: "Forget a stored conversation"},
|
||||
{Method: "PUT", Path: "/v1/memory/{key}", Summary: "Keep a note for the project",
|
||||
Request: MemoryWrite{}, Response: MemoryNote{}},
|
||||
{Method: "GET", Path: "/v1/memory/{key}", Summary: "A note", Response: MemoryNote{}},
|
||||
{Method: "GET", Path: "/v1/memory", Summary: "The project's notes", Response: MemoryList{}},
|
||||
{Method: "DELETE", Path: "/v1/memory/{key}", Summary: "Forget a note"},
|
||||
{Method: "POST", Path: "/mcp", Summary: "The gateway's MCP server: the memory notes as tools",
|
||||
Request: MCPRequest{}, Response: anyJSON},
|
||||
{Method: "GET", Path: "/me", Summary: "The caller: its key, its place in the tree, its limits and what it has used",
|
||||
Response: Me{}},
|
||||
{Method: "GET", Path: "/v1/kb/collections", Summary: "The knowledge-base collections the caller may read",
|
||||
Response: []router.KBCollectionView{}},
|
||||
{Method: "GET", Path: "/v1/kb/collections/{id}/manifest", Summary: "A collection and its documents",
|
||||
Response: router.KBManifest{}},
|
||||
{Method: "PUT", Path: "/v1/kb/collections/{id}/documents", Summary: "Add or replace a document, read and embedded by the client",
|
||||
Request: router.KBPutDocument{}, Response: router.KBPutResult{}},
|
||||
{Method: "DELETE", Path: "/v1/kb/collections/{id}/documents", Summary: "Take a document out of a collection",
|
||||
Query: []Param{{Name: "name", Required: true, Description: "The document's name, as the manifest lists it."}},
|
||||
Response: KBDeleted{}},
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
package clientapi
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"runtime"
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// routerRoutes are the client API's routes as the router mounts them, read
|
||||
// from its source: every mux.HandleFunc under /v1, /mcp and /me, with the
|
||||
// path constants it builds some of them from put back.
|
||||
func routerRoutes(t *testing.T) []string {
|
||||
t.Helper()
|
||||
_, file, _, _ := runtime.Caller(0)
|
||||
dir := filepath.Join(filepath.Dir(file), "..", "router")
|
||||
consts := map[string]string{"imagesPath": "/v1/images/generations", "meshesPath": "/v1/3d/generations"}
|
||||
literal := regexp.MustCompile(`mux\.HandleFunc\("([A-Z]+) (/[^"]*)"`)
|
||||
built := regexp.MustCompile(`mux\.HandleFunc\("([A-Z]+) "\+([A-Za-z]+Path)(\+"([^"]*)")?`)
|
||||
files, _ := filepath.Glob(filepath.Join(dir, "*.go"))
|
||||
var out []string
|
||||
add := func(method, path string) {
|
||||
if strings.HasPrefix(path, "/v1/") || path == "/mcp" || path == "/me" {
|
||||
out = append(out, method+" "+path)
|
||||
}
|
||||
}
|
||||
for _, f := range files {
|
||||
if strings.HasSuffix(f, "_test.go") {
|
||||
continue
|
||||
}
|
||||
b, _ := os.ReadFile(f)
|
||||
for _, m := range literal.FindAllStringSubmatch(string(b), -1) {
|
||||
add(m[1], m[2])
|
||||
}
|
||||
for _, m := range built.FindAllStringSubmatch(string(b), -1) {
|
||||
c, ok := consts[m[2]]
|
||||
if !ok {
|
||||
t.Fatalf("a route built from %s, which this test does not know", m[2])
|
||||
}
|
||||
add(m[1], c+m[4])
|
||||
}
|
||||
}
|
||||
slices.Sort(out)
|
||||
return slices.Compact(out)
|
||||
}
|
||||
|
||||
func TestEveryClientRouteIsDescribedAndNothingElse(t *testing.T) {
|
||||
// An endpoint added to the router and not to this table would be missing
|
||||
// from the document every SDK is generated from; one here and not in the
|
||||
// router would be a path that answers 404.
|
||||
mounted := routerRoutes(t)
|
||||
if len(mounted) < 30 {
|
||||
t.Fatalf("read only %d routes from the router: %v", len(mounted), mounted)
|
||||
}
|
||||
var described []string
|
||||
for _, r := range Routes {
|
||||
described = append(described, r.Method+" "+r.Path)
|
||||
}
|
||||
slices.Sort(described)
|
||||
for _, m := range mounted {
|
||||
if m == "GET /v1/openapi.json" {
|
||||
continue // the document itself
|
||||
}
|
||||
if !slices.Contains(described, m) {
|
||||
t.Errorf("%s is mounted and not described in clientapi.Routes", m)
|
||||
}
|
||||
}
|
||||
for _, d := range described {
|
||||
if !slices.Contains(mounted, d) {
|
||||
t.Errorf("%s is described and not mounted", d)
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user