aboutsummaryrefslogtreecommitdiff
path: root/devtools/openapi.yaml
diff options
context:
space:
mode:
Diffstat (limited to 'devtools/openapi.yaml')
-rw-r--r--devtools/openapi.yaml249
1 files changed, 249 insertions, 0 deletions
diff --git a/devtools/openapi.yaml b/devtools/openapi.yaml
new file mode 100644
index 0000000..5140186
--- /dev/null
+++ b/devtools/openapi.yaml
@@ -0,0 +1,249 @@
+openapi: 3.0.3
+info:
+ title: ffwd server API
+ version: "1.0.0"
+ description: >
+ HTTP API served by `ffwd-server`. Each loaded model has an operator-chosen
+ label; request `model` fields match that label. Embedding encoding follows
+ the serving API selected at load time (`api=openai` or `api=perplexity`).
+ Always compare embeddings with cosine similarity.
+ license:
+ name: MIT
+servers:
+ - url: http://127.0.0.1:8000
+# Auth is optional: it applies only when the server is started with --api-key
+# (or FFWD_API_KEY). The empty requirement allows unauthenticated calls.
+security:
+ - {}
+ - bearerAuth: []
+paths:
+ /v1/embeddings:
+ post:
+ summary: Create pooled embeddings
+ operationId: createEmbeddings
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/EmbeddingsRequest" }
+ responses:
+ "200":
+ description: One embedding per input, in request order.
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/EmbeddingsResponse" }
+ "422": { $ref: "#/components/responses/ValidationError" }
+ /v1/contextualizedembeddings:
+ post:
+ summary: Create contextual (late-chunking) document embeddings
+ operationId: createContextualizedEmbeddings
+ description: >
+ Each document is a list of chunk strings. Chunks are embedded with
+ document-level context and returned per document, per chunk, in order.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/ContextualRequest" }
+ responses:
+ "200":
+ description: One list of chunk embeddings per document, in order.
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/ContextualResponse" }
+ "422": { $ref: "#/components/responses/ValidationError" }
+ /v1/rerank:
+ post:
+ summary: Late-interaction (MaxSim) reranking
+ operationId: rerank
+ description: >
+ Scores each document against the query with token-level MaxSim and
+ returns documents ranked by raw score (not a probability).
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/RerankRequest" }
+ responses:
+ "200":
+ description: Documents ranked by descending relevance score.
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/RerankResponse" }
+ "422": { $ref: "#/components/responses/ValidationError" }
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ description: >
+ Single shared token set with --api-key. Not a real auth system;
+ terminate TLS and authenticate at a reverse proxy in production.
+ schemas:
+ EmbeddingsRequest:
+ type: object
+ required: [model, input]
+ properties:
+ model:
+ type: string
+ description: Served label chosen when starting `ffwd-server`.
+ example: qwen
+ input:
+ description: A single string or an array of up to 512 strings.
+ oneOf:
+ - type: string
+ - type: array
+ items: { type: string }
+ minItems: 1
+ maxItems: 512
+ encoding_format:
+ type: string
+ description: >
+ Output encoding, validated against the serving API selected for the
+ loaded label. `api=openai` accepts `float` (default; true float32)
+ and `base64` (base64 of little-endian float32). `api=perplexity`
+ accepts `base64_int8` (default), `base64_binary` (sign bits, needs
+ `dimensions` divisible by 8), and `float` (the int8-decoded view).
+ A format outside the label's serving API returns 422.
+ enum: [float, base64, base64_int8, base64_binary]
+ dimensions:
+ type: integer
+ description: >
+ Matryoshka truncation, from the configured load-time `min_dim` up to
+ the model's native dimension. Truncated normalized vectors are
+ re-normalized.
+ EmbeddingsResponse:
+ type: object
+ properties:
+ object: { type: string, example: list }
+ data:
+ type: array
+ items: { $ref: "#/components/schemas/Embedding" }
+ model: { type: string }
+ usage: { $ref: "#/components/schemas/Usage" }
+ Embedding:
+ type: object
+ properties:
+ object: { type: string, example: embedding }
+ index: { type: integer }
+ embedding:
+ description: >
+ A float array when `encoding_format` is `float`, otherwise a base64
+ string (`base64`, `base64_int8`, or `base64_binary`).
+ oneOf:
+ - type: array
+ items: { type: number, format: float }
+ - type: string
+ ContextualRequest:
+ type: object
+ required: [model, input]
+ properties:
+ model:
+ type: string
+ description: Served contextual-model label.
+ example: pplx-context
+ input:
+ description: Array of documents; each document is an array of chunk strings.
+ type: array
+ items:
+ type: array
+ items: { type: string }
+ minItems: 1
+ encoding_format:
+ type: string
+ enum: [float, base64, base64_int8, base64_binary]
+ dimensions: { type: integer }
+ ContextualResponse:
+ type: object
+ properties:
+ object: { type: string, example: list }
+ data:
+ type: array
+ description: One entry per document, in request order.
+ items:
+ type: object
+ properties:
+ object: { type: string, example: list }
+ index: { type: integer }
+ data:
+ type: array
+ description: One embedding per chunk, in document order.
+ items: { $ref: "#/components/schemas/Embedding" }
+ model: { type: string }
+ usage: { $ref: "#/components/schemas/Usage" }
+ RerankRequest:
+ type: object
+ required: [model, query, documents]
+ properties:
+ model:
+ type: string
+ description: Served late-model label.
+ example: pplx-late
+ query: { type: string }
+ documents:
+ type: array
+ items: { type: string }
+ minItems: 1
+ maxItems: 1000
+ top_n:
+ type: integer
+ description: Number of results to return. Defaults to all. `top_k` is an alias.
+ top_k:
+ type: integer
+ return_documents:
+ type: boolean
+ default: false
+ description: Include the source document text in each result.
+ additionalProperties: false
+ RerankResponse:
+ type: object
+ properties:
+ object: { type: string, example: list }
+ model: { type: string }
+ results:
+ type: array
+ items:
+ type: object
+ properties:
+ index:
+ type: integer
+ description: Index of the document in the request array.
+ relevance_score:
+ type: number
+ format: float
+ description: Raw MaxSim score (not a probability).
+ document:
+ type: string
+ description: Present only when `return_documents` is true.
+ usage:
+ type: object
+ properties:
+ query_tokens: { type: integer }
+ document_tokens: { type: integer }
+ total_tokens: { type: integer }
+ Usage:
+ type: object
+ properties:
+ prompt_tokens: { type: integer }
+ total_tokens: { type: integer }
+ ValidationDetail:
+ type: object
+ properties:
+ loc:
+ type: array
+ description: Path to the offending field, e.g. ["body","input",0].
+ items: {}
+ msg: { type: string }
+ type: { type: string }
+ ValidationError:
+ type: object
+ properties:
+ detail:
+ type: array
+ items: { $ref: "#/components/schemas/ValidationDetail" }
+ responses:
+ ValidationError:
+ description: Request body failed validation.
+ content:
+ application/json:
+ schema: { $ref: "#/components/schemas/ValidationError" }