feat: introduce API leveling, post_training to v1alpha

Rather than have a single `LLAMA_STACK_VERSION`, we need to have a `_V1`, `_V1ALPHA`, and `_V1BETA` constant.

This also necessitated addition of `level` to the `WebMethod` so that routing can be handeled properly.

move post_training to `v1alpha` as it is under heavy development and not near its final state

Signed-off-by: Charlie Doern <cdoern@redhat.com>

llama_stack/apis/post_training/post_training.py

@@ -13,6 +13,7 @@ from pydantic import BaseModel, Field
 from llama_stack.apis.common.content_types import URL
 from llama_stack.apis.common.job_types import JobStatus
 from llama_stack.apis.common.training_types import Checkpoint
+from llama_stack.apis.version import LLAMA_STACK_API_V1ALPHA
 from llama_stack.schema_utils import json_schema_type, register_schema, webmethod
 
 
@@ -283,7 +284,7 @@ class PostTrainingJobArtifactsResponse(BaseModel):
 
 
 class PostTraining(Protocol):
-    @webmethod(route="/post-training/supervised-fine-tune", method="POST")
+    @webmethod(route="/post-training/supervised-fine-tune", method="POST", level=LLAMA_STACK_API_V1ALPHA)
     async def supervised_fine_tune(
         self,
         job_uuid: str,
@@ -310,7 +311,7 @@ class PostTraining(Protocol):
         """
         ...
 
-    @webmethod(route="/post-training/preference-optimize", method="POST")
+    @webmethod(route="/post-training/preference-optimize", method="POST", level=LLAMA_STACK_API_V1ALPHA)
     async def preference_optimize(
         self,
         job_uuid: str,
@@ -332,7 +333,7 @@ class PostTraining(Protocol):
         """
         ...
 
-    @webmethod(route="/post-training/jobs", method="GET")
+    @webmethod(route="/post-training/jobs", method="GET", level=LLAMA_STACK_API_V1ALPHA)
     async def get_training_jobs(self) -> ListPostTrainingJobsResponse:
         """Get all training jobs.
 
@@ -340,7 +341,7 @@ class PostTraining(Protocol):
         """
         ...
 
-    @webmethod(route="/post-training/job/status", method="GET")
+    @webmethod(route="/post-training/job/status", method="GET", level=LLAMA_STACK_API_V1ALPHA)
     async def get_training_job_status(self, job_uuid: str) -> PostTrainingJobStatusResponse:
         """Get the status of a training job.
 
@@ -349,7 +350,7 @@ class PostTraining(Protocol):
         """
         ...
 
-    @webmethod(route="/post-training/job/cancel", method="POST")
+    @webmethod(route="/post-training/job/cancel", method="POST", level=LLAMA_STACK_API_V1ALPHA)
     async def cancel_training_job(self, job_uuid: str) -> None:
         """Cancel a training job.
 
@@ -357,7 +358,7 @@ class PostTraining(Protocol):
         """
         ...
 
-    @webmethod(route="/post-training/job/artifacts", method="GET")
+    @webmethod(route="/post-training/job/artifacts", method="GET", level=LLAMA_STACK_API_V1ALPHA)
     async def get_training_job_artifacts(self, job_uuid: str) -> PostTrainingJobArtifactsResponse:
         """Get the artifacts of a training job.
 

llama_stack/apis/version.py

@@ -4,4 +4,6 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
-LLAMA_STACK_API_VERSION = "v1"
+LLAMA_STACK_API_V1 = "v1"
+LLAMA_STACK_API_V1BETA = "v1beta"
+LLAMA_STACK_API_V1ALPHA = "v1alpha"

llama_stack/core/client.py

@@ -15,7 +15,6 @@ import httpx
 from pydantic import BaseModel, parse_obj_as
 from termcolor import cprint
 
-from llama_stack.apis.version import LLAMA_STACK_API_VERSION
 from llama_stack.providers.datatypes import RemoteProviderConfig
 
 _CLIENT_CLASSES = {}
@@ -114,7 +113,7 @@ def create_api_client_class(protocol) -> type:
                     break
                 kwargs[param.name] = args[i]
 
-            url = f"{self.base_url}/{LLAMA_STACK_API_VERSION}/{webmethod.route.lstrip('/')}"
+            url = f"{self.base_url}/{webmethod.level}/{webmethod.route.lstrip('/')}"
 
             def convert(value):
                 if isinstance(value, list):

llama_stack/core/server/routes.py

@@ -14,7 +14,6 @@ from starlette.routing import Route
 
 from llama_stack.apis.datatypes import Api, ExternalApiSpec
 from llama_stack.apis.tools import RAGToolRuntime, SpecialToolGroup
-from llama_stack.apis.version import LLAMA_STACK_API_VERSION
 from llama_stack.core.resolver import api_protocol_map
 from llama_stack.schema_utils import WebMethod
 
@@ -60,7 +59,7 @@ def get_all_api_routes(
             # The __webmethod__ attribute is dynamically added by the @webmethod decorator
             # mypy doesn't know about this dynamic attribute, so we ignore the attr-defined error
             webmethod = method.__webmethod__  # type: ignore[attr-defined]
-            path = f"/{LLAMA_STACK_API_VERSION}/{webmethod.route.lstrip('/')}"
+            path = f"/{webmethod.level}/{webmethod.route.lstrip('/')}"
             if webmethod.method == hdrs.METH_GET:
                 http_method = hdrs.METH_GET
             elif webmethod.method == hdrs.METH_DELETE:

llama_stack/schema_utils.py

@@ -13,6 +13,7 @@ from .strong_typing.schema import json_schema_type, register_schema  # noqa: F40
 
 @dataclass
 class WebMethod:
+    level: str | None = "v1"
     route: str | None = None
     public: bool = False
     request_examples: list[Any] | None = None
@@ -31,6 +32,7 @@ T = TypeVar("T", bound=Callable[..., Any])
 def webmethod(
     route: str | None = None,
     method: str | None = None,
+    level: str | None = "v1",
     public: bool | None = False,
     request_examples: list[Any] | None = None,
     response_examples: list[Any] | None = None,
@@ -54,6 +56,7 @@ def webmethod(
         func.__webmethod__ = WebMethod(  # type: ignore
             route=route,
             method=method,
+            level=level,
             public=public or False,
             request_examples=request_examples,
             response_examples=response_examples,