databricks-mason 0.1.3.dev0__tar.gz → 0.1.4.dev0__tar.gz

{databricks_mason-0.1.3.dev0 → databricks_mason-0.1.4.dev0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: databricks-mason
-Version: 0.1.3.dev0
+Version: 0.1.4.dev0
 Summary: Databricks integration for Mason
 Author-email: Databricks <agent-feedback@databricks.com>
 License-File: NOTICE
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1
-Requires-Dist: databricks-sdk>=0.49
+Requires-Dist: databricks-sdk>=0.94.0
 Requires-Dist: psycopg[binary]>=3.1
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7
@@ -31,7 +31,7 @@ Requires-Dist: openai-agents>=0.7.0; extra == 'runtime-openai'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'runtime-openai'
 Requires-Dist: uuid-utils>=0.10.0; extra == 'runtime-openai'
 Provides-Extra: tracing
-Requires-Dist: mlflow[databricks]>=3.9.0; extra == 'tracing'
+Requires-Dist: mlflow[databricks]>=3.10.1; extra == 'tracing'
 Description-Content-Type: text/markdown
 
 # `databricks-mason`
@@ -90,28 +90,57 @@ You can also pass the global `--profile/-p` option before an individual command,
 
 ## Python SDK
 
-The same memory and session APIs are available programmatically through
-`MasonClient`, which authenticates exactly like the CLI (a `.databrickscfg` profile
-or the SDK's default resolution):
+`MasonClient` adds a small resource-oriented layer over the Mason API. Pass it an
+authenticated Databricks `WorkspaceClient`, or omit the argument to use the
+Databricks SDK's default authentication resolution:
 
 ```python
+from databricks.sdk import WorkspaceClient
 from databricks_mason import MasonClient
 
-client = MasonClient(profile="my-workspace")  # or MasonClient() for default auth
+mason = MasonClient(WorkspaceClient(profile="my-workspace"))
+
+session_store = mason.session_stores.create("support-agent-sessions")
+session = session_store.add(actor_id="customer-123", session_id="case-456")
+session.append_items(
+    [
+        {"type": "message", "role": "user", "content": "I need help with my cluster."},
+        {"type": "message", "role": "assistant", "content": "Let's take a look."},
+    ]
+)
+
+memory_store = mason.memory_stores.create("coding-agent-memory")
+memory = memory_store.add(
+    actor_id="alice",
+    path="/preferences/style.md",
+    content="The user prefers concise answers.",
+)
+results = memory_store.search(
+    actor_id="alice",
+    query="response preferences",
+    limit=10,
+)
+memory = memory.update(content="The user prefers very concise answers.")
+memory.delete()
+```
 
-store = client.create_memory_store("my-store")
-print(store.name, store.display_name)  # typed attribute access
+The root collections manage stores: `mason.memory_stores.create/get/list` and
+`mason.session_stores.create/get/list`. A returned store owns operations on its
+contents, such as `memory_store.add()`, `memory_store.get("memory-id")`,
+`memory_store.list()`, and `memory_store.search()`, or `session_store.add()`,
+`session_store.get("session-id")`, and `session_store.list()`. Returned memories,
+sessions, and stores own their `update()` and `delete()` operations.
 
-client.create_memory_entry("my-store", actor_id="alice", path="/notes/1.md", content="hi")
-for entry in client.list_memory_entries("my-store", actor_id="alice").entries:
-    print(entry.path, entry.content)
-```
+All `list()` methods return iterators that automatically consume server pages. List
+`page_size` and search `limit` values must be between 1 and 100. `session.list_items()`
+also auto-pages. `session.fork(...)` creates an independent copy, optionally through
+a specific item. Deleting a session with descendants requires
+`session.delete(force=True)` to cascade the deletion.
 
-Each method maps to one `/api/agents/v1` operation. Responses come back as typed
-models (`MemoryStore`, `Session`, `SessionItemList`, ...) that expose attribute
-accessors (`store.name`) while remaining plain dicts underneath — so `store["name"]`,
-`json.dumps(store)`, and any new server-side fields keep working. API errors raise
-`databricks_mason.AgentCliError`. Deployment, sandbox, and tracing remain CLI-only.
+The resource layer intentionally does not mirror every API method. Its private
+transport will be replaced by the generated `WorkspaceClient.mason` service when that
+is released, without changing this public surface. Deployment, sandbox, tracing, and
+the existing CLI commands remain separate.
 
 ## Commands
 
@@ -122,12 +151,15 @@ mason [-p <profile>] [-o text|json]
   init         [--framework openai|langgraph] [--disable-chat-app]
                [--profile P] [--repo URL] [--ref REF] [directory]
   dev          [--source PATH] [--prepare-environment] [--app-port PORT]
-               [--memory/-m N] [--session/-s N]
-               [--with-traces C.S] [--no-create-stores]
+               [--with-traces C.S]
   memory
+    bind         STORE [--source PATH] [--no-create-stores]
+    unbind       [--source PATH]
     stores     create | list | get | update | delete
     entries    create | get | list | search | update | delete
   sessions     create | list | get | update | delete | fork
+    bind         STORE [--source PATH] [--no-create-stores]
+    unbind       [--source PATH]
     stores     create | list | get | update | delete
     items      list | append | pop | clear
   tracing
@@ -141,9 +173,7 @@ mason [-p <profile>] [-o text|json]
     add uc-function  FUNCTION [--name NAME] [--source PATH]
     add python       NAME [--source PATH]
     list             [--source PATH]
-  deploy       <name> --source PATH [--memory/-m N]
-               [--session/-s N] [--actor-id ID]
-               [--with-traces C.S] [--no-create-stores]
+  deploy       <name> --source PATH [--with-traces C.S]
   deployments  list | get | logs | start | stop | delete
 ```
 
@@ -229,16 +259,17 @@ The chat app includes synchronous, SSE streaming, background polling, Session St
 and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
 `runtime/main.py`, and UI tests.
 
-For the full deployed demo, connect both managed stores:
+For the full deployed demo, bind both managed stores, then deploy:
 
 ```sh
-mason --profile <profile> deploy mason-agent-demo --source . \
-  --session mason-demo-sessions \
-  --memory mason-demo-memory \
-  --actor-id alice
+mason sessions bind mason-demo-sessions
+mason memory bind mason-demo-memory
+mason --profile <profile> deploy mason-agent-demo --source .
 ```
 
-(Missing stores are created automatically; pass `--no-create-stores` to require they already exist.)
+(Binding creates a missing store automatically; pass `--no-create-stores` to require it already
+exists. The agent reads the bound stores from `agent.toml` at runtime; `deploy` grants the app's
+service principal access to them.)
 
 The Databricks Apps `__Host-databricks-app-router` cookie is both the sticky routing key and the
 application session id. The browser sends it automatically; API clients must reuse it as a cookie.

{databricks_mason-0.1.3.dev0 → databricks_mason-0.1.4.dev0}/README.md

@@ -54,28 +54,57 @@ You can also pass the global `--profile/-p` option before an individual command,
 
 ## Python SDK
 
-The same memory and session APIs are available programmatically through
-`MasonClient`, which authenticates exactly like the CLI (a `.databrickscfg` profile
-or the SDK's default resolution):
+`MasonClient` adds a small resource-oriented layer over the Mason API. Pass it an
+authenticated Databricks `WorkspaceClient`, or omit the argument to use the
+Databricks SDK's default authentication resolution:
 
 ```python
+from databricks.sdk import WorkspaceClient
 from databricks_mason import MasonClient
 
-client = MasonClient(profile="my-workspace")  # or MasonClient() for default auth
+mason = MasonClient(WorkspaceClient(profile="my-workspace"))
+
+session_store = mason.session_stores.create("support-agent-sessions")
+session = session_store.add(actor_id="customer-123", session_id="case-456")
+session.append_items(
+    [
+        {"type": "message", "role": "user", "content": "I need help with my cluster."},
+        {"type": "message", "role": "assistant", "content": "Let's take a look."},
+    ]
+)
+
+memory_store = mason.memory_stores.create("coding-agent-memory")
+memory = memory_store.add(
+    actor_id="alice",
+    path="/preferences/style.md",
+    content="The user prefers concise answers.",
+)
+results = memory_store.search(
+    actor_id="alice",
+    query="response preferences",
+    limit=10,
+)
+memory = memory.update(content="The user prefers very concise answers.")
+memory.delete()
+```
 
-store = client.create_memory_store("my-store")
-print(store.name, store.display_name)  # typed attribute access
+The root collections manage stores: `mason.memory_stores.create/get/list` and
+`mason.session_stores.create/get/list`. A returned store owns operations on its
+contents, such as `memory_store.add()`, `memory_store.get("memory-id")`,
+`memory_store.list()`, and `memory_store.search()`, or `session_store.add()`,
+`session_store.get("session-id")`, and `session_store.list()`. Returned memories,
+sessions, and stores own their `update()` and `delete()` operations.
 
-client.create_memory_entry("my-store", actor_id="alice", path="/notes/1.md", content="hi")
-for entry in client.list_memory_entries("my-store", actor_id="alice").entries:
-    print(entry.path, entry.content)
-```
+All `list()` methods return iterators that automatically consume server pages. List
+`page_size` and search `limit` values must be between 1 and 100. `session.list_items()`
+also auto-pages. `session.fork(...)` creates an independent copy, optionally through
+a specific item. Deleting a session with descendants requires
+`session.delete(force=True)` to cascade the deletion.
 
-Each method maps to one `/api/agents/v1` operation. Responses come back as typed
-models (`MemoryStore`, `Session`, `SessionItemList`, ...) that expose attribute
-accessors (`store.name`) while remaining plain dicts underneath — so `store["name"]`,
-`json.dumps(store)`, and any new server-side fields keep working. API errors raise
-`databricks_mason.AgentCliError`. Deployment, sandbox, and tracing remain CLI-only.
+The resource layer intentionally does not mirror every API method. Its private
+transport will be replaced by the generated `WorkspaceClient.mason` service when that
+is released, without changing this public surface. Deployment, sandbox, tracing, and
+the existing CLI commands remain separate.
 
 ## Commands
 
@@ -86,12 +115,15 @@ mason [-p <profile>] [-o text|json]
   init         [--framework openai|langgraph] [--disable-chat-app]
                [--profile P] [--repo URL] [--ref REF] [directory]
   dev          [--source PATH] [--prepare-environment] [--app-port PORT]
-               [--memory/-m N] [--session/-s N]
-               [--with-traces C.S] [--no-create-stores]
+               [--with-traces C.S]
   memory
+    bind         STORE [--source PATH] [--no-create-stores]
+    unbind       [--source PATH]
     stores     create | list | get | update | delete
     entries    create | get | list | search | update | delete
   sessions     create | list | get | update | delete | fork
+    bind         STORE [--source PATH] [--no-create-stores]
+    unbind       [--source PATH]
     stores     create | list | get | update | delete
     items      list | append | pop | clear
   tracing
@@ -105,9 +137,7 @@ mason [-p <profile>] [-o text|json]
     add uc-function  FUNCTION [--name NAME] [--source PATH]
     add python       NAME [--source PATH]
     list             [--source PATH]
-  deploy       <name> --source PATH [--memory/-m N]
-               [--session/-s N] [--actor-id ID]
-               [--with-traces C.S] [--no-create-stores]
+  deploy       <name> --source PATH [--with-traces C.S]
   deployments  list | get | logs | start | stop | delete
 ```
 
@@ -193,16 +223,17 @@ The chat app includes synchronous, SSE streaming, background polling, Session St
 and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
 `runtime/main.py`, and UI tests.
 
-For the full deployed demo, connect both managed stores:
+For the full deployed demo, bind both managed stores, then deploy:
 
 ```sh
-mason --profile <profile> deploy mason-agent-demo --source . \
-  --session mason-demo-sessions \
-  --memory mason-demo-memory \
-  --actor-id alice
+mason sessions bind mason-demo-sessions
+mason memory bind mason-demo-memory
+mason --profile <profile> deploy mason-agent-demo --source .
 ```
 
-(Missing stores are created automatically; pass `--no-create-stores` to require they already exist.)
+(Binding creates a missing store automatically; pass `--no-create-stores` to require it already
+exists. The agent reads the bound stores from `agent.toml` at runtime; `deploy` grants the app's
+service principal access to them.)
 
 The Databricks Apps `__Host-databricks-app-router` cookie is both the sticky routing key and the
 application session id. The browser sends it automatically; API clients must reuse it as a cookie.

{databricks_mason-0.1.3.dev0 → databricks_mason-0.1.4.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "databricks-mason"
-version = "0.1.3.dev0"
+version = "0.1.4.dev0"
 description = "Databricks integration for Mason"
 authors = [
     { name="Databricks", email="agent-feedback@databricks.com" },
@@ -9,7 +9,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "click>=8.1",
-    "databricks-sdk>=0.49",
+    "databricks-sdk>=0.94.0",
     "psycopg[binary]>=3.1",
     "PyYAML>=6.0",
     "rich>=13.7",
@@ -19,7 +19,7 @@ dependencies = [
 
 [project.optional-dependencies]
 tracing = [
-    "mlflow[databricks]>=3.9.0",
+    "mlflow[databricks]>=3.10.1",
 ]
 # The agent-side runtime helpers a deployed agent imports. Kept as extras so a plain
 # `pip install databricks-mason` (the CLI) stays light; each template depends on the extra for its

databricks_mason-0.1.4.dev0/src/databricks_mason/__init__.py

@@ -0,0 +1,41 @@
+"""High-level Python client and framework-neutral runtime helpers for Mason."""
+
+from typing import TYPE_CHECKING
+
+from databricks_mason.client import MasonClient
+from databricks_mason.memory_store import Memory, MemorySearchResult, MemoryStore
+from databricks_mason.session_store import Session, SessionItem, SessionStore
+
+if TYPE_CHECKING:
+    from databricks_mason.runtime import (
+        configure_tracing,
+        tag_session,
+        workspace_client,
+        workspace_headers,
+    )
+
+__all__ = [
+    "MasonClient",
+    "Memory",
+    "MemorySearchResult",
+    "MemoryStore",
+    "Session",
+    "SessionItem",
+    "SessionStore",
+    "configure_tracing",
+    "tag_session",
+    "workspace_client",
+    "workspace_headers",
+]
+
+_RUNTIME_REEXPORTS = frozenset(
+    {"configure_tracing", "tag_session", "workspace_client", "workspace_headers"}
+)
+
+
+def __getattr__(name: str) -> object:
+    if name in _RUNTIME_REEXPORTS:
+        import importlib
+
+        return getattr(importlib.import_module("databricks_mason.runtime"), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

databricks_mason-0.1.3.dev0/src/databricks_mason/client.py → databricks_mason-0.1.4.dev0/src/databricks_mason/_api_client.py

@@ -1,12 +1,9 @@
-"""Authenticated client for the agents/v1 memory and session APIs.
-
-`MasonClient` is Mason's public Python entry point: construct it with a
-`.databrickscfg` profile (or rely on the SDK's default auth) and call one method per
-API operation. It wraps a databricks-sdk `WorkspaceClient` and returns typed models
-over the JSON responses from `/api/agents/v1`. Account-routed profiles retain their
-configured vanity host and add the resolved workspace id as a routing header, matching
-the authentication behavior of the Databricks CLI.
-Deployment is handled separately (deploy.py) since it wraps the `databricks apps` CLI.
+"""Private transport for the agents/v1 memory and session APIs.
+
+The public SDK is the resource-oriented :class:`databricks_mason.MasonClient`.
+This module temporarily owns the one-method-per-endpoint transport used by that
+wrapper and the CLI. It can be replaced by the generated ``WorkspaceClient.mason``
+service without changing the public resource surface.
 """
 
 from __future__ import annotations
@@ -37,6 +34,11 @@ def _query(**kwargs: Any) -> dict[str, Any]:
     return {k: v for k, v in kwargs.items() if v is not None and v != ""}
 
 
+def _body(**kwargs: Any) -> dict[str, Any]:
+    """Build a request body while retaining meaningful empty values."""
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
 def _as(cls: type, resp: Any) -> Any:
     """Wrap a JSON response in a typed model, passing non-dicts through unchanged."""
     return cls(resp) if isinstance(resp, dict) else resp
@@ -45,8 +47,7 @@ def _as(cls: type, resp: Any) -> Any:
 def memory_store_path(name: str) -> str:
     """Normalize a store id or name into the `memory-stores/{id}` resource segment.
 
-    Validates client-side so an empty or wrong-typed argument raises a clear error
-    instead of building a URL like `memory-stores/` and leaking a raw ENDPOINT_NOT_FOUND.
+    Validate locally so malformed resource names do not produce misleading endpoint errors.
     """
     raw = (name or "").strip()
     if raw.startswith("memory-stores/"):
@@ -60,7 +61,7 @@ def memory_store_path(name: str) -> str:
 
 
 def session_store_path(name: str) -> str:
-    """Normalize/validate a session store name into the `session-stores/{name}` segment."""
+    """Normalize a session store name into the `session-stores/{name}` resource segment."""
     raw = (name or "").strip()
     if raw.startswith("session-stores/"):
         raw = raw[len("session-stores/") :]
@@ -109,19 +110,19 @@ def _workspace_client(profile: Optional[str]) -> WorkspaceClient:
     )
 
 
-class MasonClient:
-    """Thin, authenticated wrapper over the agents/v1 REST surface.
+class _MasonApiClient:
+    """Private transport for the agents/v1 API until the generated SDK is available."""
 
-    Example:
-        >>> from databricks_mason import MasonClient
-        >>> client = MasonClient(profile="my-workspace")
-        >>> store = client.create_memory_store("my-store")
-        >>> client.list_memory_stores()
-    """
-
-    def __init__(self, profile: Optional[str] = None):
+    def __init__(
+        self,
+        profile: Optional[str] = None,
+        *,
+        workspace_client: Optional[WorkspaceClient] = None,
+    ) -> None:
+        if profile is not None and workspace_client is not None:
+            raise ValueError("profile and workspace_client are mutually exclusive")
         try:
-            self._w = _workspace_client(profile)
+            self._w = workspace_client or _workspace_client(profile)
         except Exception as exc:  # noqa: BLE001 - surfaced as a clean CLI error
             raise AgentCliError(
                 f"Could not initialize Databricks auth: {exc}",
@@ -190,7 +191,7 @@ class MasonClient:
         *,
         retry_transient: bool = False,
     ) -> models.MemoryStore:
-        body = _query(display_name=display_name, description=description)
+        body = _body(display_name=display_name, description=description)
         return _as(
             models.MemoryStore,
             self._do(
@@ -219,7 +220,7 @@ class MasonClient:
     def update_memory_store(
         self, name: str, display_name: Optional[str] = None, description: Optional[str] = None
     ) -> models.MemoryStore:
-        body = _query(display_name=display_name, description=description)
+        body = _body(display_name=display_name, description=description)
         if not body:
             raise AgentCliError("No fields to update. Provide a display name and/or description.")
         mask = ",".join(body.keys())
@@ -248,7 +249,7 @@ class MasonClient:
         session_id: Optional[str] = None,
         source_type: Optional[str] = None,
     ) -> models.MemoryEntry:
-        body = _query(
+        body = _body(
             actor_id=actor_id,
             path=path,
             content=content,
@@ -261,9 +262,16 @@ class MasonClient:
             self._do("POST", f"{_BASE}/{memory_store_path(store)}/entries", body=body),
         )
 
-    def get_memory_entry(self, store: str, entry: str) -> models.MemoryEntry:
+    def get_memory_entry(
+        self, store: str, entry: str, read_mask: Optional[str] = None
+    ) -> models.MemoryEntry:
         return _as(
-            models.MemoryEntry, self._do("GET", f"{_BASE}/{memory_entry_path(store, entry)}")
+            models.MemoryEntry,
+            self._do(
+                "GET",
+                f"{_BASE}/{memory_entry_path(store, entry)}",
+                query=_query(read_mask=read_mask),
+            ),
         )
 
     def list_memory_entries(
@@ -274,6 +282,7 @@ class MasonClient:
         session_id: Optional[str] = None,
         page_size: Optional[int] = None,
         page_token: Optional[str] = None,
+        read_mask: Optional[str] = None,
     ) -> models.MemoryEntryList:
         return _as(
             models.MemoryEntryList,
@@ -286,14 +295,31 @@ class MasonClient:
                     session_id=session_id,
                     page_size=page_size,
                     page_token=page_token,
+                    read_mask=read_mask,
                 ),
             ),
         )
 
     def search_memory_entries(
-        self, store: str, actor_id: str, query: str, limit: Optional[int] = None
+        self,
+        store: str,
+        actor_id: str,
+        query: str,
+        limit: Optional[int] = None,
+        page_size: Optional[int] = None,
+        path_prefix: Optional[str] = None,
+        session_id: Optional[str] = None,
+        read_mask: Optional[str] = None,
     ) -> models.MemorySearchResult:
-        body = _query(actor_id=actor_id, query=query, limit=limit)
+        body = _body(
+            actor_id=actor_id,
+            query=query,
+            limit=limit,
+            page_size=page_size,
+            path_prefix=path_prefix,
+            session_id=session_id,
+            read_mask=read_mask,
+        )
         return _as(
             models.MemorySearchResult,
             self._do(
@@ -311,7 +337,7 @@ class MasonClient:
         content: Optional[str] = None,
         description: Optional[str] = None,
     ) -> models.MemoryEntry:
-        body = _query(content=content, description=description)
+        body = _body(content=content, description=description)
         if not body:
             raise AgentCliError("No fields to update. Provide content and/or a description.")
         return _as(
@@ -332,7 +358,7 @@ class MasonClient:
         *,
         retry_transient: bool = False,
     ) -> models.SessionStore:
-        body = _query(description=description, metadata=metadata)
+        body = _body(description=description, metadata=metadata)
         return _as(
             models.SessionStore,
             self._do(
@@ -362,7 +388,7 @@ class MasonClient:
     def update_session_store(
         self, name: str, description: Optional[str] = None, metadata: Optional[dict] = None
     ) -> models.SessionStore:
-        body = _query(description=description, metadata=metadata)
+        body = _body(description=description, metadata=metadata)
         if not body:
             raise AgentCliError("No fields to update. Provide a description and/or metadata.")
         mask = ",".join(body.keys())
@@ -389,7 +415,7 @@ class MasonClient:
         parent_session_id: Optional[str] = None,
         metadata: Optional[dict] = None,
     ) -> models.Session:
-        body = _query(actor_id=actor_id, parent_session_id=parent_session_id, metadata=metadata)
+        body = _body(actor_id=actor_id, parent_session_id=parent_session_id, metadata=metadata)
         return _as(
             models.Session,
             self._do(
@@ -433,7 +459,7 @@ class MasonClient:
                 "PATCH",
                 f"{_BASE}/session-stores/{store}/sessions/{session_id}",
                 query={"update_mask": "metadata"},
-                body=_query(metadata=metadata),
+                body=_body(metadata=metadata),
             ),
         )
 
@@ -441,7 +467,7 @@ class MasonClient:
         return self._do(
             "DELETE",
             f"{_BASE}/session-stores/{store}/sessions/{session_id}",
-            query=_query(force=force or None),
+            query={"force": True} if force else None,
         )
 
     def fork_session(
@@ -453,7 +479,7 @@ class MasonClient:
         session_id: Optional[str] = None,
         metadata: Optional[dict] = None,
     ) -> models.Session:
-        body = _query(
+        body = _body(
             source_session_id=source_session_id,
             actor_id=actor_id,
             up_to_item_id=up_to_item_id,
@@ -509,7 +535,3 @@ class MasonClient:
         return self._do(
             "POST", f"{_BASE}/session-stores/{store}/sessions/{session_id}/items:clear", body={}
         )
-
-
-# Backwards-compatible alias for the pre-1.0 internal name.
-AgentApiClient = MasonClient

databricks_mason-0.1.4.dev0/src/databricks_mason/_pagination.py

@@ -0,0 +1,15 @@
+"""Shared pagination validation for typed Mason resources."""
+
+from typing import Optional
+
+_MAX_PAGE_SIZE = 100
+
+
+def validate_page_size(page_size: Optional[int]) -> None:
+    if page_size is not None and not 1 <= page_size <= _MAX_PAGE_SIZE:
+        raise ValueError(f"page_size must be between 1 and {_MAX_PAGE_SIZE}")
+
+
+def validate_limit(limit: Optional[int]) -> None:
+    if limit is not None and not 1 <= limit <= _MAX_PAGE_SIZE:
+        raise ValueError(f"limit must be between 1 and {_MAX_PAGE_SIZE}")