Add intuitive resource APIs to MasonClient

[annzhang-db]

Adds a small resource-oriented Python SDK over the Mason APIs. It returns typed resource handles, automatically consumes paginated list results, and keeps updates and deletes on the resources they affect.

The public layer is intentionally separate from transport. It currently wraps the private _MasonApiClient; once the autogenerated API is available, that transport can be replaced by WorkspaceClient.mason without changing the resource-oriented surface below.

SDK shape

MasonClient
├── memory_stores.create(name) / get(id) / list()
│   └── MemoryStore
│       ├── add(...) / get(id) / list(...) / search(...)
│       └── update(...) / delete()
│           └── Memory.update(...) / delete()
└── session_stores.create(name) / get(name) / list()
    └── SessionStore
        ├── add(...) / get(id) / list(...)
        └── update(...) / delete()
            └── Session
                ├── append_items(...) / list_items(...)
                ├── pop_item() / clear_items() / fork(...)
                └── update(...) / delete()

Store collections use create() to create stores. Bound stores use add() for memories and sessions, leaving room for richer add semantics such as create-if-absent, append, or overwrite. IDs for memory_store.get(id) and session_store.get(id) are positional. The SDK does not implement a client-side get_or_create or non-atomic append_memory. Session deletion is non-cascading by default; pass force=True to recursively delete descendant sessions.

Examples

from databricks.sdk import WorkspaceClient
from databricks_mason import MasonClient

mason = MasonClient(WorkspaceClient(profile="my-workspace"))

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.",
)
matches = memory_store.search(
    actor_id="alice",
    query="response preferences",
    limit=10,
)
memory = memory_store.get(memory.id)
memory = memory.update(content="The user prefers very concise answers.")

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."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)
session = session_store.get("case-456")
items = list(session.list_items())

Validation

The Mason unit suite passes with 251 tests. Ruff lint/format and ty check also pass.

[smurching]

@annzhang-db thanks for adding this, how did you test it/did we do any validation to make sure the generated APIs are similar to what will eventually land in Databricks SDK?

[qinxinw-db]

for operations on the MemoryStore entity, should we simplify it to:

memory_store.add() # would prefer add over create here as we can support different semantics: create if not exist, append, overwrite. 
memory_store.search()
memory_store.get()

etc. similar for session store.

[qinxinw-db]

The api shape looks good to me!