Skip to content

Commit d0d0393

Browse files
tisniktisnik
authored
Merge pull request #560 from radofuchs/LCORE_432_update_doc_endpoints
LCORE-432: update doc for endpoints
2 parents 5eb2caa + 911945d commit d0d0393

File tree

9 files changed

+219
-31
lines changed

9 files changed

+219
-31
lines changed

‎docs/openapi.json‎

Lines changed: 108 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
"info"
5151
],
5252
"summary": "Info Endpoint Handler",
53-
"description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name and version.\n\nReturns:\n InfoResponse: An object containing the service's name and version.",
53+
"description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nReturns:\n InfoResponse: An object containing the service's name and version.",
5454
"operationId": "info_endpoint_handler_v1_info_get",
5555
"responses": {
5656
"200": {
@@ -117,7 +117,7 @@
117117
}
118118
]
119119
},
120-
"503": {
120+
"500": {
121121
"description": "Connection to Llama Stack is broken"
122122
}
123123
}
@@ -174,8 +174,8 @@
174174
}
175175
}
176176
},
177-
"503": {
178-
"description": "Service Unavailable",
177+
"500": {
178+
"description": "Internal Server Error",
179179
"detail": {
180180
"response": "Unable to connect to Llama Stack",
181181
"cause": "Connection error."
@@ -214,13 +214,56 @@
214214
},
215215
"responses": {
216216
"200": {
217-
"description": "Successful Response",
217+
"description": "Streaming response with Server-Sent Events",
218218
"content": {
219219
"application/json": {
220220
"schema": {}
221+
},
222+
"text/event-stream": {
223+
"schema": {
224+
"type": "string",
225+
"example": "data: {\"event\": \"start\", \"data\": {\"conversation_id\": \"123e4567-e89b-12d3-a456-426614174000\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 0, \"role\": \"inference\", \"token\": \"Hello\"}}\n\ndata: {\"event\": \"end\", \"data\": {\"referenced_documents\": [], \"truncated\": null, \"input_tokens\": 0, \"output_tokens\": 0}, \"available_quotas\": {}}\n\n"
226+
}
227+
}
228+
}
229+
},
230+
"400": {
231+
"description": "Missing or invalid credentials provided by client",
232+
"content": {
233+
"application/json": {
234+
"schema": {
235+
"$ref": "#/components/schemas/UnauthorizedResponse"
236+
}
237+
}
238+
}
239+
},
240+
"401": {
241+
"description": "Unauthorized: Invalid or missing Bearer token for k8s auth",
242+
"content": {
243+
"application/json": {
244+
"schema": {
245+
"$ref": "#/components/schemas/UnauthorizedResponse"
246+
}
247+
}
248+
}
249+
},
250+
"403": {
251+
"description": "User is not authorized",
252+
"content": {
253+
"application/json": {
254+
"schema": {
255+
"$ref": "#/components/schemas/ForbiddenResponse"
256+
}
221257
}
222258
}
223259
},
260+
"500": {
261+
"description": "Internal Server Error",
262+
"detail": {
263+
"response": "Unable to connect to Llama Stack",
264+
"cause": "Connection error."
265+
}
266+
},
224267
"422": {
225268
"description": "Validation Error",
226269
"content": {
@@ -473,6 +516,26 @@
473516
}
474517
]
475518
},
519+
"400": {
520+
"description": "Missing or invalid credentials provided by client",
521+
"content": {
522+
"application/json": {
523+
"schema": {
524+
"$ref": "#/components/schemas/UnauthorizedResponse"
525+
}
526+
}
527+
}
528+
},
529+
"401": {
530+
"description": "Unauthorized: Invalid or missing Bearer token",
531+
"content": {
532+
"application/json": {
533+
"schema": {
534+
"$ref": "#/components/schemas/UnauthorizedResponse"
535+
}
536+
}
537+
}
538+
},
476539
"503": {
477540
"description": "Service Unavailable",
478541
"detail": {
@@ -530,6 +593,26 @@
530593
}
531594
]
532595
},
596+
"400": {
597+
"description": "Missing or invalid credentials provided by client",
598+
"content": {
599+
"application/json": {
600+
"schema": {
601+
"$ref": "#/components/schemas/UnauthorizedResponse"
602+
}
603+
}
604+
}
605+
},
606+
"401": {
607+
"description": "Unauthorized: Invalid or missing Bearer token",
608+
"content": {
609+
"application/json": {
610+
"schema": {
611+
"$ref": "#/components/schemas/UnauthorizedResponse"
612+
}
613+
}
614+
}
615+
},
533616
"404": {
534617
"detail": {
535618
"response": "Conversation not found",
@@ -588,6 +671,26 @@
588671
"success": true,
589672
"message": "Conversation deleted successfully"
590673
},
674+
"400": {
675+
"description": "Missing or invalid credentials provided by client",
676+
"content": {
677+
"application/json": {
678+
"schema": {
679+
"$ref": "#/components/schemas/UnauthorizedResponse"
680+
}
681+
}
682+
}
683+
},
684+
"401": {
685+
"description": "Unauthorized: Invalid or missing Bearer token",
686+
"content": {
687+
"application/json": {
688+
"schema": {
689+
"$ref": "#/components/schemas/UnauthorizedResponse"
690+
}
691+
}
692+
}
693+
},
591694
"404": {
592695
"detail": {
593696
"response": "Conversation not found",

‎docs/openapi.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Handle request to the / endpoint.
3434
Handle request to the /info endpoint.
3535

3636
Process GET requests to the /info endpoint, returning the
37-
service name and version.
37+
service name, version and Llama-stack version.
3838

3939
Returns:
4040
InfoResponse: An object containing the service's name and version.
@@ -74,7 +74,7 @@ Returns:
7474
| Status Code | Description | Component |
7575
|-------------|-------------|-----------|
7676
| 200 | Successful Response | [ModelsResponse](#modelsresponse) |
77-
| 503 | Connection to Llama Stack is broken | |
77+
| 500 | Connection to Llama Stack is broken | |
7878
## POST `/v1/query`
7979

8080
> **Query Endpoint Handler**
@@ -108,7 +108,7 @@ Returns:
108108
| 200 | Successful Response | [QueryResponse](#queryresponse) |
109109
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
110110
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
111-
| 503 | Service Unavailable | |
111+
| 500 | Internal Server Error | |
112112
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
113113
## POST `/v1/streaming_query`
114114

@@ -143,7 +143,11 @@ Raises:
143143

144144
| Status Code | Description | Component |
145145
|-------------|-------------|-----------|
146-
| 200 | Successful Response | ... |
146+
| 200 | Streaming response with Server-Sent Events | ...string |
147+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
148+
| 401 | Unauthorized: Invalid or missing Bearer token for k8s auth | [UnauthorizedResponse](#unauthorizedresponse) |
149+
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
150+
| 500 | Internal Server Error | |
147151
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
148152
## GET `/v1/config`
149153

@@ -269,6 +273,8 @@ Handle request to retrieve all conversations for the authenticated user.
269273
| Status Code | Description | Component |
270274
|-------------|-------------|-----------|
271275
| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) |
276+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
277+
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
272278
| 503 | Service Unavailable | |
273279
## GET `/v1/conversations/{conversation_id}`
274280

@@ -304,6 +310,8 @@ Returns:
304310
| Status Code | Description | Component |
305311
|-------------|-------------|-----------|
306312
| 200 | Successful Response | [ConversationResponse](#conversationresponse) |
313+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
314+
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
307315
| 404 | Not Found | |
308316
| 503 | Service Unavailable | |
309317
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
@@ -335,6 +343,8 @@ Returns:
335343
| Status Code | Description | Component |
336344
|-------------|-------------|-----------|
337345
| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) |
346+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
347+
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
338348
| 404 | Not Found | |
339349
| 503 | Service Unavailable | |
340350
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
@@ -769,15 +779,6 @@ Example:
769779
user_question="what are you doing?",
770780
user_feedback="This response is not helpful",
771781
llm_response="I don't know",
772-
sentiment=1
773-
)
774-
775-
# Feedback with categories
776-
feedback_request = FeedbackRequest(
777-
conversation_id="12345678-abcd-0000-0123-456789abcdef",
778-
user_question="How do I deploy a web app?",
779-
llm_response="You need to use Docker and Kubernetes for everything.",
780-
user_feedback="This response is too general and doesn't provide specific steps.",
781782
sentiment=-1,
782783
categories=[FeedbackCategory.INCORRECT, FeedbackCategory.INCOMPLETE]
783784
)

‎docs/output.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Handle request to the / endpoint.
3434
Handle request to the /info endpoint.
3535

3636
Process GET requests to the /info endpoint, returning the
37-
service name and version.
37+
service name, version and Llama-stack version.
3838

3939
Returns:
4040
InfoResponse: An object containing the service's name and version.
@@ -74,7 +74,7 @@ Returns:
7474
| Status Code | Description | Component |
7575
|-------------|-------------|-----------|
7676
| 200 | Successful Response | [ModelsResponse](#modelsresponse) |
77-
| 503 | Connection to Llama Stack is broken | |
77+
| 500 | Connection to Llama Stack is broken | |
7878
## POST `/v1/query`
7979

8080
> **Query Endpoint Handler**
@@ -108,7 +108,7 @@ Returns:
108108
| 200 | Successful Response | [QueryResponse](#queryresponse) |
109109
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
110110
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
111-
| 503 | Service Unavailable | |
111+
| 500 | Internal Server Error | |
112112
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
113113
## POST `/v1/streaming_query`
114114

@@ -143,7 +143,11 @@ Raises:
143143

144144
| Status Code | Description | Component |
145145
|-------------|-------------|-----------|
146-
| 200 | Successful Response | ... |
146+
| 200 | Streaming response with Server-Sent Events | ...string |
147+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
148+
| 401 | Unauthorized: Invalid or missing Bearer token for k8s auth | [UnauthorizedResponse](#unauthorizedresponse) |
149+
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
150+
| 500 | Internal Server Error | |
147151
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
148152
## GET `/v1/config`
149153

@@ -269,6 +273,8 @@ Handle request to retrieve all conversations for the authenticated user.
269273
| Status Code | Description | Component |
270274
|-------------|-------------|-----------|
271275
| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) |
276+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
277+
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
272278
| 503 | Service Unavailable | |
273279
## GET `/v1/conversations/{conversation_id}`
274280

@@ -304,6 +310,8 @@ Returns:
304310
| Status Code | Description | Component |
305311
|-------------|-------------|-----------|
306312
| 200 | Successful Response | [ConversationResponse](#conversationresponse) |
313+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
314+
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
307315
| 404 | Not Found | |
308316
| 503 | Service Unavailable | |
309317
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
@@ -335,6 +343,8 @@ Returns:
335343
| Status Code | Description | Component |
336344
|-------------|-------------|-----------|
337345
| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) |
346+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
347+
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
338348
| 404 | Not Found | |
339349
| 503 | Service Unavailable | |
340350
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |

‎src/app/endpoints/conversations.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
ConversationDeleteResponse,
2020
ConversationsListResponse,
2121
ConversationDetails,
22+
UnauthorizedResponse,
2223
)
2324
from utils.endpoints import (
2425
check_configuration_loaded,
@@ -45,6 +46,14 @@
4546
}
4647
],
4748
},
49+
400: {
50+
"description": "Missing or invalid credentials provided by client",
51+
"model": UnauthorizedResponse,
52+
},
53+
401: {
54+
"description": "Unauthorized: Invalid or missing Bearer token",
55+
"model": UnauthorizedResponse,
56+
},
4857
404: {
4958
"detail": {
5059
"response": "Conversation not found",
@@ -65,6 +74,14 @@
6574
"success": True,
6675
"message": "Conversation deleted successfully",
6776
},
77+
400: {
78+
"description": "Missing or invalid credentials provided by client",
79+
"model": UnauthorizedResponse,
80+
},
81+
401: {
82+
"description": "Unauthorized: Invalid or missing Bearer token",
83+
"model": UnauthorizedResponse,
84+
},
6885
404: {
6986
"detail": {
7087
"response": "Conversation not found",
@@ -100,6 +117,14 @@
100117
},
101118
]
102119
},
120+
400: {
121+
"description": "Missing or invalid credentials provided by client",
122+
"model": UnauthorizedResponse,
123+
},
124+
401: {
125+
"description": "Unauthorized: Invalid or missing Bearer token",
126+
"model": UnauthorizedResponse,
127+
},
103128
503: {
104129
"detail": {
105130
"response": "Unable to connect to Llama Stack",

‎src/app/endpoints/info.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ async def info_endpoint_handler(
4747
Handle request to the /info endpoint.
4848
4949
Process GET requests to the /info endpoint, returning the
50-
service name and version.
50+
service name, version and Llama-stack version.
5151
5252
Returns:
5353
InfoResponse: An object containing the service's name and version.

‎src/app/endpoints/models.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@
4646
},
4747
]
4848
},
49-
503: {"description": "Connection to Llama Stack is broken"},
49+
500: {"description": "Connection to Llama Stack is broken"},
5050
}
5151

5252

‎src/app/endpoints/query.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
"description": "User is not authorized",
6060
"model": ForbiddenResponse,
6161
},
62-
503: {
62+
500: {
6363
"detail": {
6464
"response": "Unable to connect to Llama Stack",
6565
"cause": "Connection error.",

0 commit comments

Comments
 (0)