squirrels 0.1.0__py3-none-any.whl → 0.6.0.post0__py3-none-any.whl

squirrels/_py_module.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Type, Optional, Any, Iterator
+import importlib.util
+from contextlib import contextmanager
+from pathlib import Path
+import sys
+
+from . import _constants as c, _utils as u
+from ._exceptions import ConfigurationError, FileExecutionError
+
+
+@contextmanager
+def _temporary_sys_path(path: str) -> Iterator[None]:
+    """
+    Temporarily prepend `path` to sys.path for the duration of the context.
+    """
+    resolved = str(Path(path).resolve())
+    prior = list(sys.path)
+    try:
+        if resolved in sys.path:
+            # Ensure it is first, so imports resolve to this project before anything else.
+            sys.path.remove(resolved)
+        sys.path.insert(0, resolved)
+        yield
+    finally:
+        sys.path[:] = prior
+
+
+@contextmanager
+def _temporary_sys_modules(prefixes: tuple[str, ...]) -> Iterator[None]:
+    """
+    Temporarily isolate sys.modules entries for certain prefixes.
+
+    This prevents cross-project pollution when multiple SquirrelsProject instances
+    in the same process import identically named packages (e.g. "pyconfigs").
+    """
+    def _matches(name: str) -> bool:
+        return any(name == p or name.startswith(p + ".") for p in prefixes)
+
+    saved: dict[str, Any] = {k: v for k, v in sys.modules.items() if _matches(k)}
+    try:
+        # Remove matching modules so imports during this block re-resolve.
+        for k in list(sys.modules.keys()):
+            if _matches(k):
+                sys.modules.pop(k, None)
+        yield
+    finally:
+        # Remove any modules added during this block for the prefixes.
+        for k in list(sys.modules.keys()):
+            if _matches(k):
+                sys.modules.pop(k, None)
+        # Restore prior state.
+        sys.modules.update(saved)
+
+
+class PyModule:
+    def __init__(
+        self,
+        filepath: u.FilePath,
+        project_path: str,
+        *,
+        default_class: Optional[Type] = None,
+        is_required: bool = False,
+    ) -> None:
+        """
+        Constructor for PyModule, an abstract module for a file that may or may not exist
+        
+        Arguments:
+            filepath (str | pathlib.Path): The file path to the python module
+            project_path: The root folder of the Squirrels project. If provided, it is temporarily
+                added to sys.path while executing the module so imports like `from pyconfigs import user`
+                can work without globally mutating sys.path.
+            is_required: If true, throw an error if the file path doesn't exist
+        """
+        self.filepath = str(filepath)
+        try:
+            with _temporary_sys_path(project_path), _temporary_sys_modules((c.PYCONFIGS_FOLDER, c.PACKAGES_FOLDER)):
+                spec = importlib.util.spec_from_file_location(self.filepath, self.filepath)
+                assert spec is not None and spec.loader is not None
+                self.module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(self.module)
+        except FileNotFoundError as e:
+            if is_required:
+                raise ConfigurationError(f"Required file not found: '{self.filepath}'") from e
+            self.module = default_class
+    
+    def get_func_or_class(self, attr_name: str, *, default_attr: Any = None, is_required: bool = True) -> Any:
+        """
+        Get an attribute of the module. Usually a python function or class.
+
+        Arguments:
+            attr_name: The attribute name
+            default_attr: The default function or class to use if the attribute cannot be found
+            is_required: If true, throw an error if the attribute cannot be found, unless default_attr is not None
+        
+        Returns:
+            The attribute of the module
+        """
+        func_or_class = getattr(self.module, attr_name, default_attr)
+        if func_or_class is None and is_required:
+            raise ConfigurationError(f"Module '{self.filepath}' missing required attribute '{attr_name}'")
+        return func_or_class
+
+
+def run_pyconfig_main(project_path: str, filename: str, kwargs: dict[str, Any] = {}) -> Any | None:
+    """
+    Given a python file in the 'pyconfigs' folder, run its main function
+    
+    Arguments:
+        project_path: The base path of the project
+        filename: The name of the file to run main function
+        kwargs: Dictionary of the main function arguments
+    """
+    filepath = u.Path(project_path, c.PYCONFIGS_FOLDER, filename)
+    module = PyModule(filepath, project_path)
+    main_function = module.get_func_or_class(c.MAIN_FUNC, is_required=False)
+    if main_function:
+        try:
+            return main_function(**kwargs)
+        except Exception as e:
+            raise FileExecutionError(f'Failed to run python file "{filepath}"', e) from e

squirrels/_request_context.py

@@ -0,0 +1,33 @@
+"""
+Request context management using ContextVars for request-scoped data.
+Provides thread-safe and async-safe access to request IDs throughout the request lifecycle.
+"""
+from contextvars import ContextVar
+import uuid
+import base64
+
+# ContextVar for storing the current request ID
+_request_id: ContextVar[str | None] = ContextVar("request_id", default=None)
+
+
+def get_request_id() -> str | None:
+    """
+    Get the current request ID from the context.
+    
+    Returns:
+        The request ID string if available, None otherwise (e.g., in background tasks).
+    """
+    return _request_id.get()
+
+
+def set_request_id() -> str:
+    """
+    Set a new request ID in the context.
+    Uses base64 URL-safe encoding of UUID bytes to create a shorter ID (22 chars vs 36).
+    
+    Returns:
+        The request ID that was set.
+    """
+    request_id = base64.urlsafe_b64encode(uuid.uuid4().bytes).decode().rstrip('=')
+    _request_id.set(request_id)
+    return request_id

squirrels/_schemas/auth_models.py

@@ -0,0 +1,83 @@
+from typing import Callable, Any, Literal
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+class CustomUserFields(BaseModel):
+    """
+    Extend this class to add custom user fields.
+    - Only the following types are supported: [str, int, float, bool, typing.Literal]
+    - Add "| None" after the type to make it nullable. 
+    - Always set a default value for the column (use None if default is null).
+    """
+    model_config = ConfigDict(extra='allow')
+
+
+class AbstractUser(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    username: str
+    access_level: Literal["admin", "member", "guest"]
+    custom_fields: CustomUserFields
+    
+    def __hash__(self):
+        return hash(self.username)
+    
+    def __str__(self):
+        return self.username
+
+
+class GuestUser(AbstractUser):
+    access_level: Literal["guest"] = "guest"
+
+
+class RegisteredUser(AbstractUser):
+    access_level: Literal["admin", "member"] = "member"
+
+
+class ApiKey(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: str
+    last_four: str
+    title: str
+    username: str
+    created_at: datetime
+    expires_at: datetime
+    
+    @field_serializer('created_at', 'expires_at')
+    def serialize_datetime(self, dt: datetime) -> str:
+        return dt.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+class UserField(BaseModel):
+    name: str = Field(description="The name of the field")
+    label: str = Field(description="The human-friendly display name for the field")
+    type: str = Field(description="The type of the field")
+    nullable: bool = Field(description="Whether the field is nullable")
+    enum: list[str] | None = Field(description="The possible values of the field (or None if not applicable)")
+    default: Any | None = Field(description="The default value of the field (or None if field is required)")
+
+
+class UserFieldsModel(BaseModel):
+    username: UserField = Field(description="The username field metadata")
+    access_level: UserField = Field(description="The access level field metadata")
+    custom_fields: list[UserField] = Field(description="The list of custom user fields metadata for the current Squirrels project")
+
+
+class ProviderConfigs(BaseModel):
+    client_id: str
+    client_secret: str
+    server_url: str
+    server_metadata_path: str = Field(default="/.well-known/oauth-authorization-server")
+    client_kwargs: dict = Field(default_factory=dict)
+    get_user: Callable[[dict], RegisteredUser]
+
+    @property
+    def server_metadata_url(self) -> str:
+        return f"{self.server_url}{self.server_metadata_path}"
+
+
+class AuthProvider(BaseModel):
+    name: str = Field(description="The name of the provider")
+    label: str = Field(description="The human-friendly display name for the provider")
+    icon: str = Field(description="The URL of the provider's icon. Can also start with '/public/' to indicate a file in the '/resources/public/' directory.")
+    provider_configs: ProviderConfigs

squirrels/_schemas/query_param_models.py

@@ -0,0 +1,70 @@
+"""
+Query model generation utilities for API routes
+"""
+from typing import Annotated
+from dataclasses import make_dataclass
+from fastapi import Depends
+from pydantic import create_model
+
+from .._parameter_configs import APIParamFieldInfo
+
+
+def _get_query_models_helper(
+    predefined_params: list[APIParamFieldInfo], param_fields: dict[str, APIParamFieldInfo], scoped_parameters: list[str] | None = None
+):
+    """Helper function to generate query models"""
+    if scoped_parameters is None:
+        scoped_parameters = list(param_fields.keys())
+    
+    QueryModelForGetRaw = make_dataclass("QueryParams", [
+        param_fields[param].as_query_info() for param in scoped_parameters
+    ] + [param.as_query_info() for param in predefined_params])
+    QueryModelForGet = Annotated[QueryModelForGetRaw, Depends()]
+
+    field_definitions = {param: param_fields[param].as_body_info() for param in scoped_parameters}
+    for param in predefined_params:
+        field_definitions[param.name] = param.as_body_info()
+    QueryModelForPost = create_model("RequestBodyParams", **field_definitions) # type: ignore
+    return QueryModelForGet, QueryModelForPost
+
+
+def get_query_models_for_parameters(param_fields: dict[str, APIParamFieldInfo], scoped_parameters: list[str] | None = None):
+    """Generate query models for parameter endpoints"""
+    predefined_params = [
+        APIParamFieldInfo("x_parent_param", str, description="The parent parameter name used for parameter updates. If no query parameter name matches the parent parameter, then an empty list is used (which is a valid selection for multi-select parameters)"),
+    ]
+    return _get_query_models_helper(predefined_params, param_fields, scoped_parameters)
+
+
+def get_query_models_for_dataset(param_fields: dict[str, APIParamFieldInfo], scoped_parameters: list[str] | None = None):
+    """Generate query models for dataset endpoints"""
+    predefined_params = [
+        APIParamFieldInfo("x_sql_query", str, description="Optional Polars SQL to transform the final dataset. Use table name 'result' to reference the dataset."),
+        APIParamFieldInfo("x_orientation", str, default="records", description="Controls the orientation of the result data. Options: 'records' (default), 'rows', 'columns'"),
+        APIParamFieldInfo("x_offset", int, default=0, description="The number of rows to skip before returning data (applied after data caching)"),
+        APIParamFieldInfo("x_limit", int, default=1000, description="The maximum number of rows to return (applied after data caching and offset)"),
+    ]
+    return _get_query_models_helper(predefined_params, param_fields, scoped_parameters)
+
+
+def get_query_models_for_dashboard(param_fields: dict[str, APIParamFieldInfo], scoped_parameters: list[str] | None = None):
+    """Generate query models for dashboard endpoints"""
+    predefined_params = []
+    return _get_query_models_helper(predefined_params, param_fields, scoped_parameters)
+
+
+def get_query_models_for_querying_models(param_fields: dict[str, APIParamFieldInfo]):
+    """Generate query models for querying data models"""
+    predefined_params = [
+        APIParamFieldInfo("x_sql_query", str, description="The SQL query to execute on the data models"),
+        APIParamFieldInfo("x_orientation", str, default="records", description="Controls the orientation of the result data. Options: 'records' (default), 'rows', 'columns'"),
+        APIParamFieldInfo("x_offset", int, default=0, description="The number of rows to skip before returning data (applied after data caching)"),
+        APIParamFieldInfo("x_limit", int, default=1000, description="The maximum number of rows to return (applied after data caching and offset)"),
+    ]
+    return _get_query_models_helper(predefined_params, param_fields) 
+
+
+def get_query_models_for_compiled_models(param_fields: dict[str, APIParamFieldInfo]):
+    """Generate query models for fetching compiled model SQL"""
+    predefined_params = []
+    return _get_query_models_helper(predefined_params, param_fields)

squirrels/_schemas/request_models.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field, field_validator
+
+
+class McpRequestHeaders(BaseModel):
+    raw_headers: dict[str, str] = Field(default_factory=dict, description="The raw HTTP headers")
+
+    @field_validator("raw_headers")
+    @classmethod
+    def lowercase_keys(cls, v: dict[str, str]) -> dict[str, str]:
+        return {key.lower(): val for key, val in v.items()}
+
+    @property
+    def bearer_token(self) -> str | None:
+        auth_header = self.raw_headers.get("authorization", "")
+        if auth_header.lower().startswith("bearer "):
+            return auth_header[7:].strip()
+        return None
+
+    @property
+    def api_key(self) -> str | None:
+        return self.raw_headers.get("x-api-key")
+
+    @property
+    def feature_flags(self) -> set[str]:
+        feature_flags_str = self.raw_headers.get("x-feature-flags", "")
+        return set(x.strip() for x in feature_flags_str.split(",") if x.strip())

squirrels/_schemas/response_models.py

@@ -0,0 +1,286 @@
+from typing import Annotated, Literal, Any
+from textwrap import dedent
+from pydantic import BaseModel, Field
+from datetime import date
+
+from .. import _model_configs as mc, _sources as s, _constants as c
+
+
+## Simple Auth Response Models
+
+class ApiKeyResponse(BaseModel):
+    api_key: Annotated[str, Field(examples=["sqrl-12345678"], description="The API key to use subsequent API requests")]
+
+class ProviderResponse(BaseModel):
+    name: Annotated[str, Field(examples=["my_provider"], description="The name of the provider")]
+    label: Annotated[str, Field(examples=["My Provider"], description="The human-friendly display name for the provider")]
+    icon: Annotated[str, Field(examples=["https://example.com/my_provider_icon.png"], description="The URL of the provider's icon. If the path starts with '/public/', it is assumed to be a static file in the project's 'resources/public/' directory.")]
+    login_url: Annotated[str, Field(examples=["https://example.com/my_provider_login"], description="The URL to redirect to for provider login")]
+
+
+## Parameters Response Models
+
+class ParameterOptionModel(BaseModel):
+    id: Annotated[str, Field(description="The unique identifier for the option")]
+    label: Annotated[str, Field(description="The human-friendly display name for the option")]
+
+class ParameterModelBase(BaseModel):
+    widget_type: Annotated[str, Field(description="The parameter type")]
+    name: Annotated[str, Field(description="The name of the parameter. Use this as the key when providing the API request parameters")]
+    label: Annotated[str, Field(description="The human-friendly display name for the parameter")]
+    description: Annotated[str, Field(description="The description of the parameter")]
+
+class NoneParameterModel(ParameterModelBase):
+    pass
+
+class SelectParameterModel(ParameterModelBase):
+    options: Annotated[list[ParameterOptionModel], Field(description="The list of dropdown options as JSON objects containing 'id' and 'label' fields")]
+    trigger_refresh: Annotated[bool, Field(description="A boolean that's set to true for parent parameters that require a new parameters API call when the selection changes")]
+
+class SingleSelectParameterModel(SelectParameterModel):
+    widget_type: Annotated[Literal["single_select"], Field(description="The parameter type")]
+    selected_id: Annotated[str | None, Field(description="The ID of the selected / default option")]
+
+class MultiSelectParameterModel(SelectParameterModel):
+    widget_type: Annotated[Literal["multi_select"], Field(description="The parameter type")]
+    show_select_all: Annotated[bool, Field(description="A boolean for whether there should be a toggle to select all options")]
+    order_matters: Annotated[bool, Field(description="A boolean for whether the ordering of the input selections would affect the result of the dataset")]
+    selected_ids: Annotated[list[str], Field(description="A list of ids of the selected / default options")]
+
+class _DateTypeParameterModel(ParameterModelBase):
+    min_date: Annotated[date | None, Field(description='A string in "yyyy-MM-dd" format for the minimum date')]
+    max_date: Annotated[date | None, Field(description='A string in "yyyy-MM-dd" format for the maximum date')]
+
+class DateParameterModel(_DateTypeParameterModel):
+    widget_type: Annotated[Literal["date"], Field(description="The parameter type")]
+    selected_date: Annotated[date, Field(description='A string in "yyyy-MM-dd" format for the selected / default date')]
+
+class DateRangeParameterModel(_DateTypeParameterModel):
+    widget_type: Annotated[Literal["date_range"], Field(description="The parameter type")]
+    selected_start_date: Annotated[date, Field(description='A string in "yyyy-MM-dd" format for the selected / default start date')]
+    selected_end_date: Annotated[date, Field(description='A string in "yyyy-MM-dd" format for the selected / default end date')]
+
+class _NumericParameterModel(ParameterModelBase):
+    min_value: Annotated[float, Field(description="A number for the lower bound of the selectable number")]
+    max_value: Annotated[float, Field(description="A number for the upper bound of the selectable number")]
+    increment: Annotated[float, Field(description="A number for the selectable increments between the lower bound and upper bound")]
+
+class NumberParameterModel(_NumericParameterModel):
+    widget_type: Annotated[Literal["number"], Field(description="The parameter type")]
+    selected_value: Annotated[float, Field(description="A number for the selected / default number")]
+
+class NumberRangeParameterModel(_NumericParameterModel):
+    widget_type: Annotated[Literal["number_range"], Field(description="The parameter type")]
+    selected_lower_value: Annotated[float, Field(description="A number for the selected / default lower number")]
+    selected_upper_value: Annotated[float, Field(description="A number for the selected / default upper number")]
+
+class TextParameterModel(ParameterModelBase):
+    widget_type: Annotated[Literal["text"], Field(description="The parameter type")]
+    entered_text: Annotated[str, Field(description="A string for the default entered text")]
+    input_type: Annotated[str, Field(
+        description='A string for the input type (one of "text", "textarea", "number", "date", "datetime-local", "month", "time", "color", or "password")'
+    )]
+
+ParametersListType = list[
+    NoneParameterModel | SingleSelectParameterModel | MultiSelectParameterModel | DateParameterModel | DateRangeParameterModel | 
+    NumberParameterModel | NumberRangeParameterModel | TextParameterModel
+]
+
+class ParametersModel(BaseModel):
+    parameters: Annotated[ParametersListType, Field(description="The list of parameters for the dataset / dashboard")]
+
+
+## Datasets / Dashboards Catalog Response Models
+
+name_description = "The name of the dataset / dashboard (usually in snake case with underscores)"
+name_for_api_description = "The name of the dataset / dashboard for the API (with dashes instead of underscores)"
+label_description = "The human-friendly display name for the dataset / dashboard"
+description_description = "The description of the dataset / dashboard"
+parameters_path_description = "The API path to the parameters for the dataset / dashboard"
+metadata_path_description = "The API path to the metadata (i.e., description and schema) for the dataset"
+result_path_description = "The API path to the results for the dataset / dashboard"
+
+class ConfigurableOverrideModel(BaseModel):
+    name: str
+    default: str
+
+class ConfigurableItemModel(ConfigurableOverrideModel):
+    label: str
+    description: str
+
+class ColumnModel(BaseModel):
+    name: Annotated[str, Field(examples=["mycol"], description="Name of column")]
+    type: Annotated[str, Field(examples=["string", "integer", "boolean", "datetime"], description='Column type (such as "string", "integer", "boolean", "datetime", etc.)')]
+    description: Annotated[str, Field(examples=["My column description"], description="The description of the column")]
+    category: Annotated[str, Field(examples=["dimension", "measure", "misc"], description="The category of the column (such as 'dimension', 'measure', or 'misc')")]
+
+class ColumnWithConditionModel(ColumnModel):
+    condition: Annotated[list[str] | None, Field(default=None, examples=[["My condition"]], description="The condition(s) of when the field is included (such as based on a parameter selection)")]
+
+class SchemaModel(BaseModel):
+    fields: Annotated[list[ColumnModel], Field(description="A list of JSON objects containing the 'name' and 'type' for each of the columns in the result")]
+
+class SchemaWithConditionModel(BaseModel):
+    fields: Annotated[list[ColumnWithConditionModel], Field(description="A list of JSON objects containing the 'name' and 'type' for each of the columns in the result")]
+
+class DatasetItemModelForMcp(BaseModel):
+    name: Annotated[str, Field(examples=["my_dataset"], description=name_description)]
+    label: Annotated[str, Field(examples=["My Dataset"], description=label_description)]
+    description: Annotated[str, Field(examples=[""], description=description_description)]
+    parameters: Annotated[list[str], Field(examples=[["myparam1", "myparam2"]], description="The list of parameter names used by the dataset. If the list is empty, the dataset does not accept any parameters.")]
+    data_schema: Annotated[SchemaWithConditionModel, Field(alias="schema", description="JSON object describing the schema of the dataset")]
+ 
+class DatasetItemModel(DatasetItemModelForMcp):
+    name_for_api: Annotated[str, Field(examples=["my-dataset"], description=name_for_api_description)]
+    configurables: Annotated[list[ConfigurableOverrideModel], Field(default_factory=list, description="The list of configurables with their default values")]
+
+class DashboardItemModel(ParametersModel):
+    name: Annotated[str, Field(examples=["mydashboard"], description=name_description)]
+    name_for_api: Annotated[str, Field(examples=["my-dashboard"], description=name_for_api_description)]
+    label: Annotated[str, Field(examples=["My Dashboard"], description=label_description)]
+    description: Annotated[str, Field(examples=[""], description=description_description)]
+    configurables: Annotated[list[ConfigurableOverrideModel], Field(default_factory=list, description="The list of configurables with their default values")]
+    parameters: Annotated[list[str], Field(examples=[["myparam1", "myparam2"]], description="The list of parameter names used by the dashboard")]
+    result_format: Annotated[str, Field(examples=["png", "html"], description="The format of the dashboard's result API response (one of 'png' or 'html')")]
+
+ModelConfigType = mc.ModelConfig | s.Source | mc.SeedConfig | mc.BuildModelConfig | mc.DbviewModelConfig | mc.FederateModelConfig
+
+class ConnectionItemModel(BaseModel):
+    name: Annotated[str, Field(examples=["myconnection"], description="The name of the connection")]
+    label: Annotated[str, Field(examples=["My Connection"], description="The human-friendly display name for the connection")]
+
+class DataModelItem(BaseModel):
+    name: Annotated[str, Field(examples=["model_name"], description="The name of the model")]
+    model_type: Annotated[Literal["source", "dbview", "federate", "seed", "build"], Field(
+        examples=["source", "dbview", "federate", "seed", "build"], description="The type of the model"
+    )]
+    config: Annotated[ModelConfigType, Field(description="The configuration of the model")]
+    is_queryable: Annotated[bool, Field(examples=[True], description="Whether the model is queryable")]
+
+class LineageNode(BaseModel):
+    name: str
+    type: Literal["model", "dataset", "dashboard"]
+
+class LineageRelation(BaseModel):
+    type: Literal["buildtime", "runtime"]
+    source: LineageNode
+    target: LineageNode
+
+class CatalogModelForMcp(BaseModel):
+    parameters: Annotated[ParametersListType, Field(description="The list of all parameters in the project. It is possible that not all parameters are used by a dataset.")]
+    datasets: Annotated[list[DatasetItemModelForMcp], Field(description="The list of accessible datasets")]
+    
+class CatalogModel(CatalogModelForMcp):
+    datasets: Annotated[list[DatasetItemModel], Field(description="The list of accessible datasets")]
+    dashboards: Annotated[list[DashboardItemModel], Field(description="The list of accessible dashboards")]
+    connections: Annotated[list[ConnectionItemModel], Field(description="The list of connections in the project (only provided for admin users)")]
+    models: Annotated[list[DataModelItem], Field(description="The list of data models in the project (only provided for admin users)")]
+    lineage: Annotated[list[LineageRelation], Field(description="The lineage information between data assets (only provided for admin users)")]
+    configurables: Annotated[list[ConfigurableItemModel], Field(description="The list of configurables (only provided for admin users)")]
+
+
+## Dataset Results Response Models
+
+class DataDetailsModel(BaseModel):
+    num_rows: Annotated[int, Field(description="The number of rows in the data field")]
+    orientation: Annotated[Literal["records", "rows", "columns"], Field(description="The orientation of the data field")]
+
+class DatasetResultModel(BaseModel):
+    data_schema: Annotated[SchemaModel, Field(alias="schema", description="JSON object describing the schema of the dataset")]
+    total_num_rows: Annotated[int, Field(description="The total number of rows for the dataset")]
+    data_details: Annotated[DataDetailsModel, Field(description="A JSON object containing the details of the data field")]
+    data: Annotated[list[dict] | list[list] | dict[str, list], Field(
+        description=dedent("""
+        The data payload. 
+        - If orientation is 'records', this is a list of JSON objects. 
+        - If orientation is 'rows', this is a list of rows. Each row is a list of values in the same order as the columns in `schema`.
+        - If orientation is 'columns', this is a JSON object where keys are column names and values are columns. Each column is a list of values from the first to last row.
+        """).strip()
+    )]
+
+
+## Compiled Query Response Model
+
+class CompiledQueryModel(BaseModel):
+    language: Annotated[Literal["sql", "python"], Field(description="The language of the data model query: 'sql' or 'python'")]
+    definition: Annotated[str, Field("", description="The compiled SQL or Python definition of the data model.")]
+    placeholders: Annotated[dict[str, Any], Field({}, description="The placeholders for the data model.")]
+
+
+## Project Metadata Response Models
+
+SAMPLE_BASE_URL = "https://example.com/analytics/project/v1"
+SAMPLE_BASE_URL_API = f"{SAMPLE_BASE_URL}{c.LATEST_API_VERSION_MOUNT_PATH}"
+
+class PasswordRequirements(BaseModel):
+    min_length: Annotated[int, Field(default=8, description="The minimum length of the password")]
+    max_length: Annotated[int, Field(default=64, description="The maximum length of the password")] # For bcrypt, the max length must be 72 or less
+
+class ApiRoutesModel(BaseModel):
+    # Data catalog and assets routes
+    get_data_catalog_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/data-catalog"])]
+    get_parameters_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/parameters"])]
+    get_dataset_parameters_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/datasets/{{dataset_name}}/parameters"])]
+    get_dataset_results_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/datasets/{{dataset_name}}"])]
+    get_dashboard_parameters_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/dashboards/{{dashboard_name}}/parameters"])]
+    get_dashboard_results_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/dashboards/{{dashboard_name}}"])]
+
+    # Data management routes
+    trigger_build_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/build"])]
+    get_query_result_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/query-result"])]
+    get_compiled_model_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL_API}/compiled-models/{{model_name}}"])]
+
+    # Authentication routes
+    get_user_session_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/user-session"])]
+    list_providers_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/providers"])]
+    login_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/login"])]
+    logout_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/logout"])]
+    change_password_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/password"])]
+    list_api_keys_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/api-keys"])]
+    create_api_key_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/api-keys"])]
+    revoke_api_key_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/api-keys/{{key_id}}"])]
+
+    # User management routes
+    list_user_fields_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/user-management/user-fields"])]
+    list_users_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/user-management/users"])]
+    add_user_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/user-management/users"])]
+    update_user_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/user-management/users/{{username}}"])]
+    delete_user_url: Annotated[str | None, Field(default=None, examples=[f"{SAMPLE_BASE_URL_API}/auth/user-management/users/{{username}}"])]
+
+class ProjectMetadataModel(BaseModel):
+    name: Annotated[str, Field(examples=["my_project"], description="The name of the project (usually in snake case with underscores)")]
+    name_for_api: Annotated[str, Field(examples=["my-project"], description="The name of the project for the API (with dashes instead of underscores)")]
+    version: Annotated[str, Field(examples=["1"], description="The version of the project. Should be a stringified integer.")]
+    label: Annotated[str, Field(examples=["My Project"], description="The human-friendly display name for the project")]
+    description: Annotated[str, Field(examples=["My project description"], description="The description of the project")]
+    auth_strategy: Annotated[Literal["managed", "external"], Field(examples=["managed"], description="The authentication strategy for the project")]
+    auth_type: Annotated[Literal["optional", "required"], Field(examples=["optional"], description="The authentication type for the project")]
+    password_requirements: Annotated[PasswordRequirements | None, Field(description="The password requirements for the project")]
+    elevated_access_level: Annotated[Literal["admin", "member", "guest"], Field(
+        examples=["admin"], description="The access level required to access elevated features (such as configurables and data lineage)"
+    )]
+    api_routes: Annotated[ApiRoutesModel, Field(description="The API routes for the project")]
+
+
+class DocumentationRoutesModel(BaseModel):
+    swagger_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL}/docs"], description="The URL to the Swagger UI")]
+    redoc_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL}/redoc"], description="The URL to the ReDoc UI")]
+    openapi_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL}/openapi.json"], description="The URL to the OpenAPI specification")]
+
+class APIVersionMetadataModel(BaseModel):
+    project_metadata_url: Annotated[str, Field(examples=[SAMPLE_BASE_URL_API], description="The URL to the project metadata endpoint")]
+    documentation_routes: Annotated[DocumentationRoutesModel, Field(description="The API documentation for this version of the API contract")]
+
+class ExploreEndpointsModel(BaseModel):
+    health_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL}/health"], description="The URL to the health check endpoint")]
+    api_versions: Annotated[dict[str, APIVersionMetadataModel], Field(description="The set of API versions and their metadata paths")]
+    documentation_routes: Annotated[DocumentationRoutesModel, Field(description="The API documentation for the base API application")]
+    mcp_server_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL}/mcp"], description="The URL to the MCP server")]
+    studio_url: Annotated[str, Field(examples=[f"{SAMPLE_BASE_URL}/studio"], description="The URL to the Squirrels Studio UI")]
+
+
+class OAuthProtectedResourceMetadata(BaseModel):
+    """OAuth 2.1 Protected Resource Metadata (RFC 9728)"""
+    resource: str = Field(description="The resource identifier URL")
+    authorization_servers: list[str] = Field(description="List of authorization server issuer identifier URLs")
+    scopes_supported: list[str] = Field(description="List of OAuth 2.1 scope values supported")