feat: split API and provider specs into separate llama-stack-api pkg

Extract API definitions, models, and provider specifications into a
standalone llama-stack-api package that can be published to PyPI
independently of the main llama-stack server.

Motivation

External providers currently import from llama-stack, which overrides
the installed version and causes dependency conflicts. This separation
allows external providers to:

- Install only the type definitions they need without server dependencies
- Avoid version conflicts with the installed llama-stack package
- Be versioned and released independently

This enables us to re-enable external provider module tests that were
previously blocked by these import conflicts.

Changes

- Created llama-stack-api package with minimal dependencies (pydantic, jsonschema)
- Moved APIs, models, providers datatypes, strong_typing, and schema_utils
- Updated all imports from llama_stack.* to llama_stack_api.*
- Preserved git history using git mv for moved files
- Configured local editable install for development workflow
- Updated linting and type-checking configuration for both packages
- Rebased on top of upstream src/ layout changes

Testing

Package builds successfully and can be imported independently.
All pre-commit hooks pass with expected exclusions maintained.

Next Steps

- Publish llama-stack-api to PyPI
- Update external provider dependencies
- Re-enable external provider module tests

Signed-off-by: Charlie Doern <[email protected]>

Author: cdoern

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

@@ -30,13 +30,16 @@ jobs:
         activate-environment: true
         version: 0.7.6
 
+    - name: Build Llama Stack Spec package
+      working-directory: src/llama-stack-api
+      run: uv build
+
     - name: Build Llama Stack package
-      run: |
-        uv build
+      run: uv build
 
-    - name: Install Llama Stack package
+    - name: Install Llama Stack package (with spec from local build)
       run: |
-        uv pip install dist/*.whl
+        uv pip install --find-links src/llama-stack-api/dist dist/*.whl
 
     - name: Verify Llama Stack package
       run: |

.pre-commit-config.yaml

@@ -42,7 +42,7 @@ repos:
     hooks:
     -   id: ruff
         args: [ --fix ]
-        exclude: ^src/llama_stack/strong_typing/.*$
+        exclude: ^(src/llama_stack/strong_typing/.*|src/llama-stack-api/llama_stack_api/strong_typing/.*)$
     -   id: ruff-format
 
 -   repo: https://github.com/adamchainz/blacken-docs

docs/docs/api-overview.md

@@ -8,7 +8,7 @@ The Llama Stack provides a comprehensive set of APIs organized by stability leve
 
 These APIs are fully tested, documented, and stable. They follow semantic versioning principles and maintain backward compatibility within major versions. Recommended for production applications.
 
-[**Browse Stable APIs →**](./api/llama-stack-specification)
+[**Browse Stable APIs →**](./api/llama-stack-apiification)
 
 **Key Features:**
 - ✅ Backward compatibility guaranteed
@@ -24,7 +24,7 @@ These APIs are fully tested, documented, and stable. They follow semantic versio
 
 These APIs include v1alpha and v1beta endpoints that are feature-complete but may undergo changes based on feedback. Great for exploring new capabilities and providing feedback.
 
-[**Browse Experimental APIs →**](./api-experimental/llama-stack-specification-experimental-apis)
+[**Browse Experimental APIs →**](./api-experimental/llama-stack-apiification-experimental-apis)
 
 **Key Features:**
 - 🧪 Latest features and capabilities
@@ -40,7 +40,7 @@ These APIs include v1alpha and v1beta endpoints that are feature-complete but ma
 
 These APIs are deprecated and will be removed in future versions. They are provided for migration purposes and to help transition to newer, stable alternatives.
 
-[**Browse Deprecated APIs →**](./api-deprecated/llama-stack-specification-deprecated-apis)
+[**Browse Deprecated APIs →**](./api-deprecated/llama-stack-apiification-deprecated-apis)
 
 **Key Features:**
 - ⚠️ Will be removed in future versions

docs/docs/building_applications/index.mdx

@@ -80,4 +80,4 @@ Build production-ready systems with:
 - **[Getting Started](/docs/getting_started/quickstart)** - Basic setup and concepts
 - **[Providers](/docs/providers/)** - Available AI service providers
 - **[Distributions](/docs/distributions/)** - Pre-configured deployment packages
-- **[API Reference](/docs/api/llama-stack-specification)** - Complete API documentation
+- **[API Reference](/docs/api/llama-stack-apiification)** - Complete API documentation

docs/docs/building_applications/playground.mdx

@@ -295,4 +295,4 @@ llama stack run meta-reference
 - **[Agents](./agent)** - Building intelligent agents
 - **[RAG (Retrieval Augmented Generation)](./rag)** - Knowledge-enhanced applications
 - **[Evaluations](./evals)** - Comprehensive evaluation framework
-- **[API Reference](/docs/api/llama-stack-specification)** - Complete API documentation
+- **[API Reference](/docs/api/llama-stack-apiification)** - Complete API documentation

docs/docs/concepts/apis/external.mdx

@@ -58,7 +58,7 @@ External APIs must expose a `available_providers()` function in their module tha
 
 ```python
 # llama_stack_api_weather/api.py
-from llama_stack.providers.datatypes import Api, InlineProviderSpec, ProviderSpec
+from llama_stack_api.providers.datatypes import Api, InlineProviderSpec, ProviderSpec
 
 
 def available_providers() -> list[ProviderSpec]:
@@ -79,7 +79,7 @@ A Protocol class like so:
 # llama_stack_api_weather/api.py
 from typing import Protocol
 
-from llama_stack.schema_utils import webmethod
+from llama_stack_api.schema_utils import webmethod
 
 
 class WeatherAPI(Protocol):
@@ -151,12 +151,12 @@ __all__ = ["WeatherAPI", "available_providers"]
 # llama-stack-api-weather/src/llama_stack_api_weather/weather.py
 from typing import Protocol
 
-from llama_stack.providers.datatypes import (
+from llama_stack_api.providers.datatypes import (
     Api,
     ProviderSpec,
     RemoteProviderSpec,
 )
-from llama_stack.schema_utils import webmethod
+from llama_stack_api.schema_utils import webmethod
 
 
 def available_providers() -> list[ProviderSpec]:

docs/docs/distributions/building_distro.mdx

@@ -65,7 +65,7 @@ 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
+from llama_stack_api.providers.datatypes import ProviderSpec
 
 
 def get_provider_spec() -> ProviderSpec:

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

@@ -80,7 +80,7 @@ container_image: custom-vector-store:latest  # optional
 All providers must contain a `get_provider_spec` function in their `provider` module. This is a standardized structure that Llama Stack expects and is necessary for getting things such as the config class. The `get_provider_spec` method returns a structure identical to the `adapter`. An example function may look like:
 
 ```python
-from llama_stack.providers.datatypes import (
+from llama_stack_api.providers.datatypes import (
     ProviderSpec,
     Api,
     RemoteProviderSpec,

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

@@ -153,7 +153,7 @@ description: |
   Example using RAGQueryConfig with different search modes:
 
   ```python
-  from llama_stack.apis.tools import RAGQueryConfig, RRFRanker, WeightedRanker
+  from llama_stack_api.apis.tools import RAGQueryConfig, RRFRanker, WeightedRanker
 
   # Vector search
   config = RAGQueryConfig(mode="vector", max_chunks=5)
@@ -358,7 +358,7 @@ Two ranker types are supported:
 Example using RAGQueryConfig with different search modes:
 
 ```python
-from llama_stack.apis.tools import RAGQueryConfig, RRFRanker, WeightedRanker
+from llama_stack_api.apis.tools import RAGQueryConfig, RRFRanker, WeightedRanker
 
 # Vector search
 config = RAGQueryConfig(mode="vector", max_chunks=5)

docs/openapi_generator/generate.py

@@ -16,7 +16,7 @@
 import fire
 import ruamel.yaml as yaml
 
-from llama_stack.apis.version import LLAMA_STACK_API_V1 # noqa: E402
+from llama_stack_api.apis.version import LLAMA_STACK_API_V1 # noqa: E402
 from llama_stack.core.stack import LlamaStack  # noqa: E402
 
 from .pyopenapi.options import Options  # noqa: E402