UncountablePythonSDK 0.0.24__py3-none-any.whl → 0.0.131__py3-none-any.whl

pkgs/type_spec/builder_types.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(kw_only=True, frozen=True)
+class CrossOutputPaths:
+    python_types_output: str
+    typescript_types_output: str
+    typescript_routes_output_by_endpoint: dict[str, str]
+    typespec_files_input: list[str]

pkgs/type_spec/config.py

@@ -1,10 +1,10 @@
 import os
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
-from decimal import Decimal
 from typing import Self, TypeVar
 
-import yaml
+from pkgs.serialization import yaml
+from pkgs.type_spec.builder import APIEndpointInfo, EndpointKey
 
 ConfigValueType = str | None | Mapping[str, str | None] | list[str]
 
@@ -20,6 +20,22 @@ def _parse_string_lookup(
     }
 
 
+VT = TypeVar("VT")
+
+
+def _parse_data_lookup(
+    key: str,
+    raw_value: ConfigValueType,
+    conv_func: type[VT],
+) -> dict[str, VT]:
+    assert isinstance(raw_value, dict), f"{key} must be key/values"
+    return {
+        k: conv_func(**v)
+        for k, v in raw_value.items()
+        if v is not None and isinstance(v, dict)
+    }
+
+
 @dataclass(kw_only=True)
 class BaseLanguageConfig:
     types_output: (
@@ -32,18 +48,28 @@ class BaseLanguageConfig:
 
 @dataclass(kw_only=True)
 class TypeScriptConfig(BaseLanguageConfig):
-    routes_output: str  # folder for generate route files will be located.
+    endpoint_to_routes_output: dict[
+        EndpointKey, str
+    ]  # folder for generate route files will be located.
     type_info_output: str  # folder for generated type info files
     id_source_output: str | None = None  # folder for emitted id source maps.
+    endpoint_to_frontend_app_type: dict[
+        str, str
+    ]  # map from api_endpoint to frontend app type
 
     def __post_init__(self: Self) -> None:
-        self.routes_output = self.routes_output
+        self.endpoint_to_routes_output = self.endpoint_to_routes_output
         self.type_info_output = os.path.abspath(self.type_info_output)
         self.id_source_output = (
             os.path.abspath(self.id_source_output)
             if self.id_source_output is not None
             else None
         )
+        self.endpoint_to_frontend_app_type = _parse_string_lookup(
+            "typescript_endpoint_to_frontend_app_type",
+            self.endpoint_to_frontend_app_type,
+            lambda x: x,
+        )
 
 
 @dataclass(kw_only=True)
@@ -60,6 +86,7 @@ class PythonConfig(BaseLanguageConfig):
     emit_client_class: bool = False  # emit the base class for the api client
     all_named_type_exports: bool = False  # emit __all__ for all named type exports
     sdk_endpoints_only: bool = False  # only emit is_sdk endpoints
+    type_info_output: str | None = None  # folder for generated type info files
 
     def __post_init__(self: Self) -> None:
         self.routes_output = _parse_string_lookup(
@@ -71,6 +98,9 @@ class PythonConfig(BaseLanguageConfig):
             else None
         )
 
+        if self.type_info_output is not None:
+            self.type_info_output = os.path.abspath(self.type_info_output)
+
 
 @dataclass(kw_only=True)
 class OpenAPIConfig(BaseLanguageConfig):
@@ -87,45 +117,37 @@ class OpenAPIConfig(BaseLanguageConfig):
 
 @dataclass(kw_only=True)
 class Config:
+    top_namespace: str
     type_spec_types: list[str]  # folders containing the yaml type spec definitions
-    api_endpoint: dict[str, str]
+    api_endpoint: dict[str, APIEndpointInfo]
     # languages
     typescript: TypeScriptConfig | None
     python: PythonConfig
     open_api: OpenAPIConfig | None
 
 
-_T = TypeVar("_T")
+T = TypeVar("T")
 
 
-def _parse_language(config_class: type[_T], raw_value: ConfigValueType) -> _T:
+def _parse_language(config_class: type[T], raw_value: ConfigValueType) -> T:
     assert isinstance(raw_value, dict), "expecting language config to have key/values."
     return config_class(**raw_value)
 
 
-def _decimal_constructor(loader, node):  # type:ignore
-    value = loader.construct_scalar(node)
-    return Decimal(value)
-
-
-# A semi-acceptable patch to force a number to be parsed as a decimal, since pyyaml
-# parses them as lossy floats otherwise. Though a bit ugly, at least this way we have
-# support for decimal constants
-yaml.SafeLoader.add_constructor("!decimal", _decimal_constructor)
-
-
 def parse_yaml_config(config_file: str) -> Config:
     with open(config_file, encoding="utf-8") as input:
         raw_config: dict[str, ConfigValueType] = yaml.safe_load(input)
 
     raw_type_spec_types = raw_config["type_spec_types"]
-    assert isinstance(
-        raw_type_spec_types, list
-    ), "type_spec_types, must be a list of folders"
+    assert isinstance(raw_type_spec_types, list), (
+        "type_spec_types, must be a list of folders"
+    )
     type_spec_types = [os.path.abspath(folder) for folder in raw_type_spec_types]
 
-    api_endpoint = _parse_string_lookup(
-        "api_endpoint", raw_config.get("api_endpoint", {}), lambda x: x
+    api_endpoint = _parse_data_lookup(
+        "api_endpoint",
+        raw_config.get("api_endpoint", {}),
+        APIEndpointInfo,
     )
 
     raw_typescript = raw_config.get("typescript")
@@ -137,10 +159,16 @@ def parse_yaml_config(config_file: str) -> Config:
     python = _parse_language(PythonConfig, raw_config["python"])
     raw_open_api = raw_config.get("open_api")
     open_api = (
-        _parse_language(OpenAPIConfig, raw_open_api) if raw_open_api is not None else None
+        _parse_language(OpenAPIConfig, raw_open_api)
+        if raw_open_api is not None
+        else None
     )
 
+    top_namespace = raw_config["top_namespace"]
+    assert isinstance(top_namespace, str)
+
     return Config(
+        top_namespace=top_namespace,
         type_spec_types=type_spec_types,
         api_endpoint=api_endpoint,
         typescript=typescript,

pkgs/type_spec/cross_output_links.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import os
+
+from . import builder
+from .builder_types import CrossOutputPaths
+
+
+def get_python_stub_file_path(
+    function_name: str | None,
+) -> str | None:
+    if function_name is None:
+        return None
+    module_dir, file_name, _func_name = function_name.rsplit(".", 2)
+    module_path = os.path.relpath(module_dir.replace(".", "/"))
+    api_stub_file = f"{module_path}/{file_name}.py"
+    return api_stub_file
+
+
+def get_python_api_file_path(
+    cross_output_paths: CrossOutputPaths,
+    namespace: builder.SpecNamespace,
+) -> str:
+    return f"{cross_output_paths.python_types_output}/{'/'.join(namespace.path)}{'' if len(namespace.path) > 1 else '_t'}.py"
+
+
+def get_typescript_api_file_path(
+    cross_output_paths: CrossOutputPaths,
+    namespace: builder.SpecNamespace,
+    endpoint_key: builder.EndpointKey,
+) -> str:
+    return f"{cross_output_paths.typescript_routes_output_by_endpoint[endpoint_key]}/{'/'.join(namespace.path)}.tsx"
+
+
+def get_yaml_api_file_path(
+    cross_output_paths: CrossOutputPaths,
+    namespace: builder.SpecNamespace,
+) -> str:
+    abs_path = next(
+        (
+            path
+            for path in cross_output_paths.typespec_files_input
+            if (
+                namespace.endpoint is None
+                or namespace.endpoint.default_endpoint_key in path
+            )
+        ),
+        cross_output_paths.typespec_files_input[0],
+    )
+    return f"{os.path.relpath(abs_path)}/{'/'.join(namespace.path)}.yaml"
+
+
+def get_return_to_root_path(path: str) -> str:
+    return "../" * (path.count("/"))
+
+
+def get_path_links(
+    cross_output_paths: CrossOutputPaths | None,
+    namespace: builder.SpecNamespace,
+    *,
+    current_path_type: str,
+    endpoint: builder.SpecEndpoint,
+) -> str:
+    if cross_output_paths is None:
+        return ""
+
+    api_paths = {
+        "Python": get_python_api_file_path(cross_output_paths, namespace),
+        "TypeScript": get_typescript_api_file_path(
+            cross_output_paths, namespace, endpoint.default_endpoint_key
+        ),
+        "YAML": get_yaml_api_file_path(cross_output_paths, namespace),
+    }
+
+    assert current_path_type in api_paths
+
+    comment_prefix = "#"
+    if current_path_type == "TypeScript":
+        comment_prefix = "//"
+
+    return_to_root_path = get_return_to_root_path(api_paths[current_path_type])
+    del api_paths[current_path_type]
+
+    paths_string = ""
+    for path_name, path in api_paths.items():
+        paths_string += (
+            f"{comment_prefix} {path_name}: file://./{return_to_root_path}{path}\n"
+        )
+
+    if namespace.endpoint is not None:
+        for (
+            endpoint_key,
+            path_specific_endpoint,
+        ) in namespace.endpoint.path_per_api_endpoint.items():
+            path_from_root = get_python_stub_file_path(path_specific_endpoint.function)
+            if path_from_root is None:
+                continue
+            paths_string += f"{comment_prefix} Implementation for {endpoint_key}: file://./{return_to_root_path}{path_from_root}\n"
+    return paths_string

pkgs/type_spec/emit_io_ts.py

@@ -125,7 +125,7 @@ def refer_to_io_ts(
             spec = refer_to_io_ts(ctx, stype.parameters[0])
             return f"IO.array({spec})"
         if stype.defn_type.name == builder.BaseTypeName.s_union:
-            return f'IO.union([{", ".join([refer_to_io_ts(ctx, p) for p in stype.parameters])}])'
+            return f"IO.union([{', '.join([refer_to_io_ts(ctx, p) for p in stype.parameters])}])"
         if stype.defn_type.name == builder.BaseTypeName.s_optional:
             return f"IO.optional({refer_to_io_ts(ctx, stype.parameters[0])})"
         if stype.defn_type.name == builder.BaseTypeName.s_tuple:

pkgs/type_spec/emit_open_api.py

@@ -7,9 +7,11 @@ WORK-IN-PROGRESS, DON'T USE!
 import dataclasses
 import json
 import re
-from typing import Collection, cast
+from enum import StrEnum
+from typing import Collection, assert_never, cast
 
-import yaml
+from pkgs.serialization import yaml
+from pkgs.serialization_util import serialize_for_api
 
 from . import builder, util
 from .builder import EndpointGuideKey, RootGuideKey
@@ -23,6 +25,7 @@ from .emit_open_api_util import (
     EmitOpenAPIGuide,
     EmitOpenAPIPath,
     EmitOpenAPIServer,
+    EmitOpenAPIStabilityLevel,
     EmitOpenAPITag,
     GlobalContextInfo,
     TagGroupToNamedTags,
@@ -60,10 +63,14 @@ base_name_map = {
 }
 
 
+class OpenAPIDefaultBehavior(StrEnum):
+    OPTIONAL_WITH_DEFAULT = "optional_with_default"
+
+
 def _rewrite_with_notice(
     file_path: str, file_content: str, *, notice: str = MODIFY_NOTICE
 ) -> bool:
-    pattern = re.compile("^\S", re.MULTILINE)
+    pattern = re.compile(r"^\S", re.MULTILINE)
 
     file_lines = file_content.split("\n")
     comment_lines = []
@@ -78,9 +85,9 @@ def _rewrite_with_notice(
     return util.rewrite_file(file_path, f"{notice}\n{modified_file_content}")
 
 
-def _write_guide_as_html(guide: EmitOpenAPIGuide) -> str:
+def _write_guide_as_html(guide: EmitOpenAPIGuide, *, is_open: bool) -> str:
     return f"""
-        <details>
+        <details id="{guide.ref_name}" {"open" if is_open else ""}>
         <summary>{guide.title}</summary>
         {guide.html_content}
         </details>"""
@@ -89,7 +96,10 @@ def _write_guide_as_html(guide: EmitOpenAPIGuide) -> str:
 def _open_api_info(
     config: OpenAPIConfig, guides: list[EmitOpenAPIGuide]
 ) -> GlobalContextInfo:
-    full_guides = "<br/>".join([_write_guide_as_html(guide) for guide in guides])
+    full_guides = "<br/>".join([
+        _write_guide_as_html(guide, is_open=True)
+        for guide in sorted(guides, key=lambda g: g.ref_name)
+    ])
     full_description = f"{config.description}<br/>{full_guides}"
     info: GlobalContextInfo = dict()
     info["version"] = "1.0.0"
@@ -107,7 +117,9 @@ def _open_api_servers(config: OpenAPIConfig) -> list[EmitOpenAPIServer]:
 def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> None:
     root_guides = builder.guides.get(RootGuideKey(), [])
     openapi_guides = [
-        EmitOpenAPIGuide(title=guide.title, html_content=guide.html_content)
+        EmitOpenAPIGuide(
+            ref_name=guide.ref_name, title=guide.title, html_content=guide.html_content
+        )
         for guide in root_guides
     ]
     gctx = EmitOpenAPIGlobalContext(
@@ -119,7 +131,11 @@ def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> Non
     for namespace in sorted(builder.namespaces.values(), key=lambda ns: ns.name):
         ctx = EmitOpenAPIContext(namespace=namespace)
 
-        if ctx.namespace.endpoint is not None and ctx.namespace.endpoint.is_beta:
+        if (
+            ctx.namespace.endpoint is not None
+            and ctx.namespace.endpoint.stability_level
+            == EmitOpenAPIStabilityLevel.draft
+        ):
             continue
 
         if ctx.namespace.name == "base":
@@ -163,7 +179,7 @@ def _serialize_global_context(ctx: EmitOpenAPIGlobalContext) -> str:
         oa_paths[path.path] = {"$ref": path.ref}
     oa_root["paths"] = oa_paths
 
-    return yaml.dump(oa_root, sort_keys=False)
+    return yaml.dumps(oa_root, sort_keys=False)
 
 
 def _is_empty_object_type(typ: OpenAPIType) -> bool:
@@ -245,10 +261,35 @@ def _emit_endpoint_parameters(
     } | _emit_endpoint_parameter_examples(examples)
 
 
-def _emit_is_beta(is_beta: bool) -> DictApiSchema:
-    if is_beta:
-        return {"x-beta": True}
-    return {}
+def _emit_endpoint_deprecated(deprecated: bool) -> DictApiSchema:
+    return {"deprecated": True} if deprecated else {}
+
+
+def _emit_stability_level(
+    stability_level: EmitOpenAPIStabilityLevel | None,
+) -> DictApiSchema:
+    stability_info: dict[str, ApiSchema] = {}
+    resolved_stability_level = (
+        stability_level
+        if stability_level is not None
+        else EmitOpenAPIStabilityLevel.stable
+    )
+    stability_info["x-stability-level"] = str(resolved_stability_level)
+    match resolved_stability_level:
+        case EmitOpenAPIStabilityLevel.draft:
+            stability_info["x-beta"] = True
+        case EmitOpenAPIStabilityLevel.beta:
+            stability_info["x-badges"] = [
+                {
+                    "name": "Beta",
+                    "color": "DarkOrange",
+                }
+            ]
+        case EmitOpenAPIStabilityLevel.stable:
+            pass
+        case _:
+            assert_never(stability_level)
+    return stability_info
 
 
 def _emit_endpoint_request_body(
@@ -271,7 +312,9 @@ def _emit_endpoint_request_body(
                         "type": "object",
                         "title": "Body",
                         "required": ["data"],
-                        "properties": {"data": {"$ref": "#/components/schema/Arguments"}},
+                        "properties": {
+                            "data": {"$ref": "#/components/schema/Arguments"}
+                        },
                     }
                 }
                 | _emit_endpoint_argument_examples(examples)
@@ -296,15 +339,57 @@ def _emit_endpoint_response_examples(
     return {"examples": response_examples}
 
 
+def _create_warning_banner(api_type: str, message: str) -> str:
+    return (
+        f'<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; '
+        f'border-radius: 4px; padding: 12px; margin-bottom: 16px;">'
+        f"<strong>⚠️ {api_type} API:</strong> {message}"
+        f"</div>"
+    )
+
+
+def _get_stability_warning(
+    stability_level: EmitOpenAPIStabilityLevel | None,
+) -> str:
+    resolved_stability_level = (
+        stability_level
+        if stability_level is not None
+        else EmitOpenAPIStabilityLevel.stable
+    )
+
+    match resolved_stability_level:
+        case EmitOpenAPIStabilityLevel.draft:
+            return _create_warning_banner(
+                "Draft",
+                "This endpoint is in draft status and may change significantly. Not recommended for production use.",
+            )
+        case EmitOpenAPIStabilityLevel.beta:
+            return _create_warning_banner(
+                "Beta",
+                "This endpoint is in beta and its required parameters may change. Use with caution in production environments.",
+            )
+        case EmitOpenAPIStabilityLevel.stable:
+            return ""
+
+
 def _emit_endpoint_description(
-    description: str, guides: list[EmitOpenAPIGuide]
+    description: str,
+    guides: list[EmitOpenAPIGuide],
+    stability_level: EmitOpenAPIStabilityLevel | None = None,
 ) -> dict[str, str]:
-    full_guides = "<br/>".join([_write_guide_as_html(guide) for guide in guides])
-    return {
-        "description": description
-        if len(guides) == 0
-        else f"{description}<br/>{full_guides}"
-    }
+    stability_warning = _get_stability_warning(stability_level)
+
+    full_guides = "<br/>".join([
+        _write_guide_as_html(guide, is_open=False)
+        for guide in sorted(guides, key=lambda g: g.ref_name)
+    ])
+
+    full_description_parts = [
+        part for part in [stability_warning, description, full_guides] if part
+    ]
+    full_description = "<br/>".join(full_description_parts)
+
+    return {"description": full_description}
 
 
 def _emit_namespace(
@@ -339,10 +424,15 @@ def _emit_namespace(
                 "tags": endpoint.tags,
                 "summary": endpoint.summary,
             }
-            | _emit_endpoint_description(endpoint.description, ctx.endpoint.guides)
-            | _emit_is_beta(endpoint.is_beta)
+            | _emit_endpoint_deprecated(endpoint.deprecated)
+            | _emit_endpoint_description(
+                endpoint.description, ctx.endpoint.guides, endpoint.stability_level
+            )
+            | _emit_stability_level(endpoint.stability_level)
             | _emit_endpoint_parameters(endpoint, argument_type, ctx.endpoint.examples)
-            | _emit_endpoint_request_body(endpoint, argument_type, ctx.endpoint.examples)
+            | _emit_endpoint_request_body(
+                endpoint, argument_type, ctx.endpoint.examples
+            )
             | {
                 "responses": {
                     "200": {
@@ -395,7 +485,19 @@ def _emit_namespace(
 
     path = f"{config.types_output}/common/{'/'.join(namespace.path)}.yaml"
     oa_namespace = {"components": oa_components}
-    _rewrite_with_notice(path, yaml.dump(oa_namespace, sort_keys=False))
+    _rewrite_with_notice(path, yaml.dumps(oa_namespace, sort_keys=False))
+
+
+def _get_openapi_default_behavior(
+    prop: builder.SpecProperty,
+) -> OpenAPIDefaultBehavior | None:
+    if prop.ext_info is None or prop.ext_info.get("open_api") is None:
+        return None
+    value_passed = prop.ext_info["open_api"].get("default_required_behavior")
+    if value_passed is None:
+        return None
+    assert isinstance(value_passed, str)
+    return OpenAPIDefaultBehavior(value_passed)
 
 
 def _emit_type(
@@ -422,6 +524,22 @@ def _emit_type(
         ctx.types[stype.name] = open_api_type(ctx, stype.alias, config=config)
         return
 
+    if isinstance(stype, builder.SpecTypeDefnUnion):
+        converted_discriminator_map: dict[str, OpenAPIRefType] = dict()
+        if stype.discriminator_map is not None:
+            for discriminator_value, base_type in stype.discriminator_map.items():
+                converted_base_type = open_api_type(ctx, base_type, config=config)
+                assert isinstance(converted_base_type, OpenAPIRefType)
+                converted_discriminator_map[discriminator_value] = converted_base_type
+        ctx.types[stype.name] = OpenAPIUnionType(
+            [open_api_type(ctx, p, config=config) for p in stype.types],
+            discriminator=stype.discriminator,
+            discriminator_map=converted_discriminator_map
+            if stype.discriminator_map is not None
+            else None,
+        )
+        return
+
     if isinstance(stype, builder.SpecTypeDefnStringEnum):
         # TODO: check that these are always string enums
         # IMPROVE: reflect the enum names in the description
@@ -455,6 +573,16 @@ def _emit_type(
                 # arguments, thus treat like extant==missing
                 # IMPROVE: if we can decide they are meant as output instead, then
                 # they should be marked as required
+                openapi_default_beahvior = _get_openapi_default_behavior(prop)
+                match openapi_default_beahvior:
+                    case None:
+                        pass
+                    case OpenAPIDefaultBehavior.OPTIONAL_WITH_DEFAULT:
+                        ref_type.nullable = True
+                        assert prop.default is not None, (
+                            "optional_with_default requires default"
+                        )
+                        ref_type.default = prop.default
                 properties[prop_name] = ref_type
             elif prop.extant == builder.PropertyExtant.missing:
                 # Unlike optional below, missing does not imply null is possible. They
@@ -482,18 +610,6 @@ def _emit_type(
     ctx.types[stype.name] = final_type
 
 
-def _emit_constant(ctx: EmitOpenAPIContext, sconst: builder.SpecConstant) -> None:
-    if sconst.value_type.is_base_type(builder.BaseTypeName.s_string):
-        value = util.encode_common_string(cast(str, sconst.value))
-    elif sconst.value_type.is_base_type(builder.BaseTypeName.s_integer):
-        value = str(sconst.value)
-    else:
-        raise Exception("invalid constant type", sconst.name)
-
-    const_name = sconst.name.upper()
-    print("_emit_constant", value, const_name)
-
-
 def _emit_endpoint(
     gctx: EmitOpenAPIGlobalContext,
     ctx: EmitOpenAPIContext,
@@ -534,7 +650,7 @@ def _emit_endpoint(
     ep = namespace.endpoint
     gctx.paths.append(
         EmitOpenAPIPath(
-            path=f"/{ep.path_root}/{ep.path_dirname}/{ep.path_basename}",
+            path=f"/{ep.resolved_path}",
             ref=ref_path,
         )
     )
@@ -544,24 +660,27 @@ def _emit_endpoint(
         description = f"**[External API-Endpoint]** <br/> {description}"
 
     path_cutoff = min(3, len(namespace.path) - 1)
+
     ctx.endpoint = EmitOpenAPIEndpoint(
         method=namespace.endpoint.method.lower(),
         tags=[tag_name],
         summary=f"{'/'.join(namespace.path[path_cutoff:])}",
         description=description,
-        is_beta=namespace.endpoint.is_beta,
+        deprecated=namespace.endpoint.deprecated,
+        stability_level=namespace.endpoint.stability_level,
         examples=[
             EmitOpenAPIEndpointExample(
                 ref_name=f"ex_{i}",
                 summary=example.summary,
                 description=example.description,
-                arguments=example.arguments,
-                data=example.data,
+                arguments=serialize_for_api(example.arguments),
+                data=serialize_for_api(example.data),
             )
             for i, example in enumerate(endpoint_examples)
         ],
         guides=[
             EmitOpenAPIGuide(
+                ref_name=guide.ref_name,
                 title=guide.title,
                 html_content=guide.html_content,
             )

pkgs/type_spec/emit_open_api_util.py

@@ -6,16 +6,17 @@ WORK-IN-PROGRESS, DON'T USE!
 
 from collections import defaultdict
 from dataclasses import dataclass, field
-from typing import TypeAlias
+
+from pkgs.serialization_util import JsonValue
 
 from . import builder
 from .open_api_util import OpenAPIType
 
 MODIFY_NOTICE = "# DO NOT MODIFY -- This file is generated by type_spec"
 
-GlobalContextInfo: TypeAlias = dict[str, str | dict[str, str]]
-TagGroupToNamedTags: TypeAlias = dict[str, str | list[str]]
-TagPathsToRef: TypeAlias = dict[str, dict[str, str]]
+GlobalContextInfo = dict[str, str | dict[str, str]]
+TagGroupToNamedTags = dict[str, str | list[str]]
+TagPathsToRef = dict[str, dict[str, str]]
 
 
 @dataclass
@@ -45,6 +46,7 @@ class EmitOpenAPIServer:
 
 @dataclass(kw_only=True)
 class EmitOpenAPIGuide:
+    ref_name: str
     title: str
     html_content: str
 
@@ -67,8 +69,11 @@ class EmitOpenAPIEndpointExample:
     ref_name: str
     summary: str
     description: str
-    arguments: dict[str, object]
-    data: dict[str, object]
+    arguments: dict[str, JsonValue]
+    data: dict[str, JsonValue]
+
+
+EmitOpenAPIStabilityLevel = builder.StabilityLevel
 
 
 @dataclass
@@ -77,7 +82,8 @@ class EmitOpenAPIEndpoint:
     tags: list[str]
     summary: str
     description: str
-    is_beta: bool
+    deprecated: bool
+    stability_level: EmitOpenAPIStabilityLevel | None
     examples: list[EmitOpenAPIEndpointExample]
     guides: list[EmitOpenAPIGuide]