Skip to content

README.md

Latest commit

 

History

History
101 lines (70 loc) · 7.85 KB

README.md

File metadata and controls

101 lines (70 loc) · 7.85 KB
Raw

Kasal documentation

Kasal is an AI agent workflow orchestration platform for Databricks. This hub links every active doc, grouped by what you're trying to do.

New here? Start with Why Kasal for the problem it solves, then the end-user tutorial to build your first workflow. The docs are organized in the four Diátaxis modes (tutorials, how-to guides, reference, and concepts), plus dedicated sections for Power BI migration and security.

In this hub

Get started and tutorials

Learn Kasal by building something end to end.

How-to guides

Reach a specific goal, assuming you already know the basics.

  • Upgrading from v1.3.0: attach the existing database as the required lakebase resource, back up first, and check the first-start schema self-heal in the logs and /health/db.
  • Crew export and deployment: export CrewAI crews to Python projects, Databricks notebooks, or deployable Databricks Apps, and ship them to Model Serving.
  • Lakebase setup for Kasal: configure managed Lakebase PostgreSQL so crews, agents, tasks, and run history survive Databricks Apps restarts.
  • MLflow tracing setup: export every crew and flow execution to MLflow Tracing for observability.
  • Prompt optimization (GEPA) setup: the Unity Catalog grant the app service principal needs to register prompts before an optimization run.
  • Measuring workflow-recipe effectiveness: run a controlled holdout to find out whether reusing past crews actually improves generated ones.
  • Developer guide: local setup, local authentication, the architecture rules, and how to test your change.

Reference

Look up exact facts: endpoints, config keys, and repository layout.

Concepts and architecture

Understand why Kasal is built the way it is.

  • Why Kasal: the problems Kasal solves and who it's for on Databricks.
  • Solution architecture: platform layers, request lifecycle, and the security model.
  • LLM architecture: the four layers behind a model call — facade, configuration, endpoint policy, transport — and which one owns what.
  • Decision model: the optional, per-workspace provider (Jev today) that makes bounded choices among candidates Kasal already authorized, what it sends, and how it falls back.
  • Memory: what a memory record is, how it is written and recalled, the passes that keep the store true, and which tuning knobs actually do something.
  • Flows: what a flow is, how one is authored and compiled, and how state, routing, checkpoints and approval gates work end to end.
  • Conversational flow state: channels, reducers, and the thread that lets a flow answer a follow-up question instead of starting over.
  • Workflow recipes: why Kasal keeps the crews you have already run, and why it refuses to reuse them until a person says they were any good.
  • PBI → UCMV pipeline architecture: end-to-end walkthrough of how a Power BI model becomes UC Metric Views — extraction, config generation, the M-query path, and the LLM-first DAX translation with skill files, with the code location of each stage.
  • Harnesses: Kasal's own agent runtime and the CrewAI harness, and how a run picks one.

Power BI to Unity Catalog migration

Migrate Power BI semantic models to Unity Catalog Metric Views and run live analytics against Power BI data.

Security and compliance

How Kasal protects workflows, dependencies, and tenant data.

  • Security: identity, request authentication, authorization boundaries, and the security controls.
  • Security compliance: mapping of Databricks AI security guidance to its Kasal implementation, with runtime log evidence.
  • Security guardrails test guide: verify all five phases of security measures via automated tests and manual inspection.
  • Supply chain security: impact of the litellm supply chain compromise and the dependency-layer defenses proposed in response.

Run Kasal locally

Run the backend and frontend on your machine. You need Python 3.11, uv and Node.js 22.

git clone https://github.com/nehmetohme/kasal.git

# Start the backend: SQLite, http://127.0.0.1:8000, dependencies synced by uv
cd kasal/src/backend && ./run.sh

# In another terminal, start the frontend
cd kasal/src/frontend && npm ci && npm start

The app is served at http://localhost:3000. run.sh turns on a local development identity (LOCAL_DEV_AUTH); without it, API calls get 401. For details, see the quick start and the developer guide.

For contributors

Writing or editing docs in src/docs/? Follow the documentation style guide, which covers the Diátaxis modes, page anatomy, linking rules, and the per-page checklist. Each subfolder (powerbi/, examples/, Blueprints/) has its own README.md index; keep this hub's links in sync when you add or move a page.

Engineering proposals, backlogs, reviews and superseded pages also live in src/docs/ (for example archive/), but they are not user documentation and are left out of the app bundle and the pip wheel. The exclusion rules are in src/scripts/build-tasks.cjs: the archive/ and reviews/ folders, a list of named files, and any page whose opening carries a **Status: internal banner. Don't link to those pages from a shipped doc; the build fails if you do.