llama-stack-api 0.4.4__py3-none-any.whl → 0.5.0rc1__py3-none-any.whl

llama_stack_api/prompts/models.py

@@ -0,0 +1,177 @@
+# 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.
+
+"""Pydantic models for Prompts API requests and responses.
+
+This module defines the request and response models for the Prompts API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+import re
+import secrets
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from llama_stack_api.schema_utils import json_schema_type
+
+
+@json_schema_type
+class Prompt(BaseModel):
+    """A prompt resource representing a stored OpenAI Compatible prompt template in Llama Stack."""
+
+    prompt: str | None = Field(default=None, description="The system prompt with variable placeholders")
+    version: int = Field(description="Version (integer starting at 1, incremented on save)", ge=1)
+    prompt_id: str = Field(description="Unique identifier in format 'pmpt_<48-digit-hash>'")
+    variables: list[str] = Field(
+        default_factory=list, description="List of variable names that can be used in the prompt template"
+    )
+    is_default: bool = Field(
+        default=False, description="Boolean indicating whether this version is the default version"
+    )
+
+    @field_validator("prompt_id")
+    @classmethod
+    def validate_prompt_id(cls, prompt_id: str) -> str:
+        if not isinstance(prompt_id, str):
+            raise TypeError("prompt_id must be a string in format 'pmpt_<48-digit-hash>'")
+
+        if not prompt_id.startswith("pmpt_"):
+            raise ValueError("prompt_id must start with 'pmpt_' prefix")
+
+        hex_part = prompt_id[5:]
+        if len(hex_part) != 48:
+            raise ValueError("prompt_id must be in format 'pmpt_<48-digit-hash>' (48 lowercase hex chars)")
+
+        for char in hex_part:
+            if char not in "0123456789abcdef":
+                raise ValueError("prompt_id hex part must contain only lowercase hex characters [0-9a-f]")
+
+        return prompt_id
+
+    @field_validator("version")
+    @classmethod
+    def validate_version(cls, prompt_version: int) -> int:
+        if prompt_version < 1:
+            raise ValueError("version must be >= 1")
+        return prompt_version
+
+    @model_validator(mode="after")
+    def validate_prompt_variables(self):
+        """Validate that all variables used in the prompt are declared in the variables list."""
+        if not self.prompt:
+            return self
+
+        prompt_variables = set(re.findall(r"{{\s*(\w+)\s*}}", self.prompt))
+        declared_variables = set(self.variables)
+
+        undeclared = prompt_variables - declared_variables
+        if undeclared:
+            raise ValueError(f"Prompt contains undeclared variables: {sorted(undeclared)}")
+
+        return self
+
+    @classmethod
+    def generate_prompt_id(cls) -> str:
+        # Generate 48 hex characters (24 bytes)
+        random_bytes = secrets.token_bytes(24)
+        hex_string = random_bytes.hex()
+        return f"pmpt_{hex_string}"
+
+
+@json_schema_type
+class ListPromptsResponse(BaseModel):
+    """Response model to list prompts."""
+
+    data: list[Prompt]
+
+
+# Request models for each endpoint
+
+
+@json_schema_type
+class ListPromptVersionsRequest(BaseModel):
+    """Request model for listing all versions of a prompt."""
+
+    prompt_id: str = Field(..., description="The identifier of the prompt to list versions for.")
+
+
+@json_schema_type
+class GetPromptRequest(BaseModel):
+    """Request model for getting a prompt by ID and optional version."""
+
+    prompt_id: str = Field(..., description="The identifier of the prompt to get.")
+    version: int | None = Field(default=None, description="The version of the prompt to get (defaults to latest).")
+
+
+@json_schema_type
+class CreatePromptRequest(BaseModel):
+    """Request model for creating a new prompt."""
+
+    prompt: str = Field(..., description="The prompt text content with variable placeholders.")
+    variables: list[str] | None = Field(
+        default=None, description="List of variable names that can be used in the prompt template."
+    )
+
+
+@json_schema_type
+class UpdatePromptBodyRequest(BaseModel):
+    """Request body model for updating a prompt."""
+
+    prompt: str = Field(..., description="The updated prompt text content.")
+    version: int = Field(..., description="The current version of the prompt being updated.")
+    variables: list[str] | None = Field(
+        default=None, description="Updated list of variable names that can be used in the prompt template."
+    )
+    set_as_default: bool = Field(default=True, description="Set the new version as the default (default=True).")
+
+
+@json_schema_type
+class UpdatePromptRequest(BaseModel):
+    """Request model for updating a prompt (combines path and body parameters)."""
+
+    prompt_id: str = Field(..., description="The identifier of the prompt to update.")
+    prompt: str = Field(..., description="The updated prompt text content.")
+    version: int = Field(..., description="The current version of the prompt being updated.")
+    variables: list[str] | None = Field(
+        default=None, description="Updated list of variable names that can be used in the prompt template."
+    )
+    set_as_default: bool = Field(default=True, description="Set the new version as the default (default=True).")
+
+
+@json_schema_type
+class DeletePromptRequest(BaseModel):
+    """Request model for deleting a prompt."""
+
+    prompt_id: str = Field(..., description="The identifier of the prompt to delete.")
+
+
+@json_schema_type
+class SetDefaultVersionBodyRequest(BaseModel):
+    """Request body model for setting the default version of a prompt."""
+
+    version: int = Field(..., description="The version to set as default.")
+
+
+@json_schema_type
+class SetDefaultVersionRequest(BaseModel):
+    """Request model for setting the default version of a prompt (combines path and body parameters)."""
+
+    prompt_id: str = Field(..., description="The identifier of the prompt.")
+    version: int = Field(..., description="The version to set as default.")
+
+
+__all__ = [
+    "CreatePromptRequest",
+    "DeletePromptRequest",
+    "GetPromptRequest",
+    "ListPromptVersionsRequest",
+    "ListPromptsResponse",
+    "Prompt",
+    "SetDefaultVersionBodyRequest",
+    "SetDefaultVersionRequest",
+    "UpdatePromptBodyRequest",
+    "UpdatePromptRequest",
+]

llama_stack_api/resource.py

@@ -19,7 +19,6 @@ class ResourceType(StrEnum):
     tool = "tool"
     tool_group = "tool_group"
     prompt = "prompt"
-    connector = "connector"
 
 
 class Resource(BaseModel):

llama_stack_api/safety/__init__.py

@@ -0,0 +1,37 @@
+# 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.
+
+"""Safety API protocol and models.
+
+This module contains the Safety protocol definition for content moderation and safety shields.
+Pydantic models are defined in llama_stack_api.safety.models.
+The FastAPI router is defined in llama_stack_api.safety.fastapi_routes.
+"""
+
+from . import fastapi_routes
+from .api import Safety
+from .datatypes import (
+    ModerationObject,
+    ModerationObjectResults,
+    RunShieldResponse,
+    SafetyViolation,
+    ShieldStore,
+    ViolationLevel,
+)
+from .models import RunModerationRequest, RunShieldRequest
+
+__all__ = [
+    "Safety",
+    "ShieldStore",
+    "ModerationObject",
+    "ModerationObjectResults",
+    "ViolationLevel",
+    "SafetyViolation",
+    "RunShieldResponse",
+    "RunShieldRequest",
+    "RunModerationRequest",
+    "fastapi_routes",
+]

llama_stack_api/safety/api.py

@@ -0,0 +1,29 @@
+# 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.
+
+from typing import Protocol, runtime_checkable
+
+from llama_stack_api.safety.datatypes import ModerationObject, RunShieldResponse, ShieldStore
+
+from .models import RunModerationRequest, RunShieldRequest
+
+
+@runtime_checkable
+class Safety(Protocol):
+    """Safety API for content moderation and safety shields.
+
+    OpenAI-compatible Moderations API with additional shield capabilities.
+    """
+
+    shield_store: ShieldStore
+
+    async def run_shield(self, request: RunShieldRequest) -> RunShieldResponse:
+        """Run a safety shield on messages."""
+        ...
+
+    async def run_moderation(self, request: RunModerationRequest) -> ModerationObject:
+        """Classify if inputs are potentially harmful."""
+        ...

llama_stack_api/safety/datatypes.py

@@ -0,0 +1,83 @@
+# 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.
+
+from enum import Enum
+from typing import Any, Protocol
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type
+from llama_stack_api.shields import GetShieldRequest, Shield
+
+
+@json_schema_type
+class ModerationObjectResults(BaseModel):
+    """A moderation result object containing flagged status and category information."""
+
+    flagged: bool = Field(..., description="Whether any of the below categories are flagged")
+    categories: dict[str, bool] | None = Field(
+        None, description="A dictionary of the categories, and whether they are flagged or not"
+    )
+    category_applied_input_types: dict[str, list[str]] | None = Field(
+        None, description="A dictionary of the categories along with the input type(s) that the score applies to"
+    )
+    category_scores: dict[str, float] | None = Field(
+        None, description="A dictionary of the categories along with their scores as predicted by model"
+    )
+    user_message: str | None = Field(None, description="A message to convey to the user about the moderation result")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata about the moderation")
+
+
+@json_schema_type
+class ModerationObject(BaseModel):
+    """A moderation object containing the results of content classification."""
+
+    id: str = Field(..., description="The unique identifier for the moderation request")
+    model: str = Field(..., description="The model used to generate the moderation results")
+    results: list[ModerationObjectResults] = Field(..., description="A list of moderation result objects")
+
+
+@json_schema_type
+class ViolationLevel(Enum):
+    """Severity level of a safety violation."""
+
+    INFO = "info"  # Informational level violation that does not require action
+    WARN = "warn"  # Warning level violation that suggests caution but allows continuation
+    ERROR = "error"  # Error level violation that requires blocking or intervention
+
+
+@json_schema_type
+class SafetyViolation(BaseModel):
+    """Details of a safety violation detected by content moderation."""
+
+    violation_level: ViolationLevel = Field(..., description="Severity level of the violation")
+    user_message: str | None = Field(None, description="Message to convey to the user about the violation")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata including specific violation codes"
+    )
+
+
+@json_schema_type
+class RunShieldResponse(BaseModel):
+    """Response from running a safety shield."""
+
+    violation: SafetyViolation | None = Field(None, description="Safety violation detected by the shield, if any")
+
+
+class ShieldStore(Protocol):
+    """Protocol for accessing shields."""
+
+    async def get_shield(self, request: GetShieldRequest) -> Shield: ...
+
+
+__all__ = [
+    "ModerationObjectResults",
+    "ModerationObject",
+    "ViolationLevel",
+    "SafetyViolation",
+    "RunShieldResponse",
+    "ShieldStore",
+]

llama_stack_api/safety/fastapi_routes.py

@@ -0,0 +1,55 @@
+# 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.
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body
+
+from llama_stack_api.router_utils import standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Safety
+from .datatypes import ModerationObject, RunShieldResponse
+from .models import RunModerationRequest, RunShieldRequest
+
+
+def create_router(impl: Safety) -> APIRouter:
+    """Create a FastAPI router for the Safety API."""
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Safety"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/safety/run-shield",
+        response_model=RunShieldResponse,
+        summary="Run Shield",
+        description="Run a safety shield on messages to check for policy violations.",
+        responses={
+            200: {"description": "The shield response indicating any violations detected."},
+        },
+    )
+    async def run_shield(
+        request: Annotated[RunShieldRequest, Body(...)],
+    ) -> RunShieldResponse:
+        return await impl.run_shield(request)
+
+    @router.post(
+        "/moderations",
+        response_model=ModerationObject,
+        summary="Create Moderation",
+        description="Classifies if text inputs are potentially harmful. OpenAI-compatible endpoint.",
+        responses={
+            200: {"description": "The moderation results for the input."},
+        },
+    )
+    async def run_moderation(
+        request: Annotated[RunModerationRequest, Body(...)],
+    ) -> ModerationObject:
+        return await impl.run_moderation(request)
+
+    return router

llama_stack_api/safety/models.py

@@ -0,0 +1,38 @@
+# 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.
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.inference import OpenAIMessageParam
+from llama_stack_api.schema_utils import json_schema_type
+
+
+@json_schema_type
+class RunShieldRequest(BaseModel):
+    """Request model for running a safety shield."""
+
+    shield_id: str = Field(..., description="The identifier of the shield to run", min_length=1)
+    messages: list[OpenAIMessageParam] = Field(..., description="The messages to run the shield on")
+
+
+@json_schema_type
+class RunModerationRequest(BaseModel):
+    """Request model for running content moderation."""
+
+    input: str | list[str] = Field(
+        ...,
+        description="Input (or inputs) to classify. Can be a single string or an array of strings.",
+    )
+    model: str | None = Field(
+        None,
+        description="The content moderation model to use. If not specified, the default shield will be used.",
+    )
+
+
+__all__ = [
+    "RunShieldRequest",
+    "RunModerationRequest",
+]

llama_stack_api/schema_utils.py

@@ -149,7 +149,6 @@ class WebMethod:
     raw_bytes_request_body: bool | None = False
     # A descriptive name of the corresponding span created by tracing
     descriptive_name: str | None = None
-    required_scope: str | None = None
     deprecated: bool | None = False
     require_authentication: bool | None = True
 
@@ -166,7 +165,6 @@ def webmethod(
     response_examples: list[Any] | None = None,
     raw_bytes_request_body: bool | None = False,
     descriptive_name: str | None = None,
-    required_scope: str | None = None,
     deprecated: bool | None = False,
     require_authentication: bool | None = True,
 ) -> Callable[[CallableT], CallableT]:
@@ -177,7 +175,6 @@ def webmethod(
     :param public: True if the operation can be invoked without prior authentication.
     :param request_examples: Sample requests that the operation might take. Pass a list of objects, not JSON.
     :param response_examples: Sample responses that the operation might produce. Pass a list of objects, not JSON.
-    :param required_scope: Required scope for this endpoint (e.g., 'monitoring.viewer').
     :param require_authentication: Whether this endpoint requires authentication (default True).
     """
 
@@ -191,7 +188,6 @@ def webmethod(
             response_examples=response_examples,
             raw_bytes_request_body=raw_bytes_request_body,
             descriptive_name=descriptive_name,
-            required_scope=required_scope,
             deprecated=deprecated,
             require_authentication=require_authentication if require_authentication is not None else True,
         )
@@ -206,3 +202,50 @@ def webmethod(
         return func
 
     return wrap
+
+
+def remove_null_from_anyof(schema: dict, *, add_nullable: bool = False) -> None:
+    """Remove null type from anyOf and optionally add nullable flag.
+
+    Converts Pydantic's default OpenAPI 3.1 style:
+        anyOf: [{type: X, enum: [...]}, {type: null}]
+
+    To flattened format:
+        type: X
+        enum: [...]
+        nullable: true  # only if add_nullable=True
+
+    Args:
+        schema: The JSON schema dict to modify in-place
+        add_nullable: If True, adds 'nullable: true' when null was present.
+                      Use True for OpenAPI 3.0 compatibility with OpenAI's spec.
+    """
+    # Handle anyOf format: anyOf: [{type: string, enum: [...]}, {type: null}]
+    if "anyOf" in schema:
+        non_null = [s for s in schema["anyOf"] if s.get("type") != "null"]
+        has_null = len(non_null) < len(schema["anyOf"])
+
+        if len(non_null) == 1:
+            # Flatten to single type
+            only_schema = non_null[0]
+            schema.pop("anyOf")
+            schema.update(only_schema)
+            if has_null and add_nullable:
+                schema["nullable"] = True
+
+    # Handle OpenAPI 3.1 format: type: ['string', 'null']
+    elif isinstance(schema.get("type"), list) and "null" in schema["type"]:
+        has_null = "null" in schema["type"]
+        schema["type"].remove("null")
+        if len(schema["type"]) == 1:
+            schema["type"] = schema["type"][0]
+        if has_null and add_nullable:
+            schema["nullable"] = True
+
+
+def nullable_openai_style(schema: dict) -> None:
+    """Shorthand for remove_null_from_anyof with add_nullable=True.
+
+    Use this for fields that need OpenAPI 3.0 nullable style to match OpenAI's spec.
+    """
+    remove_null_from_anyof(schema, add_nullable=True)

llama_stack_api/scoring/__init__.py

@@ -0,0 +1,66 @@
+# 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.
+
+"""Scoring API protocol and models.
+
+This module contains the Scoring protocol definition.
+Pydantic models are defined in llama_stack_api.scoring.models.
+The FastAPI router is defined in llama_stack_api.scoring.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+# Import scoring_functions for re-export
+from llama_stack_api.scoring_functions import (
+    AggregationFunctionType,
+    BasicScoringFnParams,
+    CommonScoringFnFields,
+    ListScoringFunctionsResponse,
+    LLMAsJudgeScoringFnParams,
+    RegexParserScoringFnParams,
+    ScoringFn,
+    ScoringFnInput,
+    ScoringFnParams,
+    ScoringFnParamsType,
+    ScoringFunctions,
+)
+
+from . import fastapi_routes
+
+# Import protocol for FastAPI router
+from .api import Scoring, ScoringFunctionStore
+
+# Import models for re-export
+from .models import (
+    ScoreBatchRequest,
+    ScoreBatchResponse,
+    ScoreRequest,
+    ScoreResponse,
+    ScoringResult,
+    ScoringResultRow,
+)
+
+__all__ = [
+    "Scoring",
+    "ScoringFunctionStore",
+    "ScoringResult",
+    "ScoringResultRow",
+    "ScoreBatchResponse",
+    "ScoreResponse",
+    "ScoreRequest",
+    "ScoreBatchRequest",
+    "AggregationFunctionType",
+    "BasicScoringFnParams",
+    "CommonScoringFnFields",
+    "LLMAsJudgeScoringFnParams",
+    "ListScoringFunctionsResponse",
+    "RegexParserScoringFnParams",
+    "ScoringFn",
+    "ScoringFnInput",
+    "ScoringFnParams",
+    "ScoringFnParamsType",
+    "ScoringFunctions",
+    "fastapi_routes",
+]

llama_stack_api/scoring/api.py

@@ -0,0 +1,35 @@
+# 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.
+
+"""Scoring API protocol definition.
+
+This module contains the Scoring protocol definition.
+Pydantic models are defined in llama_stack_api.scoring.models.
+The FastAPI router is defined in llama_stack_api.scoring.fastapi_routes.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from llama_stack_api.scoring_functions import ScoringFn
+
+from .models import ScoreBatchRequest, ScoreBatchResponse, ScoreRequest, ScoreResponse
+
+
+class ScoringFunctionStore(Protocol):
+    """Protocol for storing and retrieving scoring functions."""
+
+    def get_scoring_function(self, scoring_fn_id: str) -> ScoringFn: ...
+
+
+@runtime_checkable
+class Scoring(Protocol):
+    """Protocol for scoring operations."""
+
+    scoring_function_store: ScoringFunctionStore
+
+    async def score_batch(self, request: ScoreBatchRequest) -> ScoreBatchResponse: ...
+
+    async def score(self, request: ScoreRequest) -> ScoreResponse: ...

llama_stack_api/scoring/fastapi_routes.py

@@ -0,0 +1,67 @@
+# 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.
+
+"""FastAPI router for the Scoring API.
+
+This module defines the FastAPI router for the Scoring API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body
+
+from llama_stack_api.router_utils import standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Scoring
+from .models import ScoreBatchRequest, ScoreBatchResponse, ScoreRequest, ScoreResponse
+
+
+def create_router(impl: Scoring) -> APIRouter:
+    """Create a FastAPI router for the Scoring API.
+
+    Args:
+        impl: The Scoring implementation instance
+
+    Returns:
+        APIRouter configured for the Scoring API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Scoring"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/scoring/score",
+        response_model=ScoreResponse,
+        summary="Score a list of rows.",
+        description="Score a list of rows.",
+        responses={
+            200: {"description": "A ScoreResponse object containing rows and aggregated results."},
+        },
+    )
+    async def score(
+        request: Annotated[ScoreRequest, Body(...)],
+    ) -> ScoreResponse:
+        return await impl.score(request)
+
+    @router.post(
+        "/scoring/score-batch",
+        response_model=ScoreBatchResponse,
+        summary="Score a batch of rows.",
+        description="Score a batch of rows.",
+        responses={
+            200: {"description": "A ScoreBatchResponse."},
+        },
+    )
+    async def score_batch(
+        request: Annotated[ScoreBatchRequest, Body(...)],
+    ) -> ScoreBatchResponse:
+        return await impl.score_batch(request)
+
+    return router