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.
Files changed (53) hide show
  1. databricks_mason-0.1.2.dev0/NOTICE +39 -0
  2. databricks_mason-0.1.2.dev0/PKG-INFO +238 -0
  3. databricks_mason-0.1.2.dev0/README.md +202 -0
  4. databricks_mason-0.1.2.dev0/pyproject.toml +93 -0
  5. databricks_mason-0.1.2.dev0/src/databricks_mason/__init__.py +89 -0
  6. databricks_mason-0.1.2.dev0/src/databricks_mason/agent_project.py +391 -0
  7. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/auth.py +2 -2
  8. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/cli.py +18 -5
  9. databricks_mason-0.1.2.dev0/src/databricks_mason/client.py +467 -0
  10. databricks_mason-0.1.2.dev0/src/databricks_mason/deploy.py +583 -0
  11. databricks_mason-0.1.2.dev0/src/databricks_mason/dev.py +194 -0
  12. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/errors.py +21 -0
  13. databricks_mason-0.1.2.dev0/src/databricks_mason/help.py +139 -0
  14. databricks_mason-0.1.2.dev0/src/databricks_mason/init.py +263 -0
  15. databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/__init__.py +94 -0
  16. databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/mcp.py +112 -0
  17. databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/memory.py +63 -0
  18. databricks_mason-0.1.2.dev0/src/databricks_mason/langgraph/session_store.py +469 -0
  19. databricks_mason-0.1.2.dev0/src/databricks_mason/mcp.py +89 -0
  20. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/memory.py +92 -23
  21. databricks_mason-0.1.2.dev0/src/databricks_mason/memory_store_access.py +30 -0
  22. databricks_mason-0.1.2.dev0/src/databricks_mason/models.py +270 -0
  23. databricks_mason-0.1.2.dev0/src/databricks_mason/openai/__init__.py +89 -0
  24. databricks_mason-0.1.2.dev0/src/databricks_mason/openai/mcp.py +94 -0
  25. databricks_mason-0.1.2.dev0/src/databricks_mason/openai/memory.py +63 -0
  26. databricks_mason-0.1.2.dev0/src/databricks_mason/openai/sessions.py +159 -0
  27. databricks_mason-0.1.2.dev0/src/databricks_mason/project_config.py +141 -0
  28. databricks_mason-0.1.2.dev0/src/databricks_mason/py.typed +0 -0
  29. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/render.py +13 -0
  30. databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/__init__.py +45 -0
  31. databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/background.py +37 -0
  32. databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/session_store_client.py +120 -0
  33. databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/tool_manifest.py +149 -0
  34. databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/tracing.py +52 -0
  35. databricks_mason-0.1.2.dev0/src/databricks_mason/runtime/workspace.py +27 -0
  36. databricks_mason-0.1.2.dev0/src/databricks_mason/sandbox.py +822 -0
  37. databricks_mason-0.1.2.dev0/src/databricks_mason/session_store_access.py +18 -0
  38. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/sessions.py +52 -7
  39. databricks_mason-0.1.2.dev0/src/databricks_mason/store_access.py +196 -0
  40. databricks_mason-0.1.2.dev0/src/databricks_mason/templates/python_tool_langgraph.py +9 -0
  41. databricks_mason-0.1.2.dev0/src/databricks_mason/templates/python_tool_test.py +12 -0
  42. databricks_mason-0.1.2.dev0/src/databricks_mason/templates/sandbox_mcp.py +39 -0
  43. databricks_mason-0.1.2.dev0/src/databricks_mason/templates/sandbox_mcp_langgraph.py +39 -0
  44. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/timefmt.py +4 -4
  45. databricks_mason-0.1.2.dev0/src/databricks_mason/tools.py +343 -0
  46. {databricks_mason-0.1.0.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/tracing.py +101 -16
  47. databricks_mason-0.1.0.dev0/PKG-INFO +0 -80
  48. databricks_mason-0.1.0.dev0/README.md +0 -65
  49. databricks_mason-0.1.0.dev0/pyproject.toml +0 -59
  50. databricks_mason-0.1.0.dev0/src/databricks_mason/__init__.py +0 -1
  51. databricks_mason-0.1.0.dev0/src/databricks_mason/client.py +0 -298
  52. databricks_mason-0.1.0.dev0/src/databricks_mason/deploy.py +0 -325
  53. {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}")