From 224c99560c55cc2cc368c13f3c3d11c4b1a13633 Mon Sep 17 00:00:00 2001 From: Alexey Rybak <50731695+reluctantfuturist@users.noreply.github.com> Date: Fri, 17 Oct 2025 10:41:50 -0700 Subject: [PATCH] docs: update docstrings for better formatting (#3838) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # What does this PR do? Updates docstrings for Conversations and Eval APIs to render better in the docs nav sidebar. Before: Screenshot 2025-10-17 at 9 52 17 AM After: Screenshot 2025-10-17 at 9 52 11 AM ## Test Plan * Manual testing --- docs/docs/providers/eval/index.mdx | 8 ++- docs/static/deprecated-llama-stack-spec.html | 4 +- docs/static/deprecated-llama-stack-spec.yaml | 4 +- .../static/experimental-llama-stack-spec.html | 4 +- .../static/experimental-llama-stack-spec.yaml | 4 +- docs/static/llama-stack-spec.html | 34 +++++------ docs/static/llama-stack-spec.yaml | 56 +++++++++++------ docs/static/stainless-llama-stack-spec.html | 38 ++++++------ docs/static/stainless-llama-stack-spec.yaml | 60 +++++++++++++------ .../apis/conversations/conversations.py | 34 ++++++++--- llama_stack/apis/eval/eval.py | 4 +- 11 files changed, 159 insertions(+), 91 deletions(-) diff --git a/docs/docs/providers/eval/index.mdx b/docs/docs/providers/eval/index.mdx index 73b0b89aa..94bafe15e 100644 --- a/docs/docs/providers/eval/index.mdx +++ b/docs/docs/providers/eval/index.mdx @@ -1,5 +1,7 @@ --- -description: "Llama Stack Evaluation API for running evaluations on model and agent candidates." +description: "Evaluations + + Llama Stack Evaluation API for running evaluations on model and agent candidates." sidebar_label: Eval title: Eval --- @@ -8,6 +10,8 @@ title: Eval ## Overview -Llama Stack Evaluation API for running evaluations on model and agent candidates. +Evaluations + + Llama Stack Evaluation API for running evaluations on model and agent candidates. This section contains documentation for all available providers for the **eval** API. diff --git a/docs/static/deprecated-llama-stack-spec.html b/docs/static/deprecated-llama-stack-spec.html index e5c02381b..60a8b9fbd 100644 --- a/docs/static/deprecated-llama-stack-spec.html +++ b/docs/static/deprecated-llama-stack-spec.html @@ -13449,8 +13449,8 @@ }, { "name": "Eval", - "description": "", - "x-displayName": "Llama Stack Evaluation API for running evaluations on model and agent candidates." + "description": "Llama Stack Evaluation API for running evaluations on model and agent candidates.", + "x-displayName": "Evaluations" }, { "name": "Files", diff --git a/docs/static/deprecated-llama-stack-spec.yaml b/docs/static/deprecated-llama-stack-spec.yaml index 43f748d14..aaa6cd413 100644 --- a/docs/static/deprecated-llama-stack-spec.yaml +++ b/docs/static/deprecated-llama-stack-spec.yaml @@ -10196,9 +10196,9 @@ tags: - name: Datasets description: '' - name: Eval - description: '' - x-displayName: >- + description: >- Llama Stack Evaluation API for running evaluations on model and agent candidates. + x-displayName: Evaluations - name: Files description: >- This API is used to upload documents that can be used with other Llama Stack diff --git a/docs/static/experimental-llama-stack-spec.html b/docs/static/experimental-llama-stack-spec.html index e3edf2ffc..7d572f89f 100644 --- a/docs/static/experimental-llama-stack-spec.html +++ b/docs/static/experimental-llama-stack-spec.html @@ -5518,8 +5518,8 @@ }, { "name": "Eval", - "description": "", - "x-displayName": "Llama Stack Evaluation API for running evaluations on model and agent candidates." + "description": "Llama Stack Evaluation API for running evaluations on model and agent candidates.", + "x-displayName": "Evaluations" }, { "name": "PostTraining (Coming Soon)", diff --git a/docs/static/experimental-llama-stack-spec.yaml b/docs/static/experimental-llama-stack-spec.yaml index 7ee5a6cdf..fee20814c 100644 --- a/docs/static/experimental-llama-stack-spec.yaml +++ b/docs/static/experimental-llama-stack-spec.yaml @@ -4119,9 +4119,9 @@ tags: - name: Datasets description: '' - name: Eval - description: '' - x-displayName: >- + description: >- Llama Stack Evaluation API for running evaluations on model and agent candidates. + x-displayName: Evaluations - name: PostTraining (Coming Soon) description: '' x-tagGroups: diff --git a/docs/static/llama-stack-spec.html b/docs/static/llama-stack-spec.html index 92ba11d58..413e4f23e 100644 --- a/docs/static/llama-stack-spec.html +++ b/docs/static/llama-stack-spec.html @@ -282,7 +282,7 @@ "Conversations" ], "summary": "Create a conversation.", - "description": "Create a conversation.", + "description": "Create a conversation.\nCreate a conversation.", "parameters": [], "requestBody": { "content": { @@ -326,8 +326,8 @@ "tags": [ "Conversations" ], - "summary": "Get a conversation with the given ID.", - "description": "Get a conversation with the given ID.", + "summary": "Retrieve a conversation.", + "description": "Retrieve a conversation.\nGet a conversation with the given ID.", "parameters": [ { "name": "conversation_id", @@ -369,8 +369,8 @@ "tags": [ "Conversations" ], - "summary": "Update a conversation's metadata with the given ID.", - "description": "Update a conversation's metadata with the given ID.", + "summary": "Update a conversation.", + "description": "Update a conversation.\nUpdate a conversation's metadata with the given ID.", "parameters": [ { "name": "conversation_id", @@ -422,8 +422,8 @@ "tags": [ "Conversations" ], - "summary": "Delete a conversation with the given ID.", - "description": "Delete a conversation with the given ID.", + "summary": "Delete a conversation.", + "description": "Delete a conversation.\nDelete a conversation with the given ID.", "parameters": [ { "name": "conversation_id", @@ -467,8 +467,8 @@ "tags": [ "Conversations" ], - "summary": "List items in the conversation.", - "description": "List items in the conversation.", + "summary": "List items.", + "description": "List items.\nList items in the conversation.", "parameters": [ { "name": "conversation_id", @@ -597,8 +597,8 @@ "tags": [ "Conversations" ], - "summary": "Create items in the conversation.", - "description": "Create items in the conversation.", + "summary": "Create items.", + "description": "Create items.\nCreate items in the conversation.", "parameters": [ { "name": "conversation_id", @@ -652,8 +652,8 @@ "tags": [ "Conversations" ], - "summary": "Retrieve a conversation item.", - "description": "Retrieve a conversation item.", + "summary": "Retrieve an item.", + "description": "Retrieve an item.\nRetrieve a conversation item.", "parameters": [ { "name": "conversation_id", @@ -704,8 +704,8 @@ "tags": [ "Conversations" ], - "summary": "Delete a conversation item.", - "description": "Delete a conversation item.", + "summary": "Delete an item.", + "description": "Delete an item.\nDelete a conversation item.", "parameters": [ { "name": "conversation_id", @@ -13251,8 +13251,8 @@ }, { "name": "Conversations", - "description": "", - "x-displayName": "Protocol for conversation management operations." + "description": "Protocol for conversation management operations.", + "x-displayName": "Conversations" }, { "name": "Files", diff --git a/docs/static/llama-stack-spec.yaml b/docs/static/llama-stack-spec.yaml index f7f77e635..93e51de6a 100644 --- a/docs/static/llama-stack-spec.yaml +++ b/docs/static/llama-stack-spec.yaml @@ -192,7 +192,10 @@ paths: tags: - Conversations summary: Create a conversation. - description: Create a conversation. + description: >- + Create a conversation. + + Create a conversation. parameters: [] requestBody: content: @@ -222,8 +225,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Get a conversation with the given ID. - description: Get a conversation with the given ID. + summary: Retrieve a conversation. + description: >- + Retrieve a conversation. + + Get a conversation with the given ID. parameters: - name: conversation_id in: path @@ -252,9 +258,10 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: >- - Update a conversation's metadata with the given ID. + summary: Update a conversation. description: >- + Update a conversation. + Update a conversation's metadata with the given ID. parameters: - name: conversation_id @@ -290,8 +297,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Delete a conversation with the given ID. - description: Delete a conversation with the given ID. + summary: Delete a conversation. + description: >- + Delete a conversation. + + Delete a conversation with the given ID. parameters: - name: conversation_id in: path @@ -321,8 +331,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: List items in the conversation. - description: List items in the conversation. + summary: List items. + description: >- + List items. + + List items in the conversation. parameters: - name: conversation_id in: path @@ -495,8 +508,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Create items in the conversation. - description: Create items in the conversation. + summary: Create items. + description: >- + Create items. + + Create items in the conversation. parameters: - name: conversation_id in: path @@ -532,8 +548,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Retrieve a conversation item. - description: Retrieve a conversation item. + summary: Retrieve an item. + description: >- + Retrieve an item. + + Retrieve a conversation item. parameters: - name: conversation_id in: path @@ -568,8 +587,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Delete a conversation item. - description: Delete a conversation item. + summary: Delete an item. + description: >- + Delete an item. + + Delete a conversation item. parameters: - name: conversation_id in: path @@ -10146,9 +10168,9 @@ tags: - `background` x-displayName: Agents - name: Conversations - description: '' - x-displayName: >- + description: >- Protocol for conversation management operations. + x-displayName: Conversations - name: Files description: >- This API is used to upload documents that can be used with other Llama Stack diff --git a/docs/static/stainless-llama-stack-spec.html b/docs/static/stainless-llama-stack-spec.html index 08f19ff59..858f20725 100644 --- a/docs/static/stainless-llama-stack-spec.html +++ b/docs/static/stainless-llama-stack-spec.html @@ -282,7 +282,7 @@ "Conversations" ], "summary": "Create a conversation.", - "description": "Create a conversation.", + "description": "Create a conversation.\nCreate a conversation.", "parameters": [], "requestBody": { "content": { @@ -326,8 +326,8 @@ "tags": [ "Conversations" ], - "summary": "Get a conversation with the given ID.", - "description": "Get a conversation with the given ID.", + "summary": "Retrieve a conversation.", + "description": "Retrieve a conversation.\nGet a conversation with the given ID.", "parameters": [ { "name": "conversation_id", @@ -369,8 +369,8 @@ "tags": [ "Conversations" ], - "summary": "Update a conversation's metadata with the given ID.", - "description": "Update a conversation's metadata with the given ID.", + "summary": "Update a conversation.", + "description": "Update a conversation.\nUpdate a conversation's metadata with the given ID.", "parameters": [ { "name": "conversation_id", @@ -422,8 +422,8 @@ "tags": [ "Conversations" ], - "summary": "Delete a conversation with the given ID.", - "description": "Delete a conversation with the given ID.", + "summary": "Delete a conversation.", + "description": "Delete a conversation.\nDelete a conversation with the given ID.", "parameters": [ { "name": "conversation_id", @@ -467,8 +467,8 @@ "tags": [ "Conversations" ], - "summary": "List items in the conversation.", - "description": "List items in the conversation.", + "summary": "List items.", + "description": "List items.\nList items in the conversation.", "parameters": [ { "name": "conversation_id", @@ -597,8 +597,8 @@ "tags": [ "Conversations" ], - "summary": "Create items in the conversation.", - "description": "Create items in the conversation.", + "summary": "Create items.", + "description": "Create items.\nCreate items in the conversation.", "parameters": [ { "name": "conversation_id", @@ -652,8 +652,8 @@ "tags": [ "Conversations" ], - "summary": "Retrieve a conversation item.", - "description": "Retrieve a conversation item.", + "summary": "Retrieve an item.", + "description": "Retrieve an item.\nRetrieve a conversation item.", "parameters": [ { "name": "conversation_id", @@ -704,8 +704,8 @@ "tags": [ "Conversations" ], - "summary": "Delete a conversation item.", - "description": "Delete a conversation item.", + "summary": "Delete an item.", + "description": "Delete an item.\nDelete a conversation item.", "parameters": [ { "name": "conversation_id", @@ -17928,8 +17928,8 @@ }, { "name": "Conversations", - "description": "", - "x-displayName": "Protocol for conversation management operations." + "description": "Protocol for conversation management operations.", + "x-displayName": "Conversations" }, { "name": "DatasetIO", @@ -17941,8 +17941,8 @@ }, { "name": "Eval", - "description": "", - "x-displayName": "Llama Stack Evaluation API for running evaluations on model and agent candidates." + "description": "Llama Stack Evaluation API for running evaluations on model and agent candidates.", + "x-displayName": "Evaluations" }, { "name": "Files", diff --git a/docs/static/stainless-llama-stack-spec.yaml b/docs/static/stainless-llama-stack-spec.yaml index 5469b3cc2..886549dbc 100644 --- a/docs/static/stainless-llama-stack-spec.yaml +++ b/docs/static/stainless-llama-stack-spec.yaml @@ -195,7 +195,10 @@ paths: tags: - Conversations summary: Create a conversation. - description: Create a conversation. + description: >- + Create a conversation. + + Create a conversation. parameters: [] requestBody: content: @@ -225,8 +228,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Get a conversation with the given ID. - description: Get a conversation with the given ID. + summary: Retrieve a conversation. + description: >- + Retrieve a conversation. + + Get a conversation with the given ID. parameters: - name: conversation_id in: path @@ -255,9 +261,10 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: >- - Update a conversation's metadata with the given ID. + summary: Update a conversation. description: >- + Update a conversation. + Update a conversation's metadata with the given ID. parameters: - name: conversation_id @@ -293,8 +300,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Delete a conversation with the given ID. - description: Delete a conversation with the given ID. + summary: Delete a conversation. + description: >- + Delete a conversation. + + Delete a conversation with the given ID. parameters: - name: conversation_id in: path @@ -324,8 +334,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: List items in the conversation. - description: List items in the conversation. + summary: List items. + description: >- + List items. + + List items in the conversation. parameters: - name: conversation_id in: path @@ -498,8 +511,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Create items in the conversation. - description: Create items in the conversation. + summary: Create items. + description: >- + Create items. + + Create items in the conversation. parameters: - name: conversation_id in: path @@ -535,8 +551,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Retrieve a conversation item. - description: Retrieve a conversation item. + summary: Retrieve an item. + description: >- + Retrieve an item. + + Retrieve a conversation item. parameters: - name: conversation_id in: path @@ -571,8 +590,11 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Conversations - summary: Delete a conversation item. - description: Delete a conversation item. + summary: Delete an item. + description: >- + Delete an item. + + Delete a conversation item. parameters: - name: conversation_id in: path @@ -13533,17 +13555,17 @@ tags: - name: Benchmarks description: '' - name: Conversations - description: '' - x-displayName: >- + description: >- Protocol for conversation management operations. + x-displayName: Conversations - name: DatasetIO description: '' - name: Datasets description: '' - name: Eval - description: '' - x-displayName: >- + description: >- Llama Stack Evaluation API for running evaluations on model and agent candidates. + x-displayName: Evaluations - name: Files description: >- This API is used to upload documents that can be used with other Llama Stack diff --git a/llama_stack/apis/conversations/conversations.py b/llama_stack/apis/conversations/conversations.py index 3fa51f0fb..d7752995d 100644 --- a/llama_stack/apis/conversations/conversations.py +++ b/llama_stack/apis/conversations/conversations.py @@ -173,7 +173,9 @@ class ConversationItemDeletedResource(BaseModel): @runtime_checkable @trace_protocol class Conversations(Protocol): - """Protocol for conversation management operations.""" + """Conversations + + Protocol for conversation management operations.""" @webmethod(route="/conversations", method="POST", level=LLAMA_STACK_API_V1) async def create_conversation( @@ -181,6 +183,8 @@ class Conversations(Protocol): ) -> Conversation: """Create a conversation. + Create a conversation. + :param items: Initial items to include in the conversation context. :param metadata: Set of key-value pairs that can be attached to an object. :returns: The created conversation object. @@ -189,7 +193,9 @@ class Conversations(Protocol): @webmethod(route="/conversations/{conversation_id}", method="GET", level=LLAMA_STACK_API_V1) async def get_conversation(self, conversation_id: str) -> Conversation: - """Get a conversation with the given ID. + """Retrieve a conversation. + + Get a conversation with the given ID. :param conversation_id: The conversation identifier. :returns: The conversation object. @@ -198,7 +204,9 @@ class Conversations(Protocol): @webmethod(route="/conversations/{conversation_id}", method="POST", level=LLAMA_STACK_API_V1) async def update_conversation(self, conversation_id: str, metadata: Metadata) -> Conversation: - """Update a conversation's metadata with the given ID. + """Update a conversation. + + Update a conversation's metadata with the given ID. :param conversation_id: The conversation identifier. :param metadata: Set of key-value pairs that can be attached to an object. @@ -208,7 +216,9 @@ class Conversations(Protocol): @webmethod(route="/conversations/{conversation_id}", method="DELETE", level=LLAMA_STACK_API_V1) async def openai_delete_conversation(self, conversation_id: str) -> ConversationDeletedResource: - """Delete a conversation with the given ID. + """Delete a conversation. + + Delete a conversation with the given ID. :param conversation_id: The conversation identifier. :returns: The deleted conversation resource. @@ -217,7 +227,9 @@ class Conversations(Protocol): @webmethod(route="/conversations/{conversation_id}/items", method="POST", level=LLAMA_STACK_API_V1) async def add_items(self, conversation_id: str, items: list[ConversationItem]) -> ConversationItemList: - """Create items in the conversation. + """Create items. + + Create items in the conversation. :param conversation_id: The conversation identifier. :param items: Items to include in the conversation context. @@ -227,7 +239,9 @@ class Conversations(Protocol): @webmethod(route="/conversations/{conversation_id}/items/{item_id}", method="GET", level=LLAMA_STACK_API_V1) async def retrieve(self, conversation_id: str, item_id: str) -> ConversationItem: - """Retrieve a conversation item. + """Retrieve an item. + + Retrieve a conversation item. :param conversation_id: The conversation identifier. :param item_id: The item identifier. @@ -244,7 +258,9 @@ class Conversations(Protocol): limit: int | NotGiven = NOT_GIVEN, order: Literal["asc", "desc"] | NotGiven = NOT_GIVEN, ) -> ConversationItemList: - """List items in the conversation. + """List items. + + List items in the conversation. :param conversation_id: The conversation identifier. :param after: An item ID to list items after, used in pagination. @@ -259,7 +275,9 @@ class Conversations(Protocol): async def openai_delete_conversation_item( self, conversation_id: str, item_id: str ) -> ConversationItemDeletedResource: - """Delete a conversation item. + """Delete an item. + + Delete a conversation item. :param conversation_id: The conversation identifier. :param item_id: The item identifier. diff --git a/llama_stack/apis/eval/eval.py b/llama_stack/apis/eval/eval.py index bb81778f1..c9418b04b 100644 --- a/llama_stack/apis/eval/eval.py +++ b/llama_stack/apis/eval/eval.py @@ -82,7 +82,9 @@ class EvaluateResponse(BaseModel): class Eval(Protocol): - """Llama Stack Evaluation API for running evaluations on model and agent candidates.""" + """Evaluations + + Llama Stack Evaluation API for running evaluations on model and agent candidates.""" @webmethod(route="/eval/benchmarks/{benchmark_id}/jobs", method="POST", level=LLAMA_STACK_API_V1, deprecated=True) @webmethod(route="/eval/benchmarks/{benchmark_id}/jobs", method="POST", level=LLAMA_STACK_API_V1ALPHA)