aboutsummaryrefslogtreecommitdiff
path: root/devtools/openapi.yaml
blob: 5140186329a159826ea9566caedaa44d144d3c99 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
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" }