databricks-mason 0.1.0.dev0__tar.gz → 0.1.2.dev0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- databricks_mason-0.1.2.dev0/NOTICE +39 -0
- databricks_mason-0.1.2.dev0/PKG-INFO +238 -0
- databricks_mason-0.1.2.dev0/README.md +202 -0
- databricks_mason-0.1.2.dev0/pyproject.toml +93 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/__init__.py +89 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/agent_project.py +391 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/auth.py +2 -2
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/cli.py +18 -5
- databricks_mason-0.1.2.dev0/src/databricks_mason/client.py +467 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/deploy.py +583 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/dev.py +194 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/errors.py +21 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/help.py +139 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/init.py +263 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/__init__.py +94 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/mcp.py +112 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/memory.py +63 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/session_store.py +469 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/mcp.py +89 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/memory.py +92 -23
- databricks_mason-0.1.2.dev0/src/databricks_mason/memory_store_access.py +30 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/models.py +270 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/openai/__init__.py +89 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/openai/mcp.py +94 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/openai/memory.py +63 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/openai/sessions.py +159 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/project_config.py +141 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/py.typed +0 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/render.py +13 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/__init__.py +45 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/background.py +37 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/session_store_client.py +120 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/tool_manifest.py +149 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/tracing.py +52 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/workspace.py +27 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/sandbox.py +822 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/session_store_access.py +18 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/sessions.py +52 -7
- databricks_mason-0.1.2.dev0/src/databricks_mason/store_access.py +196 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/templates/python_tool_langgraph.py +9 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/templates/python_tool_test.py +12 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/templates/sandbox_mcp.py +39 -0
- databricks_mason-0.1.2.dev0/src/databricks_mason/templates/sandbox_mcp_langgraph.py +39 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/timefmt.py +4 -4
- databricks_mason-0.1.2.dev0/src/databricks_mason/tools.py +343 -0
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/tracing.py +101 -16
- databricks_mason-0.1.0.dev0/PKG-INFO +0 -80
- databricks_mason-0.1.0.dev0/README.md +0 -65
- databricks_mason-0.1.0.dev0/pyproject.toml +0 -59
- databricks_mason-0.1.0.dev0/src/databricks_mason/__init__.py +0 -1
- databricks_mason-0.1.0.dev0/src/databricks_mason/client.py +0 -298
- databricks_mason-0.1.0.dev0/src/databricks_mason/deploy.py +0 -325
- {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/.gitignore +0 -0
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
Copyright (c) 2026 Databricks, Inc. All rights reserved.
|
|
2
|
+
|
|
3
|
+
This Software is the property of Databricks, Inc. ("Databricks") and no license, right, or authorization to install, use, copy, modify, or distribute this Software is granted except pursuant to Databricks' prior written authorization. Any use of this Software without such written authorization from Databricks is strictly prohibited.
|
|
4
|
+
|
|
5
|
+
# MIT License
|
|
6
|
+
|
|
7
|
+
This Software contains code from the following open source projects, licensed under the MIT license (https://opensource.org/licenses/MIT).
|
|
8
|
+
|
|
9
|
+
Package: PyYAML
|
|
10
|
+
Project URL: https://github.com/yaml/pyyaml
|
|
11
|
+
Copyright: 2017-2021 Ingy döt Net, 2006-2016 Kirill Simonov
|
|
12
|
+
|
|
13
|
+
Package: rich
|
|
14
|
+
Project URL: https://github.com/Textualize/rich
|
|
15
|
+
Copyright: 2020 Will McGugan
|
|
16
|
+
|
|
17
|
+
Package: tomli
|
|
18
|
+
Project URL: https://github.com/hukkin/tomli
|
|
19
|
+
Copyright: 2021 Taneli Hukkinen
|
|
20
|
+
|
|
21
|
+
Package: tomlkit
|
|
22
|
+
Project URL: https://github.com/python-poetry/tomlkit
|
|
23
|
+
Copyright: 2018 Sébastien Eustace
|
|
24
|
+
|
|
25
|
+
# Apache License 2.0
|
|
26
|
+
|
|
27
|
+
This Software contains code from the following open source projects, licensed under the Apache License 2.0 license (https://www.apache.org/licenses/LICENSE-2.0).
|
|
28
|
+
|
|
29
|
+
Package: databricks-sdk
|
|
30
|
+
Project URL: https://github.com/databricks/databricks-sdk-py
|
|
31
|
+
Copyright: 2023 Databricks, Inc.
|
|
32
|
+
|
|
33
|
+
# BSD 3-Clause License
|
|
34
|
+
|
|
35
|
+
This Software contains code from the following open source projects, licensed under the BSD 3-Clause License (https://opensource.org/license/bsd-3-clause).
|
|
36
|
+
|
|
37
|
+
Package: click
|
|
38
|
+
Project URL: https://github.com/pallets/click
|
|
39
|
+
Copyright: 2014 Pallets
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: databricks-mason
|
|
3
|
+
Version: 0.1.2.dev0
|
|
4
|
+
Summary: Databricks integration for Mason
|
|
5
|
+
Author-email: Databricks <agent-feedback@databricks.com>
|
|
6
|
+
License-File: NOTICE
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Requires-Dist: click>=8.1
|
|
9
|
+
Requires-Dist: databricks-sdk>=0.49
|
|
10
|
+
Requires-Dist: psycopg[binary]>=3.1
|
|
11
|
+
Requires-Dist: pyyaml>=6.0
|
|
12
|
+
Requires-Dist: rich>=13.7
|
|
13
|
+
Requires-Dist: tomli>=2.0
|
|
14
|
+
Requires-Dist: tomlkit>=0.13
|
|
15
|
+
Provides-Extra: runtime
|
|
16
|
+
Requires-Dist: databricks-agents>=1.9.3; extra == 'runtime'
|
|
17
|
+
Requires-Dist: databricks-langchain>=0.17.0; extra == 'runtime'
|
|
18
|
+
Requires-Dist: fastapi>=0.129.0; extra == 'runtime'
|
|
19
|
+
Requires-Dist: langchain-mcp-adapters>=0.2.1; extra == 'runtime'
|
|
20
|
+
Requires-Dist: langchain>=1.0.0; extra == 'runtime'
|
|
21
|
+
Requires-Dist: langgraph>=1.1.0; extra == 'runtime'
|
|
22
|
+
Requires-Dist: mlflow>=3.10.1; extra == 'runtime'
|
|
23
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'runtime'
|
|
24
|
+
Requires-Dist: uuid-utils>=0.10.0; extra == 'runtime'
|
|
25
|
+
Provides-Extra: runtime-openai
|
|
26
|
+
Requires-Dist: databricks-agents>=1.9.3; extra == 'runtime-openai'
|
|
27
|
+
Requires-Dist: databricks-openai>=0.13.0; extra == 'runtime-openai'
|
|
28
|
+
Requires-Dist: fastapi>=0.129.0; extra == 'runtime-openai'
|
|
29
|
+
Requires-Dist: mlflow>=3.10.1; extra == 'runtime-openai'
|
|
30
|
+
Requires-Dist: openai-agents>=0.4.1; extra == 'runtime-openai'
|
|
31
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'runtime-openai'
|
|
32
|
+
Requires-Dist: uuid-utils>=0.10.0; extra == 'runtime-openai'
|
|
33
|
+
Provides-Extra: tracing
|
|
34
|
+
Requires-Dist: mlflow[databricks]>=3.9.0; extra == 'tracing'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# `databricks-mason`
|
|
38
|
+
|
|
39
|
+
Mason is an experimental CLI for Databricks custom agent preview APIs and
|
|
40
|
+
deployments. It manages memory, sessions, tracing, and deployments from one
|
|
41
|
+
authenticated command.
|
|
42
|
+
|
|
43
|
+
> The underlying APIs are in preview and may need workspace enablement.
|
|
44
|
+
|
|
45
|
+
## Installation
|
|
46
|
+
|
|
47
|
+
From PyPI:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
pip install databricks-mason
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
From source:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
pip install 'git+https://github.com/databricks/databricks-ai-bridge.git#subdirectory=integrations/mason'
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
For tracing commands, install Mason with tracing extras:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
pip install 'databricks-mason[tracing]'
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Authentication
|
|
66
|
+
|
|
67
|
+
Mason uses [Databricks authentication](https://docs.databricks.com/aws/en/dev-tools/cli/authentication).
|
|
68
|
+
If you do not already have credentials, authenticate a named profile first. You can
|
|
69
|
+
then ask Mason to validate and remember that profile:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
databricks auth login --profile <profile>
|
|
73
|
+
mason login --profile <profile>
|
|
74
|
+
mason sessions stores list
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`mason login` does not create credentials; it stores the selected profile in
|
|
78
|
+
`~/.mason/config.json`. `mason logout` forgets that selection without revoking the
|
|
79
|
+
underlying credentials. If Databricks SDK default authentication is already configured,
|
|
80
|
+
you can skip `mason login`. You can also pass `--profile/-p` for an individual command.
|
|
81
|
+
Use `--output json` for scripting.
|
|
82
|
+
|
|
83
|
+
## Python SDK
|
|
84
|
+
|
|
85
|
+
The same memory and session APIs are available programmatically through
|
|
86
|
+
`MasonClient`, which authenticates exactly like the CLI (a `.databrickscfg` profile
|
|
87
|
+
or the SDK's default resolution):
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from databricks_mason import MasonClient
|
|
91
|
+
|
|
92
|
+
client = MasonClient(profile="my-workspace") # or MasonClient() for default auth
|
|
93
|
+
|
|
94
|
+
store = client.create_memory_store("my-store")
|
|
95
|
+
print(store.name, store.display_name) # typed attribute access
|
|
96
|
+
|
|
97
|
+
client.create_memory_entry("my-store", actor_id="alice", path="/notes/1.md", content="hi")
|
|
98
|
+
for entry in client.list_memory_entries("my-store", actor_id="alice").entries:
|
|
99
|
+
print(entry.path, entry.content)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Each method maps to one `/api/agents/v1` operation. Responses come back as typed
|
|
103
|
+
models (`MemoryStore`, `Session`, `SessionItemList`, ...) that expose attribute
|
|
104
|
+
accessors (`store.name`) while remaining plain dicts underneath — so `store["name"]`,
|
|
105
|
+
`json.dumps(store)`, and any new server-side fields keep working. API errors raise
|
|
106
|
+
`databricks_mason.AgentCliError`. Deployment, sandbox, and tracing remain CLI-only.
|
|
107
|
+
|
|
108
|
+
## Commands
|
|
109
|
+
|
|
110
|
+
```text
|
|
111
|
+
mason [-p <profile>] [-o text|json]
|
|
112
|
+
login [--profile P]
|
|
113
|
+
logout
|
|
114
|
+
init [--framework openai|langgraph] [--disable-chat-app]
|
|
115
|
+
[--profile P] [--repo URL] [--ref REF] [directory]
|
|
116
|
+
dev [--source PATH] [--prepare-environment] [--app-port PORT]
|
|
117
|
+
[--memory/-m N] [--session/-s N]
|
|
118
|
+
[--with-traces C.S] [--no-create-stores]
|
|
119
|
+
memory
|
|
120
|
+
stores create | list | get | update | delete
|
|
121
|
+
entries create | get | list | search | update | delete
|
|
122
|
+
sessions create | list | get | update | delete | fork
|
|
123
|
+
stores create | list | get | update | delete
|
|
124
|
+
items list | append | pop | clear
|
|
125
|
+
tracing
|
|
126
|
+
setup --catalog C --schema S [--experiment E]
|
|
127
|
+
list | get | instrument
|
|
128
|
+
mcp
|
|
129
|
+
list [--schema CATALOG.SCHEMA]
|
|
130
|
+
tools
|
|
131
|
+
add sandbox --scope SCOPE [--scope SCOPE ...] [--source PATH]
|
|
132
|
+
add mcp SERVICE [--name NAME] [--source PATH]
|
|
133
|
+
add uc-function FUNCTION [--name NAME] [--source PATH]
|
|
134
|
+
add python NAME [--source PATH]
|
|
135
|
+
list [--source PATH]
|
|
136
|
+
deploy <name> --source PATH [--memory/-m N]
|
|
137
|
+
[--session/-s N] [--actor-id ID]
|
|
138
|
+
[--with-traces C.S] [--no-create-stores]
|
|
139
|
+
deployments list | get | logs | start | stop | delete
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Command help
|
|
143
|
+
|
|
144
|
+
Use the conventional help flag at any command level. Every command's help includes runnable
|
|
145
|
+
examples:
|
|
146
|
+
|
|
147
|
+
```sh
|
|
148
|
+
mason --help
|
|
149
|
+
mason deploy --help
|
|
150
|
+
mason sessions items append --help
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
For the shortest path from a blank directory to a running and deployed agent:
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
mason login --profile my-workspace
|
|
157
|
+
mason init my-agent
|
|
158
|
+
cd my-agent
|
|
159
|
+
mason dev
|
|
160
|
+
mason deploy my-agent
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Agent tools
|
|
164
|
+
|
|
165
|
+
`mason init` writes portable tool intent to `agent.toml` and template provenance to
|
|
166
|
+
`.mason/project.toml`. The manifest runtime is currently implemented only by the in-repository
|
|
167
|
+
`agent-langgraph` template; `mason tools add` fails explicitly for other frameworks until they
|
|
168
|
+
provide an adapter at the same runtime seam.
|
|
169
|
+
|
|
170
|
+
Remote tools update only `agent.toml`; they do not generate framework source. The LangGraph runtime
|
|
171
|
+
loads the manifest and materializes its native MCP tools when the agent runs, so a direct manifest
|
|
172
|
+
edit and a CLI edit have the same behavior:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
mason tools add sandbox --scope table:samples.nyctaxi.trips
|
|
176
|
+
mason tools add mcp system.ai.web_search
|
|
177
|
+
mason tools add uc-function catalog.schema.lookup_ticket
|
|
178
|
+
mason tools add python lookup-ticket
|
|
179
|
+
mason tools list
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Discover the MCP Services available to your user before adding one. By default Mason lists the
|
|
183
|
+
Databricks-managed services in `system.ai`; pass `--schema catalog.schema` for another Unity Catalog
|
|
184
|
+
schema. Text output includes a copyable add command, while `--output json` returns normalized service
|
|
185
|
+
records for scripts:
|
|
186
|
+
|
|
187
|
+
```sh
|
|
188
|
+
mason mcp list
|
|
189
|
+
mason mcp list --schema main.tools
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The Python command additionally creates user-owned `agent/tools/<name>.py` and
|
|
193
|
+
`tests/tools/test_<name>.py` files using the LangGraph-native `@tool` decorator. `mason dev` and
|
|
194
|
+
`mason deploy` preserve `agent.toml`; they do not generate or patch agent source.
|
|
195
|
+
|
|
196
|
+
Sandbox scopes default to read-only access. Repeat `--scope` to allow more than one resource, use
|
|
197
|
+
`volume:` or `workspace:` for those resource types, and use `--permission read_write` only when the
|
|
198
|
+
agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
|
|
199
|
+
arguments controlled by the model.
|
|
200
|
+
|
|
201
|
+
## Initialize the chat app demo
|
|
202
|
+
|
|
203
|
+
The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project.
|
|
204
|
+
It is included by default for `--framework langgraph`; pass `--disable-chat-app` to scaffold the
|
|
205
|
+
API-only backend instead.
|
|
206
|
+
|
|
207
|
+
```sh
|
|
208
|
+
mason init --framework langgraph \
|
|
209
|
+
--profile <profile> \
|
|
210
|
+
./my-agent
|
|
211
|
+
cd ./my-agent
|
|
212
|
+
uv run start-server
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
The chat app includes synchronous, SSE streaming, background polling, Session Store, Memory Store,
|
|
216
|
+
and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
|
|
217
|
+
`runtime/main.py`, and UI tests.
|
|
218
|
+
|
|
219
|
+
For the full deployed demo, connect both managed stores:
|
|
220
|
+
|
|
221
|
+
```sh
|
|
222
|
+
mason --profile <profile> deploy mason-agent-demo --source . \
|
|
223
|
+
--session mason-demo-sessions \
|
|
224
|
+
--memory mason-demo-memory \
|
|
225
|
+
--actor-id alice
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
(Missing stores are created automatically; pass `--no-create-stores` to require they already exist.)
|
|
229
|
+
|
|
230
|
+
The Databricks Apps `__Host-databricks-app-router` cookie is both the sticky routing key and the
|
|
231
|
+
application session id. The browser sends it automatically; API clients must reuse it as a cookie.
|
|
232
|
+
Request bodies never carry `session_id`. A localhost-only `mason-local-session` cookie provides the
|
|
233
|
+
same behavior outside Databricks Apps. TODO: move to `X-Routing-Key` when Apps supports it.
|
|
234
|
+
|
|
235
|
+
The generated `README.md` documents every request the client makes: config discovery, sync and SSE
|
|
236
|
+
invocations, background submission and polling, session transcript loading, HITL resume, and memory
|
|
237
|
+
entry operations. Capability colors are automatic from `/api/demo/config`; only the
|
|
238
|
+
sync/streaming/background transport selector is manual.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# `databricks-mason`
|
|
2
|
+
|
|
3
|
+
Mason is an experimental CLI for Databricks custom agent preview APIs and
|
|
4
|
+
deployments. It manages memory, sessions, tracing, and deployments from one
|
|
5
|
+
authenticated command.
|
|
6
|
+
|
|
7
|
+
> The underlying APIs are in preview and may need workspace enablement.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
From PyPI:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
pip install databricks-mason
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
From source:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
pip install 'git+https://github.com/databricks/databricks-ai-bridge.git#subdirectory=integrations/mason'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
For tracing commands, install Mason with tracing extras:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
pip install 'databricks-mason[tracing]'
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Authentication
|
|
30
|
+
|
|
31
|
+
Mason uses [Databricks authentication](https://docs.databricks.com/aws/en/dev-tools/cli/authentication).
|
|
32
|
+
If you do not already have credentials, authenticate a named profile first. You can
|
|
33
|
+
then ask Mason to validate and remember that profile:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
databricks auth login --profile <profile>
|
|
37
|
+
mason login --profile <profile>
|
|
38
|
+
mason sessions stores list
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`mason login` does not create credentials; it stores the selected profile in
|
|
42
|
+
`~/.mason/config.json`. `mason logout` forgets that selection without revoking the
|
|
43
|
+
underlying credentials. If Databricks SDK default authentication is already configured,
|
|
44
|
+
you can skip `mason login`. You can also pass `--profile/-p` for an individual command.
|
|
45
|
+
Use `--output json` for scripting.
|
|
46
|
+
|
|
47
|
+
## Python SDK
|
|
48
|
+
|
|
49
|
+
The same memory and session APIs are available programmatically through
|
|
50
|
+
`MasonClient`, which authenticates exactly like the CLI (a `.databrickscfg` profile
|
|
51
|
+
or the SDK's default resolution):
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from databricks_mason import MasonClient
|
|
55
|
+
|
|
56
|
+
client = MasonClient(profile="my-workspace") # or MasonClient() for default auth
|
|
57
|
+
|
|
58
|
+
store = client.create_memory_store("my-store")
|
|
59
|
+
print(store.name, store.display_name) # typed attribute access
|
|
60
|
+
|
|
61
|
+
client.create_memory_entry("my-store", actor_id="alice", path="/notes/1.md", content="hi")
|
|
62
|
+
for entry in client.list_memory_entries("my-store", actor_id="alice").entries:
|
|
63
|
+
print(entry.path, entry.content)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Each method maps to one `/api/agents/v1` operation. Responses come back as typed
|
|
67
|
+
models (`MemoryStore`, `Session`, `SessionItemList`, ...) that expose attribute
|
|
68
|
+
accessors (`store.name`) while remaining plain dicts underneath — so `store["name"]`,
|
|
69
|
+
`json.dumps(store)`, and any new server-side fields keep working. API errors raise
|
|
70
|
+
`databricks_mason.AgentCliError`. Deployment, sandbox, and tracing remain CLI-only.
|
|
71
|
+
|
|
72
|
+
## Commands
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
mason [-p <profile>] [-o text|json]
|
|
76
|
+
login [--profile P]
|
|
77
|
+
logout
|
|
78
|
+
init [--framework openai|langgraph] [--disable-chat-app]
|
|
79
|
+
[--profile P] [--repo URL] [--ref REF] [directory]
|
|
80
|
+
dev [--source PATH] [--prepare-environment] [--app-port PORT]
|
|
81
|
+
[--memory/-m N] [--session/-s N]
|
|
82
|
+
[--with-traces C.S] [--no-create-stores]
|
|
83
|
+
memory
|
|
84
|
+
stores create | list | get | update | delete
|
|
85
|
+
entries create | get | list | search | update | delete
|
|
86
|
+
sessions create | list | get | update | delete | fork
|
|
87
|
+
stores create | list | get | update | delete
|
|
88
|
+
items list | append | pop | clear
|
|
89
|
+
tracing
|
|
90
|
+
setup --catalog C --schema S [--experiment E]
|
|
91
|
+
list | get | instrument
|
|
92
|
+
mcp
|
|
93
|
+
list [--schema CATALOG.SCHEMA]
|
|
94
|
+
tools
|
|
95
|
+
add sandbox --scope SCOPE [--scope SCOPE ...] [--source PATH]
|
|
96
|
+
add mcp SERVICE [--name NAME] [--source PATH]
|
|
97
|
+
add uc-function FUNCTION [--name NAME] [--source PATH]
|
|
98
|
+
add python NAME [--source PATH]
|
|
99
|
+
list [--source PATH]
|
|
100
|
+
deploy <name> --source PATH [--memory/-m N]
|
|
101
|
+
[--session/-s N] [--actor-id ID]
|
|
102
|
+
[--with-traces C.S] [--no-create-stores]
|
|
103
|
+
deployments list | get | logs | start | stop | delete
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Command help
|
|
107
|
+
|
|
108
|
+
Use the conventional help flag at any command level. Every command's help includes runnable
|
|
109
|
+
examples:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
mason --help
|
|
113
|
+
mason deploy --help
|
|
114
|
+
mason sessions items append --help
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
For the shortest path from a blank directory to a running and deployed agent:
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
mason login --profile my-workspace
|
|
121
|
+
mason init my-agent
|
|
122
|
+
cd my-agent
|
|
123
|
+
mason dev
|
|
124
|
+
mason deploy my-agent
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Agent tools
|
|
128
|
+
|
|
129
|
+
`mason init` writes portable tool intent to `agent.toml` and template provenance to
|
|
130
|
+
`.mason/project.toml`. The manifest runtime is currently implemented only by the in-repository
|
|
131
|
+
`agent-langgraph` template; `mason tools add` fails explicitly for other frameworks until they
|
|
132
|
+
provide an adapter at the same runtime seam.
|
|
133
|
+
|
|
134
|
+
Remote tools update only `agent.toml`; they do not generate framework source. The LangGraph runtime
|
|
135
|
+
loads the manifest and materializes its native MCP tools when the agent runs, so a direct manifest
|
|
136
|
+
edit and a CLI edit have the same behavior:
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
mason tools add sandbox --scope table:samples.nyctaxi.trips
|
|
140
|
+
mason tools add mcp system.ai.web_search
|
|
141
|
+
mason tools add uc-function catalog.schema.lookup_ticket
|
|
142
|
+
mason tools add python lookup-ticket
|
|
143
|
+
mason tools list
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Discover the MCP Services available to your user before adding one. By default Mason lists the
|
|
147
|
+
Databricks-managed services in `system.ai`; pass `--schema catalog.schema` for another Unity Catalog
|
|
148
|
+
schema. Text output includes a copyable add command, while `--output json` returns normalized service
|
|
149
|
+
records for scripts:
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
mason mcp list
|
|
153
|
+
mason mcp list --schema main.tools
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The Python command additionally creates user-owned `agent/tools/<name>.py` and
|
|
157
|
+
`tests/tools/test_<name>.py` files using the LangGraph-native `@tool` decorator. `mason dev` and
|
|
158
|
+
`mason deploy` preserve `agent.toml`; they do not generate or patch agent source.
|
|
159
|
+
|
|
160
|
+
Sandbox scopes default to read-only access. Repeat `--scope` to allow more than one resource, use
|
|
161
|
+
`volume:` or `workspace:` for those resource types, and use `--permission read_write` only when the
|
|
162
|
+
agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
|
|
163
|
+
arguments controlled by the model.
|
|
164
|
+
|
|
165
|
+
## Initialize the chat app demo
|
|
166
|
+
|
|
167
|
+
The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project.
|
|
168
|
+
It is included by default for `--framework langgraph`; pass `--disable-chat-app` to scaffold the
|
|
169
|
+
API-only backend instead.
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
mason init --framework langgraph \
|
|
173
|
+
--profile <profile> \
|
|
174
|
+
./my-agent
|
|
175
|
+
cd ./my-agent
|
|
176
|
+
uv run start-server
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The chat app includes synchronous, SSE streaming, background polling, Session Store, Memory Store,
|
|
180
|
+
and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
|
|
181
|
+
`runtime/main.py`, and UI tests.
|
|
182
|
+
|
|
183
|
+
For the full deployed demo, connect both managed stores:
|
|
184
|
+
|
|
185
|
+
```sh
|
|
186
|
+
mason --profile <profile> deploy mason-agent-demo --source . \
|
|
187
|
+
--session mason-demo-sessions \
|
|
188
|
+
--memory mason-demo-memory \
|
|
189
|
+
--actor-id alice
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
(Missing stores are created automatically; pass `--no-create-stores` to require they already exist.)
|
|
193
|
+
|
|
194
|
+
The Databricks Apps `__Host-databricks-app-router` cookie is both the sticky routing key and the
|
|
195
|
+
application session id. The browser sends it automatically; API clients must reuse it as a cookie.
|
|
196
|
+
Request bodies never carry `session_id`. A localhost-only `mason-local-session` cookie provides the
|
|
197
|
+
same behavior outside Databricks Apps. TODO: move to `X-Routing-Key` when Apps supports it.
|
|
198
|
+
|
|
199
|
+
The generated `README.md` documents every request the client makes: config discovery, sync and SSE
|
|
200
|
+
invocations, background submission and polling, session transcript loading, HITL resume, and memory
|
|
201
|
+
entry operations. Capability colors are automatic from `/api/demo/config`; only the
|
|
202
|
+
sync/streaming/background transport selector is manual.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "databricks-mason"
|
|
3
|
+
version = "0.1.2.dev0"
|
|
4
|
+
description = "Databricks integration for Mason"
|
|
5
|
+
authors = [
|
|
6
|
+
{ name="Databricks", email="agent-feedback@databricks.com" },
|
|
7
|
+
]
|
|
8
|
+
readme = "README.md"
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
dependencies = [
|
|
11
|
+
"click>=8.1",
|
|
12
|
+
"databricks-sdk>=0.49",
|
|
13
|
+
"psycopg[binary]>=3.1",
|
|
14
|
+
"PyYAML>=6.0",
|
|
15
|
+
"rich>=13.7",
|
|
16
|
+
"tomli>=2.0",
|
|
17
|
+
"tomlkit>=0.13",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[project.optional-dependencies]
|
|
21
|
+
tracing = [
|
|
22
|
+
"mlflow[databricks]>=3.9.0",
|
|
23
|
+
]
|
|
24
|
+
# The agent-side runtime helpers a deployed agent imports. Kept as extras so a plain
|
|
25
|
+
# `pip install databricks-mason` (the CLI) stays light; each template depends on the extra for its
|
|
26
|
+
# framework. `runtime` = the LangGraph adapter (databricks_mason.langgraph); `runtime-openai` = the
|
|
27
|
+
# OpenAI Agents SDK adapter (databricks_mason.openai). Both carry the shared framework-neutral stack
|
|
28
|
+
# (databricks_mason.runtime); the framework SDKs differ, so an agent installs only the one it uses.
|
|
29
|
+
runtime = [
|
|
30
|
+
"databricks-langchain>=0.17.0",
|
|
31
|
+
"langgraph>=1.1.0",
|
|
32
|
+
"langchain>=1.0.0",
|
|
33
|
+
"langchain-mcp-adapters>=0.2.1",
|
|
34
|
+
"fastapi>=0.129.0",
|
|
35
|
+
"mlflow>=3.10.1",
|
|
36
|
+
"uuid-utils>=0.10.0",
|
|
37
|
+
"opentelemetry-exporter-otlp-proto-grpc>=1.25.0",
|
|
38
|
+
"databricks-agents>=1.9.3",
|
|
39
|
+
]
|
|
40
|
+
runtime-openai = [
|
|
41
|
+
"openai-agents>=0.4.1",
|
|
42
|
+
"databricks-openai>=0.13.0",
|
|
43
|
+
"fastapi>=0.129.0",
|
|
44
|
+
"mlflow>=3.10.1",
|
|
45
|
+
"uuid-utils>=0.10.0",
|
|
46
|
+
"opentelemetry-exporter-otlp-proto-grpc>=1.25.0",
|
|
47
|
+
"databricks-agents>=1.9.3",
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
[project.scripts]
|
|
51
|
+
mason = "databricks_mason.cli:main"
|
|
52
|
+
|
|
53
|
+
[dependency-groups]
|
|
54
|
+
dev = [
|
|
55
|
+
"ruff==0.14.10",
|
|
56
|
+
"ty==0.0.23",
|
|
57
|
+
{ include-group = "tests" },
|
|
58
|
+
]
|
|
59
|
+
tests = [
|
|
60
|
+
"pytest==9.0.2",
|
|
61
|
+
]
|
|
62
|
+
|
|
63
|
+
[build-system]
|
|
64
|
+
requires = ["hatchling"]
|
|
65
|
+
build-backend = "hatchling.build"
|
|
66
|
+
|
|
67
|
+
[tool.hatch.build]
|
|
68
|
+
include = [
|
|
69
|
+
"NOTICE",
|
|
70
|
+
"src/databricks_mason/*",
|
|
71
|
+
"src/databricks_mason/py.typed",
|
|
72
|
+
"src/databricks_mason/templates/**",
|
|
73
|
+
]
|
|
74
|
+
|
|
75
|
+
[tool.hatch.build.targets.wheel]
|
|
76
|
+
packages = ["src/databricks_mason"]
|
|
77
|
+
|
|
78
|
+
[tool.ruff]
|
|
79
|
+
include = ["pyproject.toml", "src/**/*.py", "tests/**/*.py"]
|
|
80
|
+
extend = "../../pyproject.toml"
|
|
81
|
+
|
|
82
|
+
[tool.pytest.ini_options]
|
|
83
|
+
testpaths = ["tests/unit_tests"]
|
|
84
|
+
|
|
85
|
+
[tool.ty.environment]
|
|
86
|
+
root = ["./src", "./tests"]
|
|
87
|
+
|
|
88
|
+
[tool.ty.src]
|
|
89
|
+
include = ["./src", "./tests"]
|
|
90
|
+
# The files under templates/ are code-as-data — scaffolding snippets written into a generated agent
|
|
91
|
+
# project, not importable package modules. They import scaffold-relative paths (agent.mason.*,
|
|
92
|
+
# agent.mcps) that never resolve in the package, so type-checking them here is meaningless.
|
|
93
|
+
exclude = ["./src/databricks_mason/templates"]
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""Databricks integration for Mason.
|
|
2
|
+
|
|
3
|
+
Mason ships a `mason` CLI and this Python SDK over the same agents/v1 preview APIs.
|
|
4
|
+
Construct a `MasonClient` and call one method per API operation:
|
|
5
|
+
|
|
6
|
+
from databricks_mason import MasonClient
|
|
7
|
+
|
|
8
|
+
client = MasonClient(profile="my-workspace")
|
|
9
|
+
client.create_memory_store("my-store")
|
|
10
|
+
for entry in client.list_memory_entries("my-store", actor_id="alice").get("entries", []):
|
|
11
|
+
...
|
|
12
|
+
|
|
13
|
+
Auth resolves through the Databricks SDK: pass a `.databrickscfg` profile or rely on
|
|
14
|
+
its default resolution. API errors surface as `AgentCliError`.
|
|
15
|
+
|
|
16
|
+
The framework-neutral runtime helpers (``configure_tracing``, ``tag_session``, ``workspace_client``,
|
|
17
|
+
``workspace_headers``) are also re-exported here for convenience — they live in
|
|
18
|
+
:mod:`databricks_mason.runtime` and are resolved lazily (PEP 562) so a plain CLI ``import
|
|
19
|
+
databricks_mason`` does not pull in the tracing module's ``mlflow`` dependency.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from typing import TYPE_CHECKING
|
|
23
|
+
|
|
24
|
+
from databricks_mason.client import MasonClient, memory_entry_path, memory_store_path
|
|
25
|
+
from databricks_mason.errors import AgentCliError
|
|
26
|
+
from databricks_mason.models import (
|
|
27
|
+
MemoryEntry,
|
|
28
|
+
MemoryEntryList,
|
|
29
|
+
MemorySearchHit,
|
|
30
|
+
MemorySearchResult,
|
|
31
|
+
MemoryStore,
|
|
32
|
+
MemoryStoreList,
|
|
33
|
+
PoppedSessionItem,
|
|
34
|
+
Session,
|
|
35
|
+
SessionItem,
|
|
36
|
+
SessionItemList,
|
|
37
|
+
SessionList,
|
|
38
|
+
SessionStore,
|
|
39
|
+
SessionStoreList,
|
|
40
|
+
StorageBackend,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
if TYPE_CHECKING:
|
|
44
|
+
from databricks_mason.runtime import (
|
|
45
|
+
configure_tracing,
|
|
46
|
+
tag_session,
|
|
47
|
+
workspace_client,
|
|
48
|
+
workspace_headers,
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
__all__ = [
|
|
52
|
+
"MasonClient",
|
|
53
|
+
"AgentCliError",
|
|
54
|
+
"memory_store_path",
|
|
55
|
+
"memory_entry_path",
|
|
56
|
+
"MemoryStore",
|
|
57
|
+
"MemoryStoreList",
|
|
58
|
+
"MemoryEntry",
|
|
59
|
+
"MemoryEntryList",
|
|
60
|
+
"MemorySearchResult",
|
|
61
|
+
"MemorySearchHit",
|
|
62
|
+
"StorageBackend",
|
|
63
|
+
"SessionStore",
|
|
64
|
+
"SessionStoreList",
|
|
65
|
+
"Session",
|
|
66
|
+
"SessionList",
|
|
67
|
+
"SessionItem",
|
|
68
|
+
"SessionItemList",
|
|
69
|
+
"PoppedSessionItem",
|
|
70
|
+
# Framework-neutral runtime helpers (lazily re-exported from databricks_mason.runtime).
|
|
71
|
+
"configure_tracing",
|
|
72
|
+
"tag_session",
|
|
73
|
+
"workspace_client",
|
|
74
|
+
"workspace_headers",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
# Neutral runtime helpers, re-exported lazily so the light CLI import path stays free of the agent
|
|
78
|
+
# stack (mlflow, etc.). Everything else above is light and imported eagerly.
|
|
79
|
+
_RUNTIME_REEXPORTS = frozenset(
|
|
80
|
+
{"configure_tracing", "tag_session", "workspace_client", "workspace_headers"}
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def __getattr__(name: str) -> object:
|
|
85
|
+
if name in _RUNTIME_REEXPORTS:
|
|
86
|
+
import importlib
|
|
87
|
+
|
|
88
|
+
return getattr(importlib.import_module("databricks_mason.runtime"), name)
|
|
89
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|