Databricks Solution Builder

Build your use-case on Databricks — with the assurance you're using Databricks best practices.
_{On synthetic data, or on your own real data. Same engine. Same patterns.}

---

Describe what you want to build and an AI agent designs, writes, and ships it for you — on Databricks, the way Databricks intends. Customer-facing solution, internal POC, pilot on your own production data: same engine. Whether you start with synthetic data or point at your real tables, what comes out is a real, running solution in your workspace — yours to inspect, edit, and own.

In one line: describe it, ship it, iterate on what actually matters.

Two ways in. Run the full app for chat + UI + gallery, or install just the CLI skill into ~/.claude/ and drive everything from any terminal. Same library, same outputs.

Caution

Use at your own risk. Databricks Solution Builder spanws AI agents writing code and creating resources on your behalf with full permission.

Shared container. When deployed as a Databricks App, every user's session runs AI Agents inside the same container with full access to your Databricks resources — The Unity Catalog objects, jobs, pipelines, dashboards, and anything else your identity can reach. The AI Agent can easily escape the project. Share the app to users you trust, or deploy 1 app instance per user (this will be improved soon).

Deploy on an isolated workspace, don't deploy and use this app on a sensitive, production-grade workspace. Don't point it at production data you can't afford to lose. Software provided "as is" — see LICENSE.

---

💡 Why you'll love it

01   Bring your own data, or start with ours

Trying an idea? The agent fabricates realistic synthetic data and gives you something to click through in minutes. Bringing your own? Point at the tables you already have. You don't switch tools when you graduate from sandbox to production — same engine, same patterns, same result.

02   Done the Databricks way — every time

No improvisation. No "I hope this is the right pattern." The agent works from a curated library and hands off to an interface that already knows the right way to do every Databricks thing. You can show the result to your customer on Monday with confidence.

03   Two surfaces, one library

Prefer your terminal? Install the Solution Generator Skill into any Claude Code project and use it from the CLI. Want a guided UI with chat, file viewer, and live diagrams? Use this app. Same library, same outputs, same deploys — pick whichever surface fits the moment.

04   Reuse and remix

Every solution becomes context for the next. Reskin one industry for another; swap one pattern for a related one; recombine for a new pitch. Publish finished projects as templates that anyone in your org can fork from the gallery. The library compounds.

---

Important

Beta — account admin access required. Databricks Solution Builder is currently in beta and depends on the all-apis OAuth scope to talk to the full surface of Databricks APIs reliably. Granting that scope requires account admin privileges on your Databricks account. Until the scope requirement is narrowed, this app is best run in development or sandbox workspaces — not against production. If you don't have account admin rights, ask whoever does to either grant the scope post-deploy (see Deploy to Databricks) or run the app for you on a dev workspace.

🚀 Quickstart (local dev)

# 1. Clone
git clone https://github.com/databricks-solutions/solution-builder.git
cd solution-builder/app

# 2. Authenticate the Databricks CLI (one-time)
databricks auth login --host https://<workspace-url> --profile MY_WORKSPACE

# 3. Configure env
cp .env.example .env
# edit .env → DATABRICKS_CONFIG_PROFILE=MY_WORKSPACE

# 4. Install deps
uv sync          # Python (creates .venv)
bun install      # Frontend

# 5. Run (backend :8000 + frontend :5173, hot reload, opens browser)
./scripts/dev.sh

PGLite auto-provisions a local Postgres — no DB setup required. Reset with RESET_DB=1 ./scripts/dev.sh.

Prerequisites: uv · bun · Databricks CLI v0.239.0+ authenticated to a workspace.

🔧 Environment variables — click to expand

All of these live in app/.env (copy from app/.env.example). The bold ones are the minimum to boot.

Variable	Required	Default	Purpose
DATABRICKS_CONFIG_PROFILE	✅	DEFAULT	Profile from ~/.databrickscfg (set via databricks auth login)
DATABRICKS_HOST / DATABRICKS_TOKEN	alt	—	Direct token auth (CI/CD); use instead of the profile
LAKEBASE_DATABASE_PATH	optional	—	projects/<id>/branches/<id>/databases/<name> — omit to use PGLite
USE_PGLITE	optional	—	Force PGLite even if LAKEBASE_DATABASE_PATH is set
ANTHROPIC_LLM_ENDPOINT	✅	databricks-claude-sonnet-4-6	Model the agent talks to (via FMAPI Anthropic bridge)
ANTHROPIC_BASE_PATH	✅	serving-endpoints/anthropic	FMAPI bridge path — switch to ai-gateway/anthropic for AI Gateway endpoints
AI_GATEWAY	✅	databricks-claude-opus-4-7	Primary AI Gateway endpoint for the backend
AI_GATEWAY_MINI	✅	databricks-gpt-5-4-mini	Cheap/fast endpoint for utility calls
AI_GATEWAY_EMBEDDING	✅	databricks-qwen3-embedding-0-6b	Embedding endpoint for template semantic search
AI_DEV_KIT_BRANCH	optional	experimental	Branch of ai-dev-kit that dev.sh clones
DEMO_PROMPT_GENERATOR_TRACKER_ENABLED	optional	1	Anonymous usage analytics — see the privacy note below; set to 0 to opt out

See app/.env.example for the full annotated list with inline guidance.

📊 Anonymous usage analytics are on by default. We collect aggregated, anonymized events (page views, feature usage counts) only to understand what's working and what needs improvement — never for sales contact. The underlying dbdemos-tracker package filters at the source so events fire only for @databricks.com users; external installations send nothing. See PRIVACY.md for the full list of fields. Opt out anytime with DEMO_PROMPT_GENERATOR_TRACKER_ENABLED=0.

Type checking:

cd app
npx tsc --noEmit          # TypeScript
uv run mypy src           # Python

---

🛠️ Three ways to run

Mode	Where it runs	Auth model	Use case
Local dev	Your laptop	~/.databrickscfg profile	Day-to-day development with hot reload
Databricks App	A Databricks workspace	App service principal (OAuth)	Shared deployment for your team
Electron	Your laptop, packaged	~/.databrickscfg profile	Standalone desktop app for end-users

📦 Deploy to Databricks (production) — click to expand

The app deploys as a Databricks Asset Bundle — Lakebase database, App resource, model-serving permissions, and source code in one command.

cd app

# One-time setup
databricks auth login --host https://<workspace-url> --profile MY_WORKSPACE
cp databricks.prod.yml.example databricks.prod.yml
# fill in workspace.profile, variables, env

# Deploy
databricks bundle deploy
databricks bundle run demo-prompt-generator-app

databricks.prod.yml is gitignored — it holds workspace-specific values (profile, app name, Lakebase instance, model endpoints).

Verify:

databricks apps get <your-app-name> --output json | jq -r '
  "URL:    \(.url)",
  "App:    \(.app_status.state)",
  "Deploy: \(.active_deployment.status.state) — \(.active_deployment.status.message)"
'
# app_status.state should reach "RUNNING"

Post-deploy: grant the app all-apis OAuth scope. This step requires account admin access on the Databricks account — the app is in beta and currently depends on the full all-apis scope to function reliably, which is why we recommend deploying only to development/sandbox workspaces for now. Each databricks bundle deploy may rotate the OAuth integration ID, so re-run this whenever you redeploy:

./scripts/set-app-oauth-scopes.sh                 # uses target=prod
./scripts/set-app-oauth-scopes.sh --target prod   # explicit

The script reads the app name from databricks.<target>.yml, auto-detects your account-level CLI profile, finds the matching OAuth integration, and grants all-apis. Idempotent.

Config flow:

databricks.prod.yml (env:)  →  build.sh reads via `databricks bundle summary`
                            →  writes .build/app.yml (env: 1:1 copy)
                            →  Databricks Apps runtime exports env vars into the container
                            →  backend reads them via Pydantic Settings

Bundle targets: prod (default) and staging. Add a third with two files: databricks.qa.yml{,.example} + a stub targets.qa: in databricks.yml.

Staging-specific setup:

cd app
cp databricks.staging.yml.example databricks.staging.yml
databricks bundle deploy -t staging
./scripts/set-app-oauth-scopes.sh --target staging
# Lakebase UI: grant the new staging SP CAN_CONNECT_AND_CREATE on the project.
databricks bundle run demo-prompt-generator-app -t staging

Auth model (deployed): The app authenticates as a service principal that Databricks Apps creates and binds to the deployment. The SDK reads DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET from the runtime and mints OAuth tokens automatically — no PATs are stored anywhere. End-users browsing the app authenticate via OAuth and the agent runs Databricks CLI commands on their behalf via x-forwarded-access-token.

🖥️ Build the Electron desktop app — click to expand

Bundles Python, the FastAPI backend, the React frontend, and Electron into a single .dmg / .exe / .AppImage.

cd app
./scripts/build-electron.sh                   # Build for current arch
./scripts/build-electron.sh --arch arm64      # Apple Silicon
./scripts/build-electron.sh --arch x64        # Intel Mac / Linux
./scripts/build-electron.sh --arch universal  # Mac universal binary

Output lands in app/dist-electron/. First launch prompts for a profile via the in-app config UI.

To cut a versioned release:

./scripts/release.sh patch         # 0.1.0 → 0.1.1
./scripts/release.sh minor         # 0.1.0 → 0.2.0
./scripts/release.sh 1.2.3         # explicit version

---

🧰 Use it from the CLI — no app required

Install the Solution Generator skill (and, optionally, the AI Dev Kit) into your ~/.claude/ once, then drive everything from any terminal:

bash <(curl -sL https://raw.githubusercontent.com/databricks-solutions/solution-builder/main/install.sh)

cd into any project, run claude, and the skill loads automatically — the agent can design, write, and build Databricks assets end-to-end from the terminal.

Flags:

Flag	Behavior
(none)	Installs skill to ~/.claude/skills/ and the AI Dev Kit globally
--project	Installs the skill into ./.claude/skills/ in the current directory instead
--skill-only	Skips the AI Dev Kit step (skill only)
--branch <name>	Pulls the skill from a non-main branch

Same library as the app, same outputs — pick whichever surface fits the moment. Use the app when you want chat + file viewer + gallery; use the CLI when you want to stay in your terminal.

---

🏗️ Architecture reference

Lakebase tables

Table	Purpose
users	User configuration — email, preferred Databricks profile
projects	Top-level containers — name, description, stage, compute resources, session state
project_files	Files tracked per project — compressed content, SHA-256 hash, sync timestamps
project_stars	User favorites (star/unstar)
project_shares	Project sharing between users (read-only access)
messages	Chat messages within a project (user/assistant/system roles, reasoning data)
executions	Agent execution state — enables session resumption after page refresh
templates	Published project snapshots — name, industry, capabilities, pgvector embedding
template_content	Files stored in a template (compressed, like project files)

Tables are auto-created on startup via SQLModel + DDL migrations in lakebase.py.

API surface (all routes prefixed with /api)

Projects

Method	Path	Description
GET	/projects	List current user's projects
POST	/projects	Create a new project (LLM generates name/description)
GET	/projects/{id}	Get project details
PATCH	/projects/{id}	Update project name/description
PATCH	/projects/{id}/resources	Update compute resources
DELETE	/projects/{id}	Delete a project and its files
POST	/projects/{id}/sync	Sync files between disk and database
POST	/projects/{id}/star	Toggle starred status
POST	/projects/{id}/share	Share project with another user
GET	/projects/{id}/shares	List shares for a project
DELETE	/projects/{id}/share/{share_id}	Remove a share
GET	/shared-projects	List projects shared with current user

Project files

Method	Path	Description
GET	/projects/{id}/files	List files in a project
GET	/projects/{id}/files/{path}	Read file content
GET	/projects/{id}/download	Download project as zip
GET	/projects/{id}/deployed-resources	Get deployed Databricks resource links

Messages

Method	Path	Description
GET	/projects/{id}/messages	Get message history
POST	/projects/{id}/messages	Add a message
DELETE	/projects/{id}/messages	Clear message history
POST	/projects/{id}/session/clear	Clear agent session

Agent

Method	Path	Description
POST	/invoke_agent	Start agent execution, returns execution_id
POST	/stream_progress/{execution_id}	SSE stream of agent events
POST	/stop_stream/{execution_id}	Cancel running execution
GET	/projects/{id}/execution	Get active execution for a project

Templates

Method	Path	Description
GET	/templates	List templates (filterable by status/industry)
GET	/templates/{id}	Get template details
GET	/templates/{id}/files	List template files
GET	/templates/{id}/files/{path}	Read template file content
POST	/templates/search	Semantic search via pgvector
POST	/templates/from-project/{id}	Publish a project as a template
POST	/templates/{id}/status	Update review status (admin)
POST	/templates/{id}/create-project	Fork template into a new project
POST	/templates/{id}/open-project	Open existing project for a template
PUT	/templates/{id}/update-from-project/{id}	Sync template from updated project
GET	/templates/by-project/{id}	Find template linked to a project
PATCH	/templates/{id}/owner	Transfer template ownership
DELETE	/templates/{id}	Delete a template

Skills & resources

Method	Path	Description
GET	/projects/{id}/skills	List available AI Dev Kit skills
GET	/projects/{id}/skills/{name}/files	List files in a skill
GET	/projects/{id}/skills/{name}/files/{path}	Read skill file content
POST	/projects/{id}/skills/refresh	Re-sync skills from AI Dev Kit
GET	/projects/{id}/system-prompt	Preview the agent's system prompt
GET	/resources/clusters	List available clusters
GET	/resources/warehouses	List available SQL warehouses
GET	/resources/catalogs	List Unity Catalog catalogs
GET	/resources/schemas	List schemas in a catalog
GET	/resources/defaults	Get default resource settings
POST	/resources/refresh	Refresh cached resource lists

Other

Method	Path	Description
GET	/version	App version
GET	/health	Health check
GET	/current-user	Current Databricks user info
GET	/config/status	Configuration status (DB, profiles, user)
GET	/constants/industries	List of supported industries
GET	/constants/capabilities	List of available capability blocks
POST	/capabilities/suggest	AI-powered capability suggestions for a scenario
POST	/block-factory/process	Decompose a document into context blocks

Project structure

solution-builder/
├── app/                          # Full-stack application (see app/CLAUDE.md)
│   ├── src/demo_prompt_generator/
│   │   ├── backend/
│   │   │   ├── app.py            # FastAPI entry point
│   │   │   ├── models.py         # SQLModel tables + Pydantic schemas
│   │   │   ├── router.py         # Singleton router, imports all route modules
│   │   │   ├── core/             # App factory, config, DI, DB engine, static serving
│   │   │   ├── routes/           # API routes (agent, projects, files, messages, etc.)
│   │   │   └── services/         # Business logic (agent, LLM, file sync, skills, templates)
│   │   └── ui/                   # React frontend
│   │       ├── routes/           # TanStack Router file-based routes
│   │       ├── components/       # UI components (project/, layout/, ui/, template/)
│   │       ├── lib/              # API clients, utilities, config
│   │       ├── hooks/            # Custom React hooks
│   │       └── styles/           # Tailwind CSS globals
│   ├── databricks.yml            # DAB config — generic resource shape
│   ├── databricks.prod.yml.example  # Per-deployment config template (gitignored when filled in)
│   ├── pyproject.toml            # Python deps (use uv, never pip)
│   ├── package.json              # Frontend deps (use bun)
│   ├── scripts/                  # dev.sh, build.sh, build-electron.sh, release.sh
│   └── .env.example              # Local-dev environment variable template
├── .claude/skills/databricks-demo-generator/
│   └── references/blocks/        # Context blocks (Solution Generator Skill)
│       ├── capabilities/         #   26+ Databricks feature blocks
│       ├── domains/              #   Industry verticals
│       └── patterns/             #   Analytical patterns
├── docs/                         # Diagrams + screenshots used in this README
├── tests/                        # Playwright E2E tests
├── install_demo_generator_skill.sh  # Standalone skill installer
└── playwright.config.ts          # Test config (targets localhost:9000)

Extending — adding a context block

Create a Markdown file in the appropriate .claude/skills/databricks-demo-generator/references/blocks/ subdirectory (domains/, capabilities/, or patterns/) with YAML frontmatter:

---
name: My New Block
slug: my-new-block
category: capability
tags: [tag1, tag2]
description: One-line summary of what this block provides.
related: [genie, retail]
---

Block content goes here — terminology, best practices, configuration guidance, etc.

Blocks on disk are automatically available to the agent's system prompt for all new projects.

---

⭐ Star history

---

📜 License & attribution — click to expand

Licensed under the Databricks License. Built on top of and powered by the following open-source projects.

Core runtimes & SDKs

Package	Version	License	Project URL
claude-agent-sdk	≥0.2.83	MIT	https://github.com/anthropics/claude-agent-sdk
databricks-sdk	≥0.114.0	Apache-2.0	https://github.com/databricks/databricks-sdk-py
databricks-connect	≥16.1,<16.2	Databricks	https://docs.databricks.com/dev-tools/databricks-connect.html
ai-dev-kit	—	Databricks	https://github.com/databricks-solutions/ai-dev-kit

Backend (Python)

Package	Version	License	Project URL
fastapi	≥0.119.0	MIT	https://github.com/fastapi/fastapi
uvicorn	≥0.37.0	BSD-3-Clause	https://github.com/encode/uvicorn
pydantic-settings	≥2.11.0	MIT	https://github.com/pydantic/pydantic-settings
sqlmodel	≥0.0.27	MIT	https://github.com/tiangolo/sqlmodel
sqlalchemy	≥2.0	MIT	https://github.com/sqlalchemy/sqlalchemy
alembic	≥1.16	MIT	https://github.com/sqlalchemy/alembic
psycopg	≥3.2.11	LGPL-3.0	https://github.com/psycopg/psycopg
pglite	≥0.2.0	Apache-2.0	https://github.com/electric-sql/pglite
httpx	≥0.28.0	BSD-3-Clause	https://github.com/encode/httpx
watchdog	≥4.0.0	Apache-2.0	https://github.com/gorakhargosh/watchdog
pyyaml	≥6.0	MIT	https://github.com/yaml/pyyaml
python-docx	≥1.1.0	MIT	https://github.com/python-openxml/python-docx
mcp	≥1.0.0	MIT	https://github.com/modelcontextprotocol/python-sdk
fastmcp	==3.1.1	Apache-2.0	https://github.com/jlowin/fastmcp
sqlglot	≥20.0.0	MIT	https://github.com/tobymao/sqlglot
sqlfluff	≥3.0.0	MIT	https://github.com/sqlfluff/sqlfluff
plutoprint	==0.19.0	MIT	https://github.com/plutoprint/plutoprint
faker	≥30.0	MIT	https://github.com/joke2k/faker

Frontend (TypeScript)

Package	Version	License	Project URL
react	19.2.3	MIT	https://github.com/facebook/react
vite	^8.0.10	MIT	https://github.com/vitejs/vite
@tanstack/react-router	1.145.7	MIT	https://github.com/TanStack/router
@tanstack/react-query	5.90.16	MIT	https://github.com/TanStack/query
tailwindcss	^4.2.4	MIT	https://github.com/tailwindlabs/tailwindcss
@radix-ui/*	^1.x	MIT	https://github.com/radix-ui/primitives
shadcn/ui	—	MIT	https://github.com/shadcn-ui/ui
motion	12.24.10	MIT	https://github.com/motiondivision/motion
lucide-react	^0.575.0	ISC	https://github.com/lucide-icons/lucide
@xyflow/react	^12.10.2	MIT	https://github.com/xyflow/xyflow
@monaco-editor/react	^4.7.0	MIT	https://github.com/suren-atoyan/monaco-react
embla-carousel-react	^8.6.0	MIT	https://github.com/davidjerleke/embla-carousel
electron	^33.4.11	MIT	https://github.com/electron/electron
playwright	— (npx)	Apache-2.0	https://github.com/microsoft/playwright

---

Built by Databricks Field Engineering.
_{Describe it. Ship it. Iterate on what matters.}