feat: add plugin description and tags metadata

Author: touale

src/framex/driver/application.py

@@ -95,6 +95,8 @@ async def _on_start(deployment: Any) -> None:
         redirect_slashes=False,
     )
 
+    application.state.tags_metadata_map = []
+
     if settings.auth.oauth:
         application.add_api_route(
             settings.auth.oauth.redirect_uri,
@@ -118,6 +120,7 @@ async def get_open_api_endpoint(_: Annotated[str, Depends(authenticate)]) -> dic
             version=VERSION,
             description=build_openapi_description(),
             routes=application.routes,
+            tags=application.state.tags_metadata_map,
         )
 
     @application.exception_handler(HTTPException)

src/framex/driver/ingress.py

@@ -60,6 +60,7 @@ def __init__(self, deployments: list[Any], plugin_apis: list["PluginApi"]) -> No
                     stream=plugin_api.stream,
                     direct_output=plugin_api.raw_response,
                     tags=plugin_api.tags,
+                    description=plugin_api.description,
                     **plugin_api.extend_kwargs,
                 )
 
@@ -73,6 +74,7 @@ def register_route(
         stream: bool = False,
         direct_output: bool = False,
         tags: list[str] | None = None,
+        description: str | None = None,
         auth_keys: list[str] | None = None,
         include_in_schema: bool = True,
         **kwargs: Any,
@@ -161,6 +163,7 @@ def _verify_api_key(request: Request, api_key: str | None = Depends(api_key_head
                 response_class=StreamingResponse if stream else JSONResponse,
                 dependencies=dependencies,
                 include_in_schema=include_in_schema,
+                description=description,
                 **kwargs,
             )
             methods_str = ",".join(m.upper() for m in methods)
@@ -188,6 +191,9 @@ def add_api_route(
         endpoint: Callable[..., Any],
         *,
         methods: list[str] | None = None,
+        tags: list[str] | None = None,
+        description: str | None = None,
+        include_in_schema: bool = True,
         **kwargs: Any,
     ) -> None:
         method_set: set[str] = {m.upper() for m in methods} if methods else {"GET"}
@@ -201,4 +207,22 @@ def add_api_route(
             ):
                 raise RuntimeError(f"Duplicate API route: {sorted(method_set)} {norm_path}")
 
-        app.add_api_route(path, endpoint, methods=list(method_set), **kwargs)
+        app.add_api_route(
+            path,
+            endpoint,
+            methods=list(method_set),  # type: ignore
+            tags=tags,  # type: ignore
+            include_in_schema=include_in_schema,
+            **kwargs,
+        )
+
+        if include_in_schema and tags:
+            names = list({tag["name"] for tag in app.state.tags_metadata_map})
+            for tag in tags:
+                if tag not in names:
+                    app.state.tags_metadata_map.append(
+                        {
+                            "name": tag,
+                            "description": description,
+                        },
+                    )

src/framex/plugin/base.py

@@ -73,3 +73,17 @@ async def _call_remote_api(self, api_name: str, **kwargs: Any) -> Any:
 
     def _post_call_remote_api_hook(self, data: Any) -> Any:
         return data
+
+
+def build_plugin_description(
+    author: str,
+    version: str,
+    description: str,
+    repo: str,
+) -> str:
+    return (
+        f"**Author**: {author}\n\n"
+        f"**Version**: {version}\n\n"
+        f"**Description**: {description}\n\n"
+        f"**Repo**: [{repo}]({repo})"
+    )

src/framex/plugin/model.py

@@ -34,6 +34,7 @@ class PluginApi(BaseModel):
     params: list[tuple[str, type[Any] | Callable[..., Any]]] = Field(default_factory=list)
     call_type: ApiType = ApiType.HTTP
     tags: list[str] | None = None
+    description: str | None = None
     stream: bool = False
     raw_response: bool = False
     extend_kwargs: dict[str, Any] = Field(default_factory=dict)

src/framex/plugin/on.py

@@ -9,6 +9,7 @@
 
 from framex.adapter import get_adapter
 from framex.consts import API_STR, PROXY_PLUGIN_NAME
+from framex.plugin.base import build_plugin_description
 from framex.plugin.model import ApiType, PluginApi, PluginDeployment
 from framex.utils import cache_decode, cache_encode, extract_method_params, plugin_to_deployment_name
 
@@ -42,11 +43,16 @@ def decorator(cls: type) -> type:
                     if func.__tags:
                         tags: list[str] = func.__tags
                     else:
-                        author: str = plugin.module.__plugin_meta__.author
-                        description = plugin.module.__plugin_meta__.description
-                        version: str = plugin.module.__plugin_meta__.version
-                        version = f"v{version}" if not version.startswith("v") else version
-                        tags = [f"{plugin.name} ({version}) by {author}: {description}"]
+                        tags = [plugin.name]
+
+                    version: str = plugin.module.__plugin_meta__.version
+                    version = f"v{version}" if not version.startswith("v") else version
+                    description = build_plugin_description(
+                        plugin.module.__plugin_meta__.author,
+                        version,
+                        plugin.module.__plugin_meta__.description,
+                        plugin.module.__plugin_meta__.url,
+                    )
 
                     plugin_apis.append(
                         PluginApi(
@@ -57,6 +63,7 @@ def decorator(cls: type) -> type:
                             params=params,
                             call_type=call_type,
                             tags=tags,
+                            description=description,
                             stream=func.__expose_stream,
                             raw_response=raw_response,
                             extend_kwargs=func.__kwargs,

src/framex/plugins/proxy/__init__.py

@@ -13,6 +13,7 @@
 from framex.consts import BACKEND_NAME, PROXY_FUNC_HTTP_PATH, PROXY_PLUGIN_NAME
 from framex.log import logger
 from framex.plugin import BasePlugin, PluginApi, PluginMetadata, on_register
+from framex.plugin.base import build_plugin_description
 from framex.plugin.model import ApiType
 from framex.plugin.on import on_request
 from framex.plugins.proxy.builder import (
@@ -30,8 +31,7 @@
 __plugin_meta__ = PluginMetadata(
     name="proxy",
     version=VERSION,
-    description="一个特殊的 framx proxy 插件, 充当透明代理。"
-    "它接收 API 请求并将其转发到已配置的外部 HTTP 端点,并将响应返回给调用者。",
+    description="proxy 是 FrameX 的核心系统插件, 作为透明代理转发 API 请求至外部 HTTP 端点并返回响应。",
     author="touale",
     url="https://github.com/touale/FrameX-kit",
     required_remote_apis=[],
@@ -170,6 +170,12 @@ async def _parse_openai_docs(self, url: str) -> None:
                     func_name="register_route",
                 )
                 handle = adapter.get_handle(PROXY_PLUGIN_NAME)
+                description = build_plugin_description(
+                    __plugin_meta__.author,
+                    f"v{__plugin_meta__.version}",
+                    __plugin_meta__.description,
+                    __plugin_meta__.url,
+                )
                 await adapter.call_func(
                     plugin_api,
                     path=path,
@@ -179,7 +185,8 @@ async def _parse_openai_docs(self, url: str) -> None:
                     handle=handle,
                     stream=is_stream,
                     direct_output=True,
-                    tags=[f"{__plugin_meta__.name} (v{__plugin_meta__.version}) by {__plugin_meta__.author} [{url}]"],
+                    tags=[f"{__plugin_meta__.name}({url})"],
+                    description=description,
                 )
 
                 # Proxy api to map

tests/driver/test_ingress.py

@@ -40,7 +40,13 @@ def test_add_first_route_success(ingress, mock_app):
 
     ingress.add_api_route("/users", endpoint, methods=["GET"])
 
-    mock_app.add_api_route.assert_called_once_with("/users", endpoint, methods=["GET"])
+    mock_app.add_api_route.assert_called_once_with(
+        "/users",
+        endpoint,
+        methods=["GET"],
+        tags=None,
+        include_in_schema=True,
+    )
 
 
 @pytest.mark.parametrize(