Metadata-Version: 2.4
Name: dazzle-dsl
Version: 0.71.84
Summary: DAZZLE — declarative SaaS framework with built-in compliance (SOC 2, ISO 27001), provable RBAC, and graph features
Author: DAZZLE Contributors
Maintainer: DAZZLE Contributors
License: MIT
Project-URL: Homepage, https://github.com/manwithacat/dazzle
Project-URL: Documentation, https://github.com/manwithacat/dazzle/blob/main/docs
Project-URL: Repository, https://github.com/manwithacat/dazzle
Project-URL: Issues, https://github.com/manwithacat/dazzle/issues
Project-URL: Changelog, https://github.com/manwithacat/dazzle/blob/main/CHANGELOG.md
Keywords: dsl,saas,compliance,soc2,iso27001,rbac,graph,openapi,llm,domain-modeling,application-framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: markdown>=3.5
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: psycopg-pool>=3.2
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: alembic>=1.14
Requires-Dist: slowapi>=0.1.9
Requires-Dist: faker>=20.0
Requires-Dist: segno>=1.5
Requires-Dist: bleach>=6.0
Requires-Dist: itsdangerous>=2.1
Requires-Dist: fastapi>=0.100.0
Provides-Extra: llm
Requires-Dist: anthropic>=0.21.0; extra == "llm"
Requires-Dist: openai>=1.0.0; extra == "llm"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: lsp
Requires-Dist: pygls>=1.0.0; extra == "lsp"
Requires-Dist: lsprotocol>=2023.0.0; extra == "lsp"
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == "graph"
Provides-Extra: compliance
Requires-Dist: weasyprint>=60.0; extra == "compliance"
Requires-Dist: markdown>=3.5; extra == "compliance"
Provides-Extra: sso
Requires-Dist: authlib<2,>=1.3.0; extra == "sso"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-xdist>=3.3; extra == "dev"
Requires-Dist: pytest-timeout>=2.2; extra == "dev"
Requires-Dist: hypothesis>=6.82; extra == "dev"
Requires-Dist: syrupy>=4.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: requests>=2.31; extra == "dev"
Requires-Dist: mutmut>=2.4; extra == "dev"
Requires-Dist: fastapi>=0.100.0; extra == "dev"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Provides-Extra: perf
Requires-Dist: opentelemetry-api<2,>=1.27; extra == "perf"
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "perf"
Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0.48b0; extra == "perf"
Requires-Dist: opentelemetry-instrumentation-psycopg<1,>=0.48b0; extra == "perf"
Requires-Dist: opentelemetry-instrumentation-asyncio<1,>=0.48b0; extra == "perf"
Provides-Extra: serve
Requires-Dist: fastapi>=0.100.0; extra == "serve"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "serve"
Requires-Dist: httpx>=0.24.0; extra == "serve"
Requires-Dist: python-multipart>=0.0.6; extra == "serve"
Provides-Extra: postgres
Provides-Extra: temporal
Requires-Dist: temporalio>=1.4.0; extra == "temporal"
Provides-Extra: celery
Requires-Dist: celery>=5.3.0; extra == "celery"
Requires-Dist: redis>=5.0; extra == "celery"
Provides-Extra: rabbitmq
Requires-Dist: aio-pika>=9.0; extra == "rabbitmq"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.9; extra == "kafka"
Provides-Extra: messaging
Requires-Dist: aio-pika>=9.0; extra == "messaging"
Requires-Dist: redis>=5.0; extra == "messaging"
Requires-Dist: aiokafka>=0.9; extra == "messaging"
Provides-Extra: events
Requires-Dist: psycopg[binary]>=3.2; extra == "events"
Provides-Extra: pitch
Requires-Dist: python-pptx>=0.6.21; extra == "pitch"
Requires-Dist: matplotlib>=3.7.0; extra == "pitch"
Provides-Extra: viewport
Requires-Dist: Pillow>=10.0.0; extra == "viewport"
Provides-Extra: tigerbeetle
Requires-Dist: tigerbeetle>=0.16.0; extra == "tigerbeetle"
Provides-Extra: mobile
Requires-Dist: PyJWT>=2.8.0; extra == "mobile"
Requires-Dist: cryptography>=41.0.0; extra == "mobile"
Provides-Extra: social-auth
Requires-Dist: google-auth>=2.25.0; extra == "social-auth"
Requires-Dist: httpx>=0.25.0; extra == "social-auth"
Provides-Extra: push
Requires-Dist: firebase-admin>=6.2.0; extra == "push"
Provides-Extra: mobile-full
Requires-Dist: PyJWT>=2.8.0; extra == "mobile-full"
Requires-Dist: cryptography>=41.0.0; extra == "mobile-full"
Requires-Dist: google-auth>=2.25.0; extra == "mobile-full"
Requires-Dist: httpx>=0.25.0; extra == "mobile-full"
Requires-Dist: firebase-admin>=6.2.0; extra == "mobile-full"
Provides-Extra: aws
Requires-Dist: aioboto3>=13.0; extra == "aws"
Requires-Dist: boto3>=1.35; extra == "aws"
Provides-Extra: sendgrid
Requires-Dist: sendgrid>=6.11; extra == "sendgrid"
Provides-Extra: i18n
Requires-Dist: babel>=2.13; extra == "i18n"
Provides-Extra: aws-test
Requires-Dist: boto3>=1.35; extra == "aws-test"
Requires-Dist: moto[s3]>=5.0; extra == "aws-test"
Dynamic: license-file

# DAZZLE

**A semantic substrate for AI-collaborative software.**
**Model your business. Ship your product. Pass your audit.**

<!-- Versions & Compatibility -->
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![Homebrew](https://img.shields.io/badge/homebrew-manwithacat%2Ftap-orange)](https://github.com/manwithacat/homebrew-tap)

<!-- Build & Quality -->
[![CI](https://github.com/manwithacat/dazzle/workflows/CI/badge.svg)](https://github.com/manwithacat/dazzle/actions)
[![codecov](https://codecov.io/gh/manwithacat/dazzle/branch/main/graph/badge.svg)](https://codecov.io/gh/manwithacat/dazzle)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)

<!-- Meta -->
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://manwithacat.github.io/dazzle/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/manwithacat/dazzle.svg?style=social)](https://github.com/manwithacat/dazzle)

Dazzle is a declarative framework for building SaaS applications — and a research project exploring what software architecture looks like when AI collaborators are treated as first-class readers and writers of the codebase. You describe your business in structured `.dsl` files: entities, roles, rules, workflows, events. The runtime executes that description directly. There is no code generation step, no scaffold to maintain, and no second source of truth.

```bash
cd examples/simple_task && dazzle serve
# UI:  http://localhost:3000
# API: http://localhost:8000/docs
```

---

## The thesis

Traditional software architecture is optimized for humans. Files, modules, conventions, and abstractions are arranged to fit a programmer's working memory.

That optimization is no longer the only one that matters. An increasing share of software work — exploration, modification, review, refactor, test — happens with an AI collaborator in the loop. Codebases that scatter meaning across controllers, models, migrations, and templates burn context window on plumbing the model already understands. Codebases whose intent is encoded in a typed, inspectable graph let the model spend its attention on the actual problem.

Dazzle is a bet that **semantic compression** — putting your application's meaning in one inspectable, machine-readable form — produces software that is easier to evolve, easier to audit, and easier to collaborate on with both humans and machines. The DSL is not a shortcut to a generated codebase. It *is* the codebase.

---

## Design principles

Eleven stated positions, defended in the [ADRs](docs/adr/INDEX.md):

1. **The DSL is the source of truth.** API specs, tests, compliance evidence, and runtime behaviour are all derived from the same IR.
2. **No code generation.** The runtime executes the IR directly. No regeneration drift, no generated files to maintain.
3. **Anti-Turing by design.** The DSL has no arbitrary computation. Everything is statically inspectable, lintable, and verifiable.
4. **PostgreSQL only.** One capable relational database plus disciplined semantics beats distributed-systems sprawl for the workloads Dazzle targets.
5. **Server-rendered HTML + HTMX.** No SPA framework, no build toolchain, no client-state fragmentation.
6. **Fragments as the only escape hatch.** When the DSL can't express it, you reach for a *fragment* — a constrained, named, semantically-tagged piece of custom rendering. Not arbitrary frontend.
7. **Append-oriented history.** Events, decisions, and grants are logged. Auditors don't need to spelunk; the trail is part of the substrate.
8. **Provable RBAC.** Scope rules compile to a formal predicate algebra and are statically validated against the FK graph.
9. **No hidden singletons.** Dependencies are explicit (`RuntimeServices`, `ServerState`) — readable by both humans and agents.
10. **No backwards-compat shims.** Pre-1.0, clean breaks beat layered workarounds. Callers are updated in the same commit.
11. **Bump on every fix.** Every push gets a unique semantic version — deployment traceability over release ceremony.

If you disagree with one of these, you'll probably disagree with the rest. That's the point of stating them up front.

---

## Why Dazzle

### Your business model IS the application

Most frameworks ask you to express your business logic across scattered files — controllers, models, migrations, middleware, templates. When requirements change, you update all of them and hope they stay in sync.

Dazzle inverts this. You write what your business *is* — entities, roles, permissions, workflows, state machines — and the runtime executes it directly. Change the DSL, refresh the browser. The DSL is the single source of truth for your application, your API spec, your test suite, and your compliance documentation.

### Built for the compliance conversation

If you're building SaaS — especially in regulated industries — you will face auditors. They will ask: *who can access what? how are changes controlled? where is sensitive data classified?*

Most teams answer these questions retroactively, combing through code to produce evidence. Dazzle answers them by construction:

- **Access control** is declared in the DSL and provably enforced. Every permission is statically verifiable.
- **State machines** model approval workflows, transitions, and four-eyes authorization.
- **Compliance evidence** is extracted automatically. Run `dazzle compliance compile --framework soc2` and get a structured audit report showing which controls your DSL satisfies.
- **Grant-based RBAC** supports delegated, time-bounded access with approval workflows — the kind of access governance auditors want to see.

Dazzle currently supports **ISO 27001** and **SOC 2 Trust Services Criteria** out of the box, with automatic evidence mapping from your DSL declarations to specific framework controls.

### From idea to running product, fast

```dsl
module my_app
app todo "Todo Application"

entity Task "Task":
  id: uuid pk
  title: str(200) required
  completed: bool=false
  created_at: datetime auto_add

surface task_list "Tasks":
  uses entity Task
  mode: list
  section main:
    field title "Title"
    field completed "Done"
```

Save this as `app.dsl`, run `dazzle serve`, and you have:
- A PostgreSQL-backed database with correct types and constraints
- CRUD API endpoints with pagination, filtering, and sorting
- A rendered list UI with sortable columns, search, and a create form
- OpenAPI documentation at `/docs`
- A health endpoint with deployment integrity verification

That's a todo app. The same language scales to 39-entity accountancy platforms with double-entry ledgers, multi-step onboarding wizards, and role-based dashboards. You add complexity only where your business needs it.

---

## What you can model

| Capability | What it does | Why it matters |
|-----------|-------------|---------------|
| **Entities** | Data models with types, constraints, relationships | Your domain model, declared once |
| **Surfaces** | List, detail, create, review views | UI and API from the same declaration |
| **Workspaces** | Role-based dashboards with filtered regions | Each persona sees what they need |
| **State Machines** | Lifecycle transitions with guards and approval | Business processes enforced, not just documented |
| **Access Control** | Cedar-style permit/forbid rules, scope predicates | Provable RBAC — auditors can verify mechanically |
| **Grant Schemas** | Delegated, time-bounded access with approval | Four-eyes authorization, SOC 2-ready |
| **Processes** | Multi-step workflows with saga patterns | Durable business operations |
| **Experiences** | Onboarding wizards, checkout flows | Guided multi-step user journeys |
| **Ledgers** | TigerBeetle-backed double-entry accounting | Financial-grade transaction integrity |
| **Graphs** | Entity relationships with CTE traversal and algorithms | Network analysis, shortest paths, community detection |
| **HLESS Events** | Intent/Fact/Observation/Derivation event semantics | Replay correctness, audit lineage, no "events as a vague bucket" |
| **Fragments** | Constrained custom rendering inside generated surfaces | Differentiated UX without losing semantic integrity |
| **Integrations** | Declarative API bindings with triggers and mappings | Connect to Stripe, HMRC, Xero, and more |
| **LLM Jobs** | Classification, extraction, generation tasks | AI capabilities without prompt engineering sprawl |
| **Compliance** | Automated evidence extraction for ISO 27001 and SOC 2 | Audit-ready from day one |

For the full DSL reference, see [docs/reference/index.md](docs/reference/index.md).

### Vocabulary glossary

A few Dazzle keywords don't map one-to-one onto industry terms. If you're skim-reading the DSL for the first time:

| Dazzle term | What other communities call this |
|-------------|----------------------------------|
| **surface** | view, page, screen — a UI/API endpoint with one entity and one mode |
| **workspace** | dashboard, role home, console |
| **experience** | wizard, flow, multi-step form |
| **rhythm** | recurring cadence, scheduled review, periodic ritual |
| **archetype** | persona pattern, role family |
| **hless** | event-stream semantics (HLESS = High-Level Event Semantics Specification — [why this name](docs/architecture/hless-deep-dive.md)) |
| **fragment** | escape-hatch component, custom partial |

---

## Compliance and security

Dazzle treats compliance as a first-class concern, not an afterthought.

### Automated evidence extraction

Every DSL construct that relates to security — access rules, data classification, state machine transitions, process workflows — is automatically mapped to compliance framework controls. Run:

```bash
dazzle compliance compile --framework iso27001   # ISO 27001 audit
dazzle compliance compile --framework soc2       # SOC 2 TSC audit
dazzle compliance gaps --framework soc2          # Show unmet controls
```

The output is a structured `AuditSpec` showing which controls are **evidenced** (your DSL satisfies them), which are **gaps** (your DSL should cover them but doesn't), and which are **excluded** (physical security, HR — outside DSL scope).

### Provable access control

Scope rules compile to a formal predicate algebra, statically validated against the FK graph at `dazzle validate` time. The verification framework has three layers:

| Layer | What it proves |
|-------|---------------|
| **Static Matrix** | Every (role, entity, operation) combination is computed from the DSL |
| **Dynamic Verification** | The running app is probed as every role to confirm runtime matches the matrix |
| **Decision Audit Trail** | Every access decision is logged with the matched rule and outcome |

```bash
dazzle rbac matrix    # Generate the access matrix (no server needed)
dazzle rbac verify    # Verify runtime matches the matrix (CI gate)
dazzle rbac report    # Compliance report for auditors
```

See [RBAC Verification](docs/reference/rbac-verification.md) and [Compliance](docs/reference/compliance.md) for details.

---

## What Dazzle is *not* for

Stating this directly because it matters:

- **Real-time collaborative editing.** No CRDT layer, no client-state model.
- **Graphics-heavy or canvas-based interfaces.** Server-rendered HTML is not the right substrate.
- **Local-first or offline-first applications.** Authority lives on the server and in PostgreSQL.
- **General-purpose programming.** The DSL is deliberately not Turing-complete. If you need arbitrary computation, you need a different tool — or you write a fragment.
- **Replacing your existing codebase wholesale.** Dazzle is most useful for new applications where governance, workflow, and audit are first-class concerns from day one.

The framework is strongest for **enterprise SaaS, workflow systems, operational tooling, and governance-heavy applications.** That's the bet.

---

## Quick Start

```bash
# Install
brew install manwithacat/tap/dazzle   # macOS/Linux (auto-registers MCP server)
# or: pip install dazzle-dsl

# Run the example
cd examples/simple_task
dazzle serve

# Open http://localhost:3000 for the UI
# Open http://localhost:8000/docs for the API
```

---

## Architecture

```
DSL Files  →  Parser + Linker  →  AppSpec (IR)  →  Runtime (live app)
                                                 →  OpenAPI / AsyncAPI specs
                                                 →  Test generation
                                                 →  Compliance evidence
                                                 →  Fidelity scoring
```

The DSL is parsed into a typed intermediate representation (AppSpec IR). The runtime executes the IR directly — no code generation step. Every artifact (API specs, tests, compliance reports, demo data) is computed from the same IR.

This architecture is deliberately **anti-Turing**: the DSL has no arbitrary computation, which means Dazzle can statically validate, lint, measure fidelity, and reason about your application. What you declare is what runs.

The frontend uses server-rendered HTML with HTMX — zero build toolchain, stable technology, and full visibility into what the runtime produces. For UX that the generated surfaces can't express, **fragments** provide a constrained escape hatch: named, semantically-tagged custom rendering that remains connected to the entity and surface graph.

For the full architecture, see [docs/architecture/overview.md](docs/architecture/overview.md). For the event-semantics rationale, see [docs/architecture/hless-deep-dive.md](docs/architecture/hless-deep-dive.md).

---

## AI-assisted development

Dazzle ships as both a runtime and an AI development environment. When used with Claude Code (via MCP), you get access to **26 tools with 170+ operations** that span the full lifecycle:

| Stage | What the tools do |
|-------|------------------|
| **Spec to DSL** | Turn a natural-language idea into validated DSL — entity discovery, lifecycle identification, persona extraction |
| **Test and Verify** | Generate stories, design tests, execute at three tiers (API, browser, LLM-guided), seed demo data |
| **Analyze and Audit** | Quality pipeline, agent-powered gap discovery, visual composition analysis, RBAC policy verification |
| **Site and Brand** | Manage public site structure, copy, theme, and design tokens from spec files |
| **Stakeholder Ops** | Launch readiness scores, investor pitch generation, user/session management |

The agent framework uses an **observe-decide-act-record** loop to autonomously explore running applications, discover gaps, and propose DSL fixes. Discovery modes include persona-based exploration, CRUD completeness analysis, workflow coherence checks, and headless DSL/KG analysis.

For the full MCP tool reference, see [Architecture: MCP Server](docs/architecture/mcp-server.md). For how the autonomous slash-command harness drives day-to-day development on the framework itself, see [Autonomous Harness](docs/autonomous-harness.md).

### Claude Code integration

```bash
# Homebrew: MCP server auto-registered during installation
brew install manwithacat/tap/dazzle

# PyPI: Register manually
pip install dazzle-dsl
dazzle mcp setup

# Verify
dazzle mcp check
```

---

## Examples

| Example | Complexity | What it demonstrates |
|---------|-----------|---------------------|
| `simple_task` | Beginner | 3 entities, state machine, personas, workspaces, access control |
| `contact_manager` | Beginner | CRM with relationships and list/detail surfaces |
| `support_tickets` | Intermediate | Ticket lifecycle with state machines and assignments |
| `ops_dashboard` | Intermediate | Workspace stages and aggregate metrics |
| `fieldtest_hub` | Advanced | Full-featured demo with integrations |
| `pra` | Advanced | 15 DSL files covering every construct: ledgers, processes, LLM, services |

---

## IDE support

Full LSP implementation: real-time diagnostics, hover docs, go-to-definition, auto-completion, document symbols.

```bash
dazzle lsp run           # Start the LSP server
dazzle lsp check         # Verify dependencies
dazzle lsp grammar-path  # TextMate grammar for syntax highlighting
```

Works with VS Code, Neovim, Emacs, and any editor supporting LSP. See [docs/reference/index.md](docs/reference/index.md) for editor setup.

---

## Documentation

- **[DSL Reference](docs/reference/index.md)** — complete guide to all DSL constructs
- **[HLESS deep dive](docs/architecture/hless-deep-dive.md)** — event semantics and why they're named this way
- **[Graphs](docs/reference/graphs.md)** — entity graph relationships, CTE traversal, algorithms
- **[Compliance](docs/reference/compliance.md)** — ISO 27001 + SOC 2 evidence pipeline
- **[RBAC Verification](docs/reference/rbac-verification.md)** — provable access control
- **[Autonomous Harness](docs/autonomous-harness.md)** — Claude Code slash commands + methodology
- **[ADRs](docs/adr/INDEX.md)** — architectural decisions, defended
- **[Architecture](docs/architecture/)** — system design, pipeline, MCP server
- **[Getting Started](docs/getting-started/)** — installation, quickstart, first app
- **[Examples](examples/)** — runnable example applications

---

## About this project

Dazzle is a research project exploring what application substrates look like when AI collaborators are treated as first-class readers and writers. It is developed in the open, primarily by a single author, with heavy AI assistance — both in the framework itself and in the example apps built on top of it. Release cadence is high (every fix gets a unique version for deployment traceability) and pre-1.0 breaks are intentional rather than apologetic. If you're evaluating Dazzle for production use, talk to us first.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE)
