# Exokit — Your Databricks Development Power Suit

Generate production-grade Databricks demo projects in minutes. Each demo includes lakehouse pipelines (bronze/silver/gold), ML models, AI/BI dashboards, Genie spaces, an AI agent use case, and a full-stack showcase app — all scaffolded with governance, agents, and skills so Claude Code can continue building.

## Prerequisites

| Tool | Required | Install |
|------|----------|---------|
| **Python** | >= 3.11 | `brew install python@3.11` or [python.org](https://python.org) |
| **uv** | >= 0.4 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| **Node.js** | >= 18 | `brew install node` or [nodejs.org](https://nodejs.org) |
| **Databricks CLI** | >= 0.200 | `brew tap databricks/tap && brew install databricks` |
| **APX** | >= 0.3 | `uv tool install apx` (for app scaffolding) |
| **Claude Code** | latest | [claude.ai/claude-code](https://claude.ai/claude-code) |

**Databricks authentication** — You need a configured CLI profile:
```bash
databricks configure --profile my-workspace
```

## Installation

### Option 1: Install as a global CLI tool (recommended)

```bash
# Clone the repo
git clone <repo-url> exokit
cd exokit

# Install globally — available from anywhere
uv tool install .

# Verify
exokit --help
```

### Option 2: Install with pipx

```bash
pipx install /path/to/exokit
exokit --help
```

### Option 3: Run from source (for development)

```bash
git clone <repo-url> exokit
cd exokit
uv sync
uv run exokit --help
```

## Quick Start

### 1. Check prerequisites

```bash
exokit validate --profile my-workspace
```

This checks that all required tools are installed and Databricks auth is valid.

### 2. Scaffold and deploy a new demo

```bash
exokit init my-demo-project
```

The CLI will ask you 8 questions:

| Question | Example |
|----------|---------|
| Company name | ACME Bank |
| Industry | fsi |
| Unity Catalog name | acme_fsi_demo |
| SQL Warehouse ID | 862f1d757f0424f7 |
| Workspace host URL | https://fevm-middle-east.cloud.databricks.com |
| Databricks CLI profile | me-aws |
| Lakebase connection URL | postgresql://... (optional) |
| Notification email | you@company.com |

After answering, exokit scaffolds the project AND deploys a working hello-world demo end-to-end:

1. Creates the Unity Catalog
2. Renders 48+ templates (CLAUDE.md, databricks.yml, jobs, pipelines, notebooks, scripts)
3. Scaffolds the full-stack app (APX + React + FastAPI)
4. Deploys the lakehouse bundle (data gen + DLT pipeline + ML training + Genie Space)
5. Deploys the app (build + upload + SP permissions)
6. Prints a resource table with links to every deployed resource

The result is a fully running hello-world demo:

```
my-demo-project/
├── CLAUDE.md                    # Claude's operating manual (~400 lines)
├── .claude/
│   ├── agents/                  # 4 specialist agents
│   ├── skills/                  # Bundled Databricks skills
│   └── commands/                # /build-next, /deploy, /talk-track
├── databricks.yml               # Asset Bundle config
├── conf/
│   ├── demo_manifest.json       # Wave-by-wave build plan
│   └── catalog_schema.json      # Unity Catalog structure
├── resources/
│   ├── jobs/                    # Data gen + ML training job configs
│   └── pipelines/               # DLT pipeline config
├── src/
│   ├── data_generation/         # Structured + unstructured data
│   ├── pipelines/               # Bronze / Silver / Gold DLT SQL
│   ├── ml/                      # Feature engineering + model training
│   ├── dashboards/              # Dashboard utilities
│   └── agents/                  # Databricks agent framework
├── apps/main-app/               # Full-stack React + FastAPI app
├── docs/                        # Architecture, standards, progress
├── scripts/                     # Deploy, setup-catalog, validate
├── .env.example                 # Environment variables
└── .mcp.json                    # MCP server config (ai-dev-kit)
```

### 3. Start building with Claude

```bash
cd my-demo-project
claude
```

Claude reads the CLAUDE.md and demo_manifest.json — it knows exactly what to build. Use `/build-next` to build wave by wave, or just describe what you want.

## What Each Demo Includes (7 Layers)

| Layer | What Gets Built |
|-------|-----------------|
| 1. Raw Data | Structured tables (Spark + Faker) + unstructured documents (PDFs for RAG) |
| 2. Pipelines | Bronze (Auto Loader) → Silver (quality constraints) → Gold (business metrics) |
| 3. Features | Feature engineering from gold tables using Databricks Feature Store |
| 4. ML Models | AutoML training, MLflow tracking, model registration in Unity Catalog |
| 5. Dashboards | AI/BI Lakeview dashboards + Genie Spaces for natural language queries |
| 6. AI Agent | RAG agent with unstructured data + UC function tools |
| 7. App | Full-stack React + FastAPI showcase app on Databricks Apps + Lakebase |

## Commands

```bash
# Scaffold + deploy a new demo project
exokit init [OUTPUT_DIR]

# Check prerequisites
exokit validate [--profile PROFILE]

# Refresh bundled skills from latest ai-dev-kit
exokit update-skills [PROJECT_DIR] [--source DIR]
```

## How It Works

```
You answer questions  →  exokit scaffolds the project  →  Claude builds the content
     (8 questions)         (deterministic templates)        (industry-specific)
```

**Deterministic scaffold** — The project structure, governance, configs, and agent definitions are always generated the same way for a given set of answers. No randomness, no AI guessing.

**Claude-driven content** — The actual data schemas, DLT SQL, ML models, dashboard KPIs, agent tools, and app pages are generated by Claude based on the industry and use case. Claude reads the CLAUDE.md and knows exactly what patterns to follow.

## Governance

Every generated project includes:

- **CLAUDE.md** (~400 lines) — Tech stack, architecture rules, wave structure, quality gates, missing context protocol
- **4 specialist agents** — lakehouse-dev, app-dev, dashboard-dev, reviewer
- **Wave-based execution** — 5 waves with quality gates between each
- **Session resilience** — demo_manifest.json + PROGRESS.md + memory files survive context resets
- **Bundled skills** — Databricks DLT, jobs, dashboards, ML serving, agent bricks, and more

## App Architecture

The showcase app uses production-grade patterns:

- **Backend**: FastAPI + Databricks SDK + Statement Execution API
- **Frontend**: React 19 + TypeScript + Vite + Tailwind CSS + shadcn/ui
- **State**: TanStack Query (server) + Zustand (client)
- **API Client**: Auto-generated from FastAPI's OpenAPI spec
- **Auth**: Service Principal for SQL queries (CAN_USE warehouse + UC grants)
- **Architecture**: 3-layer backend (Router → Service → Repository)

## Development (Contributing to Exokit)

```bash
# Install dev dependencies
uv sync

# Run tests
uv run pytest tests/ -v

# Run quality gates
uv run ruff check src/ tests/ --fix
uv run ruff format src/ tests/
uv run mypy src/exokit/
uv run pytest tests/ -v --cov=src/exokit

# Current: 444 tests, 82% coverage
```

## Roadmap

- [x] **Spec 001**: Scaffold engine (CLI + templates + APX integration)
- [x] **Spec 002**: Feedback fixes from FSI demo build (37 items)
- [x] **Hello-world**: End-to-end verified (data gen, DLT, ML, dashboard, Genie, app)
- [ ] **V2**: Web app with wizard UI + embedded Claude chat (Databricks App)
