{"id":51537592,"url":"https://github.com/databricks-solutions/lakebase-for-ai-developers","last_synced_at":"2026-07-09T10:01:46.034Z","repository":{"id":370044319,"uuid":"1280688323","full_name":"databricks-solutions/lakebase-for-ai-developers","owner":"databricks-solutions","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-08T02:17:56.000Z","size":1199,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-08T04:08:07.374Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/databricks-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS.txt","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-25T20:54:47.000Z","updated_at":"2026-07-06T19:20:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/databricks-solutions/lakebase-for-ai-developers","commit_stats":null,"previous_names":["databricks-solutions/lakebase-for-ai-developers"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/databricks-solutions/lakebase-for-ai-developers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-for-ai-developers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-for-ai-developers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-for-ai-developers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-for-ai-developers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/databricks-solutions","download_url":"https://codeload.github.com/databricks-solutions/lakebase-for-ai-developers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-for-ai-developers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35295106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-09T10:01:44.654Z","updated_at":"2026-07-09T10:01:45.969Z","avatar_url":"https://github.com/databricks-solutions.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mfg-supply-chain-copilot-agent\n\nA multi-agent **Supply-Chain Planner Copilot** for manufacturing planners — a reference build for\n**custom agents on Databricks with Lakebase**. LangGraph runs on **Databricks Apps**, all durable\nstate lives on **Lakebase** (Postgres), and retrieval spans Genie, Mosaic AI Vector Search, and\nLakebase pgvector — with human-in-the-loop approval and end-to-end MLflow tracing.\n\n![Agentic Apps Architecture](docs/diagrams/Agentic_Apps_Architecture.001.png)\n\n**What it does.** A planner asks a question; a supervisor routes it to the right engine, the\ngather agents pull context, a planner proposes a recommendation, a gate decides if approval is\nneeded, and an `interrupt()` pauses for human approve/reject before `commit`. The whole run is one\nresumable MLflow trace, durable across the pause via the Lakebase checkpoint.\n\n- **Supervisor routing** — LLM-based with a keyword fallback.\n- **Three gather agents** — Knowledge (Vector Search), Analytics (Genie), Operational (Lakebase\n  pgvector hybrid similarity + SQL join to live inventory/POs).\n- **Planner + gate** — proposes a structured plan; the gate trips on cost/action-bearing answers.\n- **HITL** — `interrupt()` approval card with durable approve/reject resume from the checkpoint.\n- **Memory** — short-term threads (`AsyncCheckpointSaver`) + long-term semantic memory\n  (`AsyncDatabricksStore`: approvals, preferences, supplier notes), all on Lakebase.\n- **App** — React/Vite chat UI with a Backend Explorer drawer and 👍/👎 feedback logged to the trace.\n\n\u003e New to the project? Read **[`CLAUDE.md`](CLAUDE.md)** first — it's the keystone for architecture,\n\u003e the Lakebase-pgvector vs. Vector-Search decision, the state/memory model, and conventions.\n\n## Set up with Claude Code (fastest)\n\nThis repo is built to be driven by a coding agent. Open it in [Claude Code](https://www.claude.com/product/claude-code)\n— it auto-loads [`CLAUDE.md`](CLAUDE.md) and the vendored skills in [`.claude/skills/`](.claude/skills/)\n(`quickstart`, `run-locally`, `deploy`, …) — and just ask:\n\n\u003e **Set up this app and run it locally.**\n\nIt'll check prerequisites, run `databricks auth login`, `uv sync`, and the frontend install, wire up\n`.env`, and start both processes. To ship it, ask:\n\n\u003e **Deploy this to my Databricks workspace** (profile `\u003cp\u003e`)**.**\n\nPrefer to do it by hand? The same steps are spelled out below.\n\n## Run locally\n\nThe app is **two processes**: the FastAPI agent backend on `:8000` and the Vite/React frontend on\n`:5173` (Vite proxies `/api/*` and `/invocations` → `:8000`). The router uses\n`databricks-claude-haiku-4-5`; the planner uses `databricks-claude-opus-4-8` — `LLM_ROUTER_ENDPOINT`\n/ `LLM_PLANNER_ENDPOINT` in `.env` take either naming, classic FM API endpoints or `system.ai.*`\nAI Gateway routes.\n\n**Prerequisites** — install these before the steps below:\n\n| Tool | Version | Install |\n|---|---|---|\n| **Databricks CLI** | ≥ 1.3.0 | `brew install databricks/tap/databricks` (or [docs](https://docs.databricks.com/dev-tools/cli/install.html)) — needed for `databricks auth login` and deploy |\n| **uv** | latest | `curl -LsSf https://astral.sh/uv/install.sh \\| sh` — manages the Python env |\n| **Python** | 3.11 or 3.12 | `uv` will fetch it if missing (`\u003c3.13` — see [`pyproject.toml`](pyproject.toml)) |\n| **Node + npm** | Node 18+ | [nodejs.org](https://nodejs.org) or `brew install node` — builds/serves the frontend |\n\nYou also need a **Databricks workspace** and a CLI profile pointed at it (the `databricks auth\nlogin` step below).\n\n```bash\n# one-time\ncp .env.example .env                       # then fill in DATABRICKS_CONFIG_PROFILE + catalog/schema/Lakebase/Genie\ndatabricks auth login --host https://\u003cws\u003e.cloud.databricks.com --profile \u003cname\u003e\nuv sync                                    # Python deps\nnpm --prefix frontend install              # frontend deps\n\n# run — two terminals\nuv run start-server                        # Terminal 1 — backend on :8000\nnpm --prefix frontend run dev              # Terminal 2 — frontend on :5173 (hot reload)\n```\n\nThen open **http://localhost:5173**.\n\n- **Offline smoke test** (no workspace round-trips): `USE_STUBS=1 uv run python -m agent_server.graph._smoke`\n  runs the full path (supervisor → gather → planner → gate → HITL → commit) against in-memory\n  fakes. Stubs also kick in automatically when an endpoint isn't configured.\n- **Single-process alternative:** `npm --prefix frontend run build`, then open\n  `http://localhost:8000/ui` (the backend serves the built SPA). Two terminals is better while\n  iterating on agent code (hot reload).\n\nSee [`CLAUDE.md` → Running locally vs. on Databricks](CLAUDE.md#running-locally-vs-on-databricks-auth--config)\nfor the auth model (local profile vs. ambient credentials on Databricks).\n\n## Deploy to Databricks\n\nOne command stands up the whole demo — the App (agent + UI at `/ui`), an MLflow experiment, the\nLakebase project, the Genie space, and a setup-and-seed job for the demo dataset. It's idempotent\nand cold-start-safe.\n\n```bash\nmake deploy      PROFILE=\u003cp\u003e              # full one-shot: build · deploy · seed · Genie · verify\nmake deploy      PROFILE=\u003cp\u003e TARGET=demo  # clean prod-style names (default: dev)\nmake redeploy    PROFILE=\u003cp\u003e              # FAST: agent-server code change → deploy + restart (~30-60s)\nmake redeploy-ui PROFILE=\u003cp\u003e              # FAST: frontend change → build + deploy + restart\n```\n\n**Prereqs (one-time):** the tools from the [Prerequisites](#run-locally) table above, plus\n**workspace admin** on the target workspace and a **writable UC catalog**. The Lakebase project,\nGenie space, and seed are all handled by the deploy — no manual setup steps.\n\n\u003e **A few env gotchas bite the first deploy** — none obvious from the error text (full list:\n\u003e [`docs/DEPLOYMENT_GUIDE.md` §8](docs/DEPLOYMENT_GUIDE.md#8-troubleshooting)):\n\u003e 1. **Public PyPI is blocked** (Jamf-managed `/etc/hosts` — don't edit it). If `uv`/`make deploy`\n\u003e    fail with `Connection refused (os error 61)`, point uv at the internal proxy first:\n\u003e    `export UV_INDEX_URL=https://pypi-proxy.cloud.databricks.com/simple`.\n\u003e 2. **Databricks Connect needs compute.** If you hit `Cluster id or serverless are required`, add\n\u003e    `serverless_compute_id = auto` to your `[\u003cprofile\u003e]` in `~/.databrickscfg`. Preflight warns if\n\u003e    it's missing.\n\u003e 3. **`uc_catalog` doesn't exist on this workspace.** The committed default is just a starting\n\u003e    point — preflight fails fast with `--uc-catalog \u003cname\u003e` (or `--var uc_catalog=\u003cname\u003e`) if it's\n\u003e    not there, instead of burning the ~10min Lakebase-provisioning wait first.\n\u003e 4. **Catalog is shared with other projects.** If seeding fails with `create-synced-table ... Table\n\u003e    already exists pointing to a different project`, another project's Synced Tables already own\n\u003e    `\u003ccatalog\u003e.public.\u003ctable\u003e` (even orphaned ones block the name). Override\n\u003e    `VARS=\"lakebase_operational_schema=\u003cunique-name\u003e\"` to a schema unique to this deployment.\n\u003e\n\u003e Hitting `Genie Space resources are only supported with direct deployment mode` or\n\u003e `lineage mismatch in state files` on a workspace you've deployed to before? Those are the\n\u003e Terraform→direct engine migration and stale-state-cache cases — see the troubleshooting guide.\n\n### Which deploy fits your access\n\nThe right command depends on what you're allowed to create on the workspace:\n\n| Your access | Use | Why |\n|---|---|---|\n| Can create a SQL warehouse (default) | `make deploy PROFILE=\u003cp\u003e` | The bundle creates its own small serverless warehouse for tracing + Genie and binds it to the app. |\n| **Can't** create a warehouse (restricted workspace) | `make deploy PROFILE=\u003cp\u003e TARGET=byo VARS=\"sql_warehouse_id=\u003cexisting-id\u003e\"` | The `byo` target omits the warehouse resource and reuses one you already have `CAN USE` on. Everything else is identical. |\n| Want clean, non-user-prefixed names (shared demo) | add `TARGET=demo` | `mode: production` naming instead of the user-prefixed `dev` names. |\n| Bringing your own data (skip the demo seed) | add `SEED=false` | Deploys the app + infra but skips the setup-and-seed job. |\n| `uc_catalog` is shared across projects/teams | add `VARS=\"lakebase_operational_schema=\u003cunique-name\u003e\"` | Synced Tables are namespaced `catalog.schema.table`; the default `public` schema can collide with another project's tables of the same name. |\n\nYou can also point at your own catalog/schema inline without editing `databricks.yml`, e.g.\n`VARS=\"uc_catalog=main uc_schema=planner\"`. Full option list: [`docs/DEPLOY.md`](docs/DEPLOY.md).\n\n- **Quick reference:** [`docs/DEPLOY.md`](docs/DEPLOY.md).\n- **Full new-workspace walkthrough + permissions checklist:** [`docs/DEPLOYMENT_GUIDE.md`](docs/DEPLOYMENT_GUIDE.md).\n- **Never delete the app — redeploy in place.** Deleting the App destroys its service principal and\n  orphans the Lakebase-owned schemas. See [`docs/lakebase-apps-permissions.md`](docs/lakebase-apps-permissions.md).\n\n## Try it\n\nSeed-data anchors (use the exact values): **Henkel AG (SUP-001)**, hero SKU **SKU-1001**\n(Structural Epoxy Adhesive), **40 on-hand** at DC-EAST, open POs **500** (Henkel, PO-2026-0042)\n\\+ **300** (DuPont, PO-2026-0043) = **760-unit gap**; Henkel status **at_risk (82.0)**; alternate\nsupplier **DuPont (SUP-002)**. Demo \"today\" = 2026-06-05.\n\n**Single-engine routing** — verify the router picks the right agent:\n\n| Question | Routes to |\n|---|---|\n| What is the total open PO quantity by supplier for Q4 2026? | analytics (Genie) |\n| What do our Caterpillar contracts say about late-delivery penalties? | knowledge (Vector Search) |\n| Find similar past quality incidents to Henkel's SKU-1001 adhesive cracking. | operational (Lakebase hybrid SQL) |\n\n**The hero loop (multi-agent + HITL):**\n\n\u003e *Henkel's SKU-1001 has recurring adhesive cracking — show me similar past cases joined to on-hand\n\u003e inventory and open POs, and recommend a mitigation.*\n\n→ `interrupt()` fires → approval card; the run pauses (Lakebase checkpoint); approve → `commit`\nwrites memory. Also test the **reject** path: approvals are always written (audit), but\npreferences/supplier-notes are written **only on approve**.\n\n**Cross-session memory:** seed memory via `GET /_seed_demo_memories` (or run/approve the hero\nquestion), then in a **new** chat ask *\"How should we handle the Henkel SKU-1001 coverage gap?\"* →\n`hydrate_memory` recalls the prior approved decision and the planner cites it.\n\n**Suggested 10-minute sequence:** single-engine #1 → single-engine #3 (show the hybrid SQL) → hero\nloop (HITL approve + commit) → new chat, cross-session recall. That hits the router, all three\ngather engines, HITL, checkpoint durability, and long-term memory.\n\n## Repo map\n\n| Path | What |\n|---|---|\n| [`CLAUDE.md`](CLAUDE.md) | Shared context — read first |\n| [`.env.example`](.env.example) | Local config template (`cp` → `.env`) |\n| [`pyproject.toml`](pyproject.toml) | Dependency contract (`uv sync`) + the `start-server` entrypoint |\n| [`databricks.yml`](databricks.yml) | DABs bundle — App, Lakebase, Genie space, experiment, seed job, `dev`/`demo` targets |\n| [`Makefile`](Makefile) / [`scripts/`](scripts/) | Deploy + redeploy wrappers; `scripts/deploy.sh` holds all deploy logic |\n| [`agent_server/`](agent_server/) | FastAPI server, agent (`@invoke`/`@stream`), web routes, config, the `graph/` (supervisor + gather + planner + gate + HITL + commit), `tools/`, long-term `memory.py`, `evaluation/` flywheel |\n| [`data/`](data/) | Synthetic operational data, the pgvector hybrid query, the Knowledge VS pipeline, and the Genie schema + space creation |\n| [`frontend/`](frontend/) | React + Vite chat UI (dev on `:5173`; built SPA served at `/ui`) |\n| [`.claude/skills/`](.claude/skills/) | Vendored, pinned build + Databricks + MLflow skills |\n\n## Docs\n\n- [`docs/architecture.md`](docs/architecture.md) — multi-agent design, topology, the pgvector/VS split, [end-to-end diagrams](docs/architecture.md#end-to-end-architecture)\n- [`docs/DEPLOY.md`](docs/DEPLOY.md) · [`docs/DEPLOYMENT_GUIDE.md`](docs/DEPLOYMENT_GUIDE.md) — deploy quick reference and full walkthrough\n- [`docs/lakebase-apps-permissions.md`](docs/lakebase-apps-permissions.md) — App SP + Lakebase schema ownership\n- [`docs/storyboard.md`](docs/storyboard.md) — the demo scenarios + planner persona\n- [`docs/references.md`](docs/references.md) — all code/demo/doc links\n\n## Primary reference\n\nBuilt on the\n[`agent-langgraph-advanced`](https://github.com/databricks/app-templates/tree/main/agent-langgraph-advanced)\ntemplate (LangGraph + Lakebase memory + MLflow). This repo swaps the template's Next.js UI for a\nVite + React frontend and ships its own vendored skills.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabricks-solutions%2Flakebase-for-ai-developers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabricks-solutions%2Flakebase-for-ai-developers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabricks-solutions%2Flakebase-for-ai-developers/lists"}