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

llama_stack_api/prompts/fastapi_routes.py

@@ -0,0 +1,163 @@
+# 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 Prompts API.
+
+This module defines the FastAPI router for the Prompts API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Depends, Path, Query
+
+from llama_stack_api.router_utils import create_path_dependency, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Prompts
+from .models import (
+    CreatePromptRequest,
+    DeletePromptRequest,
+    GetPromptRequest,
+    ListPromptsResponse,
+    ListPromptVersionsRequest,
+    Prompt,
+    SetDefaultVersionBodyRequest,
+    SetDefaultVersionRequest,
+    UpdatePromptBodyRequest,
+    UpdatePromptRequest,
+)
+
+# Path parameter dependencies for single-field models
+list_prompt_versions_request = create_path_dependency(ListPromptVersionsRequest)
+delete_prompt_request = create_path_dependency(DeletePromptRequest)
+
+
+def create_router(impl: Prompts) -> APIRouter:
+    """Create a FastAPI router for the Prompts API.
+
+    Args:
+        impl: The Prompts implementation instance
+
+    Returns:
+        APIRouter configured for the Prompts API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Prompts"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/prompts",
+        response_model=ListPromptsResponse,
+        summary="List all prompts.",
+        description="List all prompts.",
+        responses={
+            200: {"description": "A ListPromptsResponse containing all prompts."},
+        },
+    )
+    async def list_prompts() -> ListPromptsResponse:
+        return await impl.list_prompts()
+
+    @router.get(
+        "/prompts/{prompt_id}/versions",
+        response_model=ListPromptsResponse,
+        summary="List prompt versions.",
+        description="List all versions of a specific prompt.",
+        responses={
+            200: {"description": "A ListPromptsResponse containing all versions of the prompt."},
+        },
+    )
+    async def list_prompt_versions(
+        request: Annotated[ListPromptVersionsRequest, Depends(list_prompt_versions_request)],
+    ) -> ListPromptsResponse:
+        return await impl.list_prompt_versions(request)
+
+    @router.get(
+        "/prompts/{prompt_id}",
+        response_model=Prompt,
+        summary="Get a prompt.",
+        description="Get a prompt by its identifier and optional version.",
+        responses={
+            200: {"description": "A Prompt resource."},
+        },
+    )
+    async def get_prompt(
+        prompt_id: Annotated[str, Path(description="The identifier of the prompt to get.")],
+        version: Annotated[
+            int | None, Query(description="The version of the prompt to get (defaults to latest).")
+        ] = None,
+    ) -> Prompt:
+        request = GetPromptRequest(prompt_id=prompt_id, version=version)
+        return await impl.get_prompt(request)
+
+    @router.post(
+        "/prompts",
+        response_model=Prompt,
+        summary="Create a prompt.",
+        description="Create a new prompt.",
+        responses={
+            200: {"description": "The created Prompt resource."},
+        },
+    )
+    async def create_prompt(
+        request: Annotated[CreatePromptRequest, Body(...)],
+    ) -> Prompt:
+        return await impl.create_prompt(request)
+
+    @router.put(
+        "/prompts/{prompt_id}",
+        response_model=Prompt,
+        summary="Update a prompt.",
+        description="Update an existing prompt (increments version).",
+        responses={
+            200: {"description": "The updated Prompt resource with incremented version."},
+        },
+    )
+    async def update_prompt(
+        prompt_id: Annotated[str, Path(description="The identifier of the prompt to update.")],
+        body: Annotated[UpdatePromptBodyRequest, Body(...)],
+    ) -> Prompt:
+        request = UpdatePromptRequest(
+            prompt_id=prompt_id,
+            prompt=body.prompt,
+            version=body.version,
+            variables=body.variables,
+            set_as_default=body.set_as_default,
+        )
+        return await impl.update_prompt(request)
+
+    @router.delete(
+        "/prompts/{prompt_id}",
+        summary="Delete a prompt.",
+        description="Delete a prompt.",
+        responses={
+            200: {"description": "The prompt was successfully deleted."},
+        },
+    )
+    async def delete_prompt(
+        request: Annotated[DeletePromptRequest, Depends(delete_prompt_request)],
+    ) -> None:
+        return await impl.delete_prompt(request)
+
+    @router.put(
+        "/prompts/{prompt_id}/set-default-version",
+        response_model=Prompt,
+        summary="Set prompt version.",
+        description="Set which version of a prompt should be the default in get_prompt (latest).",
+        responses={
+            200: {"description": "The prompt with the specified version now set as default."},
+        },
+    )
+    async def set_default_version(
+        prompt_id: Annotated[str, Path(description="The identifier of the prompt.")],
+        body: Annotated[SetDefaultVersionBodyRequest, Body(...)],
+    ) -> Prompt:
+        request = SetDefaultVersionRequest(prompt_id=prompt_id, version=body.version)
+        return await impl.set_default_version(request)
+
+    return router

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/providers/__init__.py

@@ -0,0 +1,33 @@
+# 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.
+
+"""Providers API protocol and models.
+
+This module contains the Providers protocol definition.
+Pydantic models are defined in llama_stack_api.providers.models.
+The FastAPI router is defined in llama_stack_api.providers.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Providers
+
+# Import models for re-export
+from .models import (
+    InspectProviderRequest,
+    ListProvidersResponse,
+    ProviderInfo,
+)
+
+__all__ = [
+    "Providers",
+    "ProviderInfo",
+    "ListProvidersResponse",
+    "InspectProviderRequest",
+    "fastapi_routes",
+]

llama_stack_api/providers/api.py

@@ -0,0 +1,16 @@
+# 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 .models import InspectProviderRequest, ListProvidersResponse, ProviderInfo
+
+
+@runtime_checkable
+class Providers(Protocol):
+    async def list_providers(self) -> ListProvidersResponse: ...
+
+    async def inspect_provider(self, request: InspectProviderRequest) -> ProviderInfo: ...

llama_stack_api/providers/fastapi_routes.py

@@ -0,0 +1,57 @@
+# 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 Providers API.
+
+This module defines the FastAPI router for the Providers API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+
+from llama_stack_api.router_utils import create_path_dependency, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Providers
+from .models import InspectProviderRequest, ListProvidersResponse, ProviderInfo
+
+# Path parameter dependencies for single-field models
+get_inspect_provider_request = create_path_dependency(InspectProviderRequest)
+
+
+def create_router(impl: Providers) -> APIRouter:
+    """Create a FastAPI router for the Providers API."""
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Providers"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/providers",
+        response_model=ListProvidersResponse,
+        summary="List providers.",
+        description="List all available providers.",
+        responses={200: {"description": "A ListProvidersResponse containing information about all providers."}},
+    )
+    async def list_providers() -> ListProvidersResponse:
+        return await impl.list_providers()
+
+    @router.get(
+        "/providers/{provider_id}",
+        response_model=ProviderInfo,
+        summary="Get provider.",
+        description="Get detailed information about a specific provider.",
+        responses={200: {"description": "A ProviderInfo object containing the provider's details."}},
+    )
+    async def inspect_provider(
+        request: Annotated[InspectProviderRequest, Depends(get_inspect_provider_request)],
+    ) -> ProviderInfo:
+        return await impl.inspect_provider(request)
+
+    return router

llama_stack_api/providers/models.py

@@ -0,0 +1,24 @@
+# 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 Providers API requests and responses.
+
+This module re-exports models from llama_stack_api.admin.models to ensure
+a single source of truth and avoid type conflicts.
+"""
+
+# Import and re-export shared models from admin
+from llama_stack_api.admin.models import (
+    InspectProviderRequest,
+    ListProvidersResponse,
+    ProviderInfo,
+)
+
+__all__ = [
+    "ProviderInfo",
+    "ListProvidersResponse",
+    "InspectProviderRequest",
+]

llama_stack_api/rag_tool.py

@@ -0,0 +1,168 @@
+# 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, StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from llama_stack_api.common.content_types import URL, InterleavedContent
+
+
+class RRFRanker(BaseModel):
+    """
+    Reciprocal Rank Fusion (RRF) ranker configuration.
+
+    :param type: The type of ranker, always "rrf"
+    :param impact_factor: The impact factor for RRF scoring. Higher values give more weight to higher-ranked results.
+                         Must be greater than 0
+    """
+
+    type: Literal["rrf"] = "rrf"
+    impact_factor: float = Field(default=60.0, gt=0.0)  # default of 60 for optimal performance
+
+
+class WeightedRanker(BaseModel):
+    """
+    Weighted ranker configuration that combines vector and keyword scores.
+
+    :param type: The type of ranker, always "weighted"
+    :param alpha: Weight factor between 0 and 1.
+                 0 means only use keyword scores,
+                 1 means only use vector scores,
+                 values in between blend both scores.
+    """
+
+    type: Literal["weighted"] = "weighted"
+    alpha: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Weight factor between 0 and 1. 0 means only keyword scores, 1 means only vector scores.",
+    )
+
+
+Ranker = Annotated[
+    RRFRanker | WeightedRanker,
+    Field(discriminator="type"),
+]
+
+
+class RAGDocument(BaseModel):
+    """
+    A document to be used for document ingestion in the RAG Tool.
+
+    :param document_id: The unique identifier for the document.
+    :param content: The content of the document.
+    :param mime_type: The MIME type of the document.
+    :param metadata: Additional metadata for the document.
+    """
+
+    document_id: str
+    content: InterleavedContent | URL
+    mime_type: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RAGQueryResult(BaseModel):
+    """Result of a RAG query containing retrieved content and metadata.
+
+    :param content: (Optional) The retrieved content from the query
+    :param metadata: Additional metadata about the query result
+    """
+
+    content: InterleavedContent | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RAGQueryGenerator(Enum):
+    """Types of query generators for RAG systems.
+
+    :cvar default: Default query generator using simple text processing
+    :cvar llm: LLM-based query generator for enhanced query understanding
+    :cvar custom: Custom query generator implementation
+    """
+
+    default = "default"
+    llm = "llm"
+    custom = "custom"
+
+
+class RAGSearchMode(StrEnum):
+    """
+    Search modes for RAG query retrieval:
+    - VECTOR: Uses vector similarity search for semantic matching
+    - KEYWORD: Uses keyword-based search for exact matching
+    - HYBRID: Combines both vector and keyword search for better results
+    """
+
+    VECTOR = "vector"
+    KEYWORD = "keyword"
+    HYBRID = "hybrid"
+
+
+class DefaultRAGQueryGeneratorConfig(BaseModel):
+    """Configuration for the default RAG query generator.
+
+    :param type: Type of query generator, always 'default'
+    :param separator: String separator used to join query terms
+    """
+
+    type: Literal["default"] = "default"
+    separator: str = " "
+
+
+class LLMRAGQueryGeneratorConfig(BaseModel):
+    """Configuration for the LLM-based RAG query generator.
+
+    :param type: Type of query generator, always 'llm'
+    :param model: Name of the language model to use for query generation
+    :param template: Template string for formatting the query generation prompt
+    """
+
+    type: Literal["llm"] = "llm"
+    model: str
+    template: str
+
+
+RAGQueryGeneratorConfig = Annotated[
+    DefaultRAGQueryGeneratorConfig | LLMRAGQueryGeneratorConfig,
+    Field(discriminator="type"),
+]
+
+
+class RAGQueryConfig(BaseModel):
+    """
+    Configuration for the RAG query generation.
+
+    :param query_generator_config: Configuration for the query generator.
+    :param max_tokens_in_context: Maximum number of tokens in the context.
+    :param max_chunks: Maximum number of chunks to retrieve.
+    :param chunk_template: Template for formatting each retrieved chunk in the context.
+        Available placeholders: {index} (1-based chunk ordinal), {chunk.content} (chunk content string), {metadata} (chunk metadata dict).
+        Default: "Result {index}\\nContent: {chunk.content}\\nMetadata: {metadata}\\n"
+    :param mode: Search mode for retrieval—either "vector", "keyword", or "hybrid". Default "vector".
+    :param ranker: Configuration for the ranker to use in hybrid search. Defaults to RRF ranker.
+    """
+
+    # This config defines how a query is generated using the messages
+    # for memory bank retrieval.
+    query_generator_config: RAGQueryGeneratorConfig = Field(default=DefaultRAGQueryGeneratorConfig())
+    max_tokens_in_context: int = 4096
+    max_chunks: int = 5
+    chunk_template: str = "Result {index}\nContent: {chunk.content}\nMetadata: {metadata}\n"
+    mode: RAGSearchMode | None = RAGSearchMode.VECTOR
+    ranker: Ranker | None = Field(default=None)  # Only used for hybrid mode
+
+    @field_validator("chunk_template")
+    def validate_chunk_template(cls, v: str) -> str:
+        if "{chunk.content}" not in v:
+            raise ValueError("chunk_template must contain {chunk.content}")
+        if "{index}" not in v:
+            raise ValueError("chunk_template must contain {index}")
+        if len(v) == 0:
+            raise ValueError("chunk_template must not be empty")
+        return v

llama_stack_api/resource.py

@@ -0,0 +1,36 @@
+# 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 StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class ResourceType(StrEnum):
+    model = "model"
+    shield = "shield"
+    vector_store = "vector_store"
+    dataset = "dataset"
+    scoring_function = "scoring_function"
+    benchmark = "benchmark"
+    tool = "tool"
+    tool_group = "tool_group"
+    prompt = "prompt"
+
+
+class Resource(BaseModel):
+    """Base class for all Llama Stack resources"""
+
+    identifier: str = Field(description="Unique identifier for this resource in llama stack")
+
+    provider_resource_id: str | None = Field(
+        default=None,
+        description="Unique identifier for this resource in the provider",
+    )
+
+    provider_id: str = Field(description="ID of the provider that owns this resource")
+
+    type: ResourceType = Field(description="Type of resource (e.g. 'model', 'shield', 'vector_store', etc.)")