feat(apps): add the Impulse App as apps/adhoc-reporting

.github/workflows/app-adhoc-reporting.yml

@@ -0,0 +1,82 @@
+name: app-adhoc-reporting
+
+# Tests the ad-hoc reporting app in apps/adhoc-reporting. Framework changes (src/) trigger it as
+# well, because the contract tests build the app's generated notebooks against the framework
+# source of the same commit. Not a required check, so the framework's own CI stays unaffected.
+on:
+  pull_request:
+    types: [ opened, synchronize, ready_for_review ]
+    paths:
+      - 'apps/adhoc-reporting/**'
+      - 'src/**'
+      - '.github/workflows/app-adhoc-reporting.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'apps/adhoc-reporting/**'
+      - 'src/**'
+      - '.github/workflows/app-adhoc-reporting.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Same fork gate as acceptance.yml: fork PRs get no OIDC token, so JFrog auth cannot run.
+  not-a-fork:
+    runs-on:
+      group: databrickslabs-protected-runner-group
+      labels: linux-ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork
+    steps:
+      - run: echo "Not a fork PR, proceeding"
+
+  test:
+    name: Test the app
+    needs: not-a-fork
+    runs-on:
+      group: databrickslabs-protected-runner-group
+      labels: linux-ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: apps/adhoc-reporting
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        with:
+          version: "0.11.2"
+          checksum: "7ac2ca0449c8d68dae9b99e635cd3bc9b22a4cb1de64b7c43716398447d42981"
+
+      # The app runs on Python 3.11 (Databricks Apps), the framework contract tests on 3.12.
+      - name: Install Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: |
+            3.11
+            3.12
+
+      - name: Install Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: "22"
+
+      # After the setup steps: the action only configures the package managers it finds.
+      - name: Setup for JFrog
+        uses: ./.github/actions/jfrog-auth
+
+      - name: Unit and contract tests (pinned framework release)
+        run: make test
+
+      - name: Contract tests (framework at this commit)
+        run: make test FRAMEWORK=../..
+
+      - name: Build the frontend
+        run: make frontend

CONTRIBUTING.md

@@ -48,6 +48,12 @@ Notes specific to Impulse:
   `gold` schemas. You don't need a Databricks workspace to run the unit tests.
 - Spark warehouse output is written to `spark-warehouse/` (gitignored).
 
+## Apps
+
+The apps in [`apps/`](apps/) are separate projects with their own dependencies, tests, Makefile
+and CI workflow; the root `make` targets don't include them. For developing the Impulse App see
+[`apps/adhoc-reporting/README.md`](apps/adhoc-reporting/README.md).
+
 ## Code style
 
 We use **black** for formatting and **ruff** for linting. Both are configured in

NOTICE.md

@@ -8,7 +8,7 @@ This Software includes software developed at Databricks (https://www.databricks.
 
 Dependencies are grouped below by license. Each table row lists a third-party package bundled or used at build time, along with its license and upstream source. Dev-only dependencies (linters, test runners, build tooling) are marked `dev`; runtime dependencies are marked `runtime`.
 
-This NOTICE covers the full transitive Python graph (`uv.lock` via `pip-licenses`) plus the **direct** docs-site dependencies declared in `docs/impulse/package.json`.
+This NOTICE covers the full transitive Python graph (`uv.lock` via `pip-licenses`) plus the **direct** docs-site dependencies declared in `docs/impulse/package.json`. The optional Impulse App in `apps/adhoc-reporting` has its own section, [Impulse App](#impulse-app).
 
 ---
 
@@ -187,6 +187,111 @@ Full license text: [https://docs.python.org/3/license.html](https://docs.python.
 
 ---
 
+## Impulse App
+
+The optional Impulse App in `apps/adhoc-reporting` has its own dependencies, grouped below by license in the same way. This section covers its full transitive Python graph (`apps/adhoc-reporting/uv.lock` via `pip-licenses`) plus the **direct** frontend dependencies declared in `apps/adhoc-reporting/frontend/package.json`.
+
+### Apache License 2.0
+
+Full license text: [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| cryptography | 48.0.0 | Python | runtime | The Python Cryptographic Authority and individual contributors <[email protected]> | [https://github.com/pyca/cryptography](https://github.com/pyca/cryptography) |
+| databricks-sdk | 0.115.0 | Python | runtime | _see upstream_ | [https://databricks-sdk-py.readthedocs.io](https://databricks-sdk-py.readthedocs.io) |
+| google-auth | 2.53.0 | Python | runtime | Google Cloud Platform | [https://github.com/googleapis/google-auth-library-python](https://github.com/googleapis/google-auth-library-python) |
+| packaging | 26.3 | Python | dev | Donald Stufft <[email protected]> | [https://github.com/pypa/packaging](https://github.com/pypa/packaging) |
+| requests | 2.34.2 | Python | runtime | Kenneth Reitz <[email protected]> | [https://github.com/psf/requests](https://github.com/psf/requests) |
+| typescript | 5.9.3 | npm | dev | Microsoft Corp. | [https://github.com/microsoft/TypeScript](https://github.com/microsoft/TypeScript) |
+
+### BSD 2-Clause License
+
+Full license text: [https://opensource.org/licenses/BSD-2-Clause](https://opensource.org/licenses/BSD-2-Clause).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| pyasn1 | 0.6.3 | Python | runtime | Ilya Etingof <[email protected]> | [https://github.com/pyasn1/pyasn1](https://github.com/pyasn1/pyasn1) |
+| Pygments | 2.21.0 | Python | dev | Georg Brandl <[email protected]> | [https://pygments.org](https://pygments.org) |
+
+### BSD 3-Clause License
+
+Full license text: [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| click | 8.4.1 | Python | runtime | _see upstream_ | [https://github.com/pallets/click/](https://github.com/pallets/click/) |
+| httpcore | 1.0.9 | Python | dev | Tom Christie <[email protected]> | [https://www.encode.io/httpcore/](https://www.encode.io/httpcore/) |
+| idna | 3.17 | Python | runtime | Kim Davies <[email protected]> | [https://github.com/kjd/idna](https://github.com/kjd/idna) |
+| protobuf | 6.33.6 | Python | runtime | [email protected] | [https://developers.google.com/protocol-buffers/](https://developers.google.com/protocol-buffers/) |
+| pycparser | 3.0 | Python | runtime | Eli Bendersky <[email protected]> | [https://github.com/eliben/pycparser](https://github.com/eliben/pycparser) |
+| starlette | 1.2.1 | Python | runtime | Tom Christie <[email protected]> | [https://github.com/Kludex/starlette](https://github.com/Kludex/starlette) |
+| uvicorn | 0.48.0 | Python | runtime | Tom Christie <[email protected]> | [https://uvicorn.dev/](https://uvicorn.dev/) |
+
+### BSD License
+
+Full license text: [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| colorama | 0.4.6 | Python | runtime | Jonathan Hartley <[email protected]> | [https://github.com/tartley/colorama](https://github.com/tartley/colorama) |
+| httpx | 0.28.1 | Python | dev | Tom Christie <[email protected]> | [https://github.com/encode/httpx](https://github.com/encode/httpx) |
+| pyasn1_modules | 0.4.2 | Python | runtime | Ilya Etingof | [https://github.com/pyasn1/pyasn1-modules](https://github.com/pyasn1/pyasn1-modules) |
+
+### ISC License
+
+Full license text: [https://opensource.org/licenses/ISC](https://opensource.org/licenses/ISC).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| lucide-react | 1.48.0 | npm | runtime | Eric Fennis | [https://github.com/lucide-icons/lucide](https://github.com/lucide-icons/lucide) |
+
+### MIT License
+
+Full license text: [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| annotated-doc | 0.0.4 | Python | runtime | Sebastián Ramírez <[email protected]> | [https://github.com/fastapi/annotated-doc](https://github.com/fastapi/annotated-doc) |
+| annotated-types | 0.7.0 | Python | runtime | Adrian Garcia Badaracco <[email protected]>, Samuel Colvin <[email protected]>, Zac Hatfield-Dodds <[email protected]> | [https://github.com/annotated-types/annotated-types](https://github.com/annotated-types/annotated-types) |
+| anyio | 4.13.0 | Python | runtime | Alex Grönholm <[email protected]> | [https://anyio.readthedocs.io/en/stable/versionhistory.html](https://anyio.readthedocs.io/en/stable/versionhistory.html) |
+| cffi | 2.0.0 | Python | runtime | Armin Rigo, Maciej Fijalkowski | [https://cffi.readthedocs.io/en/latest/whatsnew.html](https://cffi.readthedocs.io/en/latest/whatsnew.html) |
+| charset-normalizer | 3.4.7 | Python | runtime | "Ahmed R. TAHRI" <[email protected]> | [https://github.com/jawah/charset_normalizer/blob/master/CHANGELOG.md](https://github.com/jawah/charset_normalizer/blob/master/CHANGELOG.md) |
+| fastapi | 0.136.3 | Python | runtime | Sebastián Ramírez <[email protected]> | [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi) |
+| h11 | 0.16.0 | Python | runtime | Nathaniel J. Smith | [https://github.com/python-hyper/h11](https://github.com/python-hyper/h11) |
+| iniconfig | 2.3.0 | Python | dev | Ronny Pfannschmidt <[email protected]>, Holger Krekel <[email protected]> | [https://github.com/pytest-dev/iniconfig](https://github.com/pytest-dev/iniconfig) |
+| pluggy | 1.6.0 | Python | dev | Holger Krekel <[email protected]> | [https://github.com/pytest-dev/pluggy](https://github.com/pytest-dev/pluggy) |
+| pydantic | 2.13.4 | Python | runtime | Samuel Colvin <[email protected]>, Eric Jolibois <[email protected]>, Hasan Ramezani <[email protected]>, Adrian Garcia Badaracco <[email protected]>, Terrence Dorsey <[email protected]>, David Montague <[email protected]>, Serge Matveenko <[email protected]>, Marcelo Trylesinski <[email protected]>, Sydney Runkle <[email protected]>, David Hewitt <[email protected]>, Alex Hall <[email protected]>, Victorien Plot <[email protected]> | [https://github.com/pydantic/pydantic](https://github.com/pydantic/pydantic) |
+| pydantic_core | 2.46.4 | Python | runtime | Samuel Colvin <[email protected]>, Adrian Garcia Badaracco <[email protected]>, David Montague <[email protected]>, David Hewitt <[email protected]>, Sydney Runkle <[email protected]>, Victorien Plot <[email protected]> | [https://github.com/pydantic](https://github.com/pydantic) |
+| pytest | 9.1.1 | Python | dev | Brianna Laugher, Bruno Oliveira, Floris Bruynooghe, Freya Bruhin, Holger Krekel, Others (See AUTHORS), Ronny Pfannschmidt | [https://docs.pytest.org/en/latest/](https://docs.pytest.org/en/latest/) |
+| PyYAML | 6.0.3 | Python | runtime | Kirill Simonov | [https://pyyaml.org/](https://pyyaml.org/) |
+| typing-inspection | 0.4.2 | Python | runtime | Victorien Plot <[email protected]> | [https://github.com/pydantic/typing-inspection](https://github.com/pydantic/typing-inspection) |
+| urllib3 | 2.7.0 | Python | runtime | Andrey Petrov <[email protected]> | [https://github.com/urllib3/urllib3/blob/main/CHANGES.rst](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst) |
+| @types/react | 19.3.0 | npm | dev | _see upstream_ | [https://github.com/DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) |
+| @types/react-dom | 19.3.0 | npm | dev | _see upstream_ | [https://github.com/DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) |
+| @vitejs/plugin-react | 6.1.1 | npm | dev | Evan You | [https://github.com/vitejs/vite-plugin-react](https://github.com/vitejs/vite-plugin-react) |
+| plotly.js-cartesian-dist-min | 3.7.0 | npm | runtime | Plotly, Inc. | [https://github.com/plotly/plotly.js](https://github.com/plotly/plotly.js) |
+| react | 19.3.0 | npm | runtime | _see upstream_ | [https://github.com/react/react](https://github.com/react/react) |
+| react-dom | 19.3.0 | npm | runtime | _see upstream_ | [https://github.com/react/react](https://github.com/react/react) |
+| vite | 8.3.1 | npm | dev | Evan You | [https://github.com/vitejs/vite](https://github.com/vitejs/vite) |
+
+### Mozilla Public License 2.0
+
+Full license text: [https://www.mozilla.org/en-US/MPL/2.0/](https://www.mozilla.org/en-US/MPL/2.0/).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| certifi | 2026.5.20 | Python | runtime | Kenneth Reitz | [https://github.com/certifi/python-certifi](https://github.com/certifi/python-certifi) |
+
+### Python Software Foundation License
+
+Full license text: [https://docs.python.org/3/license.html](https://docs.python.org/3/license.html).
+
+| Package | Version | Ecosystem | Type | Copyright | Source |
+| --- | --- | --- | --- | --- | --- |
+| typing_extensions | 4.15.0 | Python | runtime | "Guido van Rossum, Jukka Lehtosalo, Łukasz Langa, Michael Lee" <[email protected]> | [https://github.com/python/typing_extensions](https://github.com/python/typing_extensions) |
+
+---
+
 ## Bundled Datasets
 
 Datasets and other non-code assets distributed with this repository, with their attribution requirements. These are listed both here and as rows in the license tables above.

README.md

@@ -96,6 +96,12 @@ databricks workspace import-dir skills /Workspace/.assistant/skills
 
 Genie picks them up on next use — verify with *"List the Impulse skills you can use."* For Claude Code and other tools (including how to refresh after edits), see [`skills/README.md`](skills/README.md).
 
+## Apps
+
+The [`apps/`](apps/) folder contains optional Databricks Apps built on Impulse. They are separate projects, not part of the `databricks-impulse` package, and are installed on their own.
+
+- [`apps/adhoc-reporting`](apps/adhoc-reporting/) — the **Impulse App**: build reports step by step or by describing them to an assistant, run them on serverless compute and chart the results. See the [Impulse App documentation](https://databrickslabs.github.io/impulse/app/) for requirements, installation and architecture.
+
 ## Requirements
 
 Python 3.12, PySpark 4.0, Delta Lake 4.0. The full dependency list is in [pyproject.toml](pyproject.toml).

apps/adhoc-reporting/.env.example

@@ -0,0 +1,4 @@
+DATABRICKS_CONFIG_PROFILE=
+DATABRICKS_WAREHOUSE_ID=
+IMPULSE_DEMO_CATALOG=
+IMPULSE_DEMO_SCHEMA=

apps/adhoc-reporting/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.venv/
+node_modules/
+.claude/
+*.egg-info/
+.DS_Store
+CLAUDE.md
+.databricks/
+.vscode/
+frontend/dist/
+*.tsbuildinfo
+.isaac/
+.env

apps/adhoc-reporting/.python-version

@@ -0,0 +1 @@
+3.11

apps/adhoc-reporting/Makefile

@@ -0,0 +1,61 @@
+-include .env
+export
+
+APP ?= impulse-adhoc-reporting
+BUNDLE_VAR_warehouse_id = $(DATABRICKS_WAREHOUSE_ID)
+WHEEL := $(shell sed -n 's/^wheel = "\(.*\)"/\1/p' impulse.lock)
+# Framework the contract tests build against: the pinned release wheel, or the source in this repo with FRAMEWORK=../..
+FRAMEWORK ?= $(WHEEL)
+# Install from uv.lock as it is, so a local package mirror can't rewrite it; only `make lock` changes it.
+UV_RUN := uv run --frozen --python 3.11
+DEPLOY_ENV := DATABRICKS_CONFIG_PROFILE DATABRICKS_WAREHOUSE_ID
+WORKSPACE_ENV := $(DEPLOY_ENV) IMPULSE_DEMO_CATALOG IMPULSE_DEMO_SCHEMA
+require = @for v in $(1); do [ -n "$$(printenv $$v)" ] || { echo "$$v is not set: copy .env.example to .env and fill it in"; exit 1; }; done
+
+.PHONY: lock test live smoke smoke-persist eval seed frontend deploy logs
+
+lock:
+	uv lock --python 3.11
+	@# Keep the lockfiles on the public registries, also when they were resolved through a Databricks mirror.
+	@perl -pi -e 's|registry = "https://[^"]*"|registry = "https://pypi.org/simple"|g' uv.lock
+	@perl -pi -e 's|https://pypi-proxy\.[a-z]+\.databricks\.com/|https://files.pythonhosted.org/|g' uv.lock
+	@perl -pi -e 's|https://npm-proxy\.[a-z]+\.databricks\.com/|https://registry.npmjs.org/|g' frontend/package-lock.json
+	uv export --format requirements-txt --no-hashes --no-dev --no-emit-project --no-annotate --no-header --frozen -o requirements.txt
+
+test:
+	$(UV_RUN) pytest -q tests/unit
+	uv run --no-project --python 3.12 --with "databricks-impulse[local-dev] @ $(FRAMEWORK)" --with fastapi --with pyyaml --with pytest \
+		pytest -q -p no:cacheprovider -W ignore::UserWarning tests/contract
+
+live:
+	$(call require,$(WORKSPACE_ENV))
+	$(UV_RUN) pytest -q tests/live
+
+smoke:
+	$(call require,$(WORKSPACE_ENV))
+	PYTHONPATH=. $(UV_RUN) python scripts/smoke_run.py --name demo_full --spec tests/fixtures/specs/demo_full.json
+
+smoke-persist:
+	$(call require,$(WORKSPACE_ENV))
+	PYTHONPATH=. $(UV_RUN) python scripts/smoke_run.py --name demo_full_persist --spec tests/fixtures/specs/demo_full.json --persist
+
+eval:
+	$(call require,$(WORKSPACE_ENV))
+	PYTHONPATH=. $(UV_RUN) python scripts/eval_agent.py
+
+seed:
+	$(call require,$(WORKSPACE_ENV))
+	uv run --no-project --python 3.12 --with databricks-sdk python scripts/seed_demo.py
+
+frontend:
+	cd frontend && npm ci --silent && npm run build
+
+deploy: frontend
+	$(call require,$(DEPLOY_ENV))
+	@git diff --quiet -- . && git diff --cached --quiet -- . || (echo "Commit changes before deploying" && exit 1)
+	DATABRICKS_BUNDLE_ENGINE=direct databricks bundle deploy
+	DATABRICKS_BUNDLE_ENGINE=direct databricks bundle run impulse_app
+
+logs:
+	$(call require,DATABRICKS_CONFIG_PROFILE)
+	databricks apps logs $(APP) --tail-lines 300