docs: Refine and fix nits in README

kelbrown20 · kelbrown20 · commit 5599749f33b4 · 2025-11-24T09:53:02.000-05:00
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ curl -LsSf https://github.com/llamastack/llama-stack/raw/main/scripts/install.sh
 
 ### Overview
 
-Llama Stack standardizes the core building blocks that simplify AI application development. It codifies best practices across the Llama ecosystem. More specifically, it provides
+Llama Stack defines and standardizes the core building blocks that simplify AI application development. It provides a unified set of APIs with implementations from leading service providers. More specifically, it provides:
 
 - **Unified API layer** for Inference, RAG, Agents, Tools, Safety, Evals.
 - **Plugin architecture** to support the rich ecosystem of different API implementations in various environments, including local development, on-premises, cloud, and mobile.
@@ -37,18 +37,19 @@ Llama Stack standardizes the core building blocks that simplify AI application d
   />
 </div>
 
-### Llama Stack Benefits
-- **Flexible Options**: Developers can choose their preferred infrastructure without changing APIs and enjoy flexible deployment choices.
+#### Llama Stack Benefits
+
+- **Flexibility**: Developers can choose their preferred infrastructure without changing APIs and enjoy flexible deployment choices.
 - **Consistent Experience**: With its unified APIs, Llama Stack makes it easier to build, test, and deploy AI applications with consistent application behavior.
-- **Robust Ecosystem**: Llama Stack is already integrated with distribution partners (cloud providers, hardware vendors, and AI-focused companies) that offer tailored infrastructure, software, and services for deploying Llama models.
+- **Robust Ecosystem**: Llama Stack is integrated with distribution partners (cloud providers, hardware vendors, and AI-focused companies) that offer tailored infrastructure, software, and services for deploying Llama models.
 
-By reducing friction and complexity, Llama Stack empowers developers to focus on what they do best: building transformative generative AI applications.
+For more information, see the [Benefits of Llama Stack](https://llamastack.github.io/docs/v0.3.2/concepts/architecture#benefits-of-llama-stack) documentation.
 
 ### API Providers
 Here is a list of the various API providers and available distributions that can help developers get started easily with Llama Stack.
 Please checkout for [full list](https://llamastack.github.io/docs/providers)
 
-| API Provider Builder | Environments | Agents | Inference | VectorIO | Safety | Post Training | Eval | DatasetIO |
+|    API Provider      | Environments | Agents | Inference | VectorIO | Safety | Post Training | Eval | DatasetIO |
 |:--------------------:|:------------:|:------:|:---------:|:--------:|:------:|:-------------:|:----:|:--------:|
 |    Meta Reference    | Single Node | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 |      SambaNova       | Hosted | | ✅ | | ✅ | | | |
@@ -81,14 +82,17 @@ Please checkout for [full list](https://llamastack.github.io/docs/providers)
 
 ### Distributions
 
-A Llama Stack Distribution (or "distro") is a pre-configured bundle of provider implementations for each API component. Distributions make it easy to get started with a specific deployment scenario - you can begin with a local development setup (eg. ollama) and seamlessly transition to production (eg. Fireworks) without changing your application code.
+A Llama Stack Distribution (or "distro") is a pre-configured bundle of provider implementations for each API component. Distributions make it easy to get started with a specific deployment scenario. For example, you can begin with a local setup of Ollama and seamlessly transition to production, with fireworks, without changing your application code.
 Here are some of the distributions we support:
 
 |               **Distribution**                |                                                                    **Llama Stack Docker**                                                                     |                                                 Start This Distribution                                                  |
 |:---------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------:|
-|                Starter Distribution                 |           [llamastack/distribution-starter](https://hub.docker.com/repository/docker/llamastack/distribution-starter/general)           |      [Guide](https://llamastack.github.io/latest/distributions/self_hosted_distro/starter.html)      |
-|                Meta Reference                 |           [llamastack/distribution-meta-reference-gpu](https://hub.docker.com/repository/docker/llamastack/distribution-meta-reference-gpu/general)           |      [Guide](https://llamastack.github.io/latest/distributions/self_hosted_distro/meta-reference-gpu.html)      |
-|                   PostgreSQL                  |                [llamastack/distribution-postgres-demo](https://hub.docker.com/repository/docker/llamastack/distribution-postgres-demo/general)                |                  |
+|                Starter Distribution           |           [llamastack/distribution-starter](https://hub.docker.com/repository/docker/llamastack/distribution-starter/general)                                 |      [Guide](https://llamastack.github.io/latest/distributions/self_hosted_distro/starter.html)                          |
+|                Meta Reference                 |           [llamastack/distribution-meta-reference-gpu](https://hub.docker.com/repository/docker/llamastack/distribution-meta-reference-gpu/general)           |      [Guide](https://llamastack.github.io/latest/distributions/self_hosted_distro/meta-reference-gpu.html)               |
+|                   PostgreSQL                  |            [llamastack/distribution-postgres-demo](https://hub.docker.com/repository/docker/llamastack/distribution-postgres-demo/general)                    |                                                                                                                          |
+|                iOS/Android SDK                |                                                                                                 <add>                                                         |
+
+For full documentation on the Llama Stack distributions see the [Distributions Overview](https://llamastack.github.io/docs/latest/distributions) page.
 
 ### Documentation
 
@@ -107,18 +111,17 @@ Please checkout our [Documentation](https://llamastack.github.io/latest/index.ht
 
 ### Llama Stack Client SDKs
 
+Check out our client SDKs for connecting to a Llama Stack server in your preferred language.
+
 |  **Language** |  **Client SDK** | **Package** |
 | :----: | :----: | :----: |
 | Python |  [llama-stack-client-python](https://github.com/meta-llama/llama-stack-client-python) | [![PyPI version](https://img.shields.io/pypi/v/llama_stack_client.svg)](https://pypi.org/project/llama_stack_client/)
 | Swift  | [llama-stack-client-swift](https://github.com/meta-llama/llama-stack-client-swift) | [![Swift Package Index](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fmeta-llama%2Fllama-stack-client-swift%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/meta-llama/llama-stack-client-swift)
 | Typescript   | [llama-stack-client-typescript](https://github.com/meta-llama/llama-stack-client-typescript) | [![NPM version](https://img.shields.io/npm/v/llama-stack-client.svg)](https://npmjs.org/package/llama-stack-client)
 | Kotlin | [llama-stack-client-kotlin](https://github.com/meta-llama/llama-stack-client-kotlin) | [![Maven version](https://img.shields.io/maven-central/v/com.llama.llamastack/llama-stack-client-kotlin)](https://central.sonatype.com/artifact/com.llama.llamastack/llama-stack-client-kotlin)
 
-Check out our client SDKs for connecting to a Llama Stack server in your preferred language, you can choose from [python](https://github.com/meta-llama/llama-stack-client-python), [typescript](https://github.com/meta-llama/llama-stack-client-typescript), [swift](https://github.com/meta-llama/llama-stack-client-swift), and [kotlin](https://github.com/meta-llama/llama-stack-client-kotlin) programming languages to quickly build your applications.
-
 You can find more example scripts with client SDKs to talk with the Llama Stack server in our [llama-stack-apps](https://github.com/meta-llama/llama-stack-apps/tree/main/examples) repo.
 
-
 ## 🌟 GitHub Star History
 ## Star History
 
diff --git a/docs/docs/providers/agents/index.mdx b/docs/docs/providers/agents/index.mdx
@@ -2,7 +2,7 @@
 description: |
   Agents
 
-      APIs for creating and interacting with agentic systems.
+     APIs for creating and interacting with agentic systems.
 sidebar_label: Agents
 title: Agents
 ---
@@ -13,6 +13,6 @@ title: Agents
 
 Agents
 
-    APIs for creating and interacting with agentic systems.
+   APIs for creating and interacting with agentic systems.
 
 This section contains documentation for all available providers for the **agents** API.
diff --git a/docs/docs/providers/batches/index.mdx b/docs/docs/providers/batches/index.mdx
@@ -1,15 +1,15 @@
 ---
 description: |
   The Batches API enables efficient processing of multiple requests in a single operation,
-      particularly useful for processing large datasets, batch evaluation workflows, and
-      cost-effective inference at scale.
+  particularly useful for processing large datasets, batch evaluation workflows, and
+  cost-effective inference at scale.
 
-      The API is designed to allow use of openai client libraries for seamless integration.
+  The API is designed to allow use of openai client libraries for seamless integration.
 
-      This API provides the following extensions:
-       - idempotent batch creation
+  This API provides the following extensions:
+   - idempotent batch creation
 
-      Note: This API is currently under active development and may undergo changes.
+  Note: This API is currently under active development and may undergo changes.
 sidebar_label: Batches
 title: Batches
 ---
@@ -19,14 +19,14 @@ title: Batches
 ## Overview
 
 The Batches API enables efficient processing of multiple requests in a single operation,
-    particularly useful for processing large datasets, batch evaluation workflows, and
-    cost-effective inference at scale.
+particularly useful for processing large datasets, batch evaluation workflows, and
+cost-effective inference at scale.
 
-    The API is designed to allow use of openai client libraries for seamless integration.
+The API is designed to allow use of openai client libraries for seamless integration.
 
-    This API provides the following extensions:
-     - idempotent batch creation
+This API provides the following extensions:
+ - idempotent batch creation
 
-    Note: This API is currently under active development and may undergo changes.
+Note: This API is currently under active development and may undergo changes.
 
 This section contains documentation for all available providers for the **batches** API.
diff --git a/docs/docs/providers/eval/index.mdx b/docs/docs/providers/eval/index.mdx
@@ -2,7 +2,7 @@
 description: |
   Evaluations
 
-      Llama Stack Evaluation API for running evaluations on model and agent candidates.
+  Llama Stack Evaluation API for running evaluations on model and agent candidates.
 sidebar_label: Eval
 title: Eval
 ---
@@ -13,6 +13,6 @@ title: Eval
 
 Evaluations
 
-    Llama Stack Evaluation API for running evaluations on model and agent candidates.
+Llama Stack Evaluation API for running evaluations on model and agent candidates.
 
 This section contains documentation for all available providers for the **eval** API.
diff --git a/docs/docs/providers/files/index.mdx b/docs/docs/providers/files/index.mdx
@@ -2,7 +2,7 @@
 description: |
   Files
 
-      This API is used to upload documents that can be used with other Llama Stack APIs.
+  This API is used to upload documents that can be used with other Llama Stack APIs.
 sidebar_label: Files
 title: Files
 ---
@@ -13,6 +13,6 @@ title: Files
 
 Files
 
-    This API is used to upload documents that can be used with other Llama Stack APIs.
+This API is used to upload documents that can be used with other Llama Stack APIs.
 
 This section contains documentation for all available providers for the **files** API.
diff --git a/docs/docs/providers/inference/index.mdx b/docs/docs/providers/inference/index.mdx
@@ -2,12 +2,12 @@
 description: |
   Inference
 
-      Llama Stack Inference API for generating completions, chat completions, and embeddings.
+  Llama Stack Inference API for generating completions, chat completions, and embeddings.
 
-      This API provides the raw interface to the underlying models. Three kinds of models are supported:
-      - LLM models: these models generate "raw" and "chat" (conversational) completions.
-      - Embedding models: these models generate embeddings to be used for semantic search.
-      - Rerank models: these models reorder the documents based on their relevance to a query.
+  This API provides the raw interface to the underlying models. Three kinds of models are supported:
+  - LLM models: these models generate "raw" and "chat" (conversational) completions.
+  - Embedding models: these models generate embeddings to be used for semantic search.
+  - Rerank models: these models reorder the documents based on their relevance to a query.
 sidebar_label: Inference
 title: Inference
 ---
@@ -18,11 +18,11 @@ title: Inference
 
 Inference
 
-    Llama Stack Inference API for generating completions, chat completions, and embeddings.
+Llama Stack Inference API for generating completions, chat completions, and embeddings.
 
-    This API provides the raw interface to the underlying models. Three kinds of models are supported:
-    - LLM models: these models generate "raw" and "chat" (conversational) completions.
-    - Embedding models: these models generate embeddings to be used for semantic search.
-    - Rerank models: these models reorder the documents based on their relevance to a query.
+This API provides the raw interface to the underlying models. Three kinds of models are supported:
+- LLM models: these models generate "raw" and "chat" (conversational) completions.
+- Embedding models: these models generate embeddings to be used for semantic search.
+- Rerank models: these models reorder the documents based on their relevance to a query.
 
 This section contains documentation for all available providers for the **inference** API.
diff --git a/docs/docs/providers/safety/index.mdx b/docs/docs/providers/safety/index.mdx
@@ -2,7 +2,7 @@
 description: |
   Safety
 
-      OpenAI-compatible Moderations API.
+  OpenAI-compatible Moderations API.
 sidebar_label: Safety
 title: Safety
 ---
@@ -13,6 +13,6 @@ title: Safety
 
 Safety
 
-    OpenAI-compatible Moderations API.
+OpenAI-compatible Moderations API.
 
 This section contains documentation for all available providers for the **safety** API.
