mirror of
https://github.com/meta-llama/llama-stack.git
synced 2025-12-11 19:56:03 +00:00
44e36ce48d
JSON has a few advantages over YAML in this context: * No extra dependency: Removed ruamel.yaml; using the standard library json module. * Simpler code: No YAML formatting configuration (indent, flow style, string presentation, etc.). JSON serialization is straightforward. * Faster generation: JSON serialization is typically faster and more predictable than YAML formatting. * Native OpenAPI format: JSON is the native OpenAPI format. Many tools prefer JSON, reducing potential compatibility issues. * Better tooling support: JSON is widely supported. Tools like oasdiff, OpenAPI validators, and code generators work well with JSON. * Fewer formatting edge cases: YAML can have edge cases (multiline strings, special characters, quoting, scalars etc). JSON avoids these. All the tools consumming the YAMLs have been updated namely oasdiff for conformance tests, docusaurus config and the genrator. Signed-off-by: Sébastien Han <seb@redhat.com>
114 lines
4.6 KiB
Python
114 lines
4.6 KiB
Python
# Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
# All rights reserved.
|
|
#
|
|
# This source code is licensed under the terms described in the LICENSE file in
|
|
# the root directory of this source tree.
|
|
|
|
# Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
# All rights reserved.
|
|
#
|
|
# This source code is licensed under the terms described found in the
|
|
# LICENSE file in the root directory of this source tree.
|
|
|
|
from datetime import datetime
|
|
from pathlib import Path
|
|
import sys
|
|
import fire
|
|
|
|
from llama_stack.apis.version import LLAMA_STACK_API_V1 # noqa: E402
|
|
from llama_stack.core.stack import LlamaStack # noqa: E402
|
|
|
|
from .pyopenapi.options import Options # noqa: E402
|
|
from .pyopenapi.specification import Info, Server # noqa: E402
|
|
from .pyopenapi.utility import Specification, validate_api # noqa: E402
|
|
|
|
|
|
def generate_spec(output_dir: Path, stability_filter: str = None, main_spec: bool = False, combined_spec: bool = False):
|
|
"""Generate OpenAPI spec with optional stability filtering."""
|
|
|
|
if combined_spec:
|
|
# Special case for combined stable + experimental APIs
|
|
title_suffix = " - Stable & Experimental APIs"
|
|
filename_prefix = "stainless-"
|
|
description_suffix = "\n\n**🔗 COMBINED**: This specification includes both stable production-ready APIs and experimental pre-release APIs. Use stable APIs for production deployments and experimental APIs for testing new features."
|
|
# Use the special "stainless" filter to include stable + experimental APIs
|
|
stability_filter = "stainless"
|
|
elif stability_filter:
|
|
title_suffix = {
|
|
"stable": " - Stable APIs" if not main_spec else "",
|
|
"experimental": " - Experimental APIs",
|
|
"deprecated": " - Deprecated APIs"
|
|
}.get(stability_filter, f" - {stability_filter.title()} APIs")
|
|
|
|
# Use main spec filename for stable when main_spec=True
|
|
if main_spec and stability_filter == "stable":
|
|
filename_prefix = ""
|
|
else:
|
|
filename_prefix = f"{stability_filter}-"
|
|
|
|
description_suffix = {
|
|
"stable": "\n\n**✅ STABLE**: Production-ready APIs with backward compatibility guarantees.",
|
|
"experimental": "\n\n**🧪 EXPERIMENTAL**: Pre-release APIs (v1alpha, v1beta) that may change before becoming stable.",
|
|
"deprecated": "\n\n**⚠️ DEPRECATED**: Legacy APIs that may be removed in future versions. Use for migration reference only."
|
|
}.get(stability_filter, "")
|
|
else:
|
|
title_suffix = ""
|
|
filename_prefix = ""
|
|
description_suffix = ""
|
|
|
|
spec = Specification(
|
|
LlamaStack,
|
|
Options(
|
|
server=Server(url="http://any-hosted-llama-stack.com"),
|
|
info=Info(
|
|
title=f"Llama Stack Specification{title_suffix}",
|
|
version=LLAMA_STACK_API_V1,
|
|
description=f"""This is the specification of the Llama Stack that provides
|
|
a set of endpoints and their corresponding interfaces that are tailored to
|
|
best leverage Llama Models.{description_suffix}""",
|
|
),
|
|
include_standard_error_responses=True,
|
|
stability_filter=stability_filter, # Pass the filter to the generator
|
|
),
|
|
)
|
|
|
|
json_filename = f"{filename_prefix}llama-stack-spec.json"
|
|
|
|
with open(output_dir / json_filename, "w", encoding="utf-8") as fp:
|
|
spec.write_json(fp, pretty_print=True)
|
|
# add a newline to the end of the file
|
|
fp.write("\n")
|
|
|
|
print(f"Generated {json_filename}")
|
|
|
|
def main(output_dir: str):
|
|
output_dir = Path(output_dir)
|
|
if not output_dir.exists():
|
|
raise ValueError(f"Directory {output_dir} does not exist")
|
|
|
|
# Validate API protocols before generating spec
|
|
return_type_errors = validate_api()
|
|
if return_type_errors:
|
|
print("\nAPI Method Return Type Validation Errors:\n")
|
|
for error in return_type_errors:
|
|
print(error, file=sys.stderr)
|
|
sys.exit(1)
|
|
|
|
now = str(datetime.now())
|
|
print(f"Converting the spec to JSON (openapi.json) and HTML (openapi.html) at {now}")
|
|
print("")
|
|
|
|
# Generate main spec as stable APIs (llama-stack-spec.json)
|
|
print("Generating main specification (stable APIs)...")
|
|
generate_spec(output_dir, "stable", main_spec=True)
|
|
|
|
print("Generating other stability-filtered specifications...")
|
|
generate_spec(output_dir, "experimental")
|
|
generate_spec(output_dir, "deprecated")
|
|
|
|
print("Generating combined stable + experimental specification...")
|
|
generate_spec(output_dir, combined_spec=True)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
fire.Fire(main)
|