phoenix-oss/llama-stack-mirror
0
0
Fork 1
mirror of https://github.com/meta-llama/llama-stack.git synced 2025-06-28 02:53:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[docs] add openapi spec to docs (#508)

Browse source 
# What does this PR do?
- modify openapi generator to add coming soon tag for unimplemented api
- sphinx-redocs extension for openapi spec to readthedocs page

## Test Plan



https://github.com/user-attachments/assets/b4c7eebc-2361-4198-a987-dbfbcff914cf






## Before submitting

- [ ] This PR fixes a typo or improves the docs (you can dismiss the
other checks if that's the case).
- [ ] Ran pre-commit to handle lint / formatting issues.
- [ ] Read the [contributor
guideline](https://github.com/meta-llama/llama-stack/blob/main/CONTRIBUTING.md),
      Pull Request section?
- [ ] Updated relevant documentation.
- [ ] Wrote necessary unit or integration tests.
This commit is contained in:
Xi Yan 2024-11-22 17:54:32 -08:00 • committed by GitHub
parent 1b2b32f959
commit d97cfaa9d9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 80 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/openapi_generator/generate.py
View file

@ -52,13 +52,11 @@ def main(output_dir: str):
Options( Options(
server=Server(url="http://any-hosted-llama-stack.com"), server=Server(url="http://any-hosted-llama-stack.com"),
info=Info( info=Info(
title="[DRAFT] Llama Stack Specification", title="Llama Stack Specification",
version=LLAMA_STACK_API_VERSION, version=LLAMA_STACK_API_VERSION,
description="""This is the specification of the llama stack that provides description="""This is the specification of the Llama Stack that provides
a set of endpoints and their corresponding interfaces that are tailored to a set of endpoints and their corresponding interfaces that are tailored to
best leverage Llama Models. The specification is still in draft and subject to change. best leverage Llama Models.""",
Generated at """
+ now,
), ),
), ),
) )

8
docs/openapi_generator/pyopenapi/generator.py
View file

@ -438,6 +438,14 @@ class Generator:
return extra_tags return extra_tags
def _build_operation(self, op: EndpointOperation) -> Operation: def _build_operation(self, op: EndpointOperation) -> Operation:
if op.defining_class.__name__ in [
"SyntheticDataGeneration",
"PostTraining",
"BatchInference",
]:
op.defining_class.__name__ = f"{op.defining_class.__name__} (Coming Soon)"
print(op.defining_class.__name__)
doc_string = parse_type(op.func_ref) doc_string = parse_type(op.func_ref)
doc_params = dict( doc_params = dict(
(param.name, param.description) for param in doc_string.params.values() (param.name, param.description) for param in doc_string.params.values()

2
docs/requirements.txt
View file

@ -7,3 +7,5 @@ sphinx-pdj-theme
sphinx-copybutton sphinx-copybutton
sphinx-tabs sphinx-tabs
sphinx-design sphinx-design
sphinxcontrib-openapi
sphinxcontrib-redoc

39
docs/resources/llama-stack-spec.html
View file

@ -19,9 +19,9 @@
spec = { spec = {
"openapi": "3.1.0", "openapi": "3.1.0",
"info": { "info": {
"title": "[DRAFT] Llama Stack Specification", "title": "Llama Stack Specification",
"version": "alpha", "version": "alpha",
"description": "This is the specification of the llama stack that provides\n a set of endpoints and their corresponding interfaces that are tailored to\n best leverage Llama Models. The specification is still in draft and subject to change.\n Generated at 2024-11-19 09:14:01.145131" "description": "This is the specification of the Llama Stack that provides\n a set of endpoints and their corresponding interfaces that are tailored to\n best leverage Llama Models. Generated at 2024-11-22 17:23:55.034164"
}, },
"servers": [ "servers": [
{ {
@ -44,7 +44,7 @@
} }
}, },
"tags": [ "tags": [
"BatchInference" "BatchInference (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -84,7 +84,7 @@
} }
}, },
"tags": [ "tags": [
"BatchInference" "BatchInference (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -117,7 +117,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -1079,7 +1079,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -1117,7 +1117,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -1155,7 +1155,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -1193,7 +1193,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -1713,7 +1713,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -2161,7 +2161,7 @@
} }
}, },
"tags": [ "tags": [
"PostTraining" "PostTraining (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -2201,7 +2201,7 @@
} }
}, },
"tags": [ "tags": [
"SyntheticDataGeneration" "SyntheticDataGeneration (Coming Soon)"
], ],
"parameters": [ "parameters": [
{ {
@ -3861,7 +3861,8 @@
"type": "string", "type": "string",
"enum": [ "enum": [
"bing", "bing",
"brave" "brave",
"tavily"
], ],
"default": "brave" "default": "brave"
}, },
@ -8002,7 +8003,7 @@
"description": "<SchemaDefinition schemaRef=\"#/components/schemas/BatchCompletionResponse\" />" "description": "<SchemaDefinition schemaRef=\"#/components/schemas/BatchCompletionResponse\" />"
}, },
{ {
"name": "BatchInference" "name": "BatchInference (Coming Soon)"
}, },
{ {
"name": "BenchmarkEvalTaskConfig", "name": "BenchmarkEvalTaskConfig",
@ -8256,7 +8257,7 @@
"description": "<SchemaDefinition schemaRef=\"#/components/schemas/PhotogenToolDefinition\" />" "description": "<SchemaDefinition schemaRef=\"#/components/schemas/PhotogenToolDefinition\" />"
}, },
{ {
"name": "PostTraining" "name": "PostTraining (Coming Soon)"
}, },
{ {
"name": "PostTrainingJob", "name": "PostTrainingJob",
@ -8447,7 +8448,7 @@
"description": "<SchemaDefinition schemaRef=\"#/components/schemas/SyntheticDataGenerateRequest\" />" "description": "<SchemaDefinition schemaRef=\"#/components/schemas/SyntheticDataGenerateRequest\" />"
}, },
{ {
"name": "SyntheticDataGeneration" "name": "SyntheticDataGeneration (Coming Soon)"
}, },
{ {
"name": "SyntheticDataGenerationResponse", "name": "SyntheticDataGenerationResponse",
@ -8558,7 +8559,7 @@
"name": "Operations", "name": "Operations",
"tags": [ "tags": [
"Agents", "Agents",
"BatchInference", "BatchInference (Coming Soon)",
"DatasetIO", "DatasetIO",
"Datasets", "Datasets",
"Eval", "Eval",
@ -8568,12 +8569,12 @@
"Memory", "Memory",
"MemoryBanks", "MemoryBanks",
"Models", "Models",
"PostTraining", "PostTraining (Coming Soon)",
"Safety", "Safety",
"Scoring", "Scoring",
"ScoringFunctions", "ScoringFunctions",
"Shields", "Shields",
"SyntheticDataGeneration", "SyntheticDataGeneration (Coming Soon)",
"Telemetry" "Telemetry"
] ]
}, },

40
docs/resources/llama-stack-spec.yaml
View file

@ -2629,6 +2629,7 @@ components:
enum: enum:
- bing - bing
- brave - brave
- tavily
type: string type: string
input_shields: input_shields:
items: items:
@ -3397,11 +3398,10 @@ components:
- api_key - api_key
type: object type: object
info: info:
description: "This is the specification of the llama stack that provides\n \ description: "This is the specification of the Llama Stack that provides\n \
\ a set of endpoints and their corresponding interfaces that are tailored\ \ a set of endpoints and their corresponding interfaces that are tailored\
\ to\n best leverage Llama Models. The specification is still in\ \ to\n best leverage Llama Models. Generated at 2024-11-22 17:23:55.034164"
\ draft and subject to change.\n Generated at 2024-11-19 09:14:01.145131" title: Llama Stack Specification
title: '[DRAFT] Llama Stack Specification'
version: alpha version: alpha
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
openapi: 3.1.0 openapi: 3.1.0
@ -3658,7 +3658,7 @@ paths:
$ref: '#/components/schemas/BatchChatCompletionResponse' $ref: '#/components/schemas/BatchChatCompletionResponse'
description: OK description: OK
tags: tags:
- BatchInference - BatchInference (Coming Soon)
/alpha/batch-inference/completion: /alpha/batch-inference/completion:
post: post:
parameters: parameters:
@ -3683,7 +3683,7 @@ paths:
$ref: '#/components/schemas/BatchCompletionResponse' $ref: '#/components/schemas/BatchCompletionResponse'
description: OK description: OK
tags: tags:
- BatchInference - BatchInference (Coming Soon)
/alpha/datasetio/get-rows-paginated: /alpha/datasetio/get-rows-paginated:
get: get:
parameters: parameters:
@ -4337,7 +4337,7 @@ paths:
$ref: '#/components/schemas/PostTrainingJobArtifactsResponse' $ref: '#/components/schemas/PostTrainingJobArtifactsResponse'
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/post-training/job/cancel: /alpha/post-training/job/cancel:
post: post:
parameters: parameters:
@ -4358,7 +4358,7 @@ paths:
'200': '200':
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/post-training/job/logs: /alpha/post-training/job/logs:
get: get:
parameters: parameters:
@ -4382,7 +4382,7 @@ paths:
$ref: '#/components/schemas/PostTrainingJobLogStream' $ref: '#/components/schemas/PostTrainingJobLogStream'
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/post-training/job/status: /alpha/post-training/job/status:
get: get:
parameters: parameters:
@ -4406,7 +4406,7 @@ paths:
$ref: '#/components/schemas/PostTrainingJobStatusResponse' $ref: '#/components/schemas/PostTrainingJobStatusResponse'
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/post-training/jobs: /alpha/post-training/jobs:
get: get:
parameters: parameters:
@ -4425,7 +4425,7 @@ paths:
$ref: '#/components/schemas/PostTrainingJob' $ref: '#/components/schemas/PostTrainingJob'
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/post-training/preference-optimize: /alpha/post-training/preference-optimize:
post: post:
parameters: parameters:
@ -4450,7 +4450,7 @@ paths:
$ref: '#/components/schemas/PostTrainingJob' $ref: '#/components/schemas/PostTrainingJob'
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/post-training/supervised-fine-tune: /alpha/post-training/supervised-fine-tune:
post: post:
parameters: parameters:
@ -4475,7 +4475,7 @@ paths:
$ref: '#/components/schemas/PostTrainingJob' $ref: '#/components/schemas/PostTrainingJob'
description: OK description: OK
tags: tags:
- PostTraining - PostTraining (Coming Soon)
/alpha/providers/list: /alpha/providers/list:
get: get:
parameters: parameters:
@ -4755,7 +4755,7 @@ paths:
$ref: '#/components/schemas/SyntheticDataGenerationResponse' $ref: '#/components/schemas/SyntheticDataGenerationResponse'
description: OK description: OK
tags: tags:
- SyntheticDataGeneration - SyntheticDataGeneration (Coming Soon)
/alpha/telemetry/get-trace: /alpha/telemetry/get-trace:
get: get:
parameters: parameters:
@ -4863,7 +4863,7 @@ tags:
- description: <SchemaDefinition schemaRef="#/components/schemas/BatchCompletionResponse" - description: <SchemaDefinition schemaRef="#/components/schemas/BatchCompletionResponse"
/> />
name: BatchCompletionResponse name: BatchCompletionResponse
- name: BatchInference - name: BatchInference (Coming Soon)
- description: <SchemaDefinition schemaRef="#/components/schemas/BenchmarkEvalTaskConfig" - description: <SchemaDefinition schemaRef="#/components/schemas/BenchmarkEvalTaskConfig"
/> />
name: BenchmarkEvalTaskConfig name: BenchmarkEvalTaskConfig
@ -5044,7 +5044,7 @@ tags:
- description: <SchemaDefinition schemaRef="#/components/schemas/PhotogenToolDefinition" - description: <SchemaDefinition schemaRef="#/components/schemas/PhotogenToolDefinition"
/> />
name: PhotogenToolDefinition name: PhotogenToolDefinition
- name: PostTraining - name: PostTraining (Coming Soon)
- description: <SchemaDefinition schemaRef="#/components/schemas/PostTrainingJob" - description: <SchemaDefinition schemaRef="#/components/schemas/PostTrainingJob"
/> />
name: PostTrainingJob name: PostTrainingJob
@ -5179,7 +5179,7 @@ tags:
- description: <SchemaDefinition schemaRef="#/components/schemas/SyntheticDataGenerateRequest" - description: <SchemaDefinition schemaRef="#/components/schemas/SyntheticDataGenerateRequest"
/> />
name: SyntheticDataGenerateRequest name: SyntheticDataGenerateRequest
- name: SyntheticDataGeneration - name: SyntheticDataGeneration (Coming Soon)
- description: 'Response from the synthetic data generation. Batch of (prompt, response, - description: 'Response from the synthetic data generation. Batch of (prompt, response,
score) tuples that pass the threshold. score) tuples that pass the threshold.
@ -5262,7 +5262,7 @@ x-tagGroups:
- name: Operations - name: Operations
tags: tags:
- Agents - Agents
- BatchInference - BatchInference (Coming Soon)
- DatasetIO - DatasetIO
- Datasets - Datasets
- Eval - Eval
@ -5272,12 +5272,12 @@ x-tagGroups:
- Memory - Memory
- MemoryBanks - MemoryBanks
- Models - Models
- PostTraining - PostTraining (Coming Soon)
- Safety - Safety
- Scoring - Scoring
- ScoringFunctions - ScoringFunctions
- Shields - Shields
- SyntheticDataGeneration - SyntheticDataGeneration (Coming Soon)
- Telemetry - Telemetry
- name: Types - name: Types
tags: tags:

16
docs/source/conf.py
View file

@ -25,6 +25,7 @@ extensions = [
"sphinx_copybutton", "sphinx_copybutton",
"sphinx_tabs.tabs", "sphinx_tabs.tabs",
"sphinx_design", "sphinx_design",
"sphinxcontrib.redoc",
] ]
myst_enable_extensions = ["colon_fence"] myst_enable_extensions = ["colon_fence"]
@ -82,3 +83,18 @@ html_theme_options = {
html_static_path = ["../_static"] html_static_path = ["../_static"]
# html_logo = "../_static/llama-stack-logo.png" # html_logo = "../_static/llama-stack-logo.png"
html_style = "../_static/css/my_theme.css" html_style = "../_static/css/my_theme.css"
redoc = [
{
"name": "Llama Stack API",
"page": "references/api_reference/index",
"spec": "../resources/llama-stack-spec.yaml",
"opts": {
"suppress-warnings": True,
# "expand-responses": ["200", "201"],
},
"embed": True,
},
]
redoc_uri = "https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"

7
docs/source/references/api_reference/index.md Normal file
View file

@ -0,0 +1,7 @@
# API Reference
```{eval-rst}
.. sphinxcontrib-redoc:: ../resources/llama-stack-spec.yaml
:page-title: API Reference
:expand-responses: all
```

4
docs/source/references/index.md
View file

@ -1,11 +1,15 @@
# References # References
- [API Reference](api_reference/index) for the Llama Stack API specification
- [Llama CLI](llama_cli_reference/index) for building and running your Llama Stack server - [Llama CLI](llama_cli_reference/index) for building and running your Llama Stack server
- [Llama Stack Client CLI](llama_stack_client_cli_reference/index) for interacting with your Llama Stack server - [Llama Stack Client CLI](llama_stack_client_cli_reference/index) for interacting with your Llama Stack server
```{toctree} ```{toctree}
:maxdepth: 2 :maxdepth: 2
:hidden: :hidden:
api_reference/index
llama_cli_reference/index llama_cli_reference/index
llama_stack_client_cli_reference/index llama_stack_client_cli_reference/index
llama_cli_reference/download_models llama_cli_reference/download_models
```