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

llama_stack_api/common/responses.py

@@ -0,0 +1,77 @@
+# 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
+
+from pydantic import BaseModel
+
+from llama_stack_api.schema_utils import json_schema_type
+
+
+class Order(Enum):
+    """Sort order for paginated responses.
+    :cvar asc: Ascending order
+    :cvar desc: Descending order
+    """
+
+    asc = "asc"
+    desc = "desc"
+
+
+@json_schema_type
+class PaginatedResponse(BaseModel):
+    """A generic paginated response that follows a simple format.
+
+    :param data: The list of items for the current page
+    :param has_more: Whether there are more items available after this set
+    :param url: The URL for accessing this list
+    """
+
+    data: list[dict[str, Any]]
+    has_more: bool
+    url: str | None = None
+
+
+# This is a short term solution to allow inference API to return metrics
+# The ideal way to do this is to have a way for all response types to include metrics
+# and all metric events logged to the telemetry API to be included with the response
+# To do this, we will need to augment all response types with a metrics field.
+# We have hit a blocker from stainless SDK that prevents us from doing this.
+# The blocker is that if we were to augment the response types that have a data field
+# in them like so
+# class ListModelsResponse(BaseModel):
+# metrics: Optional[List[MetricEvent]] = None
+# data: List[Models]
+# ...
+# The client SDK will need to access the data by using a .data field, which is not
+# ergonomic. Stainless SDK does support unwrapping the response type, but it
+# requires that the response type to only have a single field.
+
+# We will need a way in the client SDK to signal that the metrics are needed
+# and if they are needed, the client SDK has to return the full response type
+# without unwrapping it.
+
+
+@json_schema_type
+class MetricInResponse(BaseModel):
+    """A metric value included in API responses.
+    :param metric: The name of the metric
+    :param value: The numeric value of the metric
+    :param unit: (Optional) The unit of measurement for the metric value
+    """
+
+    metric: str
+    value: int | float
+    unit: str | None = None
+
+
+class MetricResponseMixin(BaseModel):
+    """Mixin class for API responses that can include metrics.
+    :param metrics: (Optional) List of metrics associated with the API response
+    """
+
+    metrics: list[MetricInResponse] | None = None

llama_stack_api/common/training_types.py

@@ -0,0 +1,47 @@
+# 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 datetime import datetime
+
+from pydantic import BaseModel
+
+from llama_stack_api.schema_utils import json_schema_type
+
+
+@json_schema_type
+class PostTrainingMetric(BaseModel):
+    """Training metrics captured during post-training jobs.
+
+    :param epoch: Training epoch number
+    :param train_loss: Loss value on the training dataset
+    :param validation_loss: Loss value on the validation dataset
+    :param perplexity: Perplexity metric indicating model confidence
+    """
+
+    epoch: int
+    train_loss: float
+    validation_loss: float
+    perplexity: float
+
+
+@json_schema_type
+class Checkpoint(BaseModel):
+    """Checkpoint created during training runs.
+
+    :param identifier: Unique identifier for the checkpoint
+    :param created_at: Timestamp when the checkpoint was created
+    :param epoch: Training epoch when the checkpoint was saved
+    :param post_training_job_id: Identifier of the training job that created this checkpoint
+    :param path: File system path where the checkpoint is stored
+    :param training_metrics: (Optional) Training metrics associated with this checkpoint
+    """
+
+    identifier: str
+    created_at: datetime
+    epoch: int
+    post_training_job_id: str
+    path: str
+    training_metrics: PostTrainingMetric | None = None

llama_stack_api/common/type_system.py

@@ -0,0 +1,146 @@
+# 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, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type, register_schema
+
+
+@json_schema_type
+class StringType(BaseModel):
+    """Parameter type for string values.
+
+    :param type: Discriminator type. Always "string"
+    """
+
+    type: Literal["string"] = "string"
+
+
+@json_schema_type
+class NumberType(BaseModel):
+    """Parameter type for numeric values.
+
+    :param type: Discriminator type. Always "number"
+    """
+
+    type: Literal["number"] = "number"
+
+
+@json_schema_type
+class BooleanType(BaseModel):
+    """Parameter type for boolean values.
+
+    :param type: Discriminator type. Always "boolean"
+    """
+
+    type: Literal["boolean"] = "boolean"
+
+
+@json_schema_type
+class ArrayType(BaseModel):
+    """Parameter type for array values.
+
+    :param type: Discriminator type. Always "array"
+    """
+
+    type: Literal["array"] = "array"
+
+
+@json_schema_type
+class ObjectType(BaseModel):
+    """Parameter type for object values.
+
+    :param type: Discriminator type. Always "object"
+    """
+
+    type: Literal["object"] = "object"
+
+
+@json_schema_type
+class JsonType(BaseModel):
+    """Parameter type for JSON values.
+
+    :param type: Discriminator type. Always "json"
+    """
+
+    type: Literal["json"] = "json"
+
+
+@json_schema_type
+class UnionType(BaseModel):
+    """Parameter type for union values.
+
+    :param type: Discriminator type. Always "union"
+    """
+
+    type: Literal["union"] = "union"
+
+
+@json_schema_type
+class ChatCompletionInputType(BaseModel):
+    """Parameter type for chat completion input.
+
+    :param type: Discriminator type. Always "chat_completion_input"
+    """
+
+    # expects List[Message] for messages
+    type: Literal["chat_completion_input"] = "chat_completion_input"
+
+
+@json_schema_type
+class CompletionInputType(BaseModel):
+    """Parameter type for completion input.
+
+    :param type: Discriminator type. Always "completion_input"
+    """
+
+    # expects InterleavedTextMedia for content
+    type: Literal["completion_input"] = "completion_input"
+
+
+@json_schema_type
+class DialogType(BaseModel):
+    """Parameter type for dialog data with semantic output labels.
+
+    :param type: Discriminator type. Always "dialog"
+    """
+
+    # expects List[Message] for messages
+    # this type semantically contains the output label whereas ChatCompletionInputType does not
+    type: Literal["dialog"] = "dialog"
+
+
+ParamType = Annotated[
+    StringType
+    | NumberType
+    | BooleanType
+    | ArrayType
+    | ObjectType
+    | JsonType
+    | UnionType
+    | ChatCompletionInputType
+    | CompletionInputType,
+    Field(discriminator="type"),
+]
+register_schema(ParamType, name="ParamType")
+
+"""
+# TODO: recursive definition of ParamType in these containers
+# will cause infinite recursion in OpenAPI generation script
+# since we are going with ChatCompletionInputType and CompletionInputType
+# we don't need to worry about ArrayType/ObjectType/UnionType for now
+ArrayType.model_rebuild()
+ObjectType.model_rebuild()
+UnionType.model_rebuild()
+
+
+class CustomType(BaseModel):
+pylint: disable=syntax-error
+    type: Literal["custom"] = "custom"
+    validator_class: str
+"""

llama_stack_api/connectors/__init__.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.
+
+"""Connectors API package.
+
+This package contains the Connectors API definition, models, and FastAPI router.
+"""
+
+from . import fastapi_routes
+from .api import Connectors
+from .models import (
+    CommonConnectorFields,
+    Connector,
+    ConnectorInput,
+    ConnectorType,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+)
+
+__all__ = [
+    "Connectors",
+    "CommonConnectorFields",
+    "Connector",
+    "ConnectorInput",
+    "ConnectorType",
+    "GetConnectorRequest",
+    "GetConnectorToolRequest",
+    "ListConnectorsResponse",
+    "ListConnectorToolsRequest",
+    "ListToolsResponse",
+    "fastapi_routes",
+]

llama_stack_api/connectors/api.py

@@ -0,0 +1,50 @@
+# 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.
+
+"""Connectors API protocol definition.
+
+This module contains the Connectors protocol definition.
+Pydantic models are defined in llama_stack_api.connectors.models.
+The FastAPI router is defined in llama_stack_api.connectors.fastapi_routes.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from llama_stack_api.tools import ToolDef
+
+from .models import (
+    Connector,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+)
+
+
+@runtime_checkable
+class Connectors(Protocol):
+    """Protocol for connector management operations."""
+
+    async def get_connector(
+        self,
+        request: GetConnectorRequest,
+        authorization: str | None = None,
+    ) -> Connector: ...
+
+    async def list_connectors(self) -> ListConnectorsResponse: ...
+
+    async def list_connector_tools(
+        self,
+        request: ListConnectorToolsRequest,
+        authorization: str | None = None,
+    ) -> ListToolsResponse: ...
+
+    async def get_connector_tool(
+        self,
+        request: GetConnectorToolRequest,
+        authorization: str | None = None,
+    ) -> ToolDef: ...

llama_stack_api/connectors/fastapi_routes.py

@@ -0,0 +1,103 @@
+# 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 Connectors API.
+
+This module defines the FastAPI router for the Connectors API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Path, Query
+
+from llama_stack_api.router_utils import create_path_dependency, standard_responses
+from llama_stack_api.tools import ToolDef
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+from .api import Connectors
+from .models import (
+    Connector,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+)
+
+# Path parameter dependencies for single-field request models
+get_connector_request = create_path_dependency(GetConnectorRequest)
+list_connector_tools_request = create_path_dependency(ListConnectorToolsRequest)
+
+
+def create_router(impl: Connectors) -> APIRouter:
+    """Create a FastAPI router for the Connectors API.
+
+    Args:
+        impl: The Connectors implementation instance
+
+    Returns:
+        APIRouter configured for the Connectors API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1ALPHA}",
+        tags=["Connectors"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/connectors",
+        response_model=ListConnectorsResponse,
+        summary="List all connectors.",
+        description="List all configured connectors.",
+    )
+    async def list_connectors() -> ListConnectorsResponse:
+        return await impl.list_connectors()
+
+    # NOTE: Route order matters! More specific routes must come before less specific ones.
+    # /connectors/{connector_id}/tools/{tool_name} must come before /connectors/{connector_id}/tools
+    # /connectors/{connector_id}/tools must come before /connectors/{connector_id}
+
+    @router.get(
+        "/connectors/{connector_id}/tools/{tool_name}",
+        response_model=ToolDef,
+        summary="Get a tool by name from a connector.",
+        description="Get a tool definition by its name from a connector.",
+    )
+    async def get_connector_tool(
+        connector_id: Annotated[str, Path(description="Identifier for the connector")],
+        tool_name: Annotated[str, Path(description="Name of the tool")],
+        authorization: Annotated[str | None, Query(description="Authorization token")] = None,
+    ) -> ToolDef:
+        # GetConnectorToolRequest has 2 path params, so we construct it manually
+        request = GetConnectorToolRequest(connector_id=connector_id, tool_name=tool_name)
+        return await impl.get_connector_tool(request, authorization=authorization)
+
+    @router.get(
+        "/connectors/{connector_id}/tools",
+        response_model=ListToolsResponse,
+        summary="List tools from a connector.",
+        description="List all tools available from a connector.",
+    )
+    async def list_connector_tools(
+        request: Annotated[ListConnectorToolsRequest, Depends(list_connector_tools_request)],
+        authorization: Annotated[str | None, Query(description="Authorization token")] = None,
+    ) -> ListToolsResponse:
+        return await impl.list_connector_tools(request, authorization=authorization)
+
+    @router.get(
+        "/connectors/{connector_id}",
+        response_model=Connector,
+        summary="Get a connector by its ID.",
+        description="Get a connector by its ID.",
+    )
+    async def get_connector(
+        request: Annotated[GetConnectorRequest, Depends(get_connector_request)],
+        authorization: Annotated[str | None, Query(description="Authorization token")] = None,
+    ) -> Connector:
+        return await impl.get_connector(request, authorization=authorization)
+
+    return router

llama_stack_api/connectors/models.py

@@ -0,0 +1,103 @@
+# 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.
+
+"""Connectors API models.
+
+This module contains the Pydantic models for the Connectors API.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type
+from llama_stack_api.tools import ToolDef
+
+
+@json_schema_type
+class ConnectorType(StrEnum):
+    """Type of connector."""
+
+    MCP = "mcp"
+
+
+class CommonConnectorFields(BaseModel):
+    """Common fields for all connectors"""
+
+    connector_type: ConnectorType = Field(default=ConnectorType.MCP)
+    connector_id: str = Field(..., description="Identifier for the connector")
+    url: str = Field(..., description="URL of the connector")
+    server_label: str | None = Field(default=None, description="Label of the server")
+
+
+@json_schema_type
+class Connector(CommonConnectorFields):
+    """A connector registered in Llama Stack"""
+
+    model_config = {"populate_by_name": True}
+    server_name: str | None = Field(default=None, description="Name of the server")
+    server_description: str | None = Field(default=None, description="Description of the server")
+    server_version: str | None = Field(default=None, description="Version of the server")
+
+
+@json_schema_type
+class ConnectorInput(CommonConnectorFields):
+    """Input for creating a connector"""
+
+
+# Path parameter models (single field for create_path_dependency)
+
+
+@json_schema_type
+class GetConnectorRequest(BaseModel):
+    """Request model for getting a connector by ID."""
+
+    connector_id: str = Field(..., description="Identifier for the connector")
+
+
+@json_schema_type
+class ListConnectorToolsRequest(BaseModel):
+    """Request model for listing tools from a connector."""
+
+    connector_id: str = Field(..., description="Identifier for the connector")
+
+
+@json_schema_type
+class GetConnectorToolRequest(BaseModel):
+    """Request model for getting a tool from a connector."""
+
+    connector_id: str = Field(..., description="Identifier for the connector")
+    tool_name: str = Field(..., description="Name of the tool")
+
+
+# Response models
+
+
+@json_schema_type
+class ListConnectorsResponse(BaseModel):
+    """Response containing a list of configured connectors"""
+
+    data: list[Connector]
+
+
+@json_schema_type
+class ListToolsResponse(BaseModel):
+    """Response containing a list of tools"""
+
+    data: list[ToolDef]
+
+
+__all__ = [
+    "ConnectorType",
+    "CommonConnectorFields",
+    "Connector",
+    "ConnectorInput",
+    "GetConnectorRequest",
+    "ListConnectorsResponse",
+    "ListConnectorToolsRequest",
+    "ListToolsResponse",
+    "GetConnectorToolRequest",
+]

llama_stack_api/conversations/__init__.py

@@ -0,0 +1,61 @@
+# 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.
+
+"""Conversations API protocol and models.
+
+This module contains the Conversations protocol definition.
+Pydantic models are defined in llama_stack_api.conversations.models.
+The FastAPI router is defined in llama_stack_api.conversations.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Conversations
+
+# Import models for re-export
+from .models import (
+    AddItemsRequest,
+    Conversation,
+    ConversationDeletedResource,
+    ConversationItem,
+    ConversationItemCreateRequest,
+    ConversationItemDeletedResource,
+    ConversationItemInclude,
+    ConversationItemList,
+    ConversationMessage,
+    CreateConversationRequest,
+    DeleteConversationRequest,
+    DeleteItemRequest,
+    GetConversationRequest,
+    ListItemsRequest,
+    Metadata,
+    RetrieveItemRequest,
+    UpdateConversationRequest,
+)
+
+__all__ = [
+    "Conversations",
+    "Conversation",
+    "ConversationMessage",
+    "ConversationItem",
+    "ConversationDeletedResource",
+    "ConversationItemCreateRequest",
+    "ConversationItemInclude",
+    "ConversationItemList",
+    "ConversationItemDeletedResource",
+    "Metadata",
+    "CreateConversationRequest",
+    "GetConversationRequest",
+    "UpdateConversationRequest",
+    "DeleteConversationRequest",
+    "AddItemsRequest",
+    "RetrieveItemRequest",
+    "ListItemsRequest",
+    "DeleteItemRequest",
+    "fastapi_routes",
+]

llama_stack_api/conversations/api.py

@@ -0,0 +1,44 @@
+# 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 (
+    AddItemsRequest,
+    Conversation,
+    ConversationDeletedResource,
+    ConversationItem,
+    ConversationItemDeletedResource,
+    ConversationItemList,
+    CreateConversationRequest,
+    DeleteConversationRequest,
+    DeleteItemRequest,
+    GetConversationRequest,
+    ListItemsRequest,
+    RetrieveItemRequest,
+    UpdateConversationRequest,
+)
+
+
+@runtime_checkable
+class Conversations(Protocol):
+    """Protocol for conversation management operations."""
+
+    async def create_conversation(self, request: CreateConversationRequest) -> Conversation: ...
+
+    async def get_conversation(self, request: GetConversationRequest) -> Conversation: ...
+
+    async def update_conversation(self, conversation_id: str, request: UpdateConversationRequest) -> Conversation: ...
+
+    async def openai_delete_conversation(self, request: DeleteConversationRequest) -> ConversationDeletedResource: ...
+
+    async def add_items(self, conversation_id: str, request: AddItemsRequest) -> ConversationItemList: ...
+
+    async def retrieve(self, request: RetrieveItemRequest) -> ConversationItem: ...
+
+    async def list_items(self, request: ListItemsRequest) -> ConversationItemList: ...
+
+    async def openai_delete_conversation_item(self, request: DeleteItemRequest) -> ConversationItemDeletedResource: ...