Release candidate 0.2.24-dev.20251019

.dockerignore

@@ -1,19 +0,0 @@
-.venv
-__pycache__
-*.pyc
-*.pyo
-*.pyd
-*.so
-.git
-.gitignore
-htmlcov*
-.coverage
-coverage*
-.cache
-.mypy_cache
-.pytest_cache
-.ruff_cache
-uv.lock
-node_modules
-build
-/tmp

.github/actions/run-and-record-tests/action.yml

@@ -82,13 +82,11 @@ runs:
           echo "No recording changes"
         fi
 
-    - name: Write docker logs to file
+    - name: Write inference logs to file
       if: ${{ always() }}
       shell: bash
       run: |
-        # Ollama logs (if ollama container exists)
-        sudo docker logs ollama > ollama-${{ inputs.inference-mode }}.log 2>&1 || true
-        # Note: distro container logs are now dumped in integration-tests.sh before container is removed
+        sudo docker logs ollama > ollama-${{ inputs.inference-mode }}.log || true
 
     - name: Upload logs
       if: ${{ always() }}

.github/workflows/install-script-ci.yml

@@ -30,11 +30,8 @@ jobs:
 
       - name: Build a single provider
         run: |
-          docker build . \
-            -f containers/Containerfile \
-            --build-arg INSTALL_MODE=editable \
-            --build-arg DISTRO_NAME=starter \
-            --tag llama-stack:starter-ci
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run --no-sync \
+            llama stack build --template starter --image-type container --image-name test
 
       - name: Run installer end-to-end
         run: |

.github/workflows/integration-auth-tests.yml

@@ -73,24 +73,6 @@ jobs:
           image_name: kube
           apis: []
           providers: {}
-          storage:
-            backends:
-              kv_default:
-                type: kv_sqlite
-                db_path: $run_dir/kvstore.db
-              sql_default:
-                type: sql_sqlite
-                db_path: $run_dir/sql_store.db
-            stores:
-              metadata:
-                namespace: registry
-                backend: kv_default
-              inference:
-                table_name: inference_store
-                backend: sql_default
-              conversations:
-                table_name: openai_conversations
-                backend: sql_default
           server:
             port: 8321
           EOF

.github/workflows/integration-tests.yml

@@ -47,7 +47,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        client-type: [library, docker]
+        client-type: [library, server, docker]
         # Use Python 3.13 only on nightly schedule (daily latest client test), otherwise use 3.12
         python-version: ${{ github.event.schedule == '0 0 * * *' && fromJSON('["3.12", "3.13"]') || fromJSON('["3.12"]') }}
         client-version: ${{ (github.event.schedule == '0 0 * * *' || github.event.inputs.test-all-client-versions == 'true') && fromJSON('["published", "latest"]') || fromJSON('["latest"]') }}

.github/workflows/integration-vector-io-tests.yml

@@ -169,7 +169,9 @@ jobs:
         run: |
           uv run --no-sync \
             pytest -sv --stack-config="files=inline::localfs,inference=inline::sentence-transformers,vector_io=${{ matrix.vector-io-provider }}" \
-            tests/integration/vector_io
+            tests/integration/vector_io \
+            --embedding-model inline::sentence-transformers/nomic-ai/nomic-embed-text-v1.5 \
+            --embedding-dimension 768
 
       - name: Check Storage and Memory Available After Tests
         if: ${{ always() }}

.github/workflows/pre-commit.yml

@@ -37,7 +37,7 @@ jobs:
             .pre-commit-config.yaml
 
       - name: Set up Node.js
-        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           node-version: '20'
           cache: 'npm'

.github/workflows/precommit-trigger.yml

@@ -99,7 +99,7 @@ jobs:
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: ${{ steps.check_author.outputs.pr_number }},
-              body: `⏳ Running [pre-commit hooks](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) on PR #${{ steps.check_author.outputs.pr_number }}...`
+              body: `⏳ Running pre-commit hooks on PR #${{ steps.check_author.outputs.pr_number }}...`
             });
 
       - name: Checkout PR branch (same-repo)
@@ -141,7 +141,7 @@ jobs:
 
       - name: Set up Node.js
         if: steps.check_author.outputs.authorized == 'true'
-        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           node-version: '20'
           cache: 'npm'

.github/workflows/providers-build.yml

@@ -14,8 +14,6 @@ on:
       - '.github/workflows/providers-build.yml'
       - 'llama_stack/distributions/**'
       - 'pyproject.toml'
-      - 'containers/Containerfile'
-      - '.dockerignore'
 
   pull_request:
     paths:
@@ -26,8 +24,6 @@ on:
       - '.github/workflows/providers-build.yml'
       - 'llama_stack/distributions/**'
       - 'pyproject.toml'
-      - 'containers/Containerfile'
-      - '.dockerignore'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/main' && github.run_id || github.ref }}
@@ -64,19 +60,15 @@ jobs:
       - name: Install dependencies
         uses: ./.github/actions/setup-runner
 
-      - name: Install distribution into venv
-        if: matrix.image-type == 'venv'
+      - name: Print build dependencies
         run: |
-          uv run llama stack list-deps ${{ matrix.distro }} | xargs -L1 uv pip install
+          uv run llama stack build --distro ${{ matrix.distro }} --image-type ${{ matrix.image-type }} --image-name test --print-deps-only
 
-      - name: Build container image
-        if: matrix.image-type == 'container'
+      - name: Run Llama Stack Build
         run: |
-          docker build . \
-            -f containers/Containerfile \
-            --build-arg INSTALL_MODE=editable \
-            --build-arg DISTRO_NAME=${{ matrix.distro }} \
-            --tag llama-stack:${{ matrix.distro }}-ci
+          # USE_COPY_NOT_MOUNT is set to true since mounting is not supported by docker buildx, we use COPY instead
+          # LLAMA_STACK_DIR is set to the current directory so we are building from the source
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run llama stack build --distro ${{ matrix.distro }} --image-type ${{ matrix.image-type }} --image-name test
 
       - name: Print dependencies in the image
         if: matrix.image-type == 'venv'
@@ -94,8 +86,8 @@ jobs:
 
       - name: Build a single provider
         run: |
-          uv pip install -e .
-          uv run --no-sync llama stack list-deps --providers inference=remote::ollama | xargs -L1 uv pip install
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run llama stack build --image-type venv --image-name test --providers inference=remote::ollama
+
   build-custom-container-distribution:
     runs-on: ubuntu-latest
     steps:
@@ -105,16 +97,11 @@ jobs:
       - name: Install dependencies
         uses: ./.github/actions/setup-runner
 
-      - name: Build container image
+      - name: Build a single provider
         run: |
-          BASE_IMAGE=$(yq -r '.distribution_spec.container_image // "python:3.12-slim"' llama_stack/distributions/ci-tests/build.yaml)
-          docker build . \
-            -f containers/Containerfile \
-            --build-arg INSTALL_MODE=editable \
-            --build-arg DISTRO_NAME=ci-tests \
-            --build-arg BASE_IMAGE="$BASE_IMAGE" \
-            --build-arg RUN_CONFIG_PATH=/workspace/llama_stack/distributions/ci-tests/run.yaml \
-            -t llama-stack:ci-tests
+          yq -i '.image_type = "container"' llama_stack/distributions/ci-tests/build.yaml
+          yq -i '.image_name = "test"' llama_stack/distributions/ci-tests/build.yaml
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run llama stack build --config llama_stack/distributions/ci-tests/build.yaml
 
       - name: Inspect the container image entrypoint
         run: |
@@ -125,7 +112,7 @@ jobs:
           fi
           entrypoint=$(docker inspect --format '{{ .Config.Entrypoint }}' $IMAGE_ID)
           echo "Entrypoint: $entrypoint"
-          if [ "$entrypoint" != "[/usr/local/bin/llama-stack-entrypoint.sh]" ]; then
+          if [ "$entrypoint" != "[llama stack run /app/run.yaml]" ]; then
             echo "Entrypoint is not correct"
             exit 1
           fi
@@ -142,19 +129,17 @@ jobs:
       - name: Pin distribution to UBI9 base
         run: |
           yq -i '
+            .image_type    = "container" |
+            .image_name    = "ubi9-test" |
             .distribution_spec.container_image = "registry.access.redhat.com/ubi9:latest"
           ' llama_stack/distributions/ci-tests/build.yaml
 
-      - name: Build UBI9 container image
+      - name: Build dev container (UBI9)
+        env:
+          USE_COPY_NOT_MOUNT: "true"
+          LLAMA_STACK_DIR: "."
         run: |
-          BASE_IMAGE=$(yq -r '.distribution_spec.container_image // "registry.access.redhat.com/ubi9:latest"' llama_stack/distributions/ci-tests/build.yaml)
-          docker build . \
-            -f containers/Containerfile \
-            --build-arg INSTALL_MODE=editable \
-            --build-arg DISTRO_NAME=ci-tests \
-            --build-arg BASE_IMAGE="$BASE_IMAGE" \
-            --build-arg RUN_CONFIG_PATH=/workspace/llama_stack/distributions/ci-tests/run.yaml \
-            -t llama-stack:ci-tests-ubi9
+          uv run llama stack build --config llama_stack/distributions/ci-tests/build.yaml
 
       - name: Inspect UBI9 image
         run: |
@@ -165,7 +150,7 @@ jobs:
           fi
           entrypoint=$(docker inspect --format '{{ .Config.Entrypoint }}' $IMAGE_ID)
           echo "Entrypoint: $entrypoint"
-          if [ "$entrypoint" != "[/usr/local/bin/llama-stack-entrypoint.sh]" ]; then
+          if [ "$entrypoint" != "[llama stack run /app/run.yaml]" ]; then
             echo "Entrypoint is not correct"
             exit 1
           fi

.github/workflows/providers-list-deps.yml

@@ -36,7 +36,7 @@ jobs:
       distros: ${{ steps.set-matrix.outputs.distros }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Generate Distribution List
         id: set-matrix
@@ -55,7 +55,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Install dependencies
         uses: ./.github/actions/setup-runner
@@ -79,7 +79,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Install dependencies
         uses: ./.github/actions/setup-runner
@@ -92,7 +92,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Install dependencies
         uses: ./.github/actions/setup-runner

.github/workflows/python-build-test.yml

@@ -24,7 +24,7 @@ jobs:
       uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
     - name: Install uv
-      uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
+      uses: astral-sh/setup-uv@eb1897b8dc4b5d5bfe39a428a8f2304605e0983c # v7.0.0
       with:
         python-version: ${{ matrix.python-version }}
         activate-environment: true

.github/workflows/test-external-provider-module.yml

@@ -46,9 +46,9 @@ jobs:
           yq -i '.image_type = "${{ matrix.image-type }}"' tests/external/ramalama-stack/run.yaml
           cat tests/external/ramalama-stack/run.yaml
 
-      - name: Install distribution dependencies
+      - name: Build distro from config file
         run: |
-          uv run llama stack list-deps tests/external/ramalama-stack/build.yaml | xargs -L1 uv pip install
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run llama stack build --config tests/external/ramalama-stack/build.yaml
 
       - name: Start Llama Stack server in background
         if: ${{ matrix.image-type }} == 'venv'

.github/workflows/test-external.yml

@@ -44,7 +44,7 @@ jobs:
 
       - name: Print distro dependencies
         run: |
-          uv run --no-sync llama stack list-deps tests/external/build.yaml
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run --no-sync llama stack list-deps tests/external/build.yaml
 
       - name: Build distro from config file
         run: |

.github/workflows/ui-unit-tests.yml

@@ -29,7 +29,7 @@ jobs:
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Setup Node.js
-        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'

benchmarking/k8s-benchmark/stack-configmap.yaml

@@ -98,30 +98,21 @@ data:
       - provider_id: model-context-protocol
         provider_type: remote::model-context-protocol
         config: {}
-    storage:
-      backends:
-        kv_default:
-          type: kv_postgres
-          host: ${env.POSTGRES_HOST:=localhost}
-          port: ${env.POSTGRES_PORT:=5432}
-          db: ${env.POSTGRES_DB:=llamastack}
-          user: ${env.POSTGRES_USER:=llamastack}
-          password: ${env.POSTGRES_PASSWORD:=llamastack}
-          table_name: ${env.POSTGRES_TABLE_NAME:=llamastack_kvstore}
-        sql_default:
-          type: sql_postgres
-          host: ${env.POSTGRES_HOST:=localhost}
-          port: ${env.POSTGRES_PORT:=5432}
-          db: ${env.POSTGRES_DB:=llamastack}
-          user: ${env.POSTGRES_USER:=llamastack}
-          password: ${env.POSTGRES_PASSWORD:=llamastack}
-      references:
-        metadata:
-          backend: kv_default
-          namespace: registry
-        inference:
-          backend: sql_default
-          table_name: inference_store
+    metadata_store:
+      type: postgres
+      host: ${env.POSTGRES_HOST:=localhost}
+      port: ${env.POSTGRES_PORT:=5432}
+      db: ${env.POSTGRES_DB:=llamastack}
+      user: ${env.POSTGRES_USER:=llamastack}
+      password: ${env.POSTGRES_PASSWORD:=llamastack}
+      table_name: llamastack_kvstore
+    inference_store:
+      type: postgres
+      host: ${env.POSTGRES_HOST:=localhost}
+      port: ${env.POSTGRES_PORT:=5432}
+      db: ${env.POSTGRES_DB:=llamastack}
+      user: ${env.POSTGRES_USER:=llamastack}
+      password: ${env.POSTGRES_PASSWORD:=llamastack}
     models:
     - metadata:
         embedding_dimension: 768
@@ -146,4 +137,5 @@ data:
       port: 8323
 kind: ConfigMap
 metadata:
+  creationTimestamp: null
   name: llama-stack-config

benchmarking/k8s-benchmark/stack_run_config.yaml

@@ -95,30 +95,21 @@ providers:
   - provider_id: model-context-protocol
     provider_type: remote::model-context-protocol
     config: {}
-storage:
-  backends:
-    kv_default:
-      type: kv_postgres
-      host: ${env.POSTGRES_HOST:=localhost}
-      port: ${env.POSTGRES_PORT:=5432}
-      db: ${env.POSTGRES_DB:=llamastack}
-      user: ${env.POSTGRES_USER:=llamastack}
-      password: ${env.POSTGRES_PASSWORD:=llamastack}
-      table_name: ${env.POSTGRES_TABLE_NAME:=llamastack_kvstore}
-    sql_default:
-      type: sql_postgres
-      host: ${env.POSTGRES_HOST:=localhost}
-      port: ${env.POSTGRES_PORT:=5432}
-      db: ${env.POSTGRES_DB:=llamastack}
-      user: ${env.POSTGRES_USER:=llamastack}
-      password: ${env.POSTGRES_PASSWORD:=llamastack}
-  references:
-    metadata:
-      backend: kv_default
-      namespace: registry
-    inference:
-      backend: sql_default
-      table_name: inference_store
+metadata_store:
+  type: postgres
+  host: ${env.POSTGRES_HOST:=localhost}
+  port: ${env.POSTGRES_PORT:=5432}
+  db: ${env.POSTGRES_DB:=llamastack}
+  user: ${env.POSTGRES_USER:=llamastack}
+  password: ${env.POSTGRES_PASSWORD:=llamastack}
+  table_name: llamastack_kvstore
+inference_store:
+  type: postgres
+  host: ${env.POSTGRES_HOST:=localhost}
+  port: ${env.POSTGRES_PORT:=5432}
+  db: ${env.POSTGRES_DB:=llamastack}
+  user: ${env.POSTGRES_USER:=llamastack}
+  password: ${env.POSTGRES_PASSWORD:=llamastack}
 models:
 - metadata:
     embedding_dimension: 768

client-sdks/stainless/README.md

@@ -1,8 +0,0 @@
-These are the source-of-truth configuration files used to generate the Stainless client SDKs via Stainless.
-
-- `openapi.yml`: this is the OpenAPI specification for the Llama Stack API.
-- `openapi.stainless.yml`: this is the Stainless _configuration_ which instructs Stainless how to generate the client SDKs.
-
-A small side note: notice the `.yml` suffixes since Stainless uses that suffix typically for its configuration files.
-
-These files go hand-in-hand. As of now, only the `openapi.yml` file is automatically generated using the `run_openapi_generator.sh` script.

client-sdks/stainless/openapi.stainless.yml

@@ -1,610 +0,0 @@
-# yaml-language-server: $schema=https://app.stainlessapi.com/config-internal.schema.json
-
-organization:
-  # Name of your organization or company, used to determine the name of the client
-  # and headings.
-  name: llama-stack-client
-  docs: https://llama-stack.readthedocs.io/en/latest/
-  contact: llamastack@meta.com
-security:
-  - {}
-  - BearerAuth: []
-security_schemes:
-  BearerAuth:
-    type: http
-    scheme: bearer
-# `targets` define the output targets and their customization options, such as
-# whether to emit the Node SDK and what it's package name should be.
-targets:
-  node:
-    package_name: llama-stack-client
-    production_repo: llamastack/llama-stack-client-typescript
-    publish:
-      npm: false
-  python:
-    package_name: llama_stack_client
-    production_repo: llamastack/llama-stack-client-python
-    options:
-      use_uv: true
-    publish:
-      pypi: true
-    project_name: llama_stack_client
-  kotlin:
-    reverse_domain: com.llama_stack_client.api
-    production_repo: null
-    publish:
-      maven: false
-  go:
-    package_name: llama-stack-client
-    production_repo: llamastack/llama-stack-client-go
-    options:
-      enable_v2: true
-      back_compat_use_shared_package: false
-
-# `client_settings` define settings for the API client, such as extra constructor
-# arguments (used for authentication), retry behavior, idempotency, etc.
-client_settings:
-  default_env_prefix: LLAMA_STACK_CLIENT
-  opts:
-    api_key:
-      type: string
-      read_env: LLAMA_STACK_CLIENT_API_KEY
-      auth: { security_scheme: BearerAuth }
-      nullable: true
-
-# `environments` are a map of the name of the environment (e.g. "sandbox",
-# "production") to the corresponding url to use.
-environments:
-  production: http://any-hosted-llama-stack.com
-
-# `pagination` defines [pagination schemes] which provides a template to match
-# endpoints and generate next-page and auto-pagination helpers in the SDKs.
-pagination:
-  - name: datasets_iterrows
-    type: offset
-    request:
-      dataset_id:
-        type: string
-      start_index:
-        type: integer
-        x-stainless-pagination-property:
-          purpose: offset_count_param
-      limit:
-        type: integer
-    response:
-      data:
-        type: array
-        items:
-          type: object
-      next_index:
-        type: integer
-        x-stainless-pagination-property:
-          purpose: offset_count_start_field
-  - name: openai_cursor_page
-    type: cursor
-    request:
-      limit:
-        type: integer
-      after:
-        type: string
-        x-stainless-pagination-property:
-          purpose: next_cursor_param
-    response:
-      data:
-        type: array
-        items: {}
-      has_more:
-        type: boolean
-      last_id:
-        type: string
-        x-stainless-pagination-property:
-          purpose: next_cursor_field
-# `resources` define the structure and organziation for your API, such as how
-# methods and models are grouped together and accessed. See the [configuration
-# guide] for more information.
-#
-# [configuration guide]:
-#   https://app.stainlessapi.com/docs/guides/configure#resources
-resources:
-  $shared:
-    models:
-      agent_config: AgentConfig
-      interleaved_content_item: InterleavedContentItem
-      interleaved_content: InterleavedContent
-      param_type: ParamType
-      safety_violation: SafetyViolation
-      sampling_params: SamplingParams
-      scoring_result: ScoringResult
-      message: Message
-      user_message: UserMessage
-      completion_message: CompletionMessage
-      tool_response_message: ToolResponseMessage
-      system_message: SystemMessage
-      tool_call: ToolCall
-      query_result: RAGQueryResult
-      document: RAGDocument
-      query_config: RAGQueryConfig
-      response_format: ResponseFormat
-  toolgroups:
-    models:
-      tool_group: ToolGroup
-      list_tool_groups_response: ListToolGroupsResponse
-    methods:
-      register: post /v1/toolgroups
-      get: get /v1/toolgroups/{toolgroup_id}
-      list: get /v1/toolgroups
-      unregister: delete /v1/toolgroups/{toolgroup_id}
-  tools:
-    methods:
-      get: get /v1/tools/{tool_name}
-      list:
-        endpoint: get /v1/tools
-        paginated: false
-
-  tool_runtime:
-    models:
-      tool_def: ToolDef
-      tool_invocation_result: ToolInvocationResult
-    methods:
-      list_tools:
-        endpoint: get /v1/tool-runtime/list-tools
-        paginated: false
-      invoke_tool: post /v1/tool-runtime/invoke
-    subresources:
-      rag_tool:
-        methods:
-          insert: post /v1/tool-runtime/rag-tool/insert
-          query: post /v1/tool-runtime/rag-tool/query
-
-  responses:
-    models:
-      response_object_stream: OpenAIResponseObjectStream
-      response_object: OpenAIResponseObject
-    methods:
-      create:
-        type: http
-        endpoint: post /v1/responses
-        streaming:
-          stream_event_model: responses.response_object_stream
-          param_discriminator: stream
-      retrieve: get /v1/responses/{response_id}
-      list:
-        type: http
-        endpoint: get /v1/responses
-      delete:
-        type: http
-        endpoint: delete /v1/responses/{response_id}
-    subresources:
-      input_items:
-        methods:
-          list:
-            type: http
-            endpoint: get /v1/responses/{response_id}/input_items
-
-  conversations:
-    models:
-      conversation_object: Conversation
-    methods:
-      create:
-        type: http
-        endpoint: post /v1/conversations
-      retrieve: get /v1/conversations/{conversation_id}
-      update:
-        type: http
-        endpoint: post /v1/conversations/{conversation_id}
-      delete:
-        type: http
-        endpoint: delete /v1/conversations/{conversation_id}
-    subresources:
-      items:
-        methods:
-          get:
-            type: http
-            endpoint: get /v1/conversations/{conversation_id}/items/{item_id}
-          list:
-            type: http
-            endpoint: get /v1/conversations/{conversation_id}/items
-          create:
-            type: http
-            endpoint: post /v1/conversations/{conversation_id}/items
-
-  inspect:
-    models:
-      healthInfo: HealthInfo
-      providerInfo: ProviderInfo
-      routeInfo: RouteInfo
-      versionInfo: VersionInfo
-    methods:
-      health: get /v1/health
-      version: get /v1/version
-
-  embeddings:
-    models:
-      create_embeddings_response: OpenAIEmbeddingsResponse
-    methods:
-      create: post /v1/embeddings
-
-  chat:
-    models:
-      chat_completion_chunk: OpenAIChatCompletionChunk
-    subresources:
-      completions:
-        methods:
-          create:
-            type: http
-            endpoint: post /v1/chat/completions
-            streaming:
-              stream_event_model: chat.chat_completion_chunk
-              param_discriminator: stream
-          list:
-            type: http
-            endpoint: get /v1/chat/completions
-          retrieve:
-            type: http
-            endpoint: get /v1/chat/completions/{completion_id}
-  completions:
-    methods:
-      create:
-        type: http
-        endpoint: post /v1/completions
-        streaming:
-          param_discriminator: stream
-
-  vector_io:
-    models:
-      queryChunksResponse: QueryChunksResponse
-    methods:
-      insert: post /v1/vector-io/insert
-      query: post /v1/vector-io/query
-
-  vector_stores:
-    models:
-      vector_store: VectorStoreObject
-      list_vector_stores_response: VectorStoreListResponse
-      vector_store_delete_response: VectorStoreDeleteResponse
-      vector_store_search_response: VectorStoreSearchResponsePage
-    methods:
-      create: post /v1/vector_stores
-      list:
-        endpoint: get /v1/vector_stores
-      retrieve: get /v1/vector_stores/{vector_store_id}
-      update: post /v1/vector_stores/{vector_store_id}
-      delete: delete /v1/vector_stores/{vector_store_id}
-      search: post /v1/vector_stores/{vector_store_id}/search
-    subresources:
-      files:
-        models:
-          vector_store_file: VectorStoreFileObject
-        methods:
-          list: get /v1/vector_stores/{vector_store_id}/files
-          retrieve: get /v1/vector_stores/{vector_store_id}/files/{file_id}
-          update: post /v1/vector_stores/{vector_store_id}/files/{file_id}
-          delete: delete /v1/vector_stores/{vector_store_id}/files/{file_id}
-          create: post /v1/vector_stores/{vector_store_id}/files
-          content: get /v1/vector_stores/{vector_store_id}/files/{file_id}/content
-      file_batches:
-        models:
-          vector_store_file_batches: VectorStoreFileBatchObject
-          list_vector_store_files_in_batch_response: VectorStoreFilesListInBatchResponse
-        methods:
-          create: post /v1/vector_stores/{vector_store_id}/file_batches
-          retrieve: get /v1/vector_stores/{vector_store_id}/file_batches/{batch_id}
-          list_files: get /v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files
-          cancel: post /v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel
-
-  models:
-    models:
-      model: Model
-      list_models_response: ListModelsResponse
-    methods:
-      retrieve: get /v1/models/{model_id}
-      list:
-        endpoint: get /v1/models
-        paginated: false
-      register: post /v1/models
-      unregister: delete /v1/models/{model_id}
-    subresources:
-      openai:
-        methods:
-          list:
-            endpoint: get /v1/models
-            paginated: false
-
-  providers:
-    models:
-      list_providers_response: ListProvidersResponse
-    methods:
-      list:
-        endpoint: get /v1/providers
-        paginated: false
-      retrieve: get /v1/providers/{provider_id}
-
-  routes:
-    models:
-      list_routes_response: ListRoutesResponse
-    methods:
-      list:
-        endpoint: get /v1/inspect/routes
-        paginated: false
-
-
-  moderations:
-    models:
-      create_response: ModerationObject
-    methods:
-      create: post /v1/moderations
-
-
-  safety:
-    models:
-      run_shield_response: RunShieldResponse
-    methods:
-      run_shield: post /v1/safety/run-shield
-
-
-  shields:
-    models:
-      shield: Shield
-      list_shields_response: ListShieldsResponse
-    methods:
-      retrieve: get /v1/shields/{identifier}
-      list:
-        endpoint: get /v1/shields
-        paginated: false
-      register: post /v1/shields
-      delete: delete /v1/shields/{identifier}
-
-  synthetic_data_generation:
-    models:
-      syntheticDataGenerationResponse: SyntheticDataGenerationResponse
-    methods:
-      generate: post /v1/synthetic-data-generation/generate
-
-  telemetry:
-    models:
-      span_with_status: SpanWithStatus
-      trace: Trace
-      query_spans_response: QuerySpansResponse
-      event: Event
-      query_condition: QueryCondition
-    methods:
-      query_traces:
-        endpoint: post /v1alpha/telemetry/traces
-        skip_test_reason: 'unsupported query params in java / kotlin'
-      get_span_tree: post /v1alpha/telemetry/spans/{span_id}/tree
-      query_spans:
-        endpoint: post /v1alpha/telemetry/spans
-        skip_test_reason: 'unsupported query params in java / kotlin'
-      query_metrics:
-        endpoint: post /v1alpha/telemetry/metrics/{metric_name}
-        skip_test_reason: 'unsupported query params in java / kotlin'
-      # log_event: post /v1alpha/telemetry/events
-      save_spans_to_dataset: post /v1alpha/telemetry/spans/export
-      get_span: get /v1alpha/telemetry/traces/{trace_id}/spans/{span_id}
-      get_trace: get /v1alpha/telemetry/traces/{trace_id}
-
-  scoring:
-    methods:
-      score: post /v1/scoring/score
-      score_batch: post /v1/scoring/score-batch
-  scoring_functions:
-    methods:
-      retrieve: get /v1/scoring-functions/{scoring_fn_id}
-      list:
-        endpoint: get /v1/scoring-functions
-        paginated: false
-      register: post /v1/scoring-functions
-    models:
-      scoring_fn: ScoringFn
-      scoring_fn_params: ScoringFnParams
-      list_scoring_functions_response: ListScoringFunctionsResponse
-
-  benchmarks:
-    methods:
-      retrieve: get /v1alpha/eval/benchmarks/{benchmark_id}
-      list:
-        endpoint: get /v1alpha/eval/benchmarks
-        paginated: false
-      register: post /v1alpha/eval/benchmarks
-    models:
-      benchmark: Benchmark
-      list_benchmarks_response: ListBenchmarksResponse
-
-  files:
-    methods:
-      create: post /v1/files
-      list: get /v1/files
-      retrieve: get /v1/files/{file_id}
-      delete: delete /v1/files/{file_id}
-      content: get /v1/files/{file_id}/content
-    models:
-      file: OpenAIFileObject
-      list_files_response: ListOpenAIFileResponse
-      delete_file_response: OpenAIFileDeleteResponse
-
-  alpha:
-    subresources:
-      inference:
-        methods:
-          rerank: post /v1alpha/inference/rerank
-
-      post_training:
-        models:
-          algorithm_config: AlgorithmConfig
-          post_training_job: PostTrainingJob
-          list_post_training_jobs_response: ListPostTrainingJobsResponse
-        methods:
-          preference_optimize: post /v1alpha/post-training/preference-optimize
-          supervised_fine_tune: post /v1alpha/post-training/supervised-fine-tune
-        subresources:
-          job:
-            methods:
-              artifacts: get /v1alpha/post-training/job/artifacts
-              cancel: post /v1alpha/post-training/job/cancel
-              status: get /v1alpha/post-training/job/status
-              list:
-                endpoint: get /v1alpha/post-training/jobs
-                paginated: false
-
-      eval:
-        methods:
-          evaluate_rows: post /v1alpha/eval/benchmarks/{benchmark_id}/evaluations
-          run_eval: post /v1alpha/eval/benchmarks/{benchmark_id}/jobs
-          evaluate_rows_alpha: post /v1alpha/eval/benchmarks/{benchmark_id}/evaluations
-          run_eval_alpha: post /v1alpha/eval/benchmarks/{benchmark_id}/jobs
-
-        subresources:
-          jobs:
-            methods:
-              cancel: delete /v1alpha/eval/benchmarks/{benchmark_id}/jobs/{job_id}
-              status: get /v1alpha/eval/benchmarks/{benchmark_id}/jobs/{job_id}
-              retrieve: get /v1alpha/eval/benchmarks/{benchmark_id}/jobs/{job_id}/result
-        models:
-          evaluate_response: EvaluateResponse
-          benchmark_config: BenchmarkConfig
-          job: Job
-
-      agents:
-        methods:
-          create: post /v1alpha/agents
-          list: get /v1alpha/agents
-          retrieve: get /v1alpha/agents/{agent_id}
-          delete: delete /v1alpha/agents/{agent_id}
-        models:
-          inference_step: InferenceStep
-          tool_execution_step: ToolExecutionStep
-          tool_response: ToolResponse
-          shield_call_step: ShieldCallStep
-          memory_retrieval_step: MemoryRetrievalStep
-        subresources:
-          session:
-            models:
-              session: Session
-            methods:
-              list: get /v1alpha/agents/{agent_id}/sessions
-              create: post /v1alpha/agents/{agent_id}/session
-              delete: delete /v1alpha/agents/{agent_id}/session/{session_id}
-              retrieve: get /v1alpha/agents/{agent_id}/session/{session_id}
-          steps:
-            methods:
-              retrieve: get /v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}
-          turn:
-            models:
-              turn: Turn
-              turn_response_event: AgentTurnResponseEvent
-              agent_turn_response_stream_chunk: AgentTurnResponseStreamChunk
-            methods:
-              create:
-                type: http
-                endpoint: post /v1alpha/agents/{agent_id}/session/{session_id}/turn
-                streaming:
-                  stream_event_model: alpha.agents.turn.agent_turn_response_stream_chunk
-                  param_discriminator: stream
-              retrieve: get /v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}
-              resume:
-                type: http
-                endpoint: post /v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume
-                streaming:
-                  stream_event_model: alpha.agents.turn.agent_turn_response_stream_chunk
-                  param_discriminator: stream
-
-  beta:
-    subresources:
-      datasets:
-        models:
-          list_datasets_response: ListDatasetsResponse
-        methods:
-          register: post /v1beta/datasets
-          retrieve: get /v1beta/datasets/{dataset_id}
-          list:
-            endpoint: get /v1beta/datasets
-            paginated: false
-          unregister: delete /v1beta/datasets/{dataset_id}
-          iterrows: get /v1beta/datasetio/iterrows/{dataset_id}
-          appendrows: post /v1beta/datasetio/append-rows/{dataset_id}
-
-
-settings:
-  license: MIT
-  unwrap_response_fields: [ data ]
-
-openapi:
-  transformations:
-    - command: renameValue
-      reason: pydantic reserved name
-      args:
-        filter:
-          only:
-            - '$.components.schemas.InferenceStep.properties.model_response'
-        rename:
-          python:
-            property_name: 'inference_model_response'
-
-    # - command: renameValue
-    #   reason: pydantic reserved name
-    #   args:
-    #     filter:
-    #       only:
-    #         - '$.components.schemas.Model.properties.model_type'
-    #     rename:
-    #       python:
-    #         property_name: 'type'
-    - command: mergeObject
-      reason: Better return_type using enum
-      args:
-        target:
-          - '$.components.schemas'
-        object:
-          ReturnType:
-            additionalProperties: false
-            properties:
-              type:
-                enum:
-                  - string
-                  - number
-                  - boolean
-                  - array
-                  - object
-                  - json
-                  - union
-                  - chat_completion_input
-                  - completion_input
-                  - agent_turn_input
-            required:
-              - type
-            type: object
-    - command: replaceProperties
-      reason: Replace return type properties with better model (see above)
-      args:
-        filter:
-          only:
-            - '$.components.schemas.ScoringFn.properties.return_type'
-            - '$.components.schemas.RegisterScoringFunctionRequest.properties.return_type'
-        value:
-          $ref: '#/components/schemas/ReturnType'
-    - command: oneOfToAnyOf
-      reason: Prism (mock server) doesn't like one of our requests as it technically matches multiple variants
-    - reason: For better names
-      command: extractToRefs
-      args:
-        ref:
-          target: '$.components.schemas.ToolCallDelta.properties.tool_call'
-          name: '#/components/schemas/ToolCallOrString'
-
-# `readme` is used to configure the code snippets that will be rendered in the
-# README.md of various SDKs. In particular, you can change the `headline`
-# snippet's endpoint and the arguments to call it with.
-readme:
-  example_requests:
-    default:
-      type: request
-      endpoint: post /v1/chat/completions
-      params: &ref_0 {}
-    headline:
-      type: request
-      endpoint: post /v1/models
-      params: *ref_0
-    pagination:
-      type: request
-      endpoint: post /v1/chat/completions
-      params: {}

containers/Containerfile

@@ -1,137 +0,0 @@
-# syntax=docker/dockerfile:1.6
-#
-# This Dockerfile is used to build the Llama Stack container image.
-# Example:
-# docker build \
-#   -f containers/Containerfile \
-#   --build-arg DISTRO_NAME=starter \
-#   --tag llama-stack:starter .
-
-ARG BASE_IMAGE=python:3.12-slim
-FROM ${BASE_IMAGE}
-
-ARG INSTALL_MODE="pypi"
-ARG LLAMA_STACK_DIR="/workspace"
-ARG LLAMA_STACK_CLIENT_DIR=""
-ARG PYPI_VERSION=""
-ARG TEST_PYPI_VERSION=""
-ARG KEEP_WORKSPACE=""
-ARG DISTRO_NAME="starter"
-ARG RUN_CONFIG_PATH=""
-ARG UV_HTTP_TIMEOUT=500
-ENV UV_HTTP_TIMEOUT=${UV_HTTP_TIMEOUT}
-ENV PYTHONDONTWRITEBYTECODE=1
-ENV PIP_DISABLE_PIP_VERSION_CHECK=1
-WORKDIR /app
-
-RUN set -eux; \
-    if command -v dnf >/dev/null 2>&1; then \
-        dnf -y update && \
-        dnf install -y iputils git net-tools wget \
-            vim-minimal python3.12 python3.12-pip python3.12-wheel \
-            python3.12-setuptools python3.12-devel gcc gcc-c++ make && \
-        ln -sf /usr/bin/pip3.12 /usr/local/bin/pip && \
-        ln -sf /usr/bin/python3.12 /usr/local/bin/python && \
-        dnf clean all; \
-    elif command -v apt-get >/dev/null 2>&1; then \
-        apt-get update && \
-        apt-get install -y --no-install-recommends \
-            iputils-ping net-tools iproute2 dnsutils telnet \
-            curl wget git procps psmisc lsof traceroute bubblewrap \
-            gcc g++ && \
-        rm -rf /var/lib/apt/lists/*; \
-    else \
-        echo "Unsupported base image: expected dnf or apt-get" >&2; \
-        exit 1; \
-    fi
-
-RUN pip install --no-cache-dir uv
-ENV UV_SYSTEM_PYTHON=1
-
-ENV INSTALL_MODE=${INSTALL_MODE}
-ENV LLAMA_STACK_DIR=${LLAMA_STACK_DIR}
-ENV LLAMA_STACK_CLIENT_DIR=${LLAMA_STACK_CLIENT_DIR}
-ENV PYPI_VERSION=${PYPI_VERSION}
-ENV TEST_PYPI_VERSION=${TEST_PYPI_VERSION}
-ENV KEEP_WORKSPACE=${KEEP_WORKSPACE}
-ENV DISTRO_NAME=${DISTRO_NAME}
-ENV RUN_CONFIG_PATH=${RUN_CONFIG_PATH}
-
-# Copy the repository so editable installs and run configurations are available.
-COPY . /workspace
-
-# Install the client package if it is provided
-# NOTE: this is installed before llama-stack since llama-stack depends on llama-stack-client-python
-RUN set -eux; \
-    if [ -n "$LLAMA_STACK_CLIENT_DIR" ]; then \
-        if [ ! -d "$LLAMA_STACK_CLIENT_DIR" ]; then \
-            echo "LLAMA_STACK_CLIENT_DIR is set but $LLAMA_STACK_CLIENT_DIR does not exist" >&2; \
-            exit 1; \
-        fi; \
-        uv pip install --no-cache-dir -e "$LLAMA_STACK_CLIENT_DIR"; \
-    fi;
-
-# Install llama-stack
-RUN set -eux; \
-    if [ "$INSTALL_MODE" = "editable" ]; then \
-        if [ ! -d "$LLAMA_STACK_DIR" ]; then \
-            echo "INSTALL_MODE=editable requires LLAMA_STACK_DIR to point to a directory inside the build context" >&2; \
-            exit 1; \
-        fi; \
-        uv pip install --no-cache-dir -e "$LLAMA_STACK_DIR"; \
-    elif [ "$INSTALL_MODE" = "test-pypi" ]; then \
-        uv pip install --no-cache-dir fastapi libcst; \
-        if [ -n "$TEST_PYPI_VERSION" ]; then \
-            uv pip install --no-cache-dir --extra-index-url https://test.pypi.org/simple/ --index-strategy unsafe-best-match "llama-stack==$TEST_PYPI_VERSION"; \
-        else \
-            uv pip install --no-cache-dir --extra-index-url https://test.pypi.org/simple/ --index-strategy unsafe-best-match llama-stack; \
-        fi; \
-    else \
-        if [ -n "$PYPI_VERSION" ]; then \
-            uv pip install --no-cache-dir "llama-stack==$PYPI_VERSION"; \
-        else \
-            uv pip install --no-cache-dir llama-stack; \
-        fi; \
-    fi;
-
-# Install the dependencies for the distribution
-RUN set -eux; \
-    if [ -z "$DISTRO_NAME" ]; then \
-        echo "DISTRO_NAME must be provided" >&2; \
-        exit 1; \
-    fi; \
-    deps="$(llama stack list-deps "$DISTRO_NAME")"; \
-    if [ -n "$deps" ]; then \
-        printf '%s\n' "$deps" | xargs -L1 uv pip install --no-cache-dir; \
-    fi
-
-# Cleanup
-RUN set -eux; \
-    pip uninstall -y uv; \
-    should_remove=1; \
-    if [ -n "$KEEP_WORKSPACE" ]; then should_remove=0; fi; \
-    if [ "$INSTALL_MODE" = "editable" ]; then should_remove=0; fi; \
-    case "$RUN_CONFIG_PATH" in \
-        /workspace*) should_remove=0 ;; \
-    esac; \
-    if [ "$should_remove" -eq 1 ] && [ -d /workspace ]; then rm -rf /workspace; fi
-
-RUN cat <<'EOF' >/usr/local/bin/llama-stack-entrypoint.sh
-#!/bin/sh
-set -e
-
-if [ -n "$RUN_CONFIG_PATH" ] && [ -f "$RUN_CONFIG_PATH" ]; then
-  exec llama stack run "$RUN_CONFIG_PATH" "$@"
-fi
-
-if [ -n "$DISTRO_NAME" ]; then
-  exec llama stack run "$DISTRO_NAME" "$@"
-fi
-
-exec llama stack run "$@"
-EOF
-RUN chmod +x /usr/local/bin/llama-stack-entrypoint.sh
-
-RUN mkdir -p /.llama /.cache && chmod -R g+rw /app /.llama /.cache
-
-ENTRYPOINT ["/usr/local/bin/llama-stack-entrypoint.sh"]

docs/docs/advanced_apis/post_training.mdx

@@ -51,8 +51,8 @@ device: cpu
 You can access the HuggingFace trainer via the `starter` distribution:
 
 ```bash
-llama stack list-deps starter | xargs -L1 uv pip install
-llama stack run starter
+llama stack build --distro starter --image-type venv
+llama stack run ~/.llama/distributions/starter/starter-run.yaml
 ```
 
 ### Usage Example

docs/docs/building_applications/playground.mdx

@@ -175,7 +175,8 @@ llama-stack-client benchmarks register \
 **1. Start the Llama Stack API Server**
 
 ```bash
-llama stack list-deps together | xargs -L1 uv pip install
+# Build and run a distribution (example: together)
+llama stack build --distro together --image-type venv
 llama stack run together
 ```
 
@@ -208,7 +209,7 @@ The playground works with any Llama Stack distribution. Popular options include:
 <TabItem value="together" label="Together AI">
 
 ```bash
-llama stack list-deps together | xargs -L1 uv pip install
+llama stack build --distro together --image-type venv
 llama stack run together
 ```
 
@@ -221,7 +222,7 @@ llama stack run together
 <TabItem value="ollama" label="Ollama (Local)">
 
 ```bash
-llama stack list-deps ollama | xargs -L1 uv pip install
+llama stack build --distro ollama --image-type venv
 llama stack run ollama
 ```
 
@@ -234,7 +235,7 @@ llama stack run ollama
 <TabItem value="meta-reference" label="Meta Reference">
 
 ```bash
-llama stack list-deps meta-reference | xargs -L1 uv pip install
+llama stack build --distro meta-reference --image-type venv
 llama stack run meta-reference
 ```
 

docs/docs/building_applications/rag.mdx

@@ -20,8 +20,7 @@ RAG enables your applications to reference and recall information from external
 In one terminal, start the Llama Stack server:
 
 ```bash
-llama stack list-deps starter | xargs -L1 uv pip install
-llama stack run starter
+uv run llama stack build --distro starter --image-type venv --run
 ```
 
 ### 2. Connect with OpenAI Client
@@ -88,19 +87,18 @@ Llama Stack provides OpenAI-compatible RAG capabilities through:
 To enable automatic vector store creation without specifying embedding models, configure a default embedding model in your run.yaml like so:
 
 ```yaml
-vector_stores:
-  default_provider_id: faiss
-  default_embedding_model:
-    provider_id: sentence-transformers
-    model_id: nomic-ai/nomic-embed-text-v1.5
+models:
+  - model_id: nomic-ai/nomic-embed-text-v1.5
+    provider_id: inline::sentence-transformers
+    metadata:
+      embedding_dimension: 768
+      default_configured: true
 ```
 
 With this configuration:
-- `client.vector_stores.create()` works without requiring embedding model or provider parameters
-- The system automatically uses the default vector store provider (`faiss`) when multiple providers are available
-- The system automatically uses the default embedding model (`sentence-transformers/nomic-ai/nomic-embed-text-v1.5`) for any newly created vector store
-- The `default_provider_id` specifies which vector storage backend to use
-- The `default_embedding_model` specifies both the inference provider and model for embeddings
+- `client.vector_stores.create()` works without requiring embedding model parameters
+- The system automatically uses the default model and its embedding dimension for any newly created vector store
+- Only one model can be marked as `default_configured: true`
 
 ## Vector Store Operations
 
@@ -109,15 +107,14 @@ With this configuration:
 You can create vector stores with automatic or explicit embedding model selection:
 
 ```python
-# Automatic - uses default configured embedding model and vector store provider
+# Automatic - uses default configured embedding model
 vs = client.vector_stores.create()
 
-# Explicit - specify embedding model and/or provider when you need specific ones
+# Explicit - specify embedding model when you need a specific one
 vs = client.vector_stores.create(
     extra_body={
-        "provider_id": "faiss",  # Optional: specify vector store provider
-        "embedding_model": "sentence-transformers/nomic-ai/nomic-embed-text-v1.5",
-        "embedding_dimension": 768  # Optional: will be auto-detected if not provided
+        "embedding_model": "nomic-ai/nomic-embed-text-v1.5",
+        "embedding_dimension": 768
     }
 )
 ```

docs/docs/contributing/index.mdx

@@ -158,16 +158,17 @@ under the LICENSE file in the root directory of this source tree.
 
 Some tips about common tasks you work on while contributing to Llama Stack:
 
-### Setup for development
+### Installing dependencies of distributions
 
+Building a stack image will use the production version of the `llama-stack` and `llama-stack-client` packages. If you are developing with a llama-stack repository checked out and need your code to be reflected in the stack image, set `LLAMA_STACK_DIR` and `LLAMA_STACK_CLIENT_DIR` to the appropriate checked out directories when running any of the `llama` CLI commands.
+
+Example:
 ```bash
+cd work/
 git clone https://github.com/meta-llama/llama-stack.git
-cd llama-stack
-uv run llama stack list-deps <distro-name> | xargs -L1 uv pip install
-
-# (Optional) If you are developing the llama-stack-client-python package, you can add it as an editable package.
 git clone https://github.com/meta-llama/llama-stack-client-python.git
-uv add --editable ../llama-stack-client-python
+cd llama-stack
+llama stack build --distro <...>
 ```
 
 ### Updating distribution configurations

docs/docs/contributing/new_api_provider.mdx

@@ -67,7 +67,7 @@ def get_base_url(self) -> str:
 
 ## Testing the Provider
 
-Before running tests, you must have required dependencies installed. This depends on the providers or distributions you are testing. For example, if you are testing the `together` distribution, install its dependencies with `llama stack list-deps together | xargs -L1 uv pip install`.
+Before running tests, you must have required dependencies installed. This depends on the providers or distributions you are testing. For example, if you are testing the `together` distribution, you should install dependencies via `llama stack build --distro together`.
 
 ### 1. Integration Testing
 

docs/docs/distributions/building_distro.mdx

@@ -5,80 +5,225 @@ sidebar_label: Build your own Distribution
 sidebar_position: 3
 ---
 
-This guide walks you through inspecting existing distributions, customising their configuration, and building runnable artefacts for your own deployment.
+This guide will walk you through the steps to get started with building a Llama Stack distribution from scratch with your choice of API providers.
 
-### Explore existing distributions
 
-All first-party distributions live under `llama_stack/distributions/`. Each directory contains:
+### Setting your log level
 
-- `build.yaml` – the distribution specification (providers, additional dependencies, optional external provider directories).
-- `run.yaml` – sample run configuration (when provided).
-- Documentation fragments that power this site.
+In order to specify the proper logging level users can apply the following environment variable `LLAMA_STACK_LOGGING` with the following format:
 
-Browse that folder to understand available providers and copy a distribution to use as a starting point. When creating a new stack, duplicate an existing directory, rename it, and adjust the `build.yaml` file to match your requirements.
+`LLAMA_STACK_LOGGING=server=debug;core=info`
+
+Where each category in the following list:
+
+- all
+- core
+- server
+- router
+- inference
+- agents
+- safety
+- eval
+- tools
+- client
+
+Can be set to any of the following log levels:
+
+- debug
+- info
+- warning
+- error
+- critical
+
+The default global log level is `info`. `all` sets the log level for all components.
+
+A user can also set `LLAMA_STACK_LOG_FILE` which will pipe the logs to the specified path as well as to the terminal. An example would be: `export LLAMA_STACK_LOG_FILE=server.log`
+
+### Llama Stack Build
+
+In order to build your own distribution, we recommend you clone the `llama-stack` repository.
+
+
+```
+git clone git@github.com:meta-llama/llama-stack.git
+cd llama-stack
+pip install -e .
+```
+Use the CLI to build your distribution.
+The main points to consider are:
+1. **Image Type** - Do you want a venv environment or a Container (eg. Docker)
+2. **Template** - Do you want to use a template to build your distribution? or start from scratch ?
+3. **Config** - Do you want to use a pre-existing config file to build your distribution?
+
+```
+llama stack build -h
+usage: llama stack build [-h] [--config CONFIG] [--template TEMPLATE] [--distro DISTRIBUTION] [--list-distros] [--image-type {container,venv}] [--image-name IMAGE_NAME] [--print-deps-only]
+                         [--run] [--providers PROVIDERS]
+
+Build a Llama stack container
+
+options:
+  -h, --help            show this help message and exit
+  --config CONFIG       Path to a config file to use for the build. You can find example configs in llama_stack.cores/**/build.yaml. If this argument is not provided, you will be prompted to
+                        enter information interactively (default: None)
+  --template TEMPLATE   (deprecated) Name of the example template config to use for build. You may use `llama stack build --list-distros` to check out the available distributions (default:
+                        None)
+  --distro DISTRIBUTION, --distribution DISTRIBUTION
+                        Name of the distribution to use for build. You may use `llama stack build --list-distros` to check out the available distributions (default: None)
+  --list-distros, --list-distributions
+                        Show the available distributions for building a Llama Stack distribution (default: False)
+  --image-type {container,venv}
+                        Image Type to use for the build. If not specified, will use the image type from the template config. (default: None)
+  --image-name IMAGE_NAME
+                        [for image-type=container|venv] Name of the virtual environment to use for the build. If not specified, currently active environment will be used if found. (default:
+                        None)
+  --print-deps-only     Print the dependencies for the stack only, without building the stack (default: False)
+  --run                 Run the stack after building using the same image type, name, and other applicable arguments (default: False)
+  --providers PROVIDERS
+                        Build a config for a list of providers and only those providers. This list is formatted like: api1=provider1,api2=provider2. Where there can be multiple providers per
+                        API. (default: None)
+```
+
+After this step is complete, a file named `<name>-build.yaml` and template file `<name>-run.yaml` will be generated and saved at the output file path specified at the end of the command.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 <Tabs>
-<TabItem value="container" label="Building a container">
+<TabItem value="template" label="Building from a template">
+To build from alternative API providers, we provide distribution templates for users to get started building a distribution backed by different providers.
 
-Use the Containerfile at `containers/Containerfile`, which installs `llama-stack`, resolves distribution dependencies via `llama stack list-deps`, and sets the entrypoint to `llama stack run`.
-
-```bash
-docker build . \
-  -f containers/Containerfile \
-  --build-arg DISTRO_NAME=starter \
-  --tag llama-stack:starter
+The following command will allow you to see the available templates and their corresponding providers.
+```
+llama stack build --list-templates
 ```
 
-Handy build arguments:
+```
+------------------------------+-----------------------------------------------------------------------------+
+| Template Name                | Description                                                                 |
++------------------------------+-----------------------------------------------------------------------------+
+| watsonx                      | Use watsonx for running LLM inference                                       |
++------------------------------+-----------------------------------------------------------------------------+
+| vllm-gpu                     | Use a built-in vLLM engine for running LLM inference                        |
++------------------------------+-----------------------------------------------------------------------------+
+| together                     | Use Together.AI for running LLM inference                                   |
++------------------------------+-----------------------------------------------------------------------------+
+| tgi                          | Use (an external) TGI server for running LLM inference                      |
++------------------------------+-----------------------------------------------------------------------------+
+| starter                      | Quick start template for running Llama Stack with several popular providers |
++------------------------------+-----------------------------------------------------------------------------+
+| sambanova                    | Use SambaNova for running LLM inference and safety                          |
++------------------------------+-----------------------------------------------------------------------------+
+| remote-vllm                  | Use (an external) vLLM server for running LLM inference                     |
++------------------------------+-----------------------------------------------------------------------------+
+| postgres-demo                | Quick start template for running Llama Stack with several popular providers |
++------------------------------+-----------------------------------------------------------------------------+
+| passthrough                  | Use Passthrough hosted llama-stack endpoint for LLM inference               |
++------------------------------+-----------------------------------------------------------------------------+
+| open-benchmark               | Distribution for running open benchmarks                                    |
++------------------------------+-----------------------------------------------------------------------------+
+| ollama                       | Use (an external) Ollama server for running LLM inference                   |
++------------------------------+-----------------------------------------------------------------------------+
+| nvidia                       | Use NVIDIA NIM for running LLM inference, evaluation and safety             |
++------------------------------+-----------------------------------------------------------------------------+
+| meta-reference-gpu           | Use Meta Reference for running LLM inference                                |
++------------------------------+-----------------------------------------------------------------------------+
+| llama_api                    | Distribution for running e2e tests in CI                                    |
++------------------------------+-----------------------------------------------------------------------------+
+| hf-serverless                | Use (an external) Hugging Face Inference Endpoint for running LLM inference |
++------------------------------+-----------------------------------------------------------------------------+
+| hf-endpoint                  | Use (an external) Hugging Face Inference Endpoint for running LLM inference |
++------------------------------+-----------------------------------------------------------------------------+
+| groq                         | Use Groq for running LLM inference                                          |
++------------------------------+-----------------------------------------------------------------------------+
+| fireworks                    | Use Fireworks.AI for running LLM inference                                  |
++------------------------------+-----------------------------------------------------------------------------+
+| experimental-post-training   | Experimental template for post training                                     |
++------------------------------+-----------------------------------------------------------------------------+
+| dell                         | Dell's distribution of Llama Stack. TGI inference via Dell's custom         |
+|                              | container                                                                   |
++------------------------------+-----------------------------------------------------------------------------+
+| ci-tests                     | Distribution for running e2e tests in CI                                    |
++------------------------------+-----------------------------------------------------------------------------+
+| cerebras                     | Use Cerebras for running LLM inference                                      |
++------------------------------+-----------------------------------------------------------------------------+
+| bedrock                      | Use AWS Bedrock for running LLM inference and safety                        |
++------------------------------+-----------------------------------------------------------------------------+
+```
 
-- `DISTRO_NAME` – distribution directory name (defaults to `starter`).
-- `RUN_CONFIG_PATH` – absolute path inside the build context for a run config that should be baked into the image (e.g. `/workspace/run.yaml`).
-- `INSTALL_MODE=editable` – install the repository copied into `/workspace` with `uv pip install -e`. Pair it with `--build-arg LLAMA_STACK_DIR=/workspace`.
-- `LLAMA_STACK_CLIENT_DIR` – optional editable install of the Python client.
-- `PYPI_VERSION` / `TEST_PYPI_VERSION` – pin specific releases when not using editable installs.
-- `KEEP_WORKSPACE=1` – retain `/workspace` in the final image if you need to access additional files (such as sample configs or provider bundles).
+You may then pick a template to build your distribution with providers fitted to your liking.
 
-Make sure any custom `build.yaml`, run configs, or provider directories you reference are included in the Docker build context so the Containerfile can read them.
+For example, to build a distribution with TGI as the inference provider, you can run:
+```
+$ llama stack build --distro starter
+...
+You can now edit ~/.llama/distributions/llamastack-starter/starter-run.yaml and run `llama stack run ~/.llama/distributions/llamastack-starter/starter-run.yaml`
+```
 
+```{tip}
+The generated `run.yaml` file is a starting point for your configuration. For comprehensive guidance on customizing it for your specific needs, infrastructure, and deployment scenarios, see [Customizing Your run.yaml Configuration](customizing_run_yaml.md).
+```
 </TabItem>
-<TabItem value="external" label="Building with external providers">
+<TabItem value="scratch" label="Building from Scratch">
 
-External providers live outside the main repository but can be bundled by pointing `external_providers_dir` to a directory that contains your provider packages.
+If the provided templates do not fit your use case, you could start off with running `llama stack build` which will allow you to a interactively enter wizard where you will be prompted to enter build configurations.
 
-1. Copy providers into the build context, for example `cp -R path/to/providers providers.d`.
-2. Update `build.yaml` with the directory and provider entries.
-3. Adjust run configs to use the in-container path (usually `/.llama/providers.d`). Pass `--build-arg RUN_CONFIG_PATH=/workspace/run.yaml` if you want to bake the config.
+It would be best to start with a template and understand the structure of the config file and the various concepts ( APIS, providers, resources, etc.) before starting from scratch.
+```
+llama stack build
 
-Example `build.yaml` excerpt for a custom Ollama provider:
+> Enter a name for your Llama Stack (e.g. my-local-stack): my-stack
+> Enter the image type you want your Llama Stack to be built as (container or venv): venv
+
+Llama Stack is composed of several APIs working together. Let's select
+the provider types (implementations) you want to use for these APIs.
+
+Tip: use <TAB> to see options for the providers.
+
+> Enter provider for API inference: inline::meta-reference
+> Enter provider for API safety: inline::llama-guard
+> Enter provider for API agents: inline::meta-reference
+> Enter provider for API memory: inline::faiss
+> Enter provider for API datasetio: inline::meta-reference
+> Enter provider for API scoring: inline::meta-reference
+> Enter provider for API eval: inline::meta-reference
+> Enter provider for API telemetry: inline::meta-reference
+
+ > (Optional) Enter a short description for your Llama Stack:
+
+You can now edit ~/.llama/distributions/llamastack-my-local-stack/my-local-stack-run.yaml and run `llama stack run ~/.llama/distributions/llamastack-my-local-stack/my-local-stack-run.yaml`
+```
+</TabItem>
+<TabItem value="config" label="Building from a pre-existing build config file">
+- In addition to templates, you may customize the build to your liking through editing config files and build from config files with the following command.
+
+- The config file will be of contents like the ones in `llama_stack/distributions/*build.yaml`.
+
+```
+llama stack build --config llama_stack/distributions/starter/build.yaml
+```
+</TabItem>
+<TabItem value="external" label="Building with External Providers">
+
+Llama Stack supports external providers that live outside of the main codebase. This allows you to create and maintain your own providers independently or use community-provided providers.
+
+To build a distribution with external providers, you need to:
+
+1. Configure the `external_providers_dir` in your build configuration file:
 
 ```yaml
+# Example my-external-stack.yaml with external providers
+version: '2'
 distribution_spec:
+  description: Custom distro for CI tests
   providers:
     inference:
-      - remote::custom_ollama
-external_providers_dir: /workspace/providers.d
-```
-
-Inside `providers.d/custom_ollama/provider.py`, define `get_provider_spec()` so the CLI can discover dependencies:
-
-```python
-from llama_stack.providers.datatypes import ProviderSpec
-
-
-def get_provider_spec() -> ProviderSpec:
-    return ProviderSpec(
-        provider_type="remote::custom_ollama",
-        module="llama_stack_ollama_provider",
-        config_class="llama_stack_ollama_provider.config.OllamaImplConfig",
-        pip_packages=[
-            "ollama",
-            "aiohttp",
-            "llama-stack-provider-ollama",
-        ],
-    )
+    - remote::custom_ollama
+# Add more providers as needed
+image_type: container
+image_name: ci-test
+# Path to external provider implementations
+external_providers_dir: ~/.llama/providers.d
 ```
 
 Here's an example for a custom Ollama provider:
@@ -87,9 +232,9 @@ Here's an example for a custom Ollama provider:
 adapter:
   adapter_type: custom_ollama
   pip_packages:
-    - ollama
-    - aiohttp
-    - llama-stack-provider-ollama  # This is the provider package
+  - ollama
+  - aiohttp
+  - llama-stack-provider-ollama # This is the provider package
   config_class: llama_stack_ollama_provider.config.OllamaImplConfig
   module: llama_stack_ollama_provider
 api_dependencies: []
@@ -100,22 +245,53 @@ The `pip_packages` section lists the Python packages required by the provider, a
 provider package itself. The package must be available on PyPI or can be provided from a local
 directory or a git repository (git must be installed on the build environment).
 
-For deeper guidance, see the [External Providers documentation](../providers/external/).
+2. Build your distribution using the config file:
 
+```
+llama stack build --config my-external-stack.yaml
+```
+
+For more information on external providers, including directory structure, provider types, and implementation requirements, see the [External Providers documentation](../providers/external/).
 </TabItem>
-</Tabs>
+<TabItem value="container" label="Building Container">
 
-### Run your stack server
+:::tip Podman Alternative
+Podman is supported as an alternative to Docker. Set `CONTAINER_BINARY` to `podman` in your environment to use Podman.
+:::
 
-After building the image, launch it directly with Docker or Podman—the entrypoint calls `llama stack run` using the baked distribution or the bundled run config:
+To build a container image, you may start off from a template and use the `--image-type container` flag to specify `container` as the build image type.
+
+```
+llama stack build --distro starter --image-type container
+```
+
+```
+$ llama stack build --distro starter --image-type container
+...
+Containerfile created successfully in /tmp/tmp.viA3a3Rdsg/ContainerfileFROM python:3.10-slim
+...
+```
+
+You can now edit ~/meta-llama/llama-stack/tmp/configs/ollama-run.yaml and run `llama stack run ~/meta-llama/llama-stack/tmp/configs/ollama-run.yaml`
+```
+
+Now set some environment variables for the inference model ID and Llama Stack Port and create a local directory to mount into the container's file system.
 
 ```bash
+export INFERENCE_MODEL="llama3.2:3b"
+export LLAMA_STACK_PORT=8321
+mkdir -p ~/.llama
+```
+
+After this step is successful, you should be able to find the built container image and test it with the below Docker command:
+
+```
 docker run -d \
   -p $LLAMA_STACK_PORT:$LLAMA_STACK_PORT \
   -v ~/.llama:/root/.llama \
   -e INFERENCE_MODEL=$INFERENCE_MODEL \
   -e OLLAMA_URL=http://host.docker.internal:11434 \
-  llama-stack:starter \
+  localhost/distribution-ollama:dev \
   --port $LLAMA_STACK_PORT
 ```
 
@@ -135,14 +311,131 @@ Here are the docker flags and their uses:
 
 * `--port $LLAMA_STACK_PORT`: Port number for the server to listen on
 
+</TabItem>
+</Tabs>
 
 
-If you prepared a custom run config, mount it into the container and reference it explicitly:
+### Running your Stack server
+Now, let's start the Llama Stack Distribution Server. You will need the YAML configuration file which was written out at the end by the `llama stack build` step.
 
-```bash
-docker run \
-  -p $LLAMA_STACK_PORT:$LLAMA_STACK_PORT \
-  -v $(pwd)/run.yaml:/app/run.yaml \
-  llama-stack:starter \
-  /app/run.yaml
 ```
+llama stack run -h
+usage: llama stack run [-h] [--port PORT] [--image-name IMAGE_NAME]
+                       [--image-type {venv}] [--enable-ui]
+                       [config | distro]
+
+Start the server for a Llama Stack Distribution. You should have already built (or downloaded) and configured the distribution.
+
+positional arguments:
+  config | distro       Path to config file to use for the run or name of known distro (`llama stack list` for a list). (default: None)
+
+options:
+  -h, --help            show this help message and exit
+  --port PORT           Port to run the server on. It can also be passed via the env var LLAMA_STACK_PORT. (default: 8321)
+  --image-name IMAGE_NAME
+                        [DEPRECATED] This flag is no longer supported. Please activate your virtual environment before running. (default: None)
+  --image-type {venv}
+                        [DEPRECATED] This flag is no longer supported. Please activate your virtual environment before running. (default: None)
+  --enable-ui           Start the UI server (default: False)
+```
+
+**Note:** Container images built with `llama stack build --image-type container` cannot be run using `llama stack run`. Instead, they must be run directly using Docker or Podman commands as shown in the container building section above.
+
+```
+# Start using template name
+llama stack run tgi
+
+# Start using config file
+llama stack run ~/.llama/distributions/llamastack-my-local-stack/my-local-stack-run.yaml
+```
+
+```
+$ llama stack run ~/.llama/distributions/llamastack-my-local-stack/my-local-stack-run.yaml
+
+Serving API inspect
+ GET /health
+ GET /providers/list
+ GET /routes/list
+Serving API inference
+ POST /inference/chat_completion
+ POST /inference/completion
+ POST /inference/embeddings
+...
+Serving API agents
+ POST /agents/create
+ POST /agents/session/create
+ POST /agents/turn/create
+ POST /agents/delete
+ POST /agents/session/delete
+ POST /agents/session/get
+ POST /agents/step/get
+ POST /agents/turn/get
+
+Listening on ['::', '0.0.0.0']:8321
+INFO:     Started server process [2935911]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://['::', '0.0.0.0']:8321 (Press CTRL+C to quit)
+INFO:     2401:db00:35c:2d2b:face:0:c9:0:54678 - "GET /models/list HTTP/1.1" 200 OK
+```
+
+### Listing Distributions
+Using the list command, you can view all existing Llama Stack distributions, including stacks built from templates, from scratch, or using custom configuration files.
+
+```
+llama stack list -h
+usage: llama stack list [-h]
+
+list the build stacks
+
+options:
+  -h, --help  show this help message and exit
+```
+
+Example Usage
+
+```
+llama stack list
+```
+
+```
+------------------------------+-----------------------------------------------------------------+--------------+------------+
+| Stack Name                  | Path                                                            | Build Config | Run Config |
++------------------------------+-----------------------------------------------------------------------------+--------------+
+| together                    | ~/.llama/distributions/together                                 | Yes          | No         |
++------------------------------+-----------------------------------------------------------------------------+--------------+
+| bedrock                     | ~/.llama/distributions/bedrock                                  | Yes          | No         |
++------------------------------+-----------------------------------------------------------------------------+--------------+
+| starter                     | ~/.llama/distributions/starter                                  | Yes          | Yes        |
++------------------------------+-----------------------------------------------------------------------------+--------------+
+| remote-vllm                 | ~/.llama/distributions/remote-vllm                              | Yes          | Yes        |
++------------------------------+-----------------------------------------------------------------------------+--------------+
+```
+
+### Removing a Distribution
+Use the remove command to delete a distribution you've previously built.
+
+```
+llama stack rm -h
+usage: llama stack rm [-h] [--all] [name]
+
+Remove the build stack
+
+positional arguments:
+  name        Name of the stack to delete (default: None)
+
+options:
+  -h, --help  show this help message and exit
+  --all, -a   Delete all stacks (use with caution) (default: False)
+```
+
+Example
+```
+llama stack rm llamastack-test
+```
+
+To keep your environment organized and avoid clutter, consider using `llama stack list` to review old or unused distributions and `llama stack rm <name>` to delete them when they're no longer needed.
+
+### Troubleshooting
+
+If you encounter any issues, ask questions in our discord or search through our [GitHub Issues](https://github.com/meta-llama/llama-stack/issues), or file an new issue.

docs/docs/distributions/configuration.mdx

@@ -44,32 +44,18 @@ providers:
   - provider_id: meta-reference
     provider_type: inline::meta-reference
     config:
-      persistence:
-        agent_state:
-          backend: kv_default
-          namespace: agents
-        responses:
-          backend: sql_default
-          table_name: responses
+      persistence_store:
+        type: sqlite
+        namespace: null
+        db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ollama}/agents_store.db
   telemetry:
   - provider_id: meta-reference
     provider_type: inline::meta-reference
     config: {}
-storage:
-  backends:
-    kv_default:
-      type: kv_sqlite
-      db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ollama}/kvstore.db
-    sql_default:
-      type: sql_sqlite
-      db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ollama}/sqlstore.db
-  references:
-    metadata:
-      backend: kv_default
-      namespace: registry
-    inference:
-      backend: sql_default
-      table_name: inference_store
+metadata_store:
+  namespace: null
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ollama}/registry.db
 models:
 - metadata: {}
   model_id: ${env.INFERENCE_MODEL}

docs/docs/distributions/importing_as_library.mdx

@@ -12,7 +12,7 @@ This avoids the overhead of setting up a server.
 ```bash
 # setup
 uv pip install llama-stack
-llama stack list-deps starter | xargs -L1 uv pip install
+llama stack build --distro starter --image-type venv
 ```
 
 ```python

docs/docs/distributions/k8s/stack-configmap.yaml

@@ -1,155 +1,56 @@
 apiVersion: v1
 data:
-  stack_run_config.yaml: |
-    version: '2'
-    image_name: kubernetes-demo
-    apis:
-    - agents
-    - inference
-    - files
-    - safety
-    - telemetry
-    - tool_runtime
-    - vector_io
-    providers:
-      inference:
-      - provider_id: vllm-inference
-        provider_type: remote::vllm
-        config:
-          url: ${env.VLLM_URL:=http://localhost:8000/v1}
-          max_tokens: ${env.VLLM_MAX_TOKENS:=4096}
-          api_token: ${env.VLLM_API_TOKEN:=fake}
-          tls_verify: ${env.VLLM_TLS_VERIFY:=true}
-      - provider_id: vllm-safety
-        provider_type: remote::vllm
-        config:
-          url: ${env.VLLM_SAFETY_URL:=http://localhost:8000/v1}
-          max_tokens: ${env.VLLM_MAX_TOKENS:=4096}
-          api_token: ${env.VLLM_API_TOKEN:=fake}
-          tls_verify: ${env.VLLM_TLS_VERIFY:=true}
-      - provider_id: sentence-transformers
-        provider_type: inline::sentence-transformers
-        config: {}
-      vector_io:
-      - provider_id: ${env.ENABLE_CHROMADB:+chromadb}
-        provider_type: remote::chromadb
-        config:
-          url: ${env.CHROMADB_URL:=}
-          kvstore:
-            type: postgres
-            host: ${env.POSTGRES_HOST:=localhost}
-            port: ${env.POSTGRES_PORT:=5432}
-            db: ${env.POSTGRES_DB:=llamastack}
-            user: ${env.POSTGRES_USER:=llamastack}
-            password: ${env.POSTGRES_PASSWORD:=llamastack}
-      files:
-      - provider_id: meta-reference-files
-        provider_type: inline::localfs
-        config:
-          storage_dir: ${env.FILES_STORAGE_DIR:=~/.llama/distributions/starter/files}
-          metadata_store:
-            type: sqlite
-            db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/starter}/files_metadata.db
-      safety:
-      - provider_id: llama-guard
-        provider_type: inline::llama-guard
-        config:
-          excluded_categories: []
-      agents:
-      - provider_id: meta-reference
-        provider_type: inline::meta-reference
-        config:
-          persistence_store:
-            type: postgres
-            host: ${env.POSTGRES_HOST:=localhost}
-            port: ${env.POSTGRES_PORT:=5432}
-            db: ${env.POSTGRES_DB:=llamastack}
-            user: ${env.POSTGRES_USER:=llamastack}
-            password: ${env.POSTGRES_PASSWORD:=llamastack}
-          responses_store:
-            type: postgres
-            host: ${env.POSTGRES_HOST:=localhost}
-            port: ${env.POSTGRES_PORT:=5432}
-            db: ${env.POSTGRES_DB:=llamastack}
-            user: ${env.POSTGRES_USER:=llamastack}
-            password: ${env.POSTGRES_PASSWORD:=llamastack}
-      telemetry:
-      - provider_id: meta-reference
-        provider_type: inline::meta-reference
-        config:
-          service_name: "${env.OTEL_SERVICE_NAME:=\u200B}"
-          sinks: ${env.TELEMETRY_SINKS:=console}
-      tool_runtime:
-      - provider_id: brave-search
-        provider_type: remote::brave-search
-        config:
-          api_key: ${env.BRAVE_SEARCH_API_KEY:+}
-          max_results: 3
-      - provider_id: tavily-search
-        provider_type: remote::tavily-search
-        config:
-          api_key: ${env.TAVILY_SEARCH_API_KEY:+}
-          max_results: 3
-      - provider_id: rag-runtime
-        provider_type: inline::rag-runtime
-        config: {}
-      - provider_id: model-context-protocol
-        provider_type: remote::model-context-protocol
-        config: {}
-    storage:
-      backends:
-        kv_default:
-          type: kv_postgres
-          host: ${env.POSTGRES_HOST:=localhost}
-          port: ${env.POSTGRES_PORT:=5432}
-          db: ${env.POSTGRES_DB:=llamastack}
-          user: ${env.POSTGRES_USER:=llamastack}
-          password: ${env.POSTGRES_PASSWORD:=llamastack}
-          table_name: ${env.POSTGRES_TABLE_NAME:=llamastack_kvstore}
-        sql_default:
-          type: sql_postgres
-          host: ${env.POSTGRES_HOST:=localhost}
-          port: ${env.POSTGRES_PORT:=5432}
-          db: ${env.POSTGRES_DB:=llamastack}
-          user: ${env.POSTGRES_USER:=llamastack}
-          password: ${env.POSTGRES_PASSWORD:=llamastack}
-      references:
-        metadata:
-          backend: kv_default
-          namespace: registry
-        inference:
-          backend: sql_default
-          table_name: inference_store
-    models:
-    - metadata:
-        embedding_dimension: 768
-      model_id: nomic-embed-text-v1.5
-      provider_id: sentence-transformers
-      model_type: embedding
-    - metadata: {}
-      model_id: ${env.INFERENCE_MODEL}
-      provider_id: vllm-inference
-      model_type: llm
-    - metadata: {}
-      model_id: ${env.SAFETY_MODEL:=meta-llama/Llama-Guard-3-1B}
-      provider_id: vllm-safety
-      model_type: llm
-    shields:
-    - shield_id: ${env.SAFETY_MODEL:=meta-llama/Llama-Guard-3-1B}
-    vector_dbs: []
-    datasets: []
-    scoring_fns: []
-    benchmarks: []
-    tool_groups:
-    - toolgroup_id: builtin::websearch
-      provider_id: tavily-search
-    - toolgroup_id: builtin::rag
-      provider_id: rag-runtime
-    server:
-      port: 8321
-      auth:
-        provider_config:
-          type: github_token
+  stack_run_config.yaml: "version: '2'\nimage_name: kubernetes-demo\napis:\n- agents\n-
+    inference\n- files\n- safety\n- telemetry\n- tool_runtime\n- vector_io\nproviders:\n
+    \ inference:\n  - provider_id: vllm-inference\n    provider_type: remote::vllm\n
+    \   config:\n      url: ${env.VLLM_URL:=http://localhost:8000/v1}\n      max_tokens:
+    ${env.VLLM_MAX_TOKENS:=4096}\n      api_token: ${env.VLLM_API_TOKEN:=fake}\n      tls_verify:
+    ${env.VLLM_TLS_VERIFY:=true}\n  - provider_id: vllm-safety\n    provider_type:
+    remote::vllm\n    config:\n      url: ${env.VLLM_SAFETY_URL:=http://localhost:8000/v1}\n
+    \     max_tokens: ${env.VLLM_MAX_TOKENS:=4096}\n      api_token: ${env.VLLM_API_TOKEN:=fake}\n
+    \     tls_verify: ${env.VLLM_TLS_VERIFY:=true}\n  - provider_id: sentence-transformers\n
+    \   provider_type: inline::sentence-transformers\n    config: {}\n  vector_io:\n
+    \ - provider_id: ${env.ENABLE_CHROMADB:+chromadb}\n    provider_type: remote::chromadb\n
+    \   config:\n      url: ${env.CHROMADB_URL:=}\n      kvstore:\n        type: postgres\n
+    \       host: ${env.POSTGRES_HOST:=localhost}\n        port: ${env.POSTGRES_PORT:=5432}\n
+    \       db: ${env.POSTGRES_DB:=llamastack}\n        user: ${env.POSTGRES_USER:=llamastack}\n
+    \       password: ${env.POSTGRES_PASSWORD:=llamastack}\n  files:\n  - provider_id:
+    meta-reference-files\n    provider_type: inline::localfs\n    config:\n      storage_dir:
+    ${env.FILES_STORAGE_DIR:=~/.llama/distributions/starter/files}\n      metadata_store:\n
+    \       type: sqlite\n        db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/starter}/files_metadata.db
+    \ \n  safety:\n  - provider_id: llama-guard\n    provider_type: inline::llama-guard\n
+    \   config:\n      excluded_categories: []\n  agents:\n  - provider_id: meta-reference\n
+    \   provider_type: inline::meta-reference\n    config:\n      persistence_store:\n
+    \       type: postgres\n        host: ${env.POSTGRES_HOST:=localhost}\n        port:
+    ${env.POSTGRES_PORT:=5432}\n        db: ${env.POSTGRES_DB:=llamastack}\n        user:
+    ${env.POSTGRES_USER:=llamastack}\n        password: ${env.POSTGRES_PASSWORD:=llamastack}\n
+    \     responses_store:\n        type: postgres\n        host: ${env.POSTGRES_HOST:=localhost}\n
+    \       port: ${env.POSTGRES_PORT:=5432}\n        db: ${env.POSTGRES_DB:=llamastack}\n
+    \       user: ${env.POSTGRES_USER:=llamastack}\n        password: ${env.POSTGRES_PASSWORD:=llamastack}\n
+    \ telemetry:\n  - provider_id: meta-reference\n    provider_type: inline::meta-reference\n
+    \   config:\n      service_name: \"${env.OTEL_SERVICE_NAME:=\\u200B}\"\n      sinks:
+    ${env.TELEMETRY_SINKS:=console}\n  tool_runtime:\n  - provider_id: brave-search\n
+    \   provider_type: remote::brave-search\n    config:\n      api_key: ${env.BRAVE_SEARCH_API_KEY:+}\n
+    \     max_results: 3\n  - provider_id: tavily-search\n    provider_type: remote::tavily-search\n
+    \   config:\n      api_key: ${env.TAVILY_SEARCH_API_KEY:+}\n      max_results:
+    3\n  - provider_id: rag-runtime\n    provider_type: inline::rag-runtime\n    config:
+    {}\n  - provider_id: model-context-protocol\n    provider_type: remote::model-context-protocol\n
+    \   config: {}\nmetadata_store:\n  type: postgres\n  host: ${env.POSTGRES_HOST:=localhost}\n
+    \ port: ${env.POSTGRES_PORT:=5432}\n  db: ${env.POSTGRES_DB:=llamastack}\n  user:
+    ${env.POSTGRES_USER:=llamastack}\n  password: ${env.POSTGRES_PASSWORD:=llamastack}\n
+    \ table_name: llamastack_kvstore\ninference_store:\n  type: postgres\n  host:
+    ${env.POSTGRES_HOST:=localhost}\n  port: ${env.POSTGRES_PORT:=5432}\n  db: ${env.POSTGRES_DB:=llamastack}\n
+    \ user: ${env.POSTGRES_USER:=llamastack}\n  password: ${env.POSTGRES_PASSWORD:=llamastack}\nmodels:\n-
+    metadata:\n    embedding_dimension: 384\n  model_id: all-MiniLM-L6-v2\n  provider_id:
+    sentence-transformers\n  model_type: embedding\n- metadata: {}\n  model_id: ${env.INFERENCE_MODEL}\n
+    \ provider_id: vllm-inference\n  model_type: llm\n- metadata: {}\n  model_id:
+    ${env.SAFETY_MODEL:=meta-llama/Llama-Guard-3-1B}\n  provider_id: vllm-safety\n
+    \ model_type: llm\nshields:\n- shield_id: ${env.SAFETY_MODEL:=meta-llama/Llama-Guard-3-1B}\nvector_dbs:
+    []\ndatasets: []\nscoring_fns: []\nbenchmarks: []\ntool_groups:\n- toolgroup_id:
+    builtin::websearch\n  provider_id: tavily-search\n- toolgroup_id: builtin::rag\n
+    \ provider_id: rag-runtime\nserver:\n  port: 8321\n  auth:\n    provider_config:\n
+    \     type: github_token\n"
 kind: ConfigMap
 metadata:
+  creationTimestamp: null
   name: llama-stack-config

docs/docs/distributions/k8s/stack_run_config.yaml

@@ -93,30 +93,21 @@ providers:
   - provider_id: model-context-protocol
     provider_type: remote::model-context-protocol
     config: {}
-storage:
-  backends:
-    kv_default:
-      type: kv_postgres
-      host: ${env.POSTGRES_HOST:=localhost}
-      port: ${env.POSTGRES_PORT:=5432}
-      db: ${env.POSTGRES_DB:=llamastack}
-      user: ${env.POSTGRES_USER:=llamastack}
-      password: ${env.POSTGRES_PASSWORD:=llamastack}
-      table_name: ${env.POSTGRES_TABLE_NAME:=llamastack_kvstore}
-    sql_default:
-      type: sql_postgres
-      host: ${env.POSTGRES_HOST:=localhost}
-      port: ${env.POSTGRES_PORT:=5432}
-      db: ${env.POSTGRES_DB:=llamastack}
-      user: ${env.POSTGRES_USER:=llamastack}
-      password: ${env.POSTGRES_PASSWORD:=llamastack}
-  references:
-    metadata:
-      backend: kv_default
-      namespace: registry
-    inference:
-      backend: sql_default
-      table_name: inference_store
+metadata_store:
+  type: postgres
+  host: ${env.POSTGRES_HOST:=localhost}
+  port: ${env.POSTGRES_PORT:=5432}
+  db: ${env.POSTGRES_DB:=llamastack}
+  user: ${env.POSTGRES_USER:=llamastack}
+  password: ${env.POSTGRES_PASSWORD:=llamastack}
+  table_name: llamastack_kvstore
+inference_store:
+  type: postgres
+  host: ${env.POSTGRES_HOST:=localhost}
+  port: ${env.POSTGRES_PORT:=5432}
+  db: ${env.POSTGRES_DB:=llamastack}
+  user: ${env.POSTGRES_USER:=llamastack}
+  password: ${env.POSTGRES_PASSWORD:=llamastack}
 models:
 - metadata:
     embedding_dimension: 768

docs/docs/distributions/ondevice_distro/android_sdk.md

@@ -59,7 +59,7 @@ Start a Llama Stack server on localhost. Here is an example of how you can do th
 uv venv starter --python 3.12
 source starter/bin/activate  # On Windows: starter\Scripts\activate
 pip install --no-cache llama-stack==0.2.2
-llama stack list-deps starter | xargs -L1 uv pip install
+llama stack build --distro starter --image-type venv
 export FIREWORKS_API_KEY=<SOME_KEY>
 llama stack run starter --port 5050
 ```

docs/docs/distributions/self_hosted_distro/dell.md

@@ -166,10 +166,10 @@ docker run \
 
 ### Via venv
 
-Install the distribution dependencies before launching:
+Make sure you have done `pip install llama-stack` and have the Llama Stack CLI available.
 
 ```bash
-llama stack list-deps dell | xargs -L1 uv pip install
+llama stack build --distro dell --image-type venv
 INFERENCE_MODEL=$INFERENCE_MODEL \
 DEH_URL=$DEH_URL \
 CHROMA_URL=$CHROMA_URL \

docs/docs/distributions/self_hosted_distro/meta-reference-gpu.md

@@ -81,10 +81,10 @@ docker run \
 
 ### Via venv
 
-Make sure you have the Llama Stack CLI available.
+Make sure you have done `uv pip install llama-stack` and have the Llama Stack CLI available.
 
 ```bash
-llama stack list-deps meta-reference-gpu | xargs -L1 uv pip install
+llama stack build --distro meta-reference-gpu --image-type venv
 INFERENCE_MODEL=meta-llama/Llama-3.2-3B-Instruct \
 llama stack run distributions/meta-reference-gpu/run.yaml \
   --port 8321

docs/docs/distributions/self_hosted_distro/nvidia.md

@@ -136,11 +136,11 @@ docker run \
 
 ### Via venv
 
-If you've set up your local development environment, you can also install the distribution dependencies using your local virtual environment.
+If you've set up your local development environment, you can also build the image using your local virtual environment.
 
 ```bash
 INFERENCE_MODEL=meta-llama/Llama-3.1-8B-Instruct
-llama stack list-deps nvidia | xargs -L1 uv pip install
+llama stack build --distro nvidia --image-type venv
 NVIDIA_API_KEY=$NVIDIA_API_KEY \
 INFERENCE_MODEL=$INFERENCE_MODEL \
 llama stack run ./run.yaml \

docs/docs/distributions/starting_llama_stack_server.mdx

@@ -23,17 +23,6 @@ Another simple way to start interacting with Llama Stack is to just spin up a co
 If you have built a container image and want to deploy it in a Kubernetes cluster instead of starting the Llama Stack server locally. See [Kubernetes Deployment Guide](../deploying/kubernetes_deployment) for more details.
 
 
-## Configure logging
-
-Control log output via environment variables before starting the server.
-
-- `LLAMA_STACK_LOGGING` sets per-component levels, e.g. `LLAMA_STACK_LOGGING=server=debug;core=info`.
-- Supported categories: `all`, `core`, `server`, `router`, `inference`, `agents`, `safety`, `eval`, `tools`, `client`.
-- Levels: `debug`, `info`, `warning`, `error`, `critical` (default is `info`). Use `all=<level>` to apply globally.
-- `LLAMA_STACK_LOG_FILE=/path/to/log` mirrors logs to a file while still printing to stdout.
-
-Export these variables prior to running `llama stack run`, launching a container, or starting the server through any other pathway.
-
 ```{toctree}
 :maxdepth: 1
 :hidden:

docs/docs/getting_started/demo_script.py

@@ -4,24 +4,65 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
+from llama_stack_client import Agent, AgentEventLogger, RAGDocument, LlamaStackClient
 
-import io, requests
-from openai import OpenAI
+vector_db_id = "my_demo_vector_db"
+client = LlamaStackClient(base_url="http://localhost:8321")
 
-url="https://www.paulgraham.com/greatwork.html"
-client = OpenAI(base_url="http://localhost:8321/v1/", api_key="none")
+models = client.models.list()
 
-vs = client.vector_stores.create()
-response = requests.get(url)
-pseudo_file = io.BytesIO(str(response.content).encode('utf-8'))
-uploaded_file = client.files.create(file=(url, pseudo_file, "text/html"), purpose="assistants")
-client.vector_stores.files.create(vector_store_id=vs.id, file_id=uploaded_file.id)
+# Select the first LLM and first embedding models
+model_id = next(m for m in models if m.model_type == "llm").identifier
+embedding_model_id = (
+    em := next(m for m in models if m.model_type == "embedding")
+).identifier
+embedding_dimension = em.metadata["embedding_dimension"]
 
-resp = client.responses.create(
-    model="openai/gpt-4o",
-    input="How do you do great work? Use the existing knowledge_search tool.",
-    tools=[{"type": "file_search", "vector_store_ids": [vs.id]}],
-    include=["file_search_call.results"],
+vector_db = client.vector_dbs.register(
+    vector_db_id=vector_db_id,
+    embedding_model=embedding_model_id,
+    embedding_dimension=embedding_dimension,
+    provider_id="faiss",
+)
+vector_db_id = vector_db.identifier
+source = "https://www.paulgraham.com/greatwork.html"
+print("rag_tool> Ingesting document:", source)
+document = RAGDocument(
+    document_id="document_1",
+    content=source,
+    mime_type="text/html",
+    metadata={},
+)
+client.tool_runtime.rag_tool.insert(
+    documents=[document],
+    vector_db_id=vector_db_id,
+    chunk_size_in_tokens=100,
+)
+agent = Agent(
+    client,
+    model=model_id,
+    instructions="You are a helpful assistant",
+    tools=[
+        {
+            "name": "builtin::rag/knowledge_search",
+            "args": {"vector_db_ids": [vector_db_id]},
+        }
+    ],
 )
 
-print(resp)
+prompt = "How do you do great work?"
+print("prompt>", prompt)
+
+use_stream = True
+response = agent.create_turn(
+    messages=[{"role": "user", "content": prompt}],
+    session_id=agent.create_session("rag_session"),
+    stream=use_stream,
+)
+
+# Only call `AgentEventLogger().log(response)` for streaming responses.
+if use_stream:
+    for log in AgentEventLogger().log(response):
+        log.print()
+else:
+    print(response)

docs/docs/getting_started/detailed_tutorial.mdx

@@ -308,7 +308,7 @@ stream = agent.create_turn(
 for event in AgentEventLogger().log(stream):
     event.print()
 ```
-#### ii. Run the Script
+### ii. Run the Script
 Let's run the script using `uv`
 ```bash
 uv run python agent.py

docs/docs/getting_started/quickstart.mdx

@@ -35,51 +35,103 @@ OLLAMA_URL=http://localhost:11434 uv run --with llama-stack llama stack run star
 #### Step 3: Run the demo
 Now open up a new terminal and copy the following script into a file named `demo_script.py`.
 
-```python
-import io, requests
-from openai import OpenAI
+```python title="demo_script.py"
+# 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.
 
-url="https://www.paulgraham.com/greatwork.html"
-client = OpenAI(base_url="http://localhost:8321/v1/", api_key="none")
+from llama_stack_client import Agent, AgentEventLogger, RAGDocument, LlamaStackClient
 
-vs = client.vector_stores.create()
-response = requests.get(url)
-pseudo_file = io.BytesIO(str(response.content).encode('utf-8'))
-uploaded_file = client.files.create(file=(url, pseudo_file, "text/html"), purpose="assistants")
-client.vector_stores.files.create(vector_store_id=vs.id, file_id=uploaded_file.id)
+vector_db_id = "my_demo_vector_db"
+client = LlamaStackClient(base_url="http://localhost:8321")
 
-resp = client.responses.create(
-    model="openai/gpt-4o",
-    input="How do you do great work? Use the existing knowledge_search tool.",
-    tools=[{"type": "file_search", "vector_store_ids": [vs.id]}],
-    include=["file_search_call.results"],
+models = client.models.list()
+
+# Select the first LLM and first embedding models
+model_id = next(m for m in models if m.model_type == "llm").identifier
+embedding_model_id = (
+    em := next(m for m in models if m.model_type == "embedding")
+).identifier
+embedding_dimension = em.metadata["embedding_dimension"]
+
+vector_db = client.vector_dbs.register(
+    vector_db_id=vector_db_id,
+    embedding_model=embedding_model_id,
+    embedding_dimension=embedding_dimension,
+    provider_id="faiss",
+)
+vector_db_id = vector_db.identifier
+source = "https://www.paulgraham.com/greatwork.html"
+print("rag_tool> Ingesting document:", source)
+document = RAGDocument(
+    document_id="document_1",
+    content=source,
+    mime_type="text/html",
+    metadata={},
+)
+client.tool_runtime.rag_tool.insert(
+    documents=[document],
+    vector_db_id=vector_db_id,
+    chunk_size_in_tokens=100,
+)
+agent = Agent(
+    client,
+    model=model_id,
+    instructions="You are a helpful assistant",
+    tools=[
+        {
+            "name": "builtin::rag/knowledge_search",
+            "args": {"vector_db_ids": [vector_db_id]},
+        }
+    ],
 )
 
+prompt = "How do you do great work?"
+print("prompt>", prompt)
 
+use_stream = True
+response = agent.create_turn(
+    messages=[{"role": "user", "content": prompt}],
+    session_id=agent.create_session("rag_session"),
+    stream=use_stream,
+)
+
+# Only call `AgentEventLogger().log(response)` for streaming responses.
+if use_stream:
+    for log in AgentEventLogger().log(response):
+        log.print()
+else:
+    print(response)
+```
 We will use `uv` to run the script
 ```
 uv run --with llama-stack-client,fire,requests demo_script.py
 ```
 And you should see output like below.
-```python
->print(resp.output[1].content[0].text)
-To do great work, consider the following principles:
-
-1. **Follow Your Interests**: Engage in work that genuinely excites you. If you find an area intriguing, pursue it without being overly concerned about external pressures or norms. You should create things that you would want for yourself, as this often aligns with what others in your circle might want too.
-
-2. **Work Hard on Ambitious Projects**: Ambition is vital, but it should be tempered by genuine interest. Instead of detailed planning for the future, focus on exciting projects that keep your options open. This approach, known as "staying upwind," allows for adaptability and can lead to unforeseen achievements.
-
-3. **Choose Quality Colleagues**: Collaborating with talented colleagues can significantly affect your own work. Seek out individuals who offer surprising insights and whom you admire. The presence of good colleagues can elevate the quality of your work and inspire you.
-
-4. **Maintain High Morale**: Your attitude towards work and life affects your performance. Cultivating optimism and viewing yourself as lucky rather than victimized can boost your productivity. It’s essential to care for your physical health as well since it directly impacts your mental faculties and morale.
-
-5. **Be Consistent**: Great work often comes from cumulative effort. Daily progress, even in small amounts, can result in substantial achievements over time. Emphasize consistency and make the work engaging, as this reduces the perceived burden of hard labor.
-
-6. **Embrace Curiosity**: Curiosity is a driving force that can guide you in selecting fields of interest, pushing you to explore uncharted territories. Allow it to shape your work and continually seek knowledge and insights.
-
-By focusing on these aspects, you can create an environment conducive to great work and personal fulfillment.
 ```
+rag_tool> Ingesting document: https://www.paulgraham.com/greatwork.html
 
+prompt> How do you do great work?
+
+inference> [knowledge_search(query="What is the key to doing great work")]
+
+tool_execution> Tool:knowledge_search Args:{'query': 'What is the key to doing great work'}
+
+tool_execution> Tool:knowledge_search Response:[TextContentItem(text='knowledge_search tool found 5 chunks:\nBEGIN of knowledge_search tool results.\n', type='text'), TextContentItem(text="Result 1:\nDocument_id:docum\nContent:  work. Doing great work means doing something important\nso well that you expand people's ideas of what's possible. But\nthere's no threshold for importance. It's a matter of degree, and\noften hard to judge at the time anyway.\n", type='text'), TextContentItem(text="Result 2:\nDocument_id:docum\nContent:  work. Doing great work means doing something important\nso well that you expand people's ideas of what's possible. But\nthere's no threshold for importance. It's a matter of degree, and\noften hard to judge at the time anyway.\n", type='text'), TextContentItem(text="Result 3:\nDocument_id:docum\nContent:  work. Doing great work means doing something important\nso well that you expand people's ideas of what's possible. But\nthere's no threshold for importance. It's a matter of degree, and\noften hard to judge at the time anyway.\n", type='text'), TextContentItem(text="Result 4:\nDocument_id:docum\nContent:  work. Doing great work means doing something important\nso well that you expand people's ideas of what's possible. But\nthere's no threshold for importance. It's a matter of degree, and\noften hard to judge at the time anyway.\n", type='text'), TextContentItem(text="Result 5:\nDocument_id:docum\nContent:  work. Doing great work means doing something important\nso well that you expand people's ideas of what's possible. But\nthere's no threshold for importance. It's a matter of degree, and\noften hard to judge at the time anyway.\n", type='text'), TextContentItem(text='END of knowledge_search tool results.\n', type='text')]
+
+inference> Based on the search results, it seems that doing great work means doing something important so well that you expand people's ideas of what's possible. However, there is no clear threshold for importance, and it can be difficult to judge at the time.
+
+To further clarify, I would suggest that doing great work involves:
+
+* Completing tasks with high quality and attention to detail
+* Expanding on existing knowledge or ideas
+* Making a positive impact on others through your work
+* Striving for excellence and continuous improvement
+
+Ultimately, great work is about making a meaningful contribution and leaving a lasting impression.
+```
 Congratulations! You've successfully built your first RAG application using Llama Stack! 🎉🥳
 
 :::tip HuggingFace access

docs/docs/providers/agents/inline_meta-reference.mdx

@@ -14,18 +14,16 @@ Meta's reference implementation of an agent system that can use tools, access ve
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `persistence` | `<class 'inline.agents.meta_reference.config.AgentPersistenceConfig'>` | No |  |  |
+| `persistence_store` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
+| `responses_store` | `utils.sqlstore.sqlstore.SqliteSqlStoreConfig \| utils.sqlstore.sqlstore.PostgresSqlStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
-persistence:
-  agent_state:
-    namespace: agents
-    backend: kv_default
-  responses:
-    table_name: responses
-    backend: sql_default
-    max_write_queue_size: 10000
-    num_writers: 4
+persistence_store:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/agents_store.db
+responses_store:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/responses_store.db
 ```

docs/docs/providers/batches/inline_reference.mdx

@@ -14,7 +14,7 @@ Reference implementation of batches API with KVStore persistence.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `kvstore` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Configuration for the key-value store backend. |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Configuration for the key-value store backend. |
 | `max_concurrent_batches` | `<class 'int'>` | No | 1 | Maximum number of concurrent batches to process simultaneously. |
 | `max_concurrent_requests_per_batch` | `<class 'int'>` | No | 10 | Maximum number of concurrent requests to process per batch. |
 
@@ -22,6 +22,6 @@ Reference implementation of batches API with KVStore persistence.
 
 ```yaml
 kvstore:
-  namespace: batches
-  backend: kv_default
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/batches.db
 ```

docs/docs/providers/datasetio/inline_localfs.mdx

@@ -14,12 +14,12 @@ Local filesystem-based dataset I/O provider for reading and writing datasets to
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `kvstore` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
 kvstore:
-  namespace: datasetio::localfs
-  backend: kv_default
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/localfs_datasetio.db
 ```

docs/docs/providers/datasetio/remote_huggingface.mdx

@@ -14,12 +14,12 @@ HuggingFace datasets provider for accessing and managing datasets from the Huggi
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `kvstore` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
 kvstore:
-  namespace: datasetio::huggingface
-  backend: kv_default
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/huggingface_datasetio.db
 ```

docs/docs/providers/eval/inline_meta-reference.mdx

@@ -14,12 +14,12 @@ Meta's reference implementation of evaluation tasks with support for multiple la
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `kvstore` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
 kvstore:
-  namespace: eval
-  backend: kv_default
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/meta_reference_eval.db
 ```

docs/docs/providers/external/external-providers-guide.mdx

@@ -240,6 +240,6 @@ additional_pip_packages:
 - sqlalchemy[asyncio]
 ```
 
-No other steps are required beyond installing dependencies with `llama stack list-deps <distro> | xargs -L1 uv pip install` and then running `llama stack run`. The CLI will use `module` to install the provider dependencies, retrieve the spec, etc.
+No other steps are required other than `llama stack build` and `llama stack run`. The build process will use `module` to install all of the provider dependencies, retrieve the spec, etc.
 
 The provider will now be available in Llama Stack with the type `remote::ramalama`.

docs/docs/providers/files/inline_localfs.mdx

@@ -15,7 +15,7 @@ Local filesystem-based file storage provider for managing files and documents lo
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `storage_dir` | `<class 'str'>` | No |  | Directory to store uploaded files |
-| `metadata_store` | `<class 'llama_stack.core.storage.datatypes.SqlStoreReference'>` | No |  | SQL store configuration for file metadata |
+| `metadata_store` | `utils.sqlstore.sqlstore.SqliteSqlStoreConfig \| utils.sqlstore.sqlstore.PostgresSqlStoreConfig` | No | sqlite | SQL store configuration for file metadata |
 | `ttl_secs` | `<class 'int'>` | No | 31536000 |  |
 
 ## Sample Configuration
@@ -23,6 +23,6 @@ Local filesystem-based file storage provider for managing files and documents lo
 ```yaml
 storage_dir: ${env.FILES_STORAGE_DIR:=~/.llama/dummy/files}
 metadata_store:
-  table_name: files_metadata
-  backend: sql_default
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/files_metadata.db
 ```

docs/docs/providers/files/remote_s3.mdx

@@ -20,7 +20,7 @@ AWS S3-based file storage provider for scalable cloud file management with metad
 | `aws_secret_access_key` | `str \| None` | No |  | AWS secret access key (optional if using IAM roles) |
 | `endpoint_url` | `str \| None` | No |  | Custom S3 endpoint URL (for MinIO, LocalStack, etc.) |
 | `auto_create_bucket` | `<class 'bool'>` | No | False | Automatically create the S3 bucket if it doesn't exist |
-| `metadata_store` | `<class 'llama_stack.core.storage.datatypes.SqlStoreReference'>` | No |  | SQL store configuration for file metadata |
+| `metadata_store` | `utils.sqlstore.sqlstore.SqliteSqlStoreConfig \| utils.sqlstore.sqlstore.PostgresSqlStoreConfig` | No | sqlite | SQL store configuration for file metadata |
 
 ## Sample Configuration
 
@@ -32,6 +32,6 @@ aws_secret_access_key: ${env.AWS_SECRET_ACCESS_KEY:=}
 endpoint_url: ${env.S3_ENDPOINT_URL:=}
 auto_create_bucket: ${env.S3_AUTO_CREATE_BUCKET:=false}
 metadata_store:
-  table_name: s3_files_metadata
-  backend: sql_default
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/s3_files_metadata.db
 ```

docs/docs/providers/vector_io/inline_chromadb.mdx

@@ -79,13 +79,13 @@ See [Chroma's documentation](https://docs.trychroma.com/docs/overview/introducti
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `db_path` | `<class 'str'>` | No |  |  |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Config for KV store backend |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend |
 
 ## Sample Configuration
 
 ```yaml
 db_path: ${env.CHROMADB_PATH}
-persistence:
-  namespace: vector_io::chroma
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/chroma_inline_registry.db
 ```

docs/docs/providers/vector_io/inline_faiss.mdx

@@ -95,12 +95,12 @@ more details about Faiss in general.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
-persistence:
-  namespace: vector_io::faiss
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/faiss_store.db
 ```

docs/docs/providers/vector_io/inline_meta-reference.mdx

@@ -14,14 +14,14 @@ Meta's reference implementation of a vector database.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
-persistence:
-  namespace: vector_io::faiss
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/faiss_store.db
 ```
 ## Deprecation Notice
 

docs/docs/providers/vector_io/inline_milvus.mdx

@@ -17,14 +17,14 @@ Please refer to the remote provider documentation.
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `db_path` | `<class 'str'>` | No |  |  |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Config for KV store backend (SQLite only for now) |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend (SQLite only for now) |
 | `consistency_level` | `<class 'str'>` | No | Strong | The consistency level of the Milvus server |
 
 ## Sample Configuration
 
 ```yaml
 db_path: ${env.MILVUS_DB_PATH:=~/.llama/dummy}/milvus.db
-persistence:
-  namespace: vector_io::milvus
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/milvus_registry.db
 ```

docs/docs/providers/vector_io/inline_qdrant.mdx

@@ -98,13 +98,13 @@ See the [Qdrant documentation](https://qdrant.tech/documentation/) for more deta
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `path` | `<class 'str'>` | No |  |  |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
 path: ${env.QDRANT_PATH:=~/.llama/~/.llama/dummy}/qdrant.db
-persistence:
-  namespace: vector_io::qdrant
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/qdrant_registry.db
 ```

docs/docs/providers/vector_io/inline_sqlite-vec.mdx

@@ -408,13 +408,13 @@ See [sqlite-vec's GitHub repo](https://github.com/asg017/sqlite-vec/tree/main) f
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `db_path` | `<class 'str'>` | No |  | Path to the SQLite database file |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Config for KV store backend (SQLite only for now) |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend (SQLite only for now) |
 
 ## Sample Configuration
 
 ```yaml
 db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/sqlite_vec.db
-persistence:
-  namespace: vector_io::sqlite_vec
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/sqlite_vec_registry.db
 ```

docs/docs/providers/vector_io/inline_sqlite_vec.mdx

@@ -17,15 +17,15 @@ Please refer to the sqlite-vec provider documentation.
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `db_path` | `<class 'str'>` | No |  | Path to the SQLite database file |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Config for KV store backend (SQLite only for now) |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend (SQLite only for now) |
 
 ## Sample Configuration
 
 ```yaml
 db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/sqlite_vec.db
-persistence:
-  namespace: vector_io::sqlite_vec
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/sqlite_vec_registry.db
 ```
 ## Deprecation Notice
 

docs/docs/providers/vector_io/remote_chromadb.mdx

@@ -78,13 +78,13 @@ See [Chroma's documentation](https://docs.trychroma.com/docs/overview/introducti
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `url` | `str \| None` | No |  |  |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Config for KV store backend |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend |
 
 ## Sample Configuration
 
 ```yaml
 url: ${env.CHROMADB_URL}
-persistence:
-  namespace: vector_io::chroma_remote
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/chroma_remote_registry.db
 ```

docs/docs/providers/vector_io/remote_milvus.mdx

@@ -408,7 +408,7 @@ For more details on TLS configuration, refer to the [TLS setup guide](https://mi
 | `uri` | `<class 'str'>` | No |  | The URI of the Milvus server |
 | `token` | `str \| None` | No |  | The token of the Milvus server |
 | `consistency_level` | `<class 'str'>` | No | Strong | The consistency level of the Milvus server |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  | Config for KV store backend |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend |
 | `config` | `dict` | No | `{}` | This configuration allows additional fields to be passed through to the underlying Milvus client. See the [Milvus](https://milvus.io/docs/install-overview.md) documentation for more details about Milvus in general. |
 
 :::note
@@ -420,7 +420,7 @@ This configuration class accepts additional fields beyond those listed above. Yo
 ```yaml
 uri: ${env.MILVUS_ENDPOINT}
 token: ${env.MILVUS_TOKEN}
-persistence:
-  namespace: vector_io::milvus_remote
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/milvus_remote_registry.db
 ```

docs/docs/providers/vector_io/remote_pgvector.mdx

@@ -218,7 +218,7 @@ See [PGVector's documentation](https://github.com/pgvector/pgvector) for more de
 | `db` | `str \| None` | No | postgres |  |
 | `user` | `str \| None` | No | postgres |  |
 | `password` | `str \| None` | No | mysecretpassword |  |
-| `persistence` | `llama_stack.core.storage.datatypes.KVStoreReference \| None` | No |  | Config for KV store backend (SQLite only for now) |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig, annotation=NoneType, required=False, default='sqlite', discriminator='type'` | No |  | Config for KV store backend (SQLite only for now) |
 
 ## Sample Configuration
 
@@ -228,7 +228,7 @@ port: ${env.PGVECTOR_PORT:=5432}
 db: ${env.PGVECTOR_DB}
 user: ${env.PGVECTOR_USER}
 password: ${env.PGVECTOR_PASSWORD}
-persistence:
-  namespace: vector_io::pgvector
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/pgvector_registry.db
 ```

docs/docs/providers/vector_io/remote_qdrant.mdx

@@ -26,13 +26,13 @@ Please refer to the inline provider documentation.
 | `prefix` | `str \| None` | No |  |  |
 | `timeout` | `int \| None` | No |  |  |
 | `host` | `str \| None` | No |  |  |
-| `persistence` | `<class 'llama_stack.core.storage.datatypes.KVStoreReference'>` | No |  |  |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite |  |
 
 ## Sample Configuration
 
 ```yaml
 api_key: ${env.QDRANT_API_KEY:=}
-persistence:
-  namespace: vector_io::qdrant_remote
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/qdrant_registry.db
 ```

docs/docs/providers/vector_io/remote_weaviate.mdx

@@ -75,14 +75,14 @@ See [Weaviate's documentation](https://weaviate.io/developers/weaviate) for more
 |-------|------|----------|---------|-------------|
 | `weaviate_api_key` | `str \| None` | No |  | The API key for the Weaviate instance |
 | `weaviate_cluster_url` | `str \| None` | No | localhost:8080 | The URL of the Weaviate cluster |
-| `persistence` | `llama_stack.core.storage.datatypes.KVStoreReference \| None` | No |  | Config for KV store backend (SQLite only for now) |
+| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig, annotation=NoneType, required=False, default='sqlite', discriminator='type'` | No |  | Config for KV store backend (SQLite only for now) |
 
 ## Sample Configuration
 
 ```yaml
 weaviate_api_key: null
 weaviate_cluster_url: ${env.WEAVIATE_CLUSTER_URL:=localhost:8080}
-persistence:
-  namespace: vector_io::weaviate
-  backend: kv_default
+kvstore:
+  type: sqlite
+  db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/weaviate_registry.db
 ```

docs/docs/references/llama_stack_client_cli_reference.md

@@ -32,6 +32,7 @@ Commands:
   scoring_functions  Manage scoring functions.
   shields            Manage safety shield services.
   toolgroups         Manage available tool groups.
+  vector_dbs         Manage vector databases.
 ```
 
 ### `llama-stack-client configure`
@@ -210,6 +211,53 @@ Unregister a model from distribution endpoint
 llama-stack-client models unregister <model_id>
 ```
 
+## Vector DB Management
+Manage vector databases.
+
+
+### `llama-stack-client vector_dbs list`
+Show available vector dbs on distribution endpoint
+```bash
+llama-stack-client vector_dbs list
+```
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ identifier               ┃ provider_id ┃ provider_resource_id     ┃ vector_db_type ┃ params                            ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ my_demo_vector_db        │ faiss       │ my_demo_vector_db        │                │ embedding_dimension: 768          │
+│                          │             │                          │                │ embedding_model: nomic-embed-text-v1.5 │
+│                          │             │                          │                │ type: vector_db                   │
+│                          │             │                          │                │                                   │
+└──────────────────────────┴─────────────┴──────────────────────────┴────────────────┴───────────────────────────────────┘
+```
+
+### `llama-stack-client vector_dbs register`
+Create a new vector db
+```bash
+llama-stack-client vector_dbs register <vector-db-id> [--provider-id <provider-id>] [--provider-vector-db-id <provider-vector-db-id>] [--embedding-model <embedding-model>] [--embedding-dimension <embedding-dimension>]
+```
+
+
+Required arguments:
+- `VECTOR_DB_ID`: Vector DB ID
+
+Optional arguments:
+- `--provider-id`: Provider ID for the vector db
+- `--provider-vector-db-id`: Provider's vector db ID
+- `--embedding-model`: Embedding model to use. Default: `nomic-embed-text-v1.5`
+- `--embedding-dimension`: Dimension of embeddings. Default: 768
+
+### `llama-stack-client vector_dbs unregister`
+Delete a vector db
+```bash
+llama-stack-client vector_dbs unregister <vector-db-id>
+```
+
+
+Required arguments:
+- `VECTOR_DB_ID`: Vector DB ID
+
+
 ## Shield Management
 Manage safety shield services.
 ### `llama-stack-client shields list`

docs/notebooks/Alpha_Llama_Stack_Post_Training.ipynb

@@ -2864,7 +2864,7 @@
     }
    ],
    "source": [
-    "!llama stack list-deps experimental-post-training | xargs -L1 uv pip install"
+    "!llama stack build --distro experimental-post-training --image-type venv --image-name __system__"
    ]
   },
   {

docs/notebooks/Llama_Stack_Agent_Workflows.ipynb

@@ -38,7 +38,7 @@
    "source": [
     "# NBVAL_SKIP\n",
     "!pip install -U llama-stack\n",
-    "llama stack list-deps fireworks | xargs -L1 uv pip install\n"
+    "!UV_SYSTEM_PYTHON=1 llama stack build --distro fireworks --image-type venv"
    ]
   },
   {

docs/notebooks/crewai/Llama_Stack_CrewAI.ipynb

@@ -136,8 +136,7 @@
     "    \"\"\"Build and run LlamaStack server in one step using --run flag\"\"\"\n",
     "    log_file = open(\"llama_stack_server.log\", \"w\")\n",
     "    process = subprocess.Popen(\n",
-    "        \"uv run --with llama-stack llama stack list-deps starter | xargs -L1 uv pip install\",\n",
-    "        \"uv run --with llama-stack llama stack run starter\",\n",
+    "        \"uv run --with llama-stack llama stack build --distro starter --image-type venv --run\",\n",
     "        shell=True,\n",
     "        stdout=log_file,\n",
     "        stderr=log_file,\n",
@@ -173,7 +172,7 @@
     "\n",
     "def kill_llama_stack_server():\n",
     "    # Kill any existing llama stack server processes using pkill command\n",
-    "    os.system(\"pkill -f llama_stack.core.server.server\")\n"
+    "    os.system(\"pkill -f llama_stack.core.server.server\")"
    ]
   },
   {

docs/notebooks/langchain/Llama_Stack_LangChain.ipynb

@@ -105,8 +105,7 @@
     "    \"\"\"Build and run LlamaStack server in one step using --run flag\"\"\"\n",
     "    log_file = open(\"llama_stack_server.log\", \"w\")\n",
     "    process = subprocess.Popen(\n",
-    "        \"uv run --with llama-stack llama stack list-deps starter | xargs -L1 uv pip install\",\n",
-    "        \"uv run --with llama-stack llama stack run starter\",\n",
+    "        \"uv run --with llama-stack llama stack build --distro starter --image-type venv --run\",\n",
     "        shell=True,\n",
     "        stdout=log_file,\n",
     "        stderr=log_file,\n",

docs/notebooks/nvidia/beginner_e2e/Llama_Stack_NVIDIA_E2E_Flow.ipynb

@@ -92,7 +92,7 @@
    "metadata": {},
    "source": [
     "```bash\n",
-    "uv run --with llama-stack llama stack list-deps nvidia | xargs -L1 uv pip install\n",
+    "LLAMA_STACK_DIR=$(pwd) llama stack build --distro nvidia --image-type venv\n",
     "```"
    ]
   },

docs/notebooks/nvidia/tool_calling/1_data_preparation.ipynb

@@ -81,7 +81,7 @@
    "metadata": {},
    "source": [
     "```bash\n",
-    "uv run --with llama-stack llama stack list-deps nvidia | xargs -L1 uv pip install\n",
+    "LLAMA_STACK_DIR=$(pwd) llama stack build --distro nvidia --image-type venv\n",
     "```"
    ]
   },

docs/openapi_generator/run_openapi_generator.sh

@@ -30,5 +30,3 @@ fi
 stack_dir=$(dirname $(dirname $THIS_DIR))
 PYTHONPATH=$PYTHONPATH:$stack_dir \
   python -m docs.openapi_generator.generate $(dirname $THIS_DIR)/static
-
-cp $stack_dir/docs/static/stainless-llama-stack-spec.yaml $stack_dir/client-sdks/stainless/openapi.yml

docs/quick_start.ipynb

@@ -1,399 +1,366 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "c1e7571c",
-   "metadata": {
-    "id": "c1e7571c"
-   },
-   "source": [
-    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/meta-llama/llama-stack/blob/main/docs/getting_started.ipynb)\n",
-    "\n",
-    "# Llama Stack - Building AI Applications\n",
-    "\n",
-    "<img src=\"https://llamastack.github.io/latest/_images/llama-stack.png\" alt=\"drawing\" width=\"500\"/>\n",
-    "\n",
-    "Get started with Llama Stack in minutes!\n",
-    "\n",
-    "[Llama Stack](https://github.com/meta-llama/llama-stack) is a stateful service with REST APIs to support the seamless transition of AI applications across different environments. You can build and test using a local server first and deploy to a hosted endpoint for production.\n",
-    "\n",
-    "In this guide, we'll walk through how to build a RAG application locally using Llama Stack with [Ollama](https://ollama.com/)\n",
-    "as the inference [provider](docs/source/providers/index.md#inference) for a Llama Model.\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "4CV1Q19BDMVw",
-   "metadata": {
-    "id": "4CV1Q19BDMVw"
-   },
-   "source": [
-    "## Step 1: Install and setup"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "K4AvfUAJZOeS",
-   "metadata": {
-    "id": "K4AvfUAJZOeS"
-   },
-   "source": [
-    "### 1.1. Install uv and test inference with Ollama\n",
-    "\n",
-    "We'll install [uv](https://docs.astral.sh/uv/) to setup the Python virtual environment, along with [colab-xterm](https://github.com/InfuseAI/colab-xterm) for running command-line tools, and [Ollama](https://ollama.com/download) as the inference provider."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "7a2d7b85",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install uv llama_stack llama-stack-client\n",
-    "\n",
-    "## If running on Collab:\n",
-    "# !pip install colab-xterm\n",
-    "# %load_ext colabxterm\n",
-    "\n",
-    "!curl https://ollama.ai/install.sh | sh"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "39fa584b",
-   "metadata": {},
-   "source": [
-    "### 1.2. Test inference with Ollama"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "3bf81522",
-   "metadata": {},
-   "source": [
-    "We’ll now launch a terminal and run inference on a Llama model with Ollama to verify that the model is working correctly."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "a7e8e0f1",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "## If running on Colab:\n",
-    "# %xterm\n",
-    "\n",
-    "## To be ran in the terminal:\n",
-    "# ollama serve &\n",
-    "# ollama run llama3.2:3b --keepalive 60m"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "f3c5f243",
-   "metadata": {},
-   "source": [
-    "If successful, you should see the model respond to a prompt.\n",
-    "\n",
-    "...\n",
-    "```\n",
-    ">>> hi\n",
-    "Hello! How can I assist you today?\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "oDUB7M_qe-Gs",
-   "metadata": {
-    "id": "oDUB7M_qe-Gs"
-   },
-   "source": [
-    "## Step 2: Run the Llama Stack server\n",
-    "\n",
-    "In this showcase, we will start a Llama Stack server that is running locally."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "732eadc6",
-   "metadata": {},
-   "source": [
-    "### 2.1. Setup the Llama Stack Server"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "J2kGed0R5PSf",
-   "metadata": {
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "c1e7571c",
+      "metadata": {
+        "id": "c1e7571c"
+      },
+      "source": [
+        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/meta-llama/llama-stack/blob/main/docs/getting_started.ipynb)\n",
+        "\n",
+        "# Llama Stack - Building AI Applications\n",
+        "\n",
+        "<img src=\"https://llamastack.github.io/latest/_images/llama-stack.png\" alt=\"drawing\" width=\"500\"/>\n",
+        "\n",
+        "Get started with Llama Stack in minutes!\n",
+        "\n",
+        "[Llama Stack](https://github.com/meta-llama/llama-stack) is a stateful service with REST APIs to support the seamless transition of AI applications across different environments. You can build and test using a local server first and deploy to a hosted endpoint for production.\n",
+        "\n",
+        "In this guide, we'll walk through how to build a RAG application locally using Llama Stack with [Ollama](https://ollama.com/)\n",
+        "as the inference [provider](docs/source/providers/index.md#inference) for a Llama Model.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "4CV1Q19BDMVw",
+      "metadata": {
+        "id": "4CV1Q19BDMVw"
+      },
+      "source": [
+        "## Step 1: Install and setup"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "K4AvfUAJZOeS",
+      "metadata": {
+        "id": "K4AvfUAJZOeS"
+      },
+      "source": [
+        "### 1.1. Install uv and test inference with Ollama\n",
+        "\n",
+        "We'll install [uv](https://docs.astral.sh/uv/) to setup the Python virtual environment, along with [colab-xterm](https://github.com/InfuseAI/colab-xterm) for running command-line tools, and [Ollama](https://ollama.com/download) as the inference provider."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "7a2d7b85",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "%pip install uv llama_stack llama-stack-client\n",
+        "\n",
+        "## If running on Collab:\n",
+        "# !pip install colab-xterm\n",
+        "# %load_ext colabxterm\n",
+        "\n",
+        "!curl https://ollama.ai/install.sh | sh"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "39fa584b",
+      "metadata": {},
+      "source": [
+        "### 1.2. Test inference with Ollama"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "3bf81522",
+      "metadata": {},
+      "source": [
+        "We’ll now launch a terminal and run inference on a Llama model with Ollama to verify that the model is working correctly."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "a7e8e0f1",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "## If running on Colab:\n",
+        "# %xterm\n",
+        "\n",
+        "## To be ran in the terminal:\n",
+        "# ollama serve &\n",
+        "# ollama run llama3.2:3b --keepalive 60m"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "f3c5f243",
+      "metadata": {},
+      "source": [
+        "If successful, you should see the model respond to a prompt.\n",
+        "\n",
+        "...\n",
+        "```\n",
+        ">>> hi\n",
+        "Hello! How can I assist you today?\n",
+        "```"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "oDUB7M_qe-Gs",
+      "metadata": {
+        "id": "oDUB7M_qe-Gs"
+      },
+      "source": [
+        "## Step 2: Run the Llama Stack server\n",
+        "\n",
+        "In this showcase, we will start a Llama Stack server that is running locally."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "732eadc6",
+      "metadata": {},
+      "source": [
+        "### 2.1. Setup the Llama Stack Server"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "J2kGed0R5PSf",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "collapsed": true,
+        "id": "J2kGed0R5PSf",
+        "outputId": "2478ea60-8d35-48a1-b011-f233831740c5"
+      },
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "import subprocess\n",
+        "\n",
+        "if \"UV_SYSTEM_PYTHON\" in os.environ:\n",
+        "  del os.environ[\"UV_SYSTEM_PYTHON\"]\n",
+        "\n",
+        "# this command installs all the dependencies needed for the llama stack server with the ollama inference provider\n",
+        "!uv run --with llama-stack llama stack build --distro starter\n",
+        "\n",
+        "def run_llama_stack_server_background():\n",
+        "    log_file = open(\"llama_stack_server.log\", \"w\")\n",
+        "    process = subprocess.Popen(\n",
+        "        f\"OLLAMA_URL=http://localhost:11434 uv run --with llama-stack llama stack run starter\n",
+        "        shell=True,\n",
+        "        stdout=log_file,\n",
+        "        stderr=log_file,\n",
+        "        text=True\n",
+        "    )\n",
+        "\n",
+        "    print(f\"Starting Llama Stack server with PID: {process.pid}\")\n",
+        "    return process\n",
+        "\n",
+        "def wait_for_server_to_start():\n",
+        "    import requests\n",
+        "    from requests.exceptions import ConnectionError\n",
+        "    import time\n",
+        "\n",
+        "    url = \"http://0.0.0.0:8321/v1/health\"\n",
+        "    max_retries = 30\n",
+        "    retry_interval = 1\n",
+        "\n",
+        "    print(\"Waiting for server to start\", end=\"\")\n",
+        "    for _ in range(max_retries):\n",
+        "        try:\n",
+        "            response = requests.get(url)\n",
+        "            if response.status_code == 200:\n",
+        "                print(\"\\nServer is ready!\")\n",
+        "                return True\n",
+        "        except ConnectionError:\n",
+        "            print(\".\", end=\"\", flush=True)\n",
+        "            time.sleep(retry_interval)\n",
+        "\n",
+        "    print(\"\\nServer failed to start after\", max_retries * retry_interval, \"seconds\")\n",
+        "    return False\n",
+        "\n",
+        "\n",
+        "# use this helper if needed to kill the server\n",
+        "def kill_llama_stack_server():\n",
+        "    # Kill any existing llama stack server processes\n",
+        "    os.system(\"ps aux | grep -v grep | grep llama_stack.core.server.server | awk '{print $2}' | xargs kill -9\")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "c40e9efd",
+      "metadata": {},
+      "source": [
+        "### 2.2. Start the Llama Stack Server"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 7,
+      "id": "f779283d",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Starting Llama Stack server with PID: 787100\n",
+            "Waiting for server to start\n",
+            "Server is ready!\n"
+          ]
+        }
+      ],
+      "source": [
+        "server_process = run_llama_stack_server_background()\n",
+        "assert wait_for_server_to_start()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "28477c03",
+      "metadata": {},
+      "source": [
+        "## Step 3: Run the demo"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 8,
+      "id": "7da71011",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "rag_tool> Ingesting document: https://www.paulgraham.com/greatwork.html\n",
+            "prompt> How do you do great work?\n",
+            "\u001b[33minference> \u001b[0m\u001b[33m[k\u001b[0m\u001b[33mnowledge\u001b[0m\u001b[33m_search\u001b[0m\u001b[33m(query\u001b[0m\u001b[33m=\"\u001b[0m\u001b[33mWhat\u001b[0m\u001b[33m is\u001b[0m\u001b[33m the\u001b[0m\u001b[33m key\u001b[0m\u001b[33m to\u001b[0m\u001b[33m doing\u001b[0m\u001b[33m great\u001b[0m\u001b[33m work\u001b[0m\u001b[33m\")]\u001b[0m\u001b[97m\u001b[0m\n",
+            "\u001b[32mtool_execution> Tool:knowledge_search Args:{'query': 'What is the key to doing great work'}\u001b[0m\n",
+            "\u001b[32mtool_execution> Tool:knowledge_search Response:[TextContentItem(text='knowledge_search tool found 5 chunks:\\nBEGIN of knowledge_search tool results.\\n', type='text'), TextContentItem(text=\"Result 1:\\nDocument_id:docum\\nContent:  work. Doing great work means doing something important\\nso well that you expand people's ideas of what's possible. But\\nthere's no threshold for importance. It's a matter of degree, and\\noften hard to judge at the time anyway.\\n\", type='text'), TextContentItem(text=\"Result 2:\\nDocument_id:docum\\nContent:  work. Doing great work means doing something important\\nso well that you expand people's ideas of what's possible. But\\nthere's no threshold for importance. It's a matter of degree, and\\noften hard to judge at the time anyway.\\n\", type='text'), TextContentItem(text=\"Result 3:\\nDocument_id:docum\\nContent:  work. Doing great work means doing something important\\nso well that you expand people's ideas of what's possible. But\\nthere's no threshold for importance. It's a matter of degree, and\\noften hard to judge at the time anyway.\\n\", type='text'), TextContentItem(text=\"Result 4:\\nDocument_id:docum\\nContent:  work. Doing great work means doing something important\\nso well that you expand people's ideas of what's possible. But\\nthere's no threshold for importance. It's a matter of degree, and\\noften hard to judge at the time anyway.\\n\", type='text'), TextContentItem(text=\"Result 5:\\nDocument_id:docum\\nContent:  work. Doing great work means doing something important\\nso well that you expand people's ideas of what's possible. But\\nthere's no threshold for importance. It's a matter of degree, and\\noften hard to judge at the time anyway.\\n\", type='text'), TextContentItem(text='END of knowledge_search tool results.\\n', type='text'), TextContentItem(text='The above results were retrieved to help answer the user\\'s query: \"What is the key to doing great work\". Use them as supporting information only in answering this query.\\n', type='text')]\u001b[0m\n",
+            "\u001b[33minference> \u001b[0m\u001b[33mDoing\u001b[0m\u001b[33m great\u001b[0m\u001b[33m work\u001b[0m\u001b[33m means\u001b[0m\u001b[33m doing\u001b[0m\u001b[33m something\u001b[0m\u001b[33m important\u001b[0m\u001b[33m so\u001b[0m\u001b[33m well\u001b[0m\u001b[33m that\u001b[0m\u001b[33m you\u001b[0m\u001b[33m expand\u001b[0m\u001b[33m people\u001b[0m\u001b[33m's\u001b[0m\u001b[33m ideas\u001b[0m\u001b[33m of\u001b[0m\u001b[33m what\u001b[0m\u001b[33m's\u001b[0m\u001b[33m possible\u001b[0m\u001b[33m.\u001b[0m\u001b[33m However\u001b[0m\u001b[33m,\u001b[0m\u001b[33m there\u001b[0m\u001b[33m's\u001b[0m\u001b[33m no\u001b[0m\u001b[33m threshold\u001b[0m\u001b[33m for\u001b[0m\u001b[33m importance\u001b[0m\u001b[33m,\u001b[0m\u001b[33m and\u001b[0m\u001b[33m it\u001b[0m\u001b[33m's\u001b[0m\u001b[33m often\u001b[0m\u001b[33m hard\u001b[0m\u001b[33m to\u001b[0m\u001b[33m judge\u001b[0m\u001b[33m at\u001b[0m\u001b[33m the\u001b[0m\u001b[33m time\u001b[0m\u001b[33m anyway\u001b[0m\u001b[33m.\u001b[0m\u001b[33m Great\u001b[0m\u001b[33m work\u001b[0m\u001b[33m is\u001b[0m\u001b[33m a\u001b[0m\u001b[33m matter\u001b[0m\u001b[33m of\u001b[0m\u001b[33m degree\u001b[0m\u001b[33m,\u001b[0m\u001b[33m and\u001b[0m\u001b[33m it\u001b[0m\u001b[33m can\u001b[0m\u001b[33m be\u001b[0m\u001b[33m difficult\u001b[0m\u001b[33m to\u001b[0m\u001b[33m determine\u001b[0m\u001b[33m whether\u001b[0m\u001b[33m someone\u001b[0m\u001b[33m has\u001b[0m\u001b[33m done\u001b[0m\u001b[33m great\u001b[0m\u001b[33m work\u001b[0m\u001b[33m until\u001b[0m\u001b[33m after\u001b[0m\u001b[33m the\u001b[0m\u001b[33m fact\u001b[0m\u001b[33m.\u001b[0m\u001b[97m\u001b[0m\n",
+            "\u001b[30m\u001b[0m"
+          ]
+        }
+      ],
+      "source": [
+        "from llama_stack_client import Agent, AgentEventLogger, RAGDocument, LlamaStackClient\n",
+        "\n",
+        "vector_db_id = \"my_demo_vector_db\"\n",
+        "client = LlamaStackClient(base_url=\"http://0.0.0.0:8321\")\n",
+        "\n",
+        "models = client.models.list()\n",
+        "\n",
+        "# Select the first ollama and first ollama's embedding model\n",
+        "model_id = next(m for m in models if m.model_type == \"llm\" and m.provider_id == \"ollama\").identifier\n",
+        "embedding_model = next(m for m in models if m.model_type == \"embedding\" and m.provider_id == \"ollama\")\n",
+        "embedding_model_id = embedding_model.identifier\n",
+        "embedding_dimension = embedding_model.metadata[\"embedding_dimension\"]\n",
+        "\n",
+        "_ = client.vector_dbs.register(\n",
+        "    vector_db_id=vector_db_id,\n",
+        "    embedding_model=embedding_model_id,\n",
+        "    embedding_dimension=embedding_dimension,\n",
+        "    provider_id=\"faiss\",\n",
+        ")\n",
+        "source = \"https://www.paulgraham.com/greatwork.html\"\n",
+        "print(\"rag_tool> Ingesting document:\", source)\n",
+        "document = RAGDocument(\n",
+        "    document_id=\"document_1\",\n",
+        "    content=source,\n",
+        "    mime_type=\"text/html\",\n",
+        "    metadata={},\n",
+        ")\n",
+        "client.tool_runtime.rag_tool.insert(\n",
+        "    documents=[document],\n",
+        "    vector_db_id=vector_db_id,\n",
+        "    chunk_size_in_tokens=50,\n",
+        ")\n",
+        "agent = Agent(\n",
+        "    client,\n",
+        "    model=model_id,\n",
+        "    instructions=\"You are a helpful assistant\",\n",
+        "    tools=[\n",
+        "        {\n",
+        "            \"name\": \"builtin::rag/knowledge_search\",\n",
+        "            \"args\": {\"vector_db_ids\": [vector_db_id]},\n",
+        "        }\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "prompt = \"How do you do great work?\"\n",
+        "print(\"prompt>\", prompt)\n",
+        "\n",
+        "response = agent.create_turn(\n",
+        "    messages=[{\"role\": \"user\", \"content\": prompt}],\n",
+        "    session_id=agent.create_session(\"rag_session\"),\n",
+        "    stream=True,\n",
+        ")\n",
+        "\n",
+        "for log in AgentEventLogger().log(response):\n",
+        "    log.print()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "341aaadf",
+      "metadata": {},
+      "source": [
+        "Congratulations! You've successfully built your first RAG application using Llama Stack! 🎉🥳"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "e88e1185",
+      "metadata": {},
+      "source": [
+        "## Next Steps"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "bcb73600",
+      "metadata": {},
+      "source": [
+        "Now you're ready to dive deeper into Llama Stack!\n",
+        "- Explore the [Detailed Tutorial](./detailed_tutorial.md).\n",
+        "- Try the [Getting Started Notebook](https://github.com/meta-llama/llama-stack/blob/main/docs/getting_started.ipynb).\n",
+        "- Browse more [Notebooks on GitHub](https://github.com/meta-llama/llama-stack/tree/main/docs/notebooks).\n",
+        "- Learn about Llama Stack [Concepts](../concepts/index.md).\n",
+        "- Discover how to [Build Llama Stacks](../distributions/index.md).\n",
+        "- Refer to our [References](../references/index.md) for details on the Llama CLI and Python SDK.\n",
+        "- Check out the [llama-stack-apps](https://github.com/meta-llama/llama-stack-apps/tree/main/examples) repository for example applications and tutorials."
+      ]
+    }
+  ],
+  "metadata": {
+    "accelerator": "GPU",
     "colab": {
-     "base_uri": "https://localhost:8080/"
+      "gpuType": "T4",
+      "provenance": []
     },
-    "id": "J2kGed0R5PSf",
-    "outputId": "2478ea60-8d35-48a1-b011-f233831740c5"
-   },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\u001b[2mUsing Python 3.12.12 environment at: /opt/homebrew/Caskroom/miniconda/base/envs/test\u001b[0m\n",
-      "\u001b[2mAudited \u001b[1m52 packages\u001b[0m \u001b[2min 1.56s\u001b[0m\u001b[0m\n",
-      "\u001b[2mUsing Python 3.12.12 environment at: /opt/homebrew/Caskroom/miniconda/base/envs/test\u001b[0m\n",
-      "\u001b[2mAudited \u001b[1m3 packages\u001b[0m \u001b[2min 122ms\u001b[0m\u001b[0m\n",
-      "\u001b[2mUsing Python 3.12.12 environment at: /opt/homebrew/Caskroom/miniconda/base/envs/test\u001b[0m\n",
-      "\u001b[2mAudited \u001b[1m3 packages\u001b[0m \u001b[2min 197ms\u001b[0m\u001b[0m\n",
-      "\u001b[2mUsing Python 3.12.12 environment at: /opt/homebrew/Caskroom/miniconda/base/envs/test\u001b[0m\n",
-      "\u001b[2mAudited \u001b[1m1 package\u001b[0m \u001b[2min 11ms\u001b[0m\u001b[0m\n"
-     ]
-    }
-   ],
-   "source": [
-    "import os\n",
-    "import subprocess\n",
-    "\n",
-    "if \"UV_SYSTEM_PYTHON\" in os.environ:\n",
-    "  del os.environ[\"UV_SYSTEM_PYTHON\"]\n",
-    "\n",
-    "# this command installs all the dependencies needed for the llama stack server with the ollama inference provider\n",
-    "!uv run --with llama-stack llama stack list-deps starter | xargs -L1 uv pip install\n",
-    "\n",
-    "def run_llama_stack_server_background():\n",
-    "    log_file = open(\"llama_stack_server.log\", \"w\")\n",
-    "    process = subprocess.Popen(\n",
-    "        f\"OLLAMA_URL=http://localhost:11434 uv run --with llama-stack llama stack run starter\",\n",
-    "        shell=True,\n",
-    "        stdout=log_file,\n",
-    "        stderr=log_file,\n",
-    "        text=True\n",
-    "    )\n",
-    "\n",
-    "    print(f\"Starting Llama Stack server with PID: {process.pid}\")\n",
-    "    return process\n",
-    "\n",
-    "def wait_for_server_to_start():\n",
-    "    import requests\n",
-    "    from requests.exceptions import ConnectionError\n",
-    "    import time\n",
-    "\n",
-    "    url = \"http://0.0.0.0:8321/v1/health\"\n",
-    "    max_retries = 30\n",
-    "    retry_interval = 1\n",
-    "\n",
-    "    print(\"Waiting for server to start\", end=\"\")\n",
-    "    for _ in range(max_retries):\n",
-    "        try:\n",
-    "            response = requests.get(url)\n",
-    "            if response.status_code == 200:\n",
-    "                print(\"\\nServer is ready!\")\n",
-    "                return True\n",
-    "        except ConnectionError:\n",
-    "            print(\".\", end=\"\", flush=True)\n",
-    "            time.sleep(retry_interval)\n",
-    "\n",
-    "    print(\"\\nServer failed to start after\", max_retries * retry_interval, \"seconds\")\n",
-    "    return False\n",
-    "\n",
-    "\n",
-    "# use this helper if needed to kill the server\n",
-    "def kill_llama_stack_server():\n",
-    "    # Kill any existing llama stack server processes\n",
-    "    os.system(\"ps aux | grep -v grep | grep llama_stack.core.server.server | awk '{print $2}' | xargs kill -9\")\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "c40e9efd",
-   "metadata": {},
-   "source": [
-    "### 2.2. Start the Llama Stack Server"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "f779283d",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Starting Llama Stack server with PID: 20778\n",
-      "Waiting for server to start........\n",
-      "Server is ready!\n"
-     ]
-    }
-   ],
-   "source": [
-    "server_process = run_llama_stack_server_background()\n",
-    "assert wait_for_server_to_start()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "28477c03",
-   "metadata": {},
-   "source": [
-    "## Step 3: Run the demo"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 3,
-   "id": "7da71011",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "INFO:httpx:HTTP Request: GET http://0.0.0.0:8321/v1/models \"HTTP/1.1 200 OK\"\n",
-      "INFO:httpx:HTTP Request: POST http://0.0.0.0:8321/v1/files \"HTTP/1.1 200 OK\"\n",
-      "INFO:httpx:HTTP Request: POST http://0.0.0.0:8321/v1/vector_stores \"HTTP/1.1 200 OK\"\n",
-      "INFO:httpx:HTTP Request: POST http://0.0.0.0:8321/v1/conversations \"HTTP/1.1 200 OK\"\n",
-      "INFO:httpx:HTTP Request: POST http://0.0.0.0:8321/v1/responses \"HTTP/1.1 200 OK\"\n"
-     ]
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
     },
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "prompt> How do you do great work?\n",
-      "🤔 Doing great work involves a combination of skills, habits, and mindsets. Here are some key principles:\n",
-      "\n",
-      "1. **Set Clear Goals**: Start with a clear vision of what you want to achieve. Define specific, measurable, achievable, relevant, and time-bound (SMART) goals.\n",
-      "\n",
-      "2. **Plan and Prioritize**: Break your goals into smaller, manageable tasks. Prioritize these tasks based on their importance and urgency.\n",
-      "\n",
-      "3. **Focus on Quality**: Aim for high-quality outcomes rather than just finishing tasks. Pay attention to detail, and ensure your work meets or exceeds standards.\n",
-      "\n",
-      "4. **Stay Organized**: Keep your workspace, both physical and digital, organized to help you stay focused and efficient.\n",
-      "\n",
-      "5. **Manage Your Time**: Use time management techniques such as the Pomodoro Technique, time blocking, or the Eisenhower Box to maximize productivity.\n",
-      "\n",
-      "6. **Seek Feedback and Learn**: Regularly seek feedback from peers, mentors, or supervisors. Use constructive criticism to improve continuously.\n",
-      "\n",
-      "7. **Innovate and Improve**: Look for ways to improve processes or introduce new ideas. Be open to change and willing to adapt.\n",
-      "\n",
-      "8. **Stay Motivated and Persistent**: Keep your end goals in mind to stay motivated. Overcome setbacks with resilience and persistence.\n",
-      "\n",
-      "9. **Balance and Rest**: Ensure you maintain a healthy work-life balance. Take breaks and manage stress to sustain long-term productivity.\n",
-      "\n",
-      "10. **Reflect and Adjust**: Regularly assess your progress and adjust your strategies as needed. Reflect on what works well and what doesn't.\n",
-      "\n",
-      "By incorporating these elements, you can consistently produce high-quality work and achieve excellence in your endeavors.\n"
-     ]
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.10.6"
     }
-   ],
-   "source": [
-    "from llama_stack_client import Agent, AgentEventLogger, RAGDocument, LlamaStackClient\n",
-    "import requests\n",
-    "\n",
-    "vector_store_id = \"my_demo_vector_db\"\n",
-    "client = LlamaStackClient(base_url=\"http://0.0.0.0:8321\")\n",
-    "\n",
-    "models = client.models.list()\n",
-    "\n",
-    "# Select the first ollama and first ollama's embedding model\n",
-    "model_id = next(m for m in models if m.model_type == \"llm\" and m.provider_id == \"ollama\").identifier\n",
-    "\n",
-    "\n",
-    "source = \"https://www.paulgraham.com/greatwork.html\"\n",
-    "response = requests.get(source)\n",
-    "file = client.files.create(\n",
-    "    file=response.content,\n",
-    "    purpose='assistants'\n",
-    ")\n",
-    "vector_store = client.vector_stores.create(\n",
-    "    name=vector_store_id,\n",
-    "    file_ids=[file.id],\n",
-    ")\n",
-    "\n",
-    "agent = Agent(\n",
-    "    client,\n",
-    "    model=model_id,\n",
-    "    instructions=\"You are a helpful assistant\",\n",
-    "    tools=[\n",
-    "        {\n",
-    "            \"type\": \"file_search\",\n",
-    "            \"vector_store_ids\": [vector_store_id],\n",
-    "        }\n",
-    "    ],\n",
-    ")\n",
-    "\n",
-    "prompt = \"How do you do great work?\"\n",
-    "print(\"prompt>\", prompt)\n",
-    "\n",
-    "response = agent.create_turn(\n",
-    "    messages=[{\"role\": \"user\", \"content\": prompt}],\n",
-    "    session_id=agent.create_session(\"rag_session\"),\n",
-    "    stream=True,\n",
-    ")\n",
-    "\n",
-    "for log in AgentEventLogger().log(response):\n",
-    "    print(log, end=\"\")"
-   ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "341aaadf",
-   "metadata": {},
-   "source": [
-    "Congratulations! You've successfully built your first RAG application using Llama Stack! 🎉🥳"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "e88e1185",
-   "metadata": {},
-   "source": [
-    "## Next Steps"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "bcb73600",
-   "metadata": {},
-   "source": [
-    "Now you're ready to dive deeper into Llama Stack!\n",
-    "- Explore the [Detailed Tutorial](./detailed_tutorial.md).\n",
-    "- Try the [Getting Started Notebook](https://github.com/meta-llama/llama-stack/blob/main/docs/getting_started.ipynb).\n",
-    "- Browse more [Notebooks on GitHub](https://github.com/meta-llama/llama-stack/tree/main/docs/notebooks).\n",
-    "- Learn about Llama Stack [Concepts](../concepts/index.md).\n",
-    "- Discover how to [Build Llama Stacks](../distributions/index.md).\n",
-    "- Refer to our [References](../references/index.md) for details on the Llama CLI and Python SDK.\n",
-    "- Check out the [llama-stack-apps](https://github.com/meta-llama/llama-stack-apps/tree/main/examples) repository for example applications and tutorials."
-   ]
-  }
- ],
- "metadata": {
-  "accelerator": "GPU",
-  "colab": {
-   "gpuType": "T4",
-   "provenance": []
-  },
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.12.12"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
+  "nbformat": 4,
+  "nbformat_minor": 5
 }

docs/src/pages/index.js

@@ -47,11 +47,11 @@ function QuickStart() {
               <pre><code>{`# Install uv and start Ollama
 ollama run llama3.2:3b --keepalive 60m
 
-# Install server dependencies
-uv run --with llama-stack llama stack list-deps starter | xargs -L1 uv pip install
-
 # Run Llama Stack server
-OLLAMA_URL=http://localhost:11434 uv run --with llama-stack llama stack run starter
+OLLAMA_URL=http://localhost:11434 \\
+  uv run --with llama-stack \\
+  llama stack build --distro starter \\
+  --image-type venv --run
 
 # Try the Python SDK
 from llama_stack_client import LlamaStackClient

docs/static/deprecated-llama-stack-spec.html

@@ -5547,7 +5547,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -5798,7 +5798,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -9024,10 +9024,6 @@
                         "$ref": "#/components/schemas/OpenAIResponseUsage",
                         "description": "(Optional) Token usage information for the response"
                     },
-                    "instructions": {
-                        "type": "string",
-                        "description": "(Optional) System message inserted into the model's context"
-                    },
                     "input": {
                         "type": "array",
                         "items": {
@@ -9905,10 +9901,6 @@
                     "usage": {
                         "$ref": "#/components/schemas/OpenAIResponseUsage",
                         "description": "(Optional) Token usage information for the response"
-                    },
-                    "instructions": {
-                        "type": "string",
-                        "description": "(Optional) System message inserted into the model's context"
                     }
                 },
                 "additionalProperties": false,

docs/static/deprecated-llama-stack-spec.yaml

@@ -4114,7 +4114,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -4303,7 +4303,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -6734,10 +6734,6 @@ components:
           $ref: '#/components/schemas/OpenAIResponseUsage'
           description: >-
             (Optional) Token usage information for the response
-        instructions:
-          type: string
-          description: >-
-            (Optional) System message inserted into the model's context
         input:
           type: array
           items:
@@ -7407,10 +7403,6 @@ components:
           $ref: '#/components/schemas/OpenAIResponseUsage'
           description: >-
             (Optional) Token usage information for the response
-        instructions:
-          type: string
-          description: >-
-            (Optional) System message inserted into the model's context
       additionalProperties: false
       required:
         - created_at

docs/static/experimental-llama-stack-spec.html

@@ -1850,7 +1850,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -3983,7 +3983,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",

docs/static/experimental-llama-stack-spec.yaml

@@ -1320,7 +1320,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -2927,7 +2927,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark

docs/static/llama-stack-spec.html

@@ -6800,7 +6800,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -7600,10 +7600,6 @@
                         "$ref": "#/components/schemas/OpenAIResponseUsage",
                         "description": "(Optional) Token usage information for the response"
                     },
-                    "instructions": {
-                        "type": "string",
-                        "description": "(Optional) System message inserted into the model's context"
-                    },
                     "input": {
                         "type": "array",
                         "items": {
@@ -8152,10 +8148,6 @@
                     "usage": {
                         "$ref": "#/components/schemas/OpenAIResponseUsage",
                         "description": "(Optional) Token usage information for the response"
-                    },
-                    "instructions": {
-                        "type": "string",
-                        "description": "(Optional) System message inserted into the model's context"
                     }
                 },
                 "additionalProperties": false,
@@ -10205,7 +10197,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -10687,7 +10679,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -11740,7 +11732,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",

docs/static/llama-stack-spec.yaml

@@ -5227,7 +5227,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -5815,10 +5815,6 @@ components:
           $ref: '#/components/schemas/OpenAIResponseUsage'
           description: >-
             (Optional) Token usage information for the response
-        instructions:
-          type: string
-          description: >-
-            (Optional) System message inserted into the model's context
         input:
           type: array
           items:
@@ -6222,10 +6218,6 @@ components:
           $ref: '#/components/schemas/OpenAIResponseUsage'
           description: >-
             (Optional) Token usage information for the response
-        instructions:
-          type: string
-          description: >-
-            (Optional) System message inserted into the model's context
       additionalProperties: false
       required:
         - created_at
@@ -7919,7 +7911,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -8227,7 +8219,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -8990,7 +8982,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark

docs/static/stainless-llama-stack-spec.html

@@ -8472,7 +8472,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -9272,10 +9272,6 @@
                         "$ref": "#/components/schemas/OpenAIResponseUsage",
                         "description": "(Optional) Token usage information for the response"
                     },
-                    "instructions": {
-                        "type": "string",
-                        "description": "(Optional) System message inserted into the model's context"
-                    },
                     "input": {
                         "type": "array",
                         "items": {
@@ -9824,10 +9820,6 @@
                     "usage": {
                         "$ref": "#/components/schemas/OpenAIResponseUsage",
                         "description": "(Optional) Token usage information for the response"
-                    },
-                    "instructions": {
-                        "type": "string",
-                        "description": "(Optional) System message inserted into the model's context"
                     }
                 },
                 "additionalProperties": false,
@@ -11877,7 +11869,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -12359,7 +12351,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -13412,7 +13404,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -14959,7 +14951,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",
@@ -16704,7 +16696,7 @@
                         "enum": [
                             "model",
                             "shield",
-                            "vector_store",
+                            "vector_db",
                             "dataset",
                             "scoring_function",
                             "benchmark",

docs/static/stainless-llama-stack-spec.yaml

@@ -6440,7 +6440,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -7028,10 +7028,6 @@ components:
           $ref: '#/components/schemas/OpenAIResponseUsage'
           description: >-
             (Optional) Token usage information for the response
-        instructions:
-          type: string
-          description: >-
-            (Optional) System message inserted into the model's context
         input:
           type: array
           items:
@@ -7435,10 +7431,6 @@ components:
           $ref: '#/components/schemas/OpenAIResponseUsage'
           description: >-
             (Optional) Token usage information for the response
-        instructions:
-          type: string
-          description: >-
-            (Optional) System message inserted into the model's context
       additionalProperties: false
       required:
         - created_at
@@ -9132,7 +9124,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -9440,7 +9432,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -10203,7 +10195,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -11325,7 +11317,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark
@@ -12652,7 +12644,7 @@ components:
           enum:
             - model
             - shield
-            - vector_store
+            - vector_db
             - dataset
             - scoring_function
             - benchmark

docs/zero_to_hero_guide/README.md

@@ -78,14 +78,17 @@ If you're looking for more specific topics, we have a [Zero to Hero Guide](#next
 
 ## Build, Configure, and Run Llama Stack
 
-1. **Install dependencies**:
+1. **Build the Llama Stack**:
+   Build the Llama Stack using the `starter` template:
    ```bash
-   llama stack list-deps starter | xargs -L1 uv pip install
+   uv run --with llama-stack llama stack build --distro starter --image-type venv
    ```
-
-2. **Start the distribution**:
+   **Expected Output:**
    ```bash
-   llama stack run starter
+   ...
+   Build Successful!
+   You can find the newly-built template here: ~/.llama/distributions/starter/starter-run.yaml
+   You can run the new Llama Stack Distro via: uv run --with llama-stack llama stack run starter
    ```
 
 3. **Set the ENV variables by exporting them to the terminal**:

llama_stack/apis/agents/openai_responses.py

@@ -545,7 +545,6 @@ class OpenAIResponseObject(BaseModel):
     :param tools: (Optional) An array of tools the model may call while generating a response.
     :param truncation: (Optional) Truncation strategy applied to the response
     :param usage: (Optional) Token usage information for the response
-    :param instructions: (Optional) System message inserted into the model's context
     """
 
     created_at: int
@@ -565,7 +564,6 @@ class OpenAIResponseObject(BaseModel):
     tools: list[OpenAIResponseTool] | None = None
     truncation: str | None = None
     usage: OpenAIResponseUsage | None = None
-    instructions: str | None = None
 
 
 @json_schema_type

llama_stack/apis/datatypes.py

@@ -121,7 +121,6 @@ class Api(Enum, metaclass=DynamicApiMeta):
 
     models = "models"
     shields = "shields"
-    vector_stores = "vector_stores"  # only used for routing table
     datasets = "datasets"
     scoring_functions = "scoring_functions"
     benchmarks = "benchmarks"

llama_stack/apis/resource.py

@@ -13,7 +13,7 @@ from pydantic import BaseModel, Field
 class ResourceType(StrEnum):
     model = "model"
     shield = "shield"
-    vector_store = "vector_store"
+    vector_db = "vector_db"
     dataset = "dataset"
     scoring_function = "scoring_function"
     benchmark = "benchmark"
@@ -34,4 +34,4 @@ class Resource(BaseModel):
 
     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.)")
+    type: ResourceType = Field(description="Type of resource (e.g. 'model', 'shield', 'vector_db', etc.)")

llama_stack/apis/vector_dbs/__init__.py

@@ -3,3 +3,5 @@
 #
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
+
+from .vector_dbs import *

llama_stack/apis/vector_dbs/vector_dbs.py

@@ -9,43 +9,53 @@ from typing import Literal
 from pydantic import BaseModel
 
 from llama_stack.apis.resource import Resource, ResourceType
+from llama_stack.schema_utils import json_schema_type
 
 
-# Internal resource type for storing the vector store routing and other information
-class VectorStore(Resource):
+@json_schema_type
+class VectorDB(Resource):
     """Vector database resource for storing and querying vector embeddings.
 
-    :param type: Type of resource, always 'vector_store' for vector stores
+    :param type: Type of resource, always 'vector_db' for vector databases
     :param embedding_model: Name of the embedding model to use for vector generation
     :param embedding_dimension: Dimension of the embedding vectors
     """
 
-    type: Literal[ResourceType.vector_store] = ResourceType.vector_store
+    type: Literal[ResourceType.vector_db] = ResourceType.vector_db
 
     embedding_model: str
     embedding_dimension: int
-    vector_store_name: str | None = None
+    vector_db_name: str | None = None
 
     @property
-    def vector_store_id(self) -> str:
+    def vector_db_id(self) -> str:
         return self.identifier
 
     @property
-    def provider_vector_store_id(self) -> str | None:
+    def provider_vector_db_id(self) -> str | None:
         return self.provider_resource_id
 
 
-class VectorStoreInput(BaseModel):
+class VectorDBInput(BaseModel):
     """Input parameters for creating or configuring a vector database.
 
-    :param vector_store_id: Unique identifier for the vector store
+    :param vector_db_id: Unique identifier for the vector database
     :param embedding_model: Name of the embedding model to use for vector generation
     :param embedding_dimension: Dimension of the embedding vectors
-    :param provider_vector_store_id: (Optional) Provider-specific identifier for the vector store
+    :param provider_vector_db_id: (Optional) Provider-specific identifier for the vector database
     """
 
-    vector_store_id: str
+    vector_db_id: str
     embedding_model: str
     embedding_dimension: int
     provider_id: str | None = None
-    provider_vector_store_id: str | None = None
+    provider_vector_db_id: str | None = None
+
+
+class ListVectorDBsResponse(BaseModel):
+    """Response from listing vector databases.
+
+    :param data: List of vector databases
+    """
+
+    data: list[VectorDB]

llama_stack/apis/vector_io/vector_io.py

@@ -15,7 +15,7 @@ from fastapi import Body
 from pydantic import BaseModel, Field
 
 from llama_stack.apis.inference import InterleavedContent
-from llama_stack.apis.vector_stores import VectorStore
+from llama_stack.apis.vector_dbs import VectorDB
 from llama_stack.apis.version import LLAMA_STACK_API_V1
 from llama_stack.providers.utils.telemetry.trace_protocol import trace_protocol
 from llama_stack.providers.utils.vector_io.vector_utils import generate_chunk_id
@@ -140,7 +140,6 @@ class VectorStoreFileCounts(BaseModel):
     total: int
 
 
-# TODO: rename this as OpenAIVectorStore
 @json_schema_type
 class VectorStoreObject(BaseModel):
     """OpenAI Vector Store object.
@@ -518,18 +517,17 @@ class OpenAICreateVectorStoreFileBatchRequestWithExtraBody(BaseModel, extra="all
     chunking_strategy: VectorStoreChunkingStrategy | None = None
 
 
-class VectorStoreTable(Protocol):
-    def get_vector_store(self, vector_store_id: str) -> VectorStore | None: ...
+class VectorDBStore(Protocol):
+    def get_vector_db(self, vector_db_id: str) -> VectorDB | None: ...
 
 
 @runtime_checkable
 @trace_protocol
 class VectorIO(Protocol):
-    vector_store_table: VectorStoreTable | None = None
+    vector_db_store: VectorDBStore | None = None
 
     # this will just block now until chunks are inserted, but it should
     # probably return a Job instance which can be polled for completion
-    # TODO: rename vector_db_id to vector_store_id once Stainless is working
     @webmethod(route="/vector-io/insert", method="POST", level=LLAMA_STACK_API_V1)
     async def insert_chunks(
         self,
@@ -548,7 +546,6 @@ class VectorIO(Protocol):
         """
         ...
 
-    # TODO: rename vector_db_id to vector_store_id once Stainless is working
     @webmethod(route="/vector-io/query", method="POST", level=LLAMA_STACK_API_V1)
     async def query_chunks(
         self,

llama_stack/apis/vector_stores/__init__.py

@@ -1,7 +0,0 @@
-# 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 .vector_stores import *

llama_stack/cli/llama.py

@@ -6,8 +6,6 @@
 
 import argparse
 
-from llama_stack.log import setup_logging
-
 from .stack import StackParser
 from .stack.utils import print_subcommand_description
 
@@ -44,9 +42,6 @@ class LlamaCLIParser:
 
 
 def main():
-    # Initialize logging from environment variables before any other operations
-    setup_logging()
-
     parser = LlamaCLIParser()
     args = parser.parse_args()
     parser.run(args)

llama_stack/cli/stack/_build.py

@@ -0,0 +1,490 @@
+# 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 argparse
+import importlib.resources
+import json
+import os
+import shutil
+import sys
+import textwrap
+from functools import lru_cache
+from importlib.abc import Traversable
+from pathlib import Path
+
+import yaml
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.validation import Validator
+from termcolor import colored, cprint
+
+from llama_stack.cli.stack.utils import ImageType
+from llama_stack.cli.table import print_table
+from llama_stack.core.build import (
+    SERVER_DEPENDENCIES,
+    build_image,
+    get_provider_dependencies,
+)
+from llama_stack.core.configure import parse_and_maybe_upgrade_config
+from llama_stack.core.datatypes import (
+    BuildConfig,
+    BuildProvider,
+    DistributionSpec,
+    Provider,
+    StackRunConfig,
+)
+from llama_stack.core.distribution import get_provider_registry
+from llama_stack.core.external import load_external_apis
+from llama_stack.core.resolver import InvalidProviderError
+from llama_stack.core.stack import replace_env_vars
+from llama_stack.core.utils.config_dirs import DISTRIBS_BASE_DIR, EXTERNAL_PROVIDERS_DIR
+from llama_stack.core.utils.dynamic import instantiate_class_type
+from llama_stack.core.utils.exec import formulate_run_args, run_command
+from llama_stack.core.utils.image_types import LlamaStackImageType
+from llama_stack.providers.datatypes import Api
+from llama_stack.providers.utils.sqlstore.sqlstore import SqliteSqlStoreConfig
+
+DISTRIBS_PATH = Path(__file__).parent.parent.parent / "distributions"
+
+
+@lru_cache
+def available_distros_specs() -> dict[str, BuildConfig]:
+    import yaml
+
+    distro_specs = {}
+    for p in DISTRIBS_PATH.rglob("*build.yaml"):
+        distro_name = p.parent.name
+        with open(p) as f:
+            build_config = BuildConfig(**yaml.safe_load(f))
+            distro_specs[distro_name] = build_config
+    return distro_specs
+
+
+def run_stack_build_command(args: argparse.Namespace) -> None:
+    if args.list_distros:
+        return _run_distro_list_cmd()
+
+    if args.image_type == ImageType.VENV.value:
+        current_venv = os.environ.get("VIRTUAL_ENV")
+        image_name = args.image_name or current_venv
+    else:
+        image_name = args.image_name
+
+    if args.template:
+        cprint(
+            "The --template argument is deprecated. Please use --distro instead.",
+            color="red",
+            file=sys.stderr,
+        )
+        distro_name = args.template
+    else:
+        distro_name = args.distribution
+
+    if distro_name:
+        available_distros = available_distros_specs()
+        if distro_name not in available_distros:
+            cprint(
+                f"Could not find distribution {distro_name}. Please run `llama stack build --list-distros` to check out the available distributions",
+                color="red",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        build_config = available_distros[distro_name]
+        if args.image_type:
+            build_config.image_type = args.image_type
+        else:
+            cprint(
+                f"Please specify a image-type ({' | '.join(e.value for e in ImageType)}) for {distro_name}",
+                color="red",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+    elif args.providers:
+        provider_list: dict[str, list[BuildProvider]] = dict()
+        for api_provider in args.providers.split(","):
+            if "=" not in api_provider:
+                cprint(
+                    "Could not parse `--providers`. Please ensure the list is in the format api1=provider1,api2=provider2",
+                    color="red",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            api, provider_type = api_provider.split("=")
+            providers_for_api = get_provider_registry().get(Api(api), None)
+            if providers_for_api is None:
+                cprint(
+                    f"{api} is not a valid API.",
+                    color="red",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            if provider_type in providers_for_api:
+                provider = BuildProvider(
+                    provider_type=provider_type,
+                    module=None,
+                )
+                provider_list.setdefault(api, []).append(provider)
+            else:
+                cprint(
+                    f"{provider} is not a valid provider for the {api} API.",
+                    color="red",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+        distribution_spec = DistributionSpec(
+            providers=provider_list,
+            description=",".join(args.providers),
+        )
+        if not args.image_type:
+            cprint(
+                f"Please specify a image-type (container | venv) for {args.template}",
+                color="red",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        build_config = BuildConfig(image_type=args.image_type, distribution_spec=distribution_spec)
+    elif not args.config and not distro_name:
+        name = prompt(
+            "> Enter a name for your Llama Stack (e.g. my-local-stack): ",
+            validator=Validator.from_callable(
+                lambda x: len(x) > 0,
+                error_message="Name cannot be empty, please enter a name",
+            ),
+        )
+
+        image_type = prompt(
+            "> Enter the image type you want your Llama Stack to be built as (use <TAB> to see options): ",
+            completer=WordCompleter([e.value for e in ImageType]),
+            complete_while_typing=True,
+            validator=Validator.from_callable(
+                lambda x: x in [e.value for e in ImageType],
+                error_message="Invalid image type. Use <TAB> to see options",
+            ),
+        )
+
+        image_name = f"llamastack-{name}"
+
+        cprint(
+            textwrap.dedent(
+                """
+            Llama Stack is composed of several APIs working together. Let's select
+            the provider types (implementations) you want to use for these APIs.
+            """,
+            ),
+            color="green",
+            file=sys.stderr,
+        )
+
+        cprint("Tip: use <TAB> to see options for the providers.\n", color="green", file=sys.stderr)
+
+        providers: dict[str, list[BuildProvider]] = dict()
+        for api, providers_for_api in get_provider_registry().items():
+            available_providers = [x for x in providers_for_api.keys() if x not in ("remote", "remote::sample")]
+            if not available_providers:
+                continue
+            api_provider = prompt(
+                f"> Enter provider for API {api.value}: ",
+                completer=WordCompleter(available_providers),
+                complete_while_typing=True,
+                validator=Validator.from_callable(
+                    lambda x: x in available_providers,  # noqa: B023 - see https://github.com/astral-sh/ruff/issues/7847
+                    error_message="Invalid provider, use <TAB> to see options",
+                ),
+            )
+
+            string_providers = api_provider.split(" ")
+
+            for provider in string_providers:
+                providers.setdefault(api.value, []).append(BuildProvider(provider_type=provider))
+
+        description = prompt(
+            "\n > (Optional) Enter a short description for your Llama Stack: ",
+            default="",
+        )
+
+        distribution_spec = DistributionSpec(
+            providers=providers,
+            description=description,
+        )
+
+        build_config = BuildConfig(image_type=image_type, distribution_spec=distribution_spec)
+    else:
+        with open(args.config) as f:
+            try:
+                contents = yaml.safe_load(f)
+                contents = replace_env_vars(contents)
+                build_config = BuildConfig(**contents)
+                if args.image_type:
+                    build_config.image_type = args.image_type
+            except Exception as e:
+                cprint(
+                    f"Could not parse config file {args.config}: {e}",
+                    color="red",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+    if args.print_deps_only:
+        print(f"# Dependencies for {distro_name or args.config or image_name}")
+        normal_deps, special_deps, external_provider_dependencies = get_provider_dependencies(build_config)
+        normal_deps += SERVER_DEPENDENCIES
+        print(f"uv pip install {' '.join(normal_deps)}")
+        for special_dep in special_deps:
+            print(f"uv pip install {special_dep}")
+        for external_dep in external_provider_dependencies:
+            print(f"uv pip install {external_dep}")
+        return
+
+    try:
+        run_config = _run_stack_build_command_from_build_config(
+            build_config,
+            image_name=image_name,
+            config_path=args.config,
+            distro_name=distro_name,
+        )
+
+    except (Exception, RuntimeError) as exc:
+        import traceback
+
+        cprint(
+            f"Error building stack: {exc}",
+            color="red",
+            file=sys.stderr,
+        )
+        cprint("Stack trace:", color="red", file=sys.stderr)
+        traceback.print_exc()
+        sys.exit(1)
+
+    if run_config is None:
+        cprint(
+            "Run config path is empty",
+            color="red",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.run:
+        config_dict = yaml.safe_load(run_config.read_text())
+        config = parse_and_maybe_upgrade_config(config_dict)
+        if config.external_providers_dir and not config.external_providers_dir.exists():
+            config.external_providers_dir.mkdir(exist_ok=True)
+        run_args = formulate_run_args(args.image_type, image_name or config.image_name)
+        run_args.extend([str(os.getenv("LLAMA_STACK_PORT", 8321)), "--config", str(run_config)])
+        run_command(run_args)
+
+
+def _generate_run_config(
+    build_config: BuildConfig,
+    build_dir: Path,
+    image_name: str,
+) -> Path:
+    """
+    Generate a run.yaml template file for user to edit from a build.yaml file
+    """
+    apis = list(build_config.distribution_spec.providers.keys())
+    run_config = StackRunConfig(
+        container_image=(image_name if build_config.image_type == LlamaStackImageType.CONTAINER.value else None),
+        image_name=image_name,
+        apis=apis,
+        providers={},
+        external_providers_dir=build_config.external_providers_dir
+        if build_config.external_providers_dir
+        else EXTERNAL_PROVIDERS_DIR,
+    )
+    if not run_config.inference_store:
+        run_config.inference_store = SqliteSqlStoreConfig(
+            **SqliteSqlStoreConfig.sample_run_config(
+                __distro_dir__=(DISTRIBS_BASE_DIR / image_name).as_posix(), db_name="inference_store.db"
+            )
+        )
+    # build providers dict
+    provider_registry = get_provider_registry(build_config)
+    for api in apis:
+        run_config.providers[api] = []
+        providers = build_config.distribution_spec.providers[api]
+
+        for provider in providers:
+            pid = provider.provider_type.split("::")[-1]
+
+            p = provider_registry[Api(api)][provider.provider_type]
+            if p.deprecation_error:
+                raise InvalidProviderError(p.deprecation_error)
+
+            try:
+                config_type = instantiate_class_type(provider_registry[Api(api)][provider.provider_type].config_class)
+            except (ModuleNotFoundError, ValueError) as exc:
+                # HACK ALERT:
+                # This code executes after building is done, the import cannot work since the
+                # package is either available in the venv or container - not available on the host.
+                # TODO: use a "is_external" flag in ProviderSpec to check if the provider is
+                # external
+                cprint(
+                    f"Failed to import provider {provider.provider_type} for API {api} - assuming it's external, skipping: {exc}",
+                    color="yellow",
+                    file=sys.stderr,
+                )
+                # Set config_type to None to avoid UnboundLocalError
+                config_type = None
+
+            if config_type is not None and hasattr(config_type, "sample_run_config"):
+                config = config_type.sample_run_config(__distro_dir__=f"~/.llama/distributions/{image_name}")
+            else:
+                config = {}
+
+            p_spec = Provider(
+                provider_id=pid,
+                provider_type=provider.provider_type,
+                config=config,
+                module=provider.module,
+            )
+            run_config.providers[api].append(p_spec)
+
+    run_config_file = build_dir / f"{image_name}-run.yaml"
+
+    with open(run_config_file, "w") as f:
+        to_write = json.loads(run_config.model_dump_json())
+        f.write(yaml.dump(to_write, sort_keys=False))
+
+    # Only print this message for non-container builds since it will be displayed before the
+    # container is built
+    # For non-container builds, the run.yaml is generated at the very end of the build process so it
+    # makes sense to display this message
+    if build_config.image_type != LlamaStackImageType.CONTAINER.value:
+        cprint(f"You can now run your stack with `llama stack run {run_config_file}`", color="green", file=sys.stderr)
+    return run_config_file
+
+
+def _run_stack_build_command_from_build_config(
+    build_config: BuildConfig,
+    image_name: str | None = None,
+    distro_name: str | None = None,
+    config_path: str | None = None,
+) -> Path | Traversable:
+    image_name = image_name or build_config.image_name
+    if build_config.image_type == LlamaStackImageType.CONTAINER.value:
+        if distro_name:
+            image_name = f"distribution-{distro_name}"
+        else:
+            if not image_name:
+                raise ValueError("Please specify an image name when building a container image without a template")
+    else:
+        if not image_name and os.environ.get("UV_SYSTEM_PYTHON"):
+            image_name = "__system__"
+        if not image_name:
+            raise ValueError("Please specify an image name when building a venv image")
+
+    # At this point, image_name should be guaranteed to be a string
+    if image_name is None:
+        raise ValueError("image_name should not be None after validation")
+
+    if distro_name:
+        build_dir = DISTRIBS_BASE_DIR / distro_name
+        build_file_path = build_dir / f"{distro_name}-build.yaml"
+    else:
+        if image_name is None:
+            raise ValueError("image_name cannot be None")
+        build_dir = DISTRIBS_BASE_DIR / image_name
+        build_file_path = build_dir / f"{image_name}-build.yaml"
+
+    os.makedirs(build_dir, exist_ok=True)
+    run_config_file = None
+    # Generate the run.yaml so it can be included in the container image with the proper entrypoint
+    # Only do this if we're building a container image and we're not using a template
+    if build_config.image_type == LlamaStackImageType.CONTAINER.value and not distro_name and config_path:
+        cprint("Generating run.yaml file", color="yellow", file=sys.stderr)
+        run_config_file = _generate_run_config(build_config, build_dir, image_name)
+
+    with open(build_file_path, "w") as f:
+        to_write = json.loads(build_config.model_dump_json(exclude_none=True))
+        f.write(yaml.dump(to_write, sort_keys=False))
+
+    # We first install the external APIs so that the build process can use them and discover the
+    # providers dependencies
+    if build_config.external_apis_dir:
+        cprint("Installing external APIs", color="yellow", file=sys.stderr)
+        external_apis = load_external_apis(build_config)
+        if external_apis:
+            # install the external APIs
+            packages = []
+            for _, api_spec in external_apis.items():
+                if api_spec.pip_packages:
+                    packages.extend(api_spec.pip_packages)
+                    cprint(
+                        f"Installing {api_spec.name} with pip packages {api_spec.pip_packages}",
+                        color="yellow",
+                        file=sys.stderr,
+                    )
+            return_code = run_command(["uv", "pip", "install", *packages])
+            if return_code != 0:
+                packages_str = ", ".join(packages)
+                raise RuntimeError(
+                    f"Failed to install external APIs packages: {packages_str} (return code: {return_code})"
+                )
+
+    return_code = build_image(
+        build_config,
+        image_name,
+        distro_or_config=distro_name or config_path or str(build_file_path),
+        run_config=run_config_file.as_posix() if run_config_file else None,
+    )
+    if return_code != 0:
+        raise RuntimeError(f"Failed to build image {image_name}")
+
+    if distro_name:
+        # copy run.yaml from distribution to build_dir instead of generating it again
+        distro_path = importlib.resources.files("llama_stack") / f"distributions/{distro_name}/run.yaml"
+        run_config_file = build_dir / f"{distro_name}-run.yaml"
+
+        with importlib.resources.as_file(distro_path) as path:
+            shutil.copy(path, run_config_file)
+
+        cprint("Build Successful!", color="green", file=sys.stderr)
+        cprint(f"You can find the newly-built distribution here: {run_config_file}", color="blue", file=sys.stderr)
+        if build_config.image_type == LlamaStackImageType.VENV:
+            cprint(
+                "You can run the new Llama Stack distro (after activating "
+                + colored(image_name, "cyan")
+                + ") via: "
+                + colored(f"llama stack run {run_config_file}", "blue"),
+                color="green",
+                file=sys.stderr,
+            )
+        elif build_config.image_type == LlamaStackImageType.CONTAINER:
+            cprint(
+                "You can run the container with: "
+                + colored(
+                    f"docker run -p 8321:8321 -v ~/.llama:/root/.llama localhost/{image_name} --port 8321", "blue"
+                ),
+                color="green",
+                file=sys.stderr,
+            )
+        return distro_path
+    else:
+        return _generate_run_config(build_config, build_dir, image_name)
+
+
+def _run_distro_list_cmd() -> None:
+    headers = [
+        "Distribution Name",
+        # "Providers",
+        "Description",
+    ]
+
+    rows = []
+    for distro_name, spec in available_distros_specs().items():
+        rows.append(
+            [
+                distro_name,
+                # json.dumps(spec.distribution_spec.providers, indent=2),
+                spec.distribution_spec.description,
+            ]
+        )
+    print_table(
+        rows,
+        headers,
+        separate_rows=True,
+    )

llama_stack/cli/stack/build.py

@@ -0,0 +1,106 @@
+# 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 argparse
+import textwrap
+
+from llama_stack.cli.stack.utils import ImageType
+from llama_stack.cli.subcommand import Subcommand
+from llama_stack.log import get_logger
+
+logger = get_logger(__name__, category="cli")
+
+
+class StackBuild(Subcommand):
+    def __init__(self, subparsers: argparse._SubParsersAction):
+        super().__init__()
+        self.parser = subparsers.add_parser(
+            "build",
+            prog="llama stack build",
+            description="[DEPRECATED] Build a Llama stack container. This command is deprecated and will be removed in a future release. Use `llama stack list-deps <distro>' instead.",
+            formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        )
+        self._add_arguments()
+        self.parser.set_defaults(func=self._run_stack_build_command)
+
+    def _add_arguments(self):
+        self.parser.add_argument(
+            "--config",
+            type=str,
+            default=None,
+            help="Path to a config file to use for the build. You can find example configs in llama_stack.cores/**/build.yaml. If this argument is not provided, you will be prompted to enter information interactively",
+        )
+
+        self.parser.add_argument(
+            "--template",
+            type=str,
+            default=None,
+            help="""(deprecated) Name of the example template config to use for build. You may use `llama stack build --list-distros` to check out the available distributions""",
+        )
+        self.parser.add_argument(
+            "--distro",
+            "--distribution",
+            dest="distribution",
+            type=str,
+            default=None,
+            help="""Name of the distribution to use for build. You may use `llama stack build --list-distros` to check out the available distributions""",
+        )
+
+        self.parser.add_argument(
+            "--list-distros",
+            "--list-distributions",
+            action="store_true",
+            dest="list_distros",
+            default=False,
+            help="Show the available distributions for building a Llama Stack distribution",
+        )
+
+        self.parser.add_argument(
+            "--image-type",
+            type=str,
+            help="Image Type to use for the build. If not specified, will use the image type from the template config.",
+            choices=[e.value for e in ImageType],
+            default=None,  # no default so we can detect if a user specified --image-type and override image_type in the config
+        )
+
+        self.parser.add_argument(
+            "--image-name",
+            type=str,
+            help=textwrap.dedent(
+                f"""[for image-type={"|".join(e.value for e in ImageType)}] Name of the virtual environment to use for
+the build. If not specified, currently active environment will be used if found.
+            """
+            ),
+            default=None,
+        )
+        self.parser.add_argument(
+            "--print-deps-only",
+            default=False,
+            action="store_true",
+            help="Print the dependencies for the stack only, without building the stack",
+        )
+
+        self.parser.add_argument(
+            "--run",
+            action="store_true",
+            default=False,
+            help="Run the stack after building using the same image type, name, and other applicable arguments",
+        )
+        self.parser.add_argument(
+            "--providers",
+            type=str,
+            default=None,
+            help="Build a config for a list of providers and only those providers. This list is formatted like: api1=provider1,api2=provider2. Where there can be multiple providers per API.",
+        )
+
+    def _run_stack_build_command(self, args: argparse.Namespace) -> None:
+        logger.warning(
+            "The 'llama stack build' command is deprecated and will be removed in a future release. Please use 'llama stack list-deps'"
+        )
+        # always keep implementation completely silo-ed away from CLI so CLI
+        # can be fast to load and reduces dependencies
+        from ._build import run_stack_build_command
+
+        return run_stack_build_command(args)

llama_stack/cli/stack/stack.py

@@ -11,6 +11,7 @@ from llama_stack.cli.stack.list_stacks import StackListBuilds
 from llama_stack.cli.stack.utils import print_subcommand_description
 from llama_stack.cli.subcommand import Subcommand
 
+from .build import StackBuild
 from .list_apis import StackListApis
 from .list_deps import StackListDeps
 from .list_providers import StackListProviders
@@ -40,6 +41,7 @@ class StackParser(Subcommand):
 
         # Add sub-commands
         StackListDeps.create(subparsers)
+        StackBuild.create(subparsers)
         StackListApis.create(subparsers)
         StackListProviders.create(subparsers)
         StackRun.create(subparsers)

llama_stack/cli/stack/utils.py

@@ -17,19 +17,10 @@ from llama_stack.core.datatypes import (
     BuildConfig,
     Provider,
     StackRunConfig,
-    StorageConfig,
 )
 from llama_stack.core.distribution import get_provider_registry
 from llama_stack.core.resolver import InvalidProviderError
-from llama_stack.core.storage.datatypes import (
-    InferenceStoreReference,
-    KVStoreReference,
-    ServerStoresConfig,
-    SqliteKVStoreConfig,
-    SqliteSqlStoreConfig,
-    SqlStoreReference,
-)
-from llama_stack.core.utils.config_dirs import DISTRIBS_BASE_DIR, EXTERNAL_PROVIDERS_DIR
+from llama_stack.core.utils.config_dirs import EXTERNAL_PROVIDERS_DIR
 from llama_stack.core.utils.dynamic import instantiate_class_type
 from llama_stack.core.utils.image_types import LlamaStackImageType
 from llama_stack.providers.datatypes import Api
@@ -60,23 +51,11 @@ def generate_run_config(
     Generate a run.yaml template file for user to edit from a build.yaml file
     """
     apis = list(build_config.distribution_spec.providers.keys())
-    distro_dir = DISTRIBS_BASE_DIR / image_name
     run_config = StackRunConfig(
         container_image=(image_name if build_config.image_type == LlamaStackImageType.CONTAINER.value else None),
         image_name=image_name,
         apis=apis,
         providers={},
-        storage=StorageConfig(
-            backends={
-                "kv_default": SqliteKVStoreConfig(db_path=str(distro_dir / "kvstore.db")),
-                "sql_default": SqliteSqlStoreConfig(db_path=str(distro_dir / "sql_store.db")),
-            },
-            stores=ServerStoresConfig(
-                metadata=KVStoreReference(backend="kv_default", namespace="registry"),
-                inference=InferenceStoreReference(backend="sql_default", table_name="inference_store"),
-                conversations=SqlStoreReference(backend="sql_default", table_name="openai_conversations"),
-            ),
-        ),
         external_providers_dir=build_config.external_providers_dir
         if build_config.external_providers_dir
         else EXTERNAL_PROVIDERS_DIR,

llama_stack/core/access_control/datatypes.py

@@ -41,7 +41,7 @@ class AccessRule(BaseModel):
     A rule defines a list of action either to permit or to forbid. It may specify a
     principal or a resource that must match for the rule to take effect. The resource
     to match should be specified in the form of a type qualified identifier, e.g.
-    model::my-model or vector_store::some-db, or a wildcard for all resources of a type,
+    model::my-model or vector_db::some-db, or a wildcard for all resources of a type,
     e.g. model::*. If the principal or resource are not specified, they will match all
     requests.
 
@@ -79,9 +79,9 @@ class AccessRule(BaseModel):
       description: any user has read access to any resource created by a member of their team
     - forbid:
         actions: [create, read, delete]
-        resource: vector_store::*
+        resource: vector_db::*
       unless: user with admin in roles
-      description: only user with admin role can use vector_store resources
+      description: only user with admin role can use vector_db resources
 
     """
 

llama_stack/core/build_container.sh

@@ -0,0 +1,410 @@
+#!/usr/bin/env bash
+
+# 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.
+
+LLAMA_STACK_DIR=${LLAMA_STACK_DIR:-}
+LLAMA_STACK_CLIENT_DIR=${LLAMA_STACK_CLIENT_DIR:-}
+
+TEST_PYPI_VERSION=${TEST_PYPI_VERSION:-}
+PYPI_VERSION=${PYPI_VERSION:-}
+BUILD_PLATFORM=${BUILD_PLATFORM:-}
+# This timeout (in seconds) is necessary when installing PyTorch via uv since it's likely to time out
+# Reference: https://github.com/astral-sh/uv/pull/1694
+UV_HTTP_TIMEOUT=${UV_HTTP_TIMEOUT:-500}
+
+# mounting is not supported by docker buildx, so we use COPY instead
+USE_COPY_NOT_MOUNT=${USE_COPY_NOT_MOUNT:-}
+# Path to the run.yaml file in the container
+RUN_CONFIG_PATH=/app/run.yaml
+
+BUILD_CONTEXT_DIR=$(pwd)
+
+set -euo pipefail
+
+# Define color codes
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Usage function
+usage() {
+  echo "Usage: $0 --image-name <image_name> --container-base <container_base> --normal-deps <pip_dependencies> [--run-config <run_config>] [--external-provider-deps <external_provider_deps>] [--optional-deps <special_pip_deps>]"
+  echo "Example: $0 --image-name llama-stack-img --container-base python:3.12-slim --normal-deps 'numpy pandas' --run-config ./run.yaml --external-provider-deps 'foo' --optional-deps 'bar'"
+  exit 1
+}
+
+# Parse arguments
+image_name=""
+container_base=""
+normal_deps=""
+external_provider_deps=""
+optional_deps=""
+run_config=""
+distro_or_config=""
+
+while [[ $# -gt 0 ]]; do
+  key="$1"
+  case "$key" in
+    --image-name)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --image-name requires a string value" >&2
+        usage
+      fi
+      image_name="$2"
+      shift 2
+      ;;
+    --container-base)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --container-base requires a string value" >&2
+        usage
+      fi
+      container_base="$2"
+      shift 2
+      ;;
+    --normal-deps)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --normal-deps requires a string value" >&2
+        usage
+      fi
+      normal_deps="$2"
+      shift 2
+      ;;
+    --external-provider-deps)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --external-provider-deps requires a string value" >&2
+        usage
+      fi
+      external_provider_deps="$2"
+      shift 2
+      ;;
+    --optional-deps)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --optional-deps requires a string value" >&2
+        usage
+      fi
+      optional_deps="$2"
+      shift 2
+      ;;
+    --run-config)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --run-config requires a string value" >&2
+        usage
+      fi
+      run_config="$2"
+      shift 2
+      ;;
+    --distro-or-config)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --distro-or-config requires a string value" >&2
+        usage
+      fi
+      distro_or_config="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage
+      ;;
+  esac
+done
+
+# Check required arguments
+if [[ -z "$image_name" || -z "$container_base" || -z "$normal_deps" ]]; then
+  echo "Error: --image-name, --container-base, and --normal-deps are required." >&2
+  usage
+fi
+
+CONTAINER_BINARY=${CONTAINER_BINARY:-docker}
+CONTAINER_OPTS=${CONTAINER_OPTS:---progress=plain}
+TEMP_DIR=$(mktemp -d)
+SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
+source "$SCRIPT_DIR/common.sh"
+
+add_to_container() {
+  output_file="$TEMP_DIR/Containerfile"
+  if [ -t 0 ]; then
+    printf '%s\n' "$1" >>"$output_file"
+  else
+    cat >>"$output_file"
+  fi
+}
+
+if ! is_command_available "$CONTAINER_BINARY"; then
+  printf "${RED}Error: ${CONTAINER_BINARY} command not found. Is ${CONTAINER_BINARY} installed and in your PATH?${NC}" >&2
+  exit 1
+fi
+
+if [[ $container_base == *"registry.access.redhat.com/ubi9"* ]]; then
+  add_to_container << EOF
+FROM $container_base
+WORKDIR /app
+
+# We install the Python 3.12 dev headers and build tools so that any
+# C-extension wheels (e.g. polyleven, faiss-cpu) can compile successfully.
+
+RUN dnf -y update && dnf install -y iputils git net-tools wget \
+    vim-minimal python3.12 python3.12-pip python3.12-wheel \
+    python3.12-setuptools python3.12-devel gcc gcc-c++ make && \
+    ln -s /bin/pip3.12 /bin/pip && ln -s /bin/python3.12 /bin/python && dnf clean all
+
+ENV UV_SYSTEM_PYTHON=1
+RUN pip install uv
+EOF
+else
+  add_to_container << EOF
+FROM $container_base
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y \
+       iputils-ping net-tools iproute2 dnsutils telnet \
+       curl wget telnet git\
+       procps psmisc lsof \
+       traceroute \
+       bubblewrap \
+       gcc g++ \
+       && rm -rf /var/lib/apt/lists/*
+
+ENV UV_SYSTEM_PYTHON=1
+RUN pip install uv
+EOF
+fi
+
+# Add pip dependencies first since llama-stack is what will change most often
+# so we can reuse layers.
+if [ -n "$normal_deps" ]; then
+  read -ra pip_args <<<  "$normal_deps"
+  quoted_deps=$(printf " %q" "${pip_args[@]}")
+  add_to_container << EOF
+RUN uv pip install --no-cache $quoted_deps
+EOF
+fi
+
+if [ -n "$optional_deps" ]; then
+  IFS='#' read -ra parts <<<"$optional_deps"
+  for part in "${parts[@]}"; do
+    read -ra pip_args <<< "$part"
+    quoted_deps=$(printf " %q" "${pip_args[@]}")
+    add_to_container <<EOF
+RUN uv pip install --no-cache $quoted_deps
+EOF
+  done
+fi
+
+if [ -n "$external_provider_deps" ]; then
+  IFS='#' read -ra parts <<<"$external_provider_deps"
+  for part in "${parts[@]}"; do
+    read -ra pip_args <<< "$part"
+    quoted_deps=$(printf " %q" "${pip_args[@]}")
+    add_to_container <<EOF
+RUN uv pip install --no-cache $quoted_deps
+EOF
+    add_to_container <<EOF
+RUN python3 - <<PYTHON | uv pip install --no-cache -r -
+import importlib
+import sys
+
+try:
+    package_name = '$part'.split('==')[0].split('>=')[0].split('<=')[0].split('!=')[0].split('<')[0].split('>')[0]
+    module = importlib.import_module(f'{package_name}.provider')
+    spec = module.get_provider_spec()
+    if hasattr(spec, 'pip_packages') and spec.pip_packages:
+        if isinstance(spec.pip_packages, (list, tuple)):
+            print('\n'.join(spec.pip_packages))
+except Exception as e:
+    print(f'Error getting provider spec for {package_name}: {e}', file=sys.stderr)
+PYTHON
+EOF
+  done
+fi
+
+get_python_cmd() {
+    if is_command_available python; then
+        echo "python"
+    elif is_command_available python3; then
+        echo "python3"
+    else
+        echo "Error: Neither python nor python3 is installed. Please install Python to continue." >&2
+        exit 1
+    fi
+}
+
+if [ -n "$run_config" ]; then
+  # Copy the run config to the build context since it's an absolute path
+  cp "$run_config" "$BUILD_CONTEXT_DIR/run.yaml"
+
+  # Parse the run.yaml configuration to identify external provider directories
+  # If external providers are specified, copy their directory to the container
+  # and update the configuration to reference the new container path
+  python_cmd=$(get_python_cmd)
+  external_providers_dir=$($python_cmd -c "import yaml; config = yaml.safe_load(open('$run_config')); print(config.get('external_providers_dir') or '')")
+  external_providers_dir=$(eval echo "$external_providers_dir")
+  if [ -n "$external_providers_dir" ]; then
+    if [ -d "$external_providers_dir" ]; then
+    echo "Copying external providers directory: $external_providers_dir"
+    cp -r "$external_providers_dir" "$BUILD_CONTEXT_DIR/providers.d"
+    add_to_container << EOF
+COPY providers.d /.llama/providers.d
+EOF
+    fi
+
+    # Edit the run.yaml file to change the external_providers_dir to /.llama/providers.d
+    if [ "$(uname)" = "Darwin" ]; then
+      sed -i.bak -e 's|external_providers_dir:.*|external_providers_dir: /.llama/providers.d|' "$BUILD_CONTEXT_DIR/run.yaml"
+      rm -f "$BUILD_CONTEXT_DIR/run.yaml.bak"
+    else
+      sed -i 's|external_providers_dir:.*|external_providers_dir: /.llama/providers.d|' "$BUILD_CONTEXT_DIR/run.yaml"
+    fi
+  fi
+
+  # Copy run config into docker image
+  add_to_container << EOF
+COPY run.yaml $RUN_CONFIG_PATH
+EOF
+fi
+
+stack_mount="/app/llama-stack-source"
+client_mount="/app/llama-stack-client-source"
+
+install_local_package() {
+  local dir="$1"
+  local mount_point="$2"
+  local name="$3"
+
+  if [ ! -d "$dir" ]; then
+    echo "${RED}Warning: $name is set but directory does not exist: $dir${NC}" >&2
+    exit 1
+  fi
+
+  if [ "$USE_COPY_NOT_MOUNT" = "true" ]; then
+    add_to_container << EOF
+COPY $dir $mount_point
+EOF
+  fi
+  add_to_container << EOF
+RUN uv pip install --no-cache -e $mount_point
+EOF
+}
+
+
+if [ -n "$LLAMA_STACK_CLIENT_DIR" ]; then
+  install_local_package "$LLAMA_STACK_CLIENT_DIR" "$client_mount" "LLAMA_STACK_CLIENT_DIR"
+fi
+
+if [ -n "$LLAMA_STACK_DIR" ]; then
+  install_local_package "$LLAMA_STACK_DIR" "$stack_mount" "LLAMA_STACK_DIR"
+else
+  if [ -n "$TEST_PYPI_VERSION" ]; then
+    # these packages are damaged in test-pypi, so install them first
+    add_to_container << EOF
+RUN uv pip install --no-cache fastapi libcst
+EOF
+    add_to_container << EOF
+RUN uv pip install --no-cache --extra-index-url https://test.pypi.org/simple/ \
+  --index-strategy unsafe-best-match \
+  llama-stack==$TEST_PYPI_VERSION
+
+EOF
+  else
+    if [ -n "$PYPI_VERSION" ]; then
+      SPEC_VERSION="llama-stack==${PYPI_VERSION}"
+    else
+      SPEC_VERSION="llama-stack"
+    fi
+    add_to_container << EOF
+RUN uv pip install --no-cache $SPEC_VERSION
+EOF
+  fi
+fi
+
+# remove uv after installation
+  add_to_container << EOF
+RUN pip uninstall -y uv
+EOF
+
+# If a run config is provided, we use the llama stack CLI
+if [[ -n "$run_config" ]]; then
+  add_to_container << EOF
+ENTRYPOINT ["llama", "stack", "run", "$RUN_CONFIG_PATH"]
+EOF
+elif [[ "$distro_or_config" != *.yaml ]]; then
+  add_to_container << EOF
+ENTRYPOINT ["llama", "stack", "run", "$distro_or_config"]
+EOF
+fi
+
+# Add other require item commands genearic to all containers
+add_to_container << EOF
+
+RUN mkdir -p /.llama /.cache && chmod -R g+rw /.llama /.cache && (chmod -R g+rw /app 2>/dev/null || true)
+EOF
+
+printf "Containerfile created successfully in %s/Containerfile\n\n" "$TEMP_DIR"
+cat "$TEMP_DIR"/Containerfile
+printf "\n"
+
+# Start building the CLI arguments
+CLI_ARGS=()
+
+# Read CONTAINER_OPTS and put it in an array
+read -ra CLI_ARGS <<< "$CONTAINER_OPTS"
+
+if [ "$USE_COPY_NOT_MOUNT" != "true" ]; then
+  if [ -n "$LLAMA_STACK_DIR" ]; then
+    CLI_ARGS+=("-v" "$(readlink -f "$LLAMA_STACK_DIR"):$stack_mount")
+  fi
+  if [ -n "$LLAMA_STACK_CLIENT_DIR" ]; then
+    CLI_ARGS+=("-v" "$(readlink -f "$LLAMA_STACK_CLIENT_DIR"):$client_mount")
+  fi
+fi
+
+if is_command_available selinuxenabled && selinuxenabled; then
+  # Disable SELinux labels -- we don't want to relabel the llama-stack source dir
+  CLI_ARGS+=("--security-opt" "label=disable")
+fi
+
+# Set version tag based on PyPI version
+if [ -n "$PYPI_VERSION" ]; then
+  version_tag="$PYPI_VERSION"
+elif [ -n "$TEST_PYPI_VERSION" ]; then
+  version_tag="test-$TEST_PYPI_VERSION"
+elif [[ -n "$LLAMA_STACK_DIR" || -n "$LLAMA_STACK_CLIENT_DIR" ]]; then
+  version_tag="dev"
+else
+  URL="https://pypi.org/pypi/llama-stack/json"
+  version_tag=$(curl -s $URL | jq -r '.info.version')
+fi
+
+# Add version tag to image name
+image_tag="$image_name:$version_tag"
+
+# Detect platform architecture
+ARCH=$(uname -m)
+if [ -n "$BUILD_PLATFORM" ]; then
+  CLI_ARGS+=("--platform" "$BUILD_PLATFORM")
+elif [ "$ARCH" = "arm64" ] || [ "$ARCH" = "aarch64" ]; then
+  CLI_ARGS+=("--platform" "linux/arm64")
+elif [ "$ARCH" = "x86_64" ]; then
+  CLI_ARGS+=("--platform" "linux/amd64")
+else
+  echo "Unsupported architecture: $ARCH"
+  exit 1
+fi
+
+echo "PWD: $(pwd)"
+echo "Containerfile: $TEMP_DIR/Containerfile"
+set -x
+
+$CONTAINER_BINARY build \
+  "${CLI_ARGS[@]}" \
+  -t "$image_tag" \
+  -f "$TEMP_DIR/Containerfile" \
+  "$BUILD_CONTEXT_DIR"
+
+# clean up tmp/configs
+rm -rf "$BUILD_CONTEXT_DIR/run.yaml" "$TEMP_DIR"
+set +x
+
+echo "Success!"

llama_stack/core/build_venv.sh

@@ -0,0 +1,220 @@
+#!/bin/bash
+
+# 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.
+
+LLAMA_STACK_DIR=${LLAMA_STACK_DIR:-}
+LLAMA_STACK_CLIENT_DIR=${LLAMA_STACK_CLIENT_DIR:-}
+TEST_PYPI_VERSION=${TEST_PYPI_VERSION:-}
+# This timeout (in seconds) is necessary when installing PyTorch via uv since it's likely to time out
+# Reference: https://github.com/astral-sh/uv/pull/1694
+UV_HTTP_TIMEOUT=${UV_HTTP_TIMEOUT:-500}
+UV_SYSTEM_PYTHON=${UV_SYSTEM_PYTHON:-}
+VIRTUAL_ENV=${VIRTUAL_ENV:-}
+
+set -euo pipefail
+
+# Define color codes
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
+source "$SCRIPT_DIR/common.sh"
+
+# Usage function
+usage() {
+  echo "Usage: $0 --env-name <env_name> --normal-deps <pip_dependencies> [--external-provider-deps <external_provider_deps>] [--optional-deps <special_pip_deps>]"
+  echo "Example: $0 --env-name mybuild --normal-deps 'numpy pandas scipy' --external-provider-deps 'foo' --optional-deps 'bar'"
+  exit 1
+}
+
+# Parse arguments
+env_name=""
+normal_deps=""
+external_provider_deps=""
+optional_deps=""
+
+while [[ $# -gt 0 ]]; do
+  key="$1"
+  case "$key" in
+    --env-name)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --env-name requires a string value" >&2
+        usage
+      fi
+      env_name="$2"
+      shift 2
+      ;;
+    --normal-deps)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --normal-deps requires a string value" >&2
+        usage
+      fi
+      normal_deps="$2"
+      shift 2
+      ;;
+    --external-provider-deps)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --external-provider-deps requires a string value" >&2
+        usage
+      fi
+      external_provider_deps="$2"
+      shift 2
+      ;;
+    --optional-deps)
+      if [[ -z "$2" || "$2" == --* ]]; then
+        echo "Error: --optional-deps requires a string value" >&2
+        usage
+      fi
+      optional_deps="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage
+      ;;
+  esac
+done
+
+# Check required arguments
+if [[ -z "$env_name" || -z "$normal_deps" ]]; then
+  echo "Error: --env-name and --normal-deps are required." >&2
+  usage
+fi
+
+if [ -n "$LLAMA_STACK_DIR" ]; then
+  echo "Using llama-stack-dir=$LLAMA_STACK_DIR"
+fi
+if [ -n "$LLAMA_STACK_CLIENT_DIR" ]; then
+  echo "Using llama-stack-client-dir=$LLAMA_STACK_CLIENT_DIR"
+fi
+
+ENVNAME=""
+
+# pre-run checks to make sure we can proceed with the installation
+pre_run_checks() {
+  local env_name="$1"
+
+  if ! is_command_available uv; then
+    echo "uv is not installed, trying to install it."
+    if ! is_command_available pip; then
+      echo "pip is not installed, cannot automatically install 'uv'."
+      echo "Follow this link to install it:"
+      echo "https://docs.astral.sh/uv/getting-started/installation/"
+      exit 1
+    else
+      pip install uv
+    fi
+  fi
+
+  # checking if an environment with the same name already exists
+  if [ -d "$env_name" ]; then
+    echo "Environment '$env_name' already exists, re-using it."
+  fi
+}
+
+run() {
+  # Use only global variables set by flag parser
+  if [ -n "$UV_SYSTEM_PYTHON" ] || [ "$env_name" == "__system__" ]; then
+    echo "Installing dependencies in system Python environment"
+    export UV_SYSTEM_PYTHON=1
+  elif [ "$VIRTUAL_ENV" == "$env_name" ]; then
+    echo "Virtual environment $env_name is already active"
+  else
+    echo "Using virtual environment $env_name"
+    uv venv "$env_name"
+    source "$env_name/bin/activate"
+  fi
+
+  if [ -n "$TEST_PYPI_VERSION" ]; then
+    uv pip install fastapi libcst
+    uv pip install --extra-index-url https://test.pypi.org/simple/ \
+      --index-strategy unsafe-best-match \
+      llama-stack=="$TEST_PYPI_VERSION" \
+      $normal_deps
+    if [ -n "$optional_deps" ]; then
+      IFS='#' read -ra parts <<<"$optional_deps"
+      for part in "${parts[@]}"; do
+        echo "$part"
+        uv pip install $part
+      done
+    fi
+    if [ -n "$external_provider_deps" ]; then
+      IFS='#' read -ra parts <<<"$external_provider_deps"
+      for part in "${parts[@]}"; do
+        echo "$part"
+        uv pip install "$part"
+      done
+    fi
+  else
+    if [ -n "$LLAMA_STACK_DIR" ]; then
+      # only warn if DIR does not start with "git+"
+      if [ ! -d "$LLAMA_STACK_DIR" ] && [[ "$LLAMA_STACK_DIR" != git+* ]]; then
+        printf "${RED}Warning: LLAMA_STACK_DIR is set but directory does not exist: %s${NC}\n" "$LLAMA_STACK_DIR" >&2
+        exit 1
+      fi
+      printf "Installing from LLAMA_STACK_DIR: %s\n"  "$LLAMA_STACK_DIR"
+      # editable only if LLAMA_STACK_DIR does not start with "git+"
+      if [[ "$LLAMA_STACK_DIR" != git+* ]]; then
+        EDITABLE="-e"
+      else
+        EDITABLE=""
+      fi
+      uv pip install --no-cache-dir $EDITABLE "$LLAMA_STACK_DIR"
+    else
+      uv pip install --no-cache-dir llama-stack
+    fi
+
+    if [ -n "$LLAMA_STACK_CLIENT_DIR" ]; then
+      # only warn if DIR does not start with "git+"
+      if [ ! -d "$LLAMA_STACK_CLIENT_DIR" ] && [[ "$LLAMA_STACK_CLIENT_DIR" != git+* ]]; then
+        printf "${RED}Warning: LLAMA_STACK_CLIENT_DIR is set but directory does not exist: %s${NC}\n" "$LLAMA_STACK_CLIENT_DIR" >&2
+        exit 1
+      fi
+      printf "Installing from LLAMA_STACK_CLIENT_DIR: %s\n" "$LLAMA_STACK_CLIENT_DIR"
+      # editable only if LLAMA_STACK_CLIENT_DIR does not start with "git+"
+      if [[ "$LLAMA_STACK_CLIENT_DIR" != git+* ]]; then
+        EDITABLE="-e"
+      else
+        EDITABLE=""
+      fi
+      uv pip install --no-cache-dir $EDITABLE "$LLAMA_STACK_CLIENT_DIR"
+    fi
+
+    printf "Installing pip dependencies\n"
+    uv pip install $normal_deps
+    if [ -n "$optional_deps" ]; then
+      IFS='#' read -ra parts <<<"$optional_deps"
+      for part in "${parts[@]}"; do
+        echo "Installing special provider module: $part"
+        uv pip install $part
+      done
+    fi
+    if [ -n "$external_provider_deps" ]; then
+      IFS='#' read -ra parts <<<"$external_provider_deps"
+      for part in "${parts[@]}"; do
+        echo "Installing external provider module: $part"
+        uv pip install "$part"
+        echo "Getting provider spec for module: $part and installing dependencies"
+        package_name=$(echo "$part" | sed 's/[<>=!].*//')
+        python3 -c "
+import importlib
+import sys
+try:
+    module = importlib.import_module(f'$package_name.provider')
+    spec = module.get_provider_spec()
+    if hasattr(spec, 'pip_packages') and spec.pip_packages:
+        print('\\n'.join(spec.pip_packages))
+except Exception as e:
+    print(f'Error getting provider spec for $package_name: {e}', file=sys.stderr)
+" | uv pip install -r -
+      done
+    fi
+  fi
+}
+
+pre_run_checks "$env_name"
+run

llama_stack/core/configure.py

@@ -159,37 +159,6 @@ def upgrade_from_routing_table(
     config_dict["apis"] = config_dict["apis_to_serve"]
     config_dict.pop("apis_to_serve", None)
 
-    # Add default storage config if not present
-    if "storage" not in config_dict:
-        config_dict["storage"] = {
-            "backends": {
-                "kv_default": {
-                    "type": "kv_sqlite",
-                    "db_path": "~/.llama/kvstore.db",
-                },
-                "sql_default": {
-                    "type": "sql_sqlite",
-                    "db_path": "~/.llama/sql_store.db",
-                },
-            },
-            "stores": {
-                "metadata": {
-                    "namespace": "registry",
-                    "backend": "kv_default",
-                },
-                "inference": {
-                    "table_name": "inference_store",
-                    "backend": "sql_default",
-                    "max_write_queue_size": 10000,
-                    "num_writers": 4,
-                },
-                "conversations": {
-                    "table_name": "openai_conversations",
-                    "backend": "sql_default",
-                },
-            },
-        }
-
     return config_dict
 
 

llama_stack/core/conversations/conversations.py

@@ -4,6 +4,7 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
+import os
 import secrets
 import time
 from typing import Any
@@ -20,11 +21,16 @@ from llama_stack.apis.conversations.conversations import (
     Conversations,
     Metadata,
 )
-from llama_stack.core.datatypes import AccessRule, StackRunConfig
+from llama_stack.core.datatypes import AccessRule
+from llama_stack.core.utils.config_dirs import DISTRIBS_BASE_DIR
 from llama_stack.log import get_logger
 from llama_stack.providers.utils.sqlstore.api import ColumnDefinition, ColumnType
 from llama_stack.providers.utils.sqlstore.authorized_sqlstore import AuthorizedSqlStore
-from llama_stack.providers.utils.sqlstore.sqlstore import sqlstore_impl
+from llama_stack.providers.utils.sqlstore.sqlstore import (
+    SqliteSqlStoreConfig,
+    SqlStoreConfig,
+    sqlstore_impl,
+)
 
 logger = get_logger(name=__name__, category="openai_conversations")
 
@@ -32,11 +38,13 @@ logger = get_logger(name=__name__, category="openai_conversations")
 class ConversationServiceConfig(BaseModel):
     """Configuration for the built-in conversation service.
 
-    :param run_config: Stack run configuration for resolving persistence
+    :param conversations_store: SQL store configuration for conversations (defaults to SQLite)
     :param policy: Access control rules
     """
 
-    run_config: StackRunConfig
+    conversations_store: SqlStoreConfig = SqliteSqlStoreConfig(
+        db_path=(DISTRIBS_BASE_DIR / "conversations.db").as_posix()
+    )
     policy: list[AccessRule] = []
 
 
@@ -55,16 +63,14 @@ class ConversationServiceImpl(Conversations):
         self.deps = deps
         self.policy = config.policy
 
-        # Use conversations store reference from run config
-        conversations_ref = config.run_config.storage.stores.conversations
-        if not conversations_ref:
-            raise ValueError("storage.stores.conversations must be configured in run config")
-
-        base_sql_store = sqlstore_impl(conversations_ref)
+        base_sql_store = sqlstore_impl(config.conversations_store)
         self.sql_store = AuthorizedSqlStore(base_sql_store, self.policy)
 
     async def initialize(self) -> None:
         """Initialize the store and create tables."""
+        if isinstance(self.config.conversations_store, SqliteSqlStoreConfig):
+            os.makedirs(os.path.dirname(self.config.conversations_store.db_path), exist_ok=True)
+
         await self.sql_store.create_table(
             "openai_conversations",
             {

llama_stack/core/datatypes.py

@@ -23,15 +23,12 @@ from llama_stack.apis.scoring import Scoring
 from llama_stack.apis.scoring_functions import ScoringFn, ScoringFnInput
 from llama_stack.apis.shields import Shield, ShieldInput
 from llama_stack.apis.tools import ToolGroup, ToolGroupInput, ToolRuntime
+from llama_stack.apis.vector_dbs import VectorDB, VectorDBInput
 from llama_stack.apis.vector_io import VectorIO
-from llama_stack.apis.vector_stores import VectorStore, VectorStoreInput
 from llama_stack.core.access_control.datatypes import AccessRule
-from llama_stack.core.storage.datatypes import (
-    KVStoreReference,
-    StorageBackendType,
-    StorageConfig,
-)
 from llama_stack.providers.datatypes import Api, ProviderSpec
+from llama_stack.providers.utils.kvstore.config import KVStoreConfig, SqliteKVStoreConfig
+from llama_stack.providers.utils.sqlstore.sqlstore import SqlStoreConfig
 
 LLAMA_STACK_BUILD_CONFIG_VERSION = 2
 LLAMA_STACK_RUN_CONFIG_VERSION = 2
@@ -71,7 +68,7 @@ class ShieldWithOwner(Shield, ResourceWithOwner):
     pass
 
 
-class VectorStoreWithOwner(VectorStore, ResourceWithOwner):
+class VectorDBWithOwner(VectorDB, ResourceWithOwner):
     pass
 
 
@@ -91,12 +88,12 @@ class ToolGroupWithOwner(ToolGroup, ResourceWithOwner):
     pass
 
 
-RoutableObject = Model | Shield | VectorStore | Dataset | ScoringFn | Benchmark | ToolGroup
+RoutableObject = Model | Shield | VectorDB | Dataset | ScoringFn | Benchmark | ToolGroup
 
 RoutableObjectWithProvider = Annotated[
     ModelWithOwner
     | ShieldWithOwner
-    | VectorStoreWithOwner
+    | VectorDBWithOwner
     | DatasetWithOwner
     | ScoringFnWithOwner
     | BenchmarkWithOwner
@@ -354,32 +351,12 @@ class AuthenticationRequiredError(Exception):
     pass
 
 
-class QualifiedModel(BaseModel):
-    """A qualified model identifier, consisting of a provider ID and a model ID."""
-
-    provider_id: str
-    model_id: str
-
-
-class VectorStoresConfig(BaseModel):
-    """Configuration for vector stores in the stack."""
-
-    default_provider_id: str | None = Field(
-        default=None,
-        description="ID of the vector_io provider to use as default when multiple providers are available and none is specified.",
-    )
-    default_embedding_model: QualifiedModel | None = Field(
-        default=None,
-        description="Default embedding model configuration for vector stores.",
-    )
-
-
 class QuotaPeriod(StrEnum):
     DAY = "day"
 
 
 class QuotaConfig(BaseModel):
-    kvstore: KVStoreReference = Field(description="Config for KV store backend (SQLite only for now)")
+    kvstore: SqliteKVStoreConfig = Field(description="Config for KV store backend (SQLite only for now)")
     anonymous_max_requests: int = Field(default=100, description="Max requests for unauthenticated clients per period")
     authenticated_max_requests: int = Field(
         default=1000, description="Max requests for authenticated clients per period"
@@ -422,18 +399,6 @@ def process_cors_config(cors_config: bool | CORSConfig | None) -> CORSConfig | N
     raise ValueError(f"Expected bool or CORSConfig, got {type(cors_config).__name__}")
 
 
-class RegisteredResources(BaseModel):
-    """Registry of resources available in the distribution."""
-
-    models: list[ModelInput] = Field(default_factory=list)
-    shields: list[ShieldInput] = Field(default_factory=list)
-    vector_stores: list[VectorStoreInput] = Field(default_factory=list)
-    datasets: list[DatasetInput] = Field(default_factory=list)
-    scoring_fns: list[ScoringFnInput] = Field(default_factory=list)
-    benchmarks: list[BenchmarkInput] = Field(default_factory=list)
-    tool_groups: list[ToolGroupInput] = Field(default_factory=list)
-
-
 class ServerConfig(BaseModel):
     port: int = Field(
         default=8321,
@@ -473,6 +438,18 @@ class ServerConfig(BaseModel):
     )
 
 
+class InferenceStoreConfig(BaseModel):
+    sql_store_config: SqlStoreConfig
+    max_write_queue_size: int = Field(default=10000, description="Max queued writes for inference store")
+    num_writers: int = Field(default=4, description="Number of concurrent background writers")
+
+
+class ResponsesStoreConfig(BaseModel):
+    sql_store_config: SqlStoreConfig
+    max_write_queue_size: int = Field(default=10000, description="Max queued writes for responses store")
+    num_writers: int = Field(default=4, description="Number of concurrent background writers")
+
+
 class StackRunConfig(BaseModel):
     version: int = LLAMA_STACK_RUN_CONFIG_VERSION
 
@@ -499,15 +476,37 @@ One or more providers to use for each API. The same provider_type (e.g., meta-re
 can be instantiated multiple times (with different configs) if necessary.
 """,
     )
-    storage: StorageConfig = Field(
-        description="Catalog of named storage backends and references available to the stack",
+    metadata_store: KVStoreConfig | None = Field(
+        default=None,
+        description="""
+Configuration for the persistence store used by the distribution registry. If not specified,
+a default SQLite store will be used.""",
     )
 
-    registered_resources: RegisteredResources = Field(
-        default_factory=RegisteredResources,
-        description="Registry of resources available in the distribution",
+    inference_store: InferenceStoreConfig | SqlStoreConfig | None = Field(
+        default=None,
+        description="""
+Configuration for the persistence store used by the inference API. Can be either a
+InferenceStoreConfig (with queue tuning parameters) or a SqlStoreConfig (deprecated).
+If not specified, a default SQLite store will be used.""",
     )
 
+    conversations_store: SqlStoreConfig | None = Field(
+        default=None,
+        description="""
+Configuration for the persistence store used by the conversations API.
+If not specified, a default SQLite store will be used.""",
+    )
+
+    # registry of "resources" in the distribution
+    models: list[ModelInput] = Field(default_factory=list)
+    shields: list[ShieldInput] = Field(default_factory=list)
+    vector_dbs: list[VectorDBInput] = Field(default_factory=list)
+    datasets: list[DatasetInput] = Field(default_factory=list)
+    scoring_fns: list[ScoringFnInput] = Field(default_factory=list)
+    benchmarks: list[BenchmarkInput] = Field(default_factory=list)
+    tool_groups: list[ToolGroupInput] = Field(default_factory=list)
+
     logging: LoggingConfig | None = Field(default=None, description="Configuration for Llama Stack Logging")
 
     telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig, description="Configuration for telemetry")
@@ -527,11 +526,6 @@ can be instantiated multiple times (with different configs) if necessary.
         description="Path to directory containing external API implementations. The APIs code and dependencies must be installed on the system.",
     )
 
-    vector_stores: VectorStoresConfig | None = Field(
-        default=None,
-        description="Configuration for vector stores, including default embedding model",
-    )
-
     @field_validator("external_providers_dir")
     @classmethod
     def validate_external_providers_dir(cls, v):
@@ -541,49 +535,6 @@ can be instantiated multiple times (with different configs) if necessary.
             return Path(v)
         return v
 
-    @model_validator(mode="after")
-    def validate_server_stores(self) -> "StackRunConfig":
-        backend_map = self.storage.backends
-        stores = self.storage.stores
-        kv_backends = {
-            name
-            for name, cfg in backend_map.items()
-            if cfg.type
-            in {
-                StorageBackendType.KV_REDIS,
-                StorageBackendType.KV_SQLITE,
-                StorageBackendType.KV_POSTGRES,
-                StorageBackendType.KV_MONGODB,
-            }
-        }
-        sql_backends = {
-            name
-            for name, cfg in backend_map.items()
-            if cfg.type in {StorageBackendType.SQL_SQLITE, StorageBackendType.SQL_POSTGRES}
-        }
-
-        def _ensure_backend(reference, expected_set, store_name: str) -> None:
-            if reference is None:
-                return
-            backend_name = reference.backend
-            if backend_name not in backend_map:
-                raise ValueError(
-                    f"{store_name} references unknown backend '{backend_name}'. "
-                    f"Available backends: {sorted(backend_map)}"
-                )
-            if backend_name not in expected_set:
-                raise ValueError(
-                    f"{store_name} references backend '{backend_name}' of type "
-                    f"'{backend_map[backend_name].type.value}', but a backend of type "
-                    f"{'kv_*' if expected_set is kv_backends else 'sql_*'} is required."
-                )
-
-        _ensure_backend(stores.metadata, kv_backends, "storage.stores.metadata")
-        _ensure_backend(stores.inference, sql_backends, "storage.stores.inference")
-        _ensure_backend(stores.conversations, sql_backends, "storage.stores.conversations")
-        _ensure_backend(stores.responses, sql_backends, "storage.stores.responses")
-        return self
-
 
 class BuildConfig(BaseModel):
     version: int = LLAMA_STACK_BUILD_CONFIG_VERSION

llama_stack/core/distribution.py

@@ -63,10 +63,6 @@ def builtin_automatically_routed_apis() -> list[AutoRoutedApiInfo]:
             routing_table_api=Api.tool_groups,
             router_api=Api.tool_runtime,
         ),
-        AutoRoutedApiInfo(
-            routing_table_api=Api.vector_stores,
-            router_api=Api.vector_io,
-        ),
     ]