refactor: enforce top-level imports for llama-stack-api

Enforce that all imports from llama-stack-api use the form:

from llama_stack_api import <symbol>

 This prevents external code from accessing internal package structure
 (e.g., llama_stack_api.agents, llama_stack_api.common.*) and establishes
 a clear public API boundary.

 Changes:
 - Export 400+ symbols from llama_stack_api/__init__.py
 - Include all API types, common utilities, and strong_typing helpers
 - Update files across src/llama_stack, docs/, tests/, scripts/
 - Convert all submodule imports to top-level imports
 - ensure docs use the proper importing structure

 Addresses PR review feedback requiring explicit __all__ definition to
 prevent "peeking inside" the API package.

Signed-off-by: Charlie Doern <cdoern@redhat.com>

src/llama_stack/core/build.py

@@ -6,7 +6,7 @@
 
 import sys
 
-from llama_stack_api.datatypes import Api
+from llama_stack_api import Api
 from pydantic import BaseModel
 from termcolor import cprint
 

src/llama_stack/core/client.py

@@ -12,7 +12,7 @@ from enum import Enum
 from typing import Any, Union, get_args, get_origin
 
 import httpx
-from llama_stack_api.datatypes import RemoteProviderConfig
+from llama_stack_api import RemoteProviderConfig
 from pydantic import BaseModel, parse_obj_as
 from termcolor import cprint
 

src/llama_stack/core/configure.py

@@ -6,7 +6,7 @@
 import textwrap
 from typing import Any
 
-from llama_stack_api.datatypes import Api, ProviderSpec
+from llama_stack_api import Api, ProviderSpec
 
 from llama_stack.core.datatypes import (
     LLAMA_STACK_RUN_CONFIG_VERSION,

src/llama_stack/core/conversations/conversations.py

@@ -8,7 +8,7 @@ import secrets
 import time
 from typing import Any, Literal
 
-from llama_stack_api.conversations import (
+from llama_stack_api import (
     Conversation,
     ConversationDeletedResource,
     ConversationItem,

src/llama_stack/core/datatypes.py

@@ -9,21 +9,32 @@ from pathlib import Path
 from typing import Annotated, Any, Literal, Self
 from urllib.parse import urlparse
 
-from llama_stack_api.benchmarks import Benchmark, BenchmarkInput
-from llama_stack_api.datasetio import DatasetIO
-from llama_stack_api.datasets import Dataset, DatasetInput
-from llama_stack_api.datatypes import Api, ProviderSpec
-from llama_stack_api.eval import Eval
-from llama_stack_api.inference import Inference
-from llama_stack_api.models import Model, ModelInput
-from llama_stack_api.resource import Resource
-from llama_stack_api.safety import Safety
-from llama_stack_api.scoring import Scoring
-from llama_stack_api.scoring_functions import ScoringFn, ScoringFnInput
-from llama_stack_api.shields import Shield, ShieldInput
-from llama_stack_api.tools import ToolGroup, ToolGroupInput, ToolRuntime
-from llama_stack_api.vector_io import VectorIO
-from llama_stack_api.vector_stores import VectorStore, VectorStoreInput
+from llama_stack_api import (
+    Api,
+    Benchmark,
+    BenchmarkInput,
+    Dataset,
+    DatasetInput,
+    DatasetIO,
+    Eval,
+    Inference,
+    Model,
+    ModelInput,
+    ProviderSpec,
+    Resource,
+    Safety,
+    Scoring,
+    ScoringFn,
+    ScoringFnInput,
+    Shield,
+    ShieldInput,
+    ToolGroup,
+    ToolGroupInput,
+    ToolRuntime,
+    VectorIO,
+    VectorStore,
+    VectorStoreInput,
+)
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 from llama_stack.core.access_control.datatypes import AccessRule

src/llama_stack/core/distribution.py

@@ -10,7 +10,7 @@ import os
 from typing import Any
 
 import yaml
-from llama_stack_api.datatypes import (
+from llama_stack_api import (
     Api,
     InlineProviderSpec,
     ProviderSpec,

src/llama_stack/core/external.py

@@ -6,7 +6,7 @@
 
 
 import yaml
-from llama_stack_api.datatypes import Api, ExternalApiSpec
+from llama_stack_api import Api, ExternalApiSpec
 
 from llama_stack.core.datatypes import BuildConfig, StackRunConfig
 from llama_stack.log import get_logger

src/llama_stack/core/inspect.py

@@ -6,9 +6,9 @@
 
 from importlib.metadata import version
 
-from llama_stack_api.datatypes import HealthStatus
-from llama_stack_api.inspect import (
+from llama_stack_api import (
     HealthInfo,
+    HealthStatus,
     Inspect,
     ListRoutesResponse,
     RouteInfo,

src/llama_stack/core/library_client.py

@@ -18,7 +18,7 @@ from typing import Any, TypeVar, Union, get_args, get_origin
 import httpx
 import yaml
 from fastapi import Response as FastAPIResponse
-from llama_stack_api.strong_typing.inspection import is_unwrapped_body_param
+from llama_stack_api import is_unwrapped_body_param
 
 try:
     from llama_stack_client import (

src/llama_stack/core/prompts/prompts.py

@@ -7,7 +7,7 @@
 import json
 from typing import Any
 
-from llama_stack_api.prompts import ListPromptsResponse, Prompt, Prompts
+from llama_stack_api import ListPromptsResponse, Prompt, Prompts
 from pydantic import BaseModel
 
 from llama_stack.core.datatypes import StackRunConfig

src/llama_stack/core/providers.py

@@ -7,8 +7,7 @@
 import asyncio
 from typing import Any
 
-from llama_stack_api.datatypes import HealthResponse, HealthStatus
-from llama_stack_api.providers import ListProvidersResponse, ProviderInfo, Providers
+from llama_stack_api import HealthResponse, HealthStatus, ListProvidersResponse, ProviderInfo, Providers
 from pydantic import BaseModel
 
 from llama_stack.log import get_logger

src/llama_stack/core/resolver.py

@@ -8,41 +8,45 @@ import importlib.metadata
 import inspect
 from typing import Any
 
-from llama_stack_api.agents import Agents
-from llama_stack_api.batches import Batches
-from llama_stack_api.benchmarks import Benchmarks
-from llama_stack_api.conversations import Conversations
-from llama_stack_api.datasetio import DatasetIO
-from llama_stack_api.datasets import Datasets
-from llama_stack_api.datatypes import (
+from llama_stack_api import (
+    LLAMA_STACK_API_V1ALPHA,
+    Agents,
     Api,
+    Batches,
+    Benchmarks,
     BenchmarksProtocolPrivate,
+    Conversations,
+    DatasetIO,
+    Datasets,
     DatasetsProtocolPrivate,
+    Eval,
     ExternalApiSpec,
+    Files,
+    Inference,
+    InferenceProvider,
+    Inspect,
+    Models,
     ModelsProtocolPrivate,
+    PostTraining,
+    Prompts,
     ProviderSpec,
     RemoteProviderConfig,
     RemoteProviderSpec,
+    Safety,
+    Scoring,
+    ScoringFunctions,
     ScoringFunctionsProtocolPrivate,
+    Shields,
     ShieldsProtocolPrivate,
+    ToolGroups,
     ToolGroupsProtocolPrivate,
+    ToolRuntime,
+    VectorIO,
+    VectorStore,
+)
+from llama_stack_api import (
+    Providers as ProvidersAPI,
 )
-from llama_stack_api.eval import Eval
-from llama_stack_api.files import Files
-from llama_stack_api.inference import Inference, InferenceProvider
-from llama_stack_api.inspect import Inspect
-from llama_stack_api.models import Models
-from llama_stack_api.post_training import PostTraining
-from llama_stack_api.prompts import Prompts
-from llama_stack_api.providers import Providers as ProvidersAPI
-from llama_stack_api.safety import Safety
-from llama_stack_api.scoring import Scoring
-from llama_stack_api.scoring_functions import ScoringFunctions
-from llama_stack_api.shields import Shields
-from llama_stack_api.tools import ToolGroups, ToolRuntime
-from llama_stack_api.vector_io import VectorIO
-from llama_stack_api.vector_stores import VectorStore
-from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
 
 from llama_stack.core.client import get_client_impl
 from llama_stack.core.datatypes import (

src/llama_stack/core/routers/__init__.py

@@ -6,7 +6,7 @@
 
 from typing import Any
 
-from llama_stack_api.datatypes import Api, RoutingTable
+from llama_stack_api import Api, RoutingTable
 
 from llama_stack.core.datatypes import (
     AccessRule,

src/llama_stack/core/routers/datasets.py

@@ -6,10 +6,7 @@
 
 from typing import Any
 
-from llama_stack_api.common.responses import PaginatedResponse
-from llama_stack_api.datasetio import DatasetIO
-from llama_stack_api.datasets import DatasetPurpose, DataSource
-from llama_stack_api.datatypes import RoutingTable
+from llama_stack_api import DatasetIO, DatasetPurpose, DataSource, PaginatedResponse, RoutingTable
 
 from llama_stack.log import get_logger
 

src/llama_stack/core/routers/eval_scoring.py

@@ -6,9 +6,12 @@
 
 from typing import Any
 
-from llama_stack_api.datatypes import RoutingTable
-from llama_stack_api.eval import BenchmarkConfig, Eval, EvaluateResponse, Job
-from llama_stack_api.scoring import (
+from llama_stack_api import (
+    BenchmarkConfig,
+    Eval,
+    EvaluateResponse,
+    Job,
+    RoutingTable,
     ScoreBatchResponse,
     ScoreResponse,
     Scoring,

src/llama_stack/core/routers/inference.py

@@ -11,11 +11,14 @@ from datetime import UTC, datetime
 from typing import Annotated, Any
 
 from fastapi import Body
-from llama_stack_api.common.errors import ModelNotFoundError, ModelTypeError
-from llama_stack_api.datatypes import HealthResponse, HealthStatus, RoutingTable
-from llama_stack_api.inference import (
+from llama_stack_api import (
+    HealthResponse,
+    HealthStatus,
     Inference,
     ListOpenAIChatCompletionResponse,
+    ModelNotFoundError,
+    ModelType,
+    ModelTypeError,
     OpenAIAssistantMessageParam,
     OpenAIChatCompletion,
     OpenAIChatCompletionChunk,
@@ -34,8 +37,8 @@ from llama_stack_api.inference import (
     OpenAIMessageParam,
     Order,
     RerankResponse,
+    RoutingTable,
 )
-from llama_stack_api.models import ModelType
 from openai.types.chat import ChatCompletionToolChoiceOptionParam as OpenAIChatCompletionToolChoiceOptionParam
 from openai.types.chat import ChatCompletionToolParam as OpenAIChatCompletionToolParam
 from pydantic import TypeAdapter

src/llama_stack/core/routers/safety.py

@@ -6,10 +6,7 @@
 
 from typing import Any
 
-from llama_stack_api.datatypes import RoutingTable
-from llama_stack_api.inference import OpenAIMessageParam
-from llama_stack_api.safety import ModerationObject, RunShieldResponse, Safety
-from llama_stack_api.shields import Shield
+from llama_stack_api import ModerationObject, OpenAIMessageParam, RoutingTable, RunShieldResponse, Safety, Shield
 
 from llama_stack.core.datatypes import SafetyConfig
 from llama_stack.log import get_logger

src/llama_stack/core/routers/tool_runtime.py

@@ -6,10 +6,8 @@
 
 from typing import Any
 
-from llama_stack_api.common.content_types import (
+from llama_stack_api import (
     URL,
-)
-from llama_stack_api.tools import (
     ListToolDefsResponse,
     ToolRuntime,
 )

src/llama_stack/core/routers/vector_io.py

@@ -9,14 +9,16 @@ import uuid
 from typing import Annotated, Any
 
 from fastapi import Body
-from llama_stack_api.common.content_types import InterleavedContent
-from llama_stack_api.datatypes import HealthResponse, HealthStatus, RoutingTable
-from llama_stack_api.models import ModelType
-from llama_stack_api.vector_io import (
+from llama_stack_api import (
     Chunk,
+    HealthResponse,
+    HealthStatus,
+    InterleavedContent,
+    ModelType,
     OpenAICreateVectorStoreFileBatchRequestWithExtraBody,
     OpenAICreateVectorStoreRequestWithExtraBody,
     QueryChunksResponse,
+    RoutingTable,
     SearchRankingOptions,
     VectorIO,
     VectorStoreChunkingStrategy,

src/llama_stack/core/routing_tables/benchmarks.py

@@ -6,7 +6,7 @@
 
 from typing import Any
 
-from llama_stack_api.benchmarks import Benchmark, Benchmarks, ListBenchmarksResponse
+from llama_stack_api import Benchmark, Benchmarks, ListBenchmarksResponse
 
 from llama_stack.core.datatypes import (
     BenchmarkWithOwner,

src/llama_stack/core/routing_tables/common.py

@@ -6,10 +6,7 @@
 
 from typing import Any
 
-from llama_stack_api.common.errors import ModelNotFoundError
-from llama_stack_api.datatypes import Api, RoutingTable
-from llama_stack_api.models import Model
-from llama_stack_api.resource import ResourceType
+from llama_stack_api import Api, Model, ModelNotFoundError, ResourceType, RoutingTable
 
 from llama_stack.core.access_control.access_control import AccessDeniedError, is_action_allowed
 from llama_stack.core.access_control.datatypes import Action

src/llama_stack/core/routing_tables/datasets.py

@@ -7,18 +7,18 @@
 import uuid
 from typing import Any
 
-from llama_stack_api.common.errors import DatasetNotFoundError
-from llama_stack_api.datasets import (
+from llama_stack_api import (
     Dataset,
+    DatasetNotFoundError,
     DatasetPurpose,
     Datasets,
     DatasetType,
     DataSource,
     ListDatasetsResponse,
+    ResourceType,
     RowsDataSource,
     URIDataSource,
 )
-from llama_stack_api.resource import ResourceType
 
 from llama_stack.core.datatypes import (
     DatasetWithOwner,

src/llama_stack/core/routing_tables/models.py

@@ -7,10 +7,10 @@
 import time
 from typing import Any
 
-from llama_stack_api.common.errors import ModelNotFoundError
-from llama_stack_api.models import (
+from llama_stack_api import (
     ListModelsResponse,
     Model,
+    ModelNotFoundError,
     Models,
     ModelType,
     OpenAIListModelsResponse,

src/llama_stack/core/routing_tables/scoring_functions.py

@@ -4,10 +4,10 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
-from llama_stack_api.common.type_system import ParamType
-from llama_stack_api.resource import ResourceType
-from llama_stack_api.scoring_functions import (
+from llama_stack_api import (
     ListScoringFunctionsResponse,
+    ParamType,
+    ResourceType,
     ScoringFn,
     ScoringFnParams,
     ScoringFunctions,

src/llama_stack/core/routing_tables/shields.py

@@ -6,8 +6,7 @@
 
 from typing import Any
 
-from llama_stack_api.resource import ResourceType
-from llama_stack_api.shields import ListShieldsResponse, Shield, Shields
+from llama_stack_api import ListShieldsResponse, ResourceType, Shield, Shields
 
 from llama_stack.core.datatypes import (
     ShieldWithOwner,

src/llama_stack/core/routing_tables/toolgroups.py

@@ -6,9 +6,15 @@
 
 from typing import Any
 
-from llama_stack_api.common.content_types import URL
-from llama_stack_api.common.errors import ToolGroupNotFoundError
-from llama_stack_api.tools import ListToolDefsResponse, ListToolGroupsResponse, ToolDef, ToolGroup, ToolGroups
+from llama_stack_api import (
+    URL,
+    ListToolDefsResponse,
+    ListToolGroupsResponse,
+    ToolDef,
+    ToolGroup,
+    ToolGroupNotFoundError,
+    ToolGroups,
+)
 
 from llama_stack.core.datatypes import AuthenticationRequiredError, ToolGroupWithOwner
 from llama_stack.log import get_logger

src/llama_stack/core/routing_tables/vector_stores.py

@@ -6,12 +6,12 @@
 
 from typing import Any
 
-from llama_stack_api.common.errors import ModelNotFoundError, ModelTypeError
-from llama_stack_api.models import ModelType
-from llama_stack_api.resource import ResourceType
-
 # Removed VectorStores import to avoid exposing public API
-from llama_stack_api.vector_io import (
+from llama_stack_api import (
+    ModelNotFoundError,
+    ModelType,
+    ModelTypeError,
+    ResourceType,
     SearchRankingOptions,
     VectorStoreChunkingStrategy,
     VectorStoreDeleteResponse,

src/llama_stack/core/server/auth_providers.py

@@ -11,7 +11,7 @@ from urllib.parse import parse_qs, urljoin, urlparse
 
 import httpx
 import jwt
-from llama_stack_api.common.errors import TokenValidationError
+from llama_stack_api import TokenValidationError
 from pydantic import BaseModel, Field
 
 from llama_stack.core.datatypes import (

src/llama_stack/core/server/routes.py

@@ -10,8 +10,7 @@ from collections.abc import Callable
 from typing import Any
 
 from aiohttp import hdrs
-from llama_stack_api.datatypes import Api, ExternalApiSpec
-from llama_stack_api.schema_utils import WebMethod
+from llama_stack_api import Api, ExternalApiSpec, WebMethod
 from starlette.routing import Route
 
 from llama_stack.core.resolver import api_protocol_map

src/llama_stack/core/server/server.py

@@ -28,9 +28,7 @@ from fastapi import Path as FastapiPath
 from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse, StreamingResponse
-from llama_stack_api.common.errors import ConflictError, ResourceNotFoundError
-from llama_stack_api.common.responses import PaginatedResponse
-from llama_stack_api.datatypes import Api
+from llama_stack_api import Api, ConflictError, PaginatedResponse, ResourceNotFoundError
 from openai import BadRequestError
 from pydantic import BaseModel, ValidationError
 

src/llama_stack/core/stack.py

@@ -12,27 +12,30 @@ import tempfile
 from typing import Any
 
 import yaml
-from llama_stack_api.agents import Agents
-from llama_stack_api.batches import Batches
-from llama_stack_api.benchmarks import Benchmarks
-from llama_stack_api.conversations import Conversations
-from llama_stack_api.datasetio import DatasetIO
-from llama_stack_api.datasets import Datasets
-from llama_stack_api.datatypes import Api
-from llama_stack_api.eval import Eval
-from llama_stack_api.files import Files
-from llama_stack_api.inference import Inference
-from llama_stack_api.inspect import Inspect
-from llama_stack_api.models import Models
-from llama_stack_api.post_training import PostTraining
-from llama_stack_api.prompts import Prompts
-from llama_stack_api.providers import Providers
-from llama_stack_api.safety import Safety
-from llama_stack_api.scoring import Scoring
-from llama_stack_api.scoring_functions import ScoringFunctions
-from llama_stack_api.shields import Shields
-from llama_stack_api.tools import ToolGroups, ToolRuntime
-from llama_stack_api.vector_io import VectorIO
+from llama_stack_api import (
+    Agents,
+    Api,
+    Batches,
+    Benchmarks,
+    Conversations,
+    DatasetIO,
+    Datasets,
+    Eval,
+    Files,
+    Inference,
+    Inspect,
+    Models,
+    PostTraining,
+    Prompts,
+    Providers,
+    Safety,
+    Scoring,
+    ScoringFunctions,
+    Shields,
+    ToolGroups,
+    ToolRuntime,
+    VectorIO,
+)
 
 from llama_stack.core.conversations.conversations import ConversationServiceConfig, ConversationServiceImpl
 from llama_stack.core.datatypes import Provider, SafetyConfig, StackRunConfig, VectorStoresConfig

src/llama_stack/core/telemetry/telemetry.py

@@ -16,7 +16,7 @@ from typing import (
     cast,
 )
 
-from llama_stack_api.schema_utils import json_schema_type, register_schema
+from llama_stack_api import json_schema_type, register_schema
 from opentelemetry import metrics, trace
 from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter