Manager Helper

Help managers resolve complex workplace conflicts in minutes—not weeks—via multi-agent discussion that synthesizes three stakeholder perspectives into an actionable Resolve.

Built on Databricks Apps, Lakebase Postgres, LangGraph, and MLflow, with a React/Vite frontend and Databricks Asset Bundle deployment.

Advisory only — Resolve output is not HR, legal, or disciplinary authority.

---

How it works

Step	Who	Action
1	Employees (A / B / C)	Chat independently → messages persist to Lakebase
2	Manager	Discuss → LangGraph drafts a Resolve (pending)
3	Manager	Run sync → async notebook job logs case data to MLflow
4	Manager	Approve or Reject → only approved is official

Employee chat never waits on MLflow or notebook completion.

Two-clock architecture

Clock 1 — User-facing (fast)
  Perspective UI → FastAPI → Lakebase write → immediate response
  Manager Discuss → LangGraph (meta-llama-3-3-70b-instruct) → resolves (pending)
  Manager approve/reject → resolves (approved | rejected)

Clock 2 — Observability (async, manager-click only)
  Run sync → bundle job → platform/notebooks/mlflow_lakebase_sync.py → MLflow experiment

Path	MLflow in request?	LLM?
Employee chat POST	No	No
Manager Discuss	No	Yes (LangGraph)
Manager Run sync	No (notebook job)	No

---

Repository layout

Path	Purpose
frontend/	React/Vite UI — three perspective chats + manager Resolve view
src/app/	FastAPI backend (Databricks App source)
platform/	Bundle jobs, Lakebase/UC SQL, MLflow sync notebook, deploy runbook
resources/	Databricks Asset Bundle app resource wiring
tests/	Backend, API, agent, and notebook tests
databricks.yml	Bundle definition (dev target)

Deeper docs: platform/README.md · frontend/README.md · src/app/app/README.md

---

Prerequisites

• Python 3.11+
• uv for Python deps (or pip install -r src/app/requirements.txt)
• Node.js 18+ (frontend build)
• Databricks CLI with OAuth profile auth
• Lakebase project provisioned for dev (see platform/lakebase/dev.md)

---

Setup (every clone)

uv sync --group dev
cp .env.example .env
databricks auth login --profile DEFAULT   # OAuth profile — not a PAT

Do not commit .env or set DATABRICKS_TOKEN in repo files. Use CLI profile auth only.

Optional workspace-specific bundle overrides: copy databricks.local.yml.example → databricks.local.yml (gitignored).

---

Local development

Backend (in-memory DB)

cd src/app
USE_IN_MEMORY_DB=true USE_MOCK_LLM=true USE_MOCK_JOB_RUNNER=true \
  MANAGER_EMAILS=manager@example.test ALLOW_DEV_ANONYMOUS=true \
  uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend (Vite dev server)

cd frontend
npm install
npm run dev

Proxies /api to http://127.0.0.1:8000.

Tests

uv run pytest
databricks bundle validate -t dev
cd frontend && npm run build

Frontend build output goes to src/app/static/ (gitignored; required before deploy).

---

Deploy to dev

Full runbook: platform/deploy/dev.md

cd frontend && npm ci && npm run build && cd ..
uv sync --group dev
databricks bundle validate -t dev
databricks bundle deploy -t dev
databricks bundle run app -t dev

Post-deploy (required)

Set in the Databricks app UI — not in committed config:

Variable	Purpose
MANAGER_EMAILS	Comma-separated manager workspace emails (routes fail closed until set)
LAKEBASE_ENDPOINT	Usually injected via bundle postgres resource binding
MLFLOW_SYNC_JOB_ID	Injected via bundle mlflow-sync-job resource
MLFLOW_EXPERIMENT	/Shared/manager-helper/conflict-resolution

Never enable USE_IN_MEMORY_DB, USE_MOCK_LLM, USE_MOCK_JOB_RUNNER, or ALLOW_DEV_ANONYMOUS in deployed apps.

---

UI routes

Path	Screen
/perspective-a	Perspective A chat
/perspective-b	Perspective B chat
/perspective-c	Perspective C chat
/manager	Discuss, Run sync, approve/reject + advisory disclaimer

---

Dev defaults

Resource	Name
UC catalog.schema	dev_catalog.manager
Lakebase database	manager_dev
LLM endpoint	system.ai.meta-llama-3-3-70b-instruct
MLflow experiment	/Shared/manager-helper/conflict-resolution
Bundle target	dev

---

Security

See SECURITY.md for the full policy, vulnerability reporting, and controls.

Summary:

• Auth: Databricks Apps x-forwarded-email header only — never trust client-supplied identity
• Perspective isolation: each API/UI route scoped to one perspective table
• Secrets: Databricks secret scopes or platform-injected env — never in git
• No PATs or DATABRICKS_TOKEN in repo files; use CLI OAuth profile auth locally
• Manager routes fail closed until MANAGER_EMAILS is set in the deployed app UI

---

License

Document	Purpose
LICENSE	MIT — application source in this repository
DATABRICKS_LICENSE.md	Databricks DB License — platform services and Databricks-licensed materials
NOTICE.md	Third-party open-source attributions (Python + frontend deps)

Use of Databricks workspace, Lakebase, Model Serving, Jobs, and MLflow requires a valid Databricks account and agreement with Databricks, Inc.