Mozaiks：开源 AI 应用工厂，用 Genesis Build 与 Refinement Run 构建 AI 原生软件

What is Mozaiks?

Mozaiks is an open-source AI app factory for building, running, and iterating on AI-native software products.

It brings together three things that usually live in separate tools:

• Mozaiks Studio for creating apps, continuing builds, and managing them.
• AI workflow orchestration powered by AG2 for planning, tool use, human review, and generation.
• Generated app files with modules, pages, workflows, config, and brand assets that Mozaiks validates before making active.

The goal is not to generate a throwaway demo. Mozaiks stages production-shaped artifacts, validates them against strict contracts, and keeps runtime concerns separate from builder workflows.

Genesis Builds and Refinement Runs

Every Mozaiks app begins with one Genesis Build: the first complete journey from product intent to a staged, validated app. It establishes the app's first canonical artifact lineage.

Every later change is a Refinement Run. Mozaiks starts from the app's current artifacts and history, determines what the request affects, and re-enters only the parts of the build needed to stage a safe new version for review. A small copy fix and a major product rethink are both Refinement Runs; their scope and route are different, but neither discards the app's lineage.

Internally, the Refinement Engine classifies and routes Refinement Runs. Genesis Build and Refinement Run are the product-facing lifecycle terms.

Quickstart

Five steps from a checkout to your first app in Studio.

Prerequisites

• Python 3.11+
• Node.js 20.19+ or 22.12+ (the Studio frontend builds with Vite 8, which requires Node.js ^20.19.0 || >=22.12.0)
• A reachable MongoDB database for workspace state

Docker Desktop is not required; use MongoDB Atlas, a local MongoDB install, or Docker only if that is how you prefer to run MongoDB.

Commands below are shown for Windows PowerShell and for macOS / Linux shells (bash or zsh) wherever the two differ.

1. Install

Mozaiks is not published as a public PyPI package yet. Install it from a local checkout in editable mode. These commands are the same in every shell:

git clone https://github.com/BlocUnited-LLC/mozaiks.git
cd mozaiks
python -m pip install -e ".[dev]"

On macOS and Linux, use python3 wherever these steps say python if your system has no python command. If pip refuses with an externally-managed-environment error, create and activate a virtual environment first, as shown in Local Setup.

2. Point Mozaiks at MongoDB

Studio stores workspace state in MongoDB, so configure it before opening Studio:

Windows (PowerShell)

# Local MongoDB
$env:MONGO_URI="mongodb://localhost:27017/mozaiks"

# Or MongoDB Atlas
$env:MONGO_URI="<your MongoDB connection string>"

macOS / Linux (bash or zsh)

# Local MongoDB
export MONGO_URI="mongodb://localhost:27017/mozaiks"

# Or MongoDB Atlas
export MONGO_URI="<your MongoDB connection string>"

3. Set an OpenAI key

Builds call OpenAI today: the runtime builds OpenAI clients only, so set OPENAI_API_KEY:

Windows (PowerShell)

$env:OPENAI_API_KEY="sk-..."

macOS / Linux (bash or zsh)

export OPENAI_API_KEY="sk-..."

The default model is gpt-5-nano; set DEFAULT_LLM_MODEL to use another OpenAI model. Gemini and Anthropic keys are not used for builds yet, and the provider you pick in Studio or with --provider is recorded for display only.

Variables set this way last only for the current terminal session. Run step 4 in the same terminal, or set them again in a new one.

4. Create your workspace and open Studio

Windows (PowerShell)

python -m mozaiks quickstart --dir .\mozaiks-workspace

macOS / Linux (bash or zsh)

python -m mozaiks quickstart --dir ./mozaiks-workspace

This creates the mozaiks-workspace folder, starts the local Studio, and opens it in your browser.

mozaiks-workspace is the local workspace folder Mozaiks uses for generated output, config, and launch scripts. It is not the app itself. The app is created later from inside Studio.

5. Start your Genesis Build

In Studio (http://127.0.0.1:3000/apps), click Create App, then describe what you want to build. The workflow walks you through the build steps and stages the generated artifacts for review. In-progress builds stay in Apps, so you can always pick up where you left off.

After promotion, describe any later change to start a Refinement Run against the app you already have. See Genesis Builds and Refinement Runs for examples ranging from a typo fix to a major product rethink.

Troubleshooting

If setup fails, check three things first: use python -m mozaiks if the mozaiks command is unavailable, make sure MONGO_URI points to a reachable MongoDB instance, and set an LLM API key before running builds. Builds use OPENAI_API_KEY only today.

Where To Go Next

Want to contribute? See the Contributing guide.

What The Framework Gives You

Generation is the visible part. What makes the generated output worth keeping is the runtime underneath it, which is the same runtime whether an app was generated or hand-written.

Subscription to entitlement to feature gate

The pattern almost every SaaS rebuilds by hand. In Mozaiks it is a runtime primitive: a module action names a capability, and the executor checks it before dispatch.

# modules/reports/module.yaml
actions:
  - id: export_report
    description: Export the current report as CSV
    handler_method: export_report
    entitlement_gate: reports.export    # checked before the handler runs

app/config/subscriptions.yaml declares which plans grant reports.export. Apps with no subscriptions get NoOpEntitlementAdapter and are entirely unaffected. Enforcement fails closed: an adapter that errors denies rather than grants.

Ports and adapters, not a framework you are stuck inside

Infrastructure sits behind protocols the runtime declares and never implements for you:

Swap any of them for your own without forking the runtime.

Contracts that are validated, not conventions that are hoped for

Every canonical YAML shape - modules, actions, events, reactions, pages, workflows, data contracts - is backed by a strict typed model and validated before it becomes active. A contract that cannot be generated repeatably and validated deterministically is not treated as a contract.

Execution that survives a crash

The workflow queue uses leases with fencing tokens, bounded retry, and dead-lettering, so a worker dying mid-run does not strand or duplicate work. Module dispatch requires an explicit authority object rather than trusting the caller. Tenant isolation goes through one canonical scope filter instead of each query hand-rolling its own.

Apps you can leave with

Generated apps are provider-neutral and self-hostable: a Dockerfile, a compose file, an env manifest, and staged data-contract migrations. Nothing requires BlocUnited's hosted platform to run.

🎨 See It In Action

💬 Embeddable Floating Widget

Drop a floating assistant anywhere in your app — click the button to expand/collapse the chat interface

🔀 Dual-Mode Interface

Workflow Mode	Ask Mode
Chat + Artifact split view	Full chat with history sidebar

---

📚 Documentation

• Architecture Overview — System design and component model
• Getting Started — Full setup guide
• Releasing — Release hold and future publish workflow
• Workflow Routing Transitions — Flagship orchestration capability and runtime semantics
• Workflow Authoring Contracts — Canonical strict YAML contract
• Contributing — Development workflow

Preview the docs locally with python -m pip install -e ".[docs]" followed by python -m mkdocs serve (the same commands in every shell). See Contributing for details.

Contributing

Fork, branch, install development dependencies with pip install -e ".[dev]", make a focused change, run the relevant tests, and open a pull request. Documentation, most tests, and many CLI changes don't need MongoDB, Node.js, or an LLM API key. See CONTRIBUTING.md for the full path.

Looking for a first issue? Start with good first issue — comment on one to claim it before you start, so two people do not build the same fix.

Using an AI coding agent? Welcome — read the AI Policy first. It is short, and it applies to maintainers and their agents on the same terms.

Questions, or want to talk through an approach before writing code? Join us on Discord.

Contributors Wall

Everyone who reports bugs, writes docs, reviews code, or ships fixes belongs on this wall.

This project follows the Code of Conduct.

License

MIT. See LICENSE. The license covers the code, not the "Mozaiks" and "MozaiksPay" names and logo — see TRADEMARK.md.