aboutsummaryrefslogtreecommitdiff
path: root/tools/openapi.yaml
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-20 20:31:06 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-21 06:00:26 +0200
commitdbdf714bb57578431924e5d069089bdfd9f4c604 (patch)
tree4f5b59ef132220310e1e4b1dde64f5e38782369a /tools/openapi.yaml
parente9ecaeaf21050f39888d33d2c8f4216d595d4975 (diff)
downloadffwd-dbdf714bb57578431924e5d069089bdfd9f4c604.tar.gz
ffwd-dbdf714bb57578431924e5d069089bdfd9f4c604.zip
devtools: add scripts for unicode generation, model inspection, embedding ranking, and more
Diffstat (limited to 'tools/openapi.yaml')
-rw-r--r--tools/openapi.yaml249
1 files changed, 0 insertions, 249 deletions
diff --git a/tools/openapi.yaml b/tools/openapi.yaml
deleted file mode 100644
index 6dd3818..0000000
--- a/tools/openapi.yaml
+++ /dev/null
@@ -1,249 +0,0 @@
-openapi: 3.0.3
-info:
- title: embed.c server API
- version: "1.0.0"
- description: >
- HTTP API served by `embed-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 EMBED_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 `embed-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" }