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

llama_stack/cli/stack/_list_deps.py

@@ -47,16 +47,20 @@ def format_output_deps_only(
     uv_str = ""
     if uv:
         uv_str = "uv pip install "
-
-    # Quote deps with commas
-    quoted_normal_deps = [quote_if_needed(dep) for dep in normal_deps]
-    lines.append(f"{uv_str}{' '.join(quoted_normal_deps)}")
+        # Only quote when emitting a shell command. In deps-only mode, keep raw
+        # specs so they can be safely consumed via command substitution.
+        formatted_normal_deps = [quote_if_needed(dep) for dep in normal_deps]
+    else:
+        formatted_normal_deps = normal_deps
+    lines.append(f"{uv_str}{' '.join(formatted_normal_deps)}")
 
     for special_dep in special_deps:
-        lines.append(f"{uv_str}{quote_special_dep(special_dep)}")
+        formatted = quote_special_dep(special_dep) if uv else special_dep
+        lines.append(f"{uv_str}{formatted}")
 
     for external_dep in external_deps:
-        lines.append(f"{uv_str}{quote_special_dep(external_dep)}")
+        formatted = quote_special_dep(external_dep) if uv else external_dep
+        lines.append(f"{uv_str}{formatted}")
 
     return "\n".join(lines)
 
@@ -119,7 +123,7 @@ def run_stack_list_deps_command(args: argparse.Namespace) -> None:
                     file=sys.stderr,
                 )
                 sys.exit(1)
-        config = StackConfig(providers=provider_list, image_name="providers-run")
+        config = StackConfig(providers=provider_list, distro_name="providers-run")
 
     normal_deps, special_deps, external_provider_dependencies = get_provider_dependencies(config)
     normal_deps += SERVER_DEPENDENCIES

llama_stack/cli/stack/run.py

@@ -15,11 +15,10 @@ import uvicorn
 import yaml
 from termcolor import cprint
 
-from llama_stack.cli.stack.utils import ImageType
 from llama_stack.cli.subcommand import Subcommand
 from llama_stack.core.datatypes import Api, Provider, StackConfig
 from llama_stack.core.distribution import get_provider_registry
-from llama_stack.core.stack import cast_image_name_to_string, replace_env_vars
+from llama_stack.core.stack import cast_distro_name_to_string, replace_env_vars
 from llama_stack.core.storage.datatypes import (
     InferenceStoreReference,
     KVStoreReference,
@@ -65,18 +64,6 @@ class StackRun(Subcommand):
             help="Port to run the server on. It can also be passed via the env var LLAMA_STACK_PORT.",
             default=int(os.getenv("LLAMA_STACK_PORT", 8321)),
         )
-        self.parser.add_argument(
-            "--image-name",
-            type=str,
-            default=None,
-            help="[DEPRECATED] This flag is no longer supported. Please activate your virtual environment before running.",
-        )
-        self.parser.add_argument(
-            "--image-type",
-            type=str,
-            help="[DEPRECATED] This flag is no longer supported. Please activate your virtual environment before running.",
-            choices=[e.value for e in ImageType if e.value != ImageType.CONTAINER.value],
-        )
         self.parser.add_argument(
             "--enable-ui",
             action="store_true",
@@ -94,15 +81,6 @@ class StackRun(Subcommand):
 
         from llama_stack.core.configure import parse_and_maybe_upgrade_config
 
-        if args.image_type or args.image_name:
-            self.parser.error(
-                "The --image-type and --image-name flags are no longer supported.\n\n"
-                "Please activate your virtual environment manually before running `llama stack run`.\n\n"
-                "For example:\n"
-                "  source /path/to/venv/bin/activate\n"
-                "  llama stack run <config>\n"
-            )
-
         if args.enable_ui:
             self._start_ui_development_server(args.port)
 
@@ -194,7 +172,7 @@ class StackRun(Subcommand):
                 logger_config = LoggingConfig(**cfg)
             else:
                 logger_config = None
-            config = StackConfig(**cast_image_name_to_string(replace_env_vars(config_contents)))
+            config = StackConfig(**cast_distro_name_to_string(replace_env_vars(config_contents)))
 
         port = args.port or config.server.port
         host = config.server.host or ["::", "0.0.0.0"]
@@ -322,7 +300,7 @@ class StackRun(Subcommand):
         )
 
         return StackConfig(
-            image_name="providers-run",
+            distro_name="providers-run",
             apis=apis,
             providers=providers,
             storage=storage,

llama_stack/core/access_control/datatypes.py

@@ -25,6 +25,20 @@ class Scope(BaseModel):
     resource: str | None = None
 
 
+class RouteScope(BaseModel):
+    """Scope for route-level access control.
+
+    Defines which API routes can be accessed. The paths field
+    accepts single paths, lists of paths, or wildcards:
+    - Exact: "/v1/chat/completions"
+    - List: ["/v1/files*", "/v1/models*"]
+    - Prefix wildcard: "/v1/files*" matches "/v1/files" and all paths starting with "/v1/files"
+    - Full wildcard: "*"
+    """
+
+    paths: str | list[str]
+
+
 def _mutually_exclusive(obj, a: str, b: str):
     if getattr(obj, a) and getattr(obj, b):
         raise ValueError(f"{a} and {b} are mutually exclusive")
@@ -105,3 +119,67 @@ class AccessRule(BaseModel):
         elif self.unless:
             parse_conditions([self.unless])
         return self
+
+
+class RouteAccessRule(BaseModel):
+    """Route-level access rule for controlling API route access.
+
+    This rule defines which API routes users can access based on their
+    attributes (roles, teams, etc). Rules are evaluated before resource-level
+    access control.
+
+    A rule defines either permit or forbid access to specific routes. The routes
+    are specified using the 'paths' field which can be:
+    - A single exact path: "/v1/chat/completions"
+    - A list of paths: ["/v1/files*", "/v1/models*"]
+    - A wildcard prefix: "/v1/files*" matches /v1/files and all paths starting with /v1/files
+    - Full wildcard: "*" matches all routes
+
+    Path normalization: Trailing slashes are automatically removed (e.g., /v1/files/ becomes /v1/files).
+
+    A rule may also specify a condition using 'when' or 'unless', with the same
+    constraints as resource-level rules:
+    - 'user with <attr-value> in <attr-name>'
+    - 'user with <attr-value> not in <attr-name>'
+
+    If no route_policy is configured, all routes are allowed.
+    If route_policy is configured, rules are tested in order to find a match.
+
+    Examples in yaml:
+
+    - permit:
+        paths: "/v1/chat/completions"
+      when: user with developer in roles
+      description: developers can access chat completions
+
+    - permit:
+        paths: ["/v1/files*", "/v1/models*"]
+      when: user with user in roles
+      description: users can access files and models routes
+
+    - permit:
+        paths: "*"
+      when: user with admin in roles
+      description: admins have access to all routes
+    """
+
+    permit: RouteScope | None = None
+    forbid: RouteScope | None = None
+    when: str | list[str] | None = None
+    unless: str | list[str] | None = None
+    description: str | None = None
+
+    @model_validator(mode="after")
+    def validate_rule_format(self) -> Self:
+        _require_one_of(self, "permit", "forbid")
+        _mutually_exclusive(self, "permit", "forbid")
+        _mutually_exclusive(self, "when", "unless")
+        if isinstance(self.when, list):
+            parse_conditions(self.when)
+        elif self.when:
+            parse_conditions([self.when])
+        if isinstance(self.unless, list):
+            parse_conditions(self.unless)
+        elif self.unless:
+            parse_conditions([self.unless])
+        return self

llama_stack/core/configure.py

@@ -16,7 +16,7 @@ from llama_stack.core.distribution import (
     builtin_automatically_routed_apis,
     get_provider_registry,
 )
-from llama_stack.core.stack import cast_image_name_to_string, replace_env_vars
+from llama_stack.core.stack import cast_distro_name_to_string, replace_env_vars
 from llama_stack.core.utils.dynamic import instantiate_class_type
 from llama_stack.core.utils.prompt_for_config import prompt_for_config
 from llama_stack.log import get_logger
@@ -200,4 +200,4 @@ def parse_and_maybe_upgrade_config(config_dict: dict[str, Any]) -> StackConfig:
     config_dict["version"] = LLAMA_STACK_RUN_CONFIG_VERSION
 
     processed_config_dict = replace_env_vars(config_dict)
-    return StackConfig(**cast_image_name_to_string(processed_config_dict))
+    return StackConfig(**cast_distro_name_to_string(processed_config_dict))

llama_stack/{distributions/meta-reference-gpu → core/connectors}/__init__.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.
 
-from .meta_reference import get_distribution_template  # noqa: F401
+from llama_stack.core.connectors.connectors import ConnectorServiceConfig, ConnectorServiceImpl
+
+__all__ = ["ConnectorServiceConfig", "ConnectorServiceImpl"]

llama_stack/core/connectors/connectors.py

@@ -0,0 +1,162 @@
+# 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.
+
+import json
+
+from pydantic import BaseModel, Field
+
+from llama_stack.core.datatypes import StackConfig
+from llama_stack.core.storage.kvstore import KVStore, kvstore_impl
+from llama_stack.log import get_logger
+from llama_stack.providers.utils.tools.mcp import get_mcp_server_info, list_mcp_tools
+from llama_stack_api import (
+    Connector,
+    ConnectorNotFoundError,
+    Connectors,
+    ConnectorToolNotFoundError,
+    ConnectorType,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+    ToolDef,
+)
+
+logger = get_logger(name=__name__, category="connectors")
+
+
+class ConnectorServiceConfig(BaseModel):
+    """Configuration for the built-in connector service."""
+
+    config: StackConfig = Field(..., description="Stack run configuration for resolving persistence")
+
+
+async def get_provider_impl(config: ConnectorServiceConfig):
+    """Get the connector service implementation."""
+    impl = ConnectorServiceImpl(config)
+    return impl
+
+
+KEY_PREFIX = "connectors:v1:"
+
+
+class ConnectorServiceImpl(Connectors):
+    """Built-in connector service implementation."""
+
+    def __init__(self, config: ConnectorServiceConfig):
+        self.config = config
+        self.kvstore: KVStore
+
+    def _get_key(self, connector_id: str) -> str:
+        """Get the KVStore key for a connector."""
+        return f"{KEY_PREFIX}{connector_id}"
+
+    async def initialize(self):
+        """Initialize the connector service."""
+
+        # Use connectors store reference from run config
+        connectors_ref = self.config.config.storage.stores.connectors
+        if not connectors_ref:
+            raise ValueError("storage.stores.connectors must be configured in config")
+        self.kvstore = await kvstore_impl(connectors_ref)
+
+    async def register_connector(
+        self,
+        connector_id: str,
+        connector_type: ConnectorType,
+        url: str,
+        server_label: str | None = None,
+        server_name: str | None = None,
+        server_description: str | None = None,
+    ) -> Connector:
+        """Register a new connector"""
+
+        connector = Connector(
+            connector_id=connector_id,
+            connector_type=connector_type,
+            url=url,
+            server_label=server_label,
+            server_name=server_name,
+            server_description=server_description,
+        )
+
+        key = self._get_key(connector_id)
+        existing_connector_json = await self.kvstore.get(key)
+
+        if existing_connector_json:
+            existing_connector = Connector.model_validate_json(existing_connector_json)
+
+            if connector == existing_connector:
+                logger.info(
+                    "Connector %s already exists; skipping registration",
+                    connector_id,
+                )
+                return existing_connector
+
+        await self.kvstore.set(key, json.dumps(connector.model_dump()))
+
+        return connector
+
+    async def unregister_connector(self, connector_id: str):
+        """Unregister a connector."""
+        key = self._get_key(connector_id)
+        if not await self.kvstore.get(key):
+            return
+        await self.kvstore.delete(key)
+
+    async def get_connector(
+        self,
+        request: GetConnectorRequest,
+        authorization: str | None = None,
+    ) -> Connector:
+        """Get a connector by its ID."""
+
+        connector_json = await self.kvstore.get(self._get_key(request.connector_id))
+        if not connector_json:
+            raise ConnectorNotFoundError(request.connector_id)
+        connector = Connector.model_validate_json(connector_json)
+
+        server_info = await get_mcp_server_info(connector.url, authorization=authorization)
+        connector.server_name = server_info.name
+        connector.server_description = server_info.description
+        connector.server_version = server_info.version
+        return connector
+
+    async def list_connectors(self) -> ListConnectorsResponse:
+        """List all connectors."""
+        connectors = []
+        for key in await self.kvstore.keys_in_range(start_key=KEY_PREFIX, end_key=KEY_PREFIX + "\uffff"):
+            connector_json = await self.kvstore.get(key)
+            if not connector_json:
+                continue
+            connector = Connector.model_validate_json(connector_json)
+            connectors.append(connector)
+        return ListConnectorsResponse(data=connectors)
+
+    async def get_connector_tool(self, request: GetConnectorToolRequest, authorization: str | None = None) -> ToolDef:
+        """Get a tool from a connector."""
+        connector_tools = await self.list_connector_tools(
+            ListConnectorToolsRequest(connector_id=request.connector_id), authorization=authorization
+        )
+        for tool in connector_tools.data:
+            if tool.name == request.tool_name:
+                return tool
+        raise ConnectorToolNotFoundError(request.connector_id, request.tool_name)
+
+    async def list_connector_tools(
+        self, request: ListConnectorToolsRequest, authorization: str | None = None
+    ) -> ListToolsResponse:
+        """List tools from a connector."""
+        connector = await self.get_connector(
+            GetConnectorRequest(connector_id=request.connector_id), authorization=authorization
+        )
+        tools = await list_mcp_tools(endpoint=connector.url, authorization=authorization)
+        return ListToolsResponse(data=tools.data)
+
+    async def shutdown(self):
+        """Shutdown the connector service."""
+        await self.kvstore.close()

llama_stack/core/conversations/conversations.py

@@ -6,7 +6,7 @@
 
 import secrets
 import time
-from typing import Any, Literal
+from typing import Any
 
 from pydantic import BaseModel, TypeAdapter
 
@@ -14,15 +14,21 @@ from llama_stack.core.datatypes import AccessRule, StackConfig
 from llama_stack.core.storage.sqlstore.authorized_sqlstore import AuthorizedSqlStore
 from llama_stack.core.storage.sqlstore.sqlstore import sqlstore_impl
 from llama_stack.log import get_logger
-from llama_stack_api import (
+from llama_stack_api.conversations import (
+    AddItemsRequest,
     Conversation,
     ConversationDeletedResource,
     ConversationItem,
     ConversationItemDeletedResource,
-    ConversationItemInclude,
     ConversationItemList,
     Conversations,
-    Metadata,
+    CreateConversationRequest,
+    DeleteConversationRequest,
+    DeleteItemRequest,
+    GetConversationRequest,
+    ListItemsRequest,
+    RetrieveItemRequest,
+    UpdateConversationRequest,
 )
 from llama_stack_api.internal.sqlstore import ColumnDefinition, ColumnType
 
@@ -85,9 +91,7 @@ class ConversationServiceImpl(Conversations):
             },
         )
 
-    async def create_conversation(
-        self, items: list[ConversationItem] | None = None, metadata: Metadata | None = None
-    ) -> Conversation:
+    async def create_conversation(self, request: CreateConversationRequest) -> Conversation:
         """Create a conversation."""
         random_bytes = secrets.token_bytes(24)
         conversation_id = f"conv_{random_bytes.hex()}"
@@ -97,7 +101,7 @@ class ConversationServiceImpl(Conversations):
             "id": conversation_id,
             "created_at": created_at,
             "items": [],
-            "metadata": metadata,
+            "metadata": request.metadata,
         }
 
         await self.sql_store.insert(
@@ -105,9 +109,9 @@ class ConversationServiceImpl(Conversations):
             data=record_data,
         )
 
-        if items:
+        if request.items:
             item_records = []
-            for item in items:
+            for item in request.items:
                 item_dict = item.model_dump()
                 item_id = self._get_or_generate_item_id(item, item_dict)
 
@@ -125,38 +129,38 @@ class ConversationServiceImpl(Conversations):
         conversation = Conversation(
             id=conversation_id,
             created_at=created_at,
-            metadata=metadata,
+            metadata=request.metadata,
             object="conversation",
         )
 
         logger.debug(f"Created conversation {conversation_id}")
         return conversation
 
-    async def get_conversation(self, conversation_id: str) -> Conversation:
+    async def get_conversation(self, request: GetConversationRequest) -> Conversation:
         """Get a conversation with the given ID."""
-        record = await self.sql_store.fetch_one(table="openai_conversations", where={"id": conversation_id})
+        record = await self.sql_store.fetch_one(table="openai_conversations", where={"id": request.conversation_id})
 
         if record is None:
-            raise ValueError(f"Conversation {conversation_id} not found")
+            raise ValueError(f"Conversation {request.conversation_id} not found")
 
         return Conversation(
             id=record["id"], created_at=record["created_at"], metadata=record.get("metadata"), object="conversation"
         )
 
-    async def update_conversation(self, conversation_id: str, metadata: Metadata) -> Conversation:
+    async def update_conversation(self, conversation_id: str, request: UpdateConversationRequest) -> Conversation:
         """Update a conversation's metadata with the given ID"""
         await self.sql_store.update(
-            table="openai_conversations", data={"metadata": metadata}, where={"id": conversation_id}
+            table="openai_conversations", data={"metadata": request.metadata}, where={"id": conversation_id}
         )
 
-        return await self.get_conversation(conversation_id)
+        return await self.get_conversation(GetConversationRequest(conversation_id=conversation_id))
 
-    async def openai_delete_conversation(self, conversation_id: str) -> ConversationDeletedResource:
+    async def openai_delete_conversation(self, request: DeleteConversationRequest) -> ConversationDeletedResource:
         """Delete a conversation with the given ID."""
-        await self.sql_store.delete(table="openai_conversations", where={"id": conversation_id})
+        await self.sql_store.delete(table="openai_conversations", where={"id": request.conversation_id})
 
-        logger.debug(f"Deleted conversation {conversation_id}")
-        return ConversationDeletedResource(id=conversation_id)
+        logger.debug(f"Deleted conversation {request.conversation_id}")
+        return ConversationDeletedResource(id=request.conversation_id)
 
     def _validate_conversation_id(self, conversation_id: str) -> None:
         """Validate conversation ID format."""
@@ -180,16 +184,16 @@ class ConversationServiceImpl(Conversations):
     async def _get_validated_conversation(self, conversation_id: str) -> Conversation:
         """Validate conversation ID and return the conversation if it exists."""
         self._validate_conversation_id(conversation_id)
-        return await self.get_conversation(conversation_id)
+        return await self.get_conversation(GetConversationRequest(conversation_id=conversation_id))
 
-    async def add_items(self, conversation_id: str, items: list[ConversationItem]) -> ConversationItemList:
+    async def add_items(self, conversation_id: str, request: AddItemsRequest) -> ConversationItemList:
         """Create (add) items to a conversation."""
         await self._get_validated_conversation(conversation_id)
 
         created_items = []
         base_time = int(time.time())
 
-        for i, item in enumerate(items):
+        for i, item in enumerate(request.items):
             item_dict = item.model_dump()
             item_id = self._get_or_generate_item_id(item, item_dict)
 
@@ -224,48 +228,47 @@ class ConversationServiceImpl(Conversations):
             has_more=False,
         )
 
-    async def retrieve(self, conversation_id: str, item_id: str) -> ConversationItem:
+    async def retrieve(self, request: RetrieveItemRequest) -> ConversationItem:
         """Retrieve a conversation item."""
-        if not conversation_id:
-            raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}")
-        if not item_id:
-            raise ValueError(f"Expected a non-empty value for `item_id` but received {item_id!r}")
+        if not request.conversation_id:
+            raise ValueError(
+                f"Expected a non-empty value for `conversation_id` but received {request.conversation_id!r}"
+            )
+        if not request.item_id:
+            raise ValueError(f"Expected a non-empty value for `item_id` but received {request.item_id!r}")
 
         # Get item from conversation_items table
         record = await self.sql_store.fetch_one(
-            table="conversation_items", where={"id": item_id, "conversation_id": conversation_id}
+            table="conversation_items", where={"id": request.item_id, "conversation_id": request.conversation_id}
         )
 
         if record is None:
-            raise ValueError(f"Item {item_id} not found in conversation {conversation_id}")
+            raise ValueError(f"Item {request.item_id} not found in conversation {request.conversation_id}")
 
         adapter: TypeAdapter[ConversationItem] = TypeAdapter(ConversationItem)
         return adapter.validate_python(record["item_data"])
 
-    async def list_items(
-        self,
-        conversation_id: str,
-        after: str | None = None,
-        include: list[ConversationItemInclude] | None = None,
-        limit: int | None = None,
-        order: Literal["asc", "desc"] | None = None,
-    ) -> ConversationItemList:
+    async def list_items(self, request: ListItemsRequest) -> ConversationItemList:
         """List items in the conversation."""
-        if not conversation_id:
-            raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}")
+        if not request.conversation_id:
+            raise ValueError(
+                f"Expected a non-empty value for `conversation_id` but received {request.conversation_id!r}"
+            )
 
         # check if conversation exists
-        await self.get_conversation(conversation_id)
+        await self.get_conversation(GetConversationRequest(conversation_id=request.conversation_id))
 
-        result = await self.sql_store.fetch_all(table="conversation_items", where={"conversation_id": conversation_id})
+        result = await self.sql_store.fetch_all(
+            table="conversation_items", where={"conversation_id": request.conversation_id}
+        )
         records = result.data
 
-        if order is not None and order == "asc":
+        if request.order is not None and request.order == "asc":
             records.sort(key=lambda x: x["created_at"])
         else:
             records.sort(key=lambda x: x["created_at"], reverse=True)
 
-        actual_limit = limit or 20
+        actual_limit = request.limit or 20
 
         records = records[:actual_limit]
         items = [record["item_data"] for record in records]
@@ -283,30 +286,30 @@ class ConversationServiceImpl(Conversations):
             has_more=False,
         )
 
-    async def openai_delete_conversation_item(
-        self, conversation_id: str, item_id: str
-    ) -> ConversationItemDeletedResource:
+    async def openai_delete_conversation_item(self, request: DeleteItemRequest) -> ConversationItemDeletedResource:
         """Delete a conversation item."""
-        if not conversation_id:
-            raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}")
-        if not item_id:
-            raise ValueError(f"Expected a non-empty value for `item_id` but received {item_id!r}")
+        if not request.conversation_id:
+            raise ValueError(
+                f"Expected a non-empty value for `conversation_id` but received {request.conversation_id!r}"
+            )
+        if not request.item_id:
+            raise ValueError(f"Expected a non-empty value for `item_id` but received {request.item_id!r}")
 
-        _ = await self._get_validated_conversation(conversation_id)
+        _ = await self._get_validated_conversation(request.conversation_id)
 
         record = await self.sql_store.fetch_one(
-            table="conversation_items", where={"id": item_id, "conversation_id": conversation_id}
+            table="conversation_items", where={"id": request.item_id, "conversation_id": request.conversation_id}
         )
 
         if record is None:
-            raise ValueError(f"Item {item_id} not found in conversation {conversation_id}")
+            raise ValueError(f"Item {request.item_id} not found in conversation {request.conversation_id}")
 
         await self.sql_store.delete(
-            table="conversation_items", where={"id": item_id, "conversation_id": conversation_id}
+            table="conversation_items", where={"id": request.item_id, "conversation_id": request.conversation_id}
         )
 
-        logger.debug(f"Deleted item {item_id} from conversation {conversation_id}")
-        return ConversationItemDeletedResource(id=item_id)
+        logger.debug(f"Deleted item {request.item_id} from conversation {request.conversation_id}")
+        return ConversationItemDeletedResource(id=request.item_id)
 
     async def shutdown(self) -> None:
         pass