Metadata-Version: 2.4
Name: mozaiks
Version: 0.2.0
Summary: Mozaiks AG2 runtime and Studio-driven app framework
Author-email: BlocUnited LLC <info@blocunited.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BlocUnited-LLC/mozaiks
Project-URL: Repository, https://github.com/BlocUnited-LLC/mozaiks
Project-URL: Documentation, https://github.com/BlocUnited-LLC/mozaiks#readme
Keywords: mozaiks,ag2,ai,agents,workflows,multi-tenant,runtime
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ag2[a2a,openai,tracing]==1.1.2
Requires-Dist: a2a-sdk[grpc]<2,>=1.1.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.20.0
Requires-Dist: websockets>=11.0
Requires-Dist: motor>=3.3.0
Requires-Dist: pymongo>=4.5.0
Requires-Dist: dnspython>=2.4.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pydantic>=2.5.0
Requires-Dist: PyJWT[crypto]>=2.8.0
Requires-Dist: jinja2
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.2.0
Requires-Dist: httpx
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: limits>=3.6.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: tree-sitter>=0.20.0
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-css
Provides-Extra: gemini
Requires-Dist: ag2[gemini]==1.1.2; extra == "gemini"
Provides-Extra: anthropic
Requires-Dist: ag2[anthropic]==1.1.2; extra == "anthropic"
Provides-Extra: acp-coding
Requires-Dist: ag2[acp]==1.1.2; extra == "acp-coding"
Requires-Dist: agent-client-protocol==0.12.1; extra == "acp-coding"
Provides-Extra: azure
Requires-Dist: azure-identity>=1.15.0; extra == "azure"
Requires-Dist: azure-keyvault-secrets>=4.7.0; extra == "azure"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: pytest-rerunfailures>=12.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: watchdog; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ag2[acp]==1.1.2; extra == "dev"
Requires-Dist: agent-client-protocol==0.12.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == "docs"
Requires-Dist: mkdocs-material>=9.7.6; extra == "docs"
Requires-Dist: mkdocs-autorefs>=1.4.4; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "docs"
Provides-Extra: monitoring
Requires-Dist: redis[asyncio]>=5.0.0; extra == "monitoring"
Requires-Dist: boto3>=1.28.0; extra == "monitoring"
Provides-Extra: tracing
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp>=1.27.0; extra == "tracing"
Provides-Extra: e2b
Requires-Dist: e2b-code-interpreter<3,>=2.10.0; extra == "e2b"
Dynamic: license-file

# Mozaiks

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/BlocUnited-LLC/mozaiks/main/docs/assets/logo-dark.png">
  <img src="https://raw.githubusercontent.com/BlocUnited-LLC/mozaiks/main/docs/assets/logo-light.png" alt="Mozaiks" width="260"/>
</picture>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/BlocUnited-LLC/mozaiks/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11+-blue?logo=python)](https://www.python.org/)
[![AG2](https://img.shields.io/badge/AG2-1.1.2-green)](https://github.com/ag2ai/ag2)
[![Discord](https://img.shields.io/badge/Discord-join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/Qnsywad9kp)

[![Studio](https://img.shields.io/badge/Studio-management%20interface-7c3aed)](https://docs.mozaiks.ai/studio/)
[![Runtime](https://img.shields.io/badge/Runtime-AI%20substrate-0f766e)](https://github.com/BlocUnited-LLC/mozaiks/blob/main/ARCHITECTURE.md)
[![Workflows](https://img.shields.io/badge/Workflows-builder%20systems-2563eb)](https://github.com/BlocUnited-LLC/mozaiks/blob/main/docs/architecture/workflows/workflow-authoring-contracts.md)
[![Community](https://img.shields.io/badge/Community-contributors%20welcome-f59e0b)](https://github.com/BlocUnited-LLC/mozaiks/graphs/contributors)

</div>

## 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](https://github.com/ag2ai/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

Install the public package from PyPI:

```bash
python -m pip install mozaiks
```

Contributors working on the framework should instead use an editable checkout.
These commands are the same in every shell:

```bash
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](https://docs.mozaiks.ai/local-setup/#manual-editable-setup).

### 2. Point Mozaiks at MongoDB

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

**Windows (PowerShell)**

```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)**

```bash
# 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)**

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

**macOS / Linux (bash or zsh)**

```bash
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)**

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

**macOS / Linux (bash or zsh)**

```bash
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](https://docs.mozaiks.ai/getting-started/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

| Guide | What it covers |
|---|---|
| [Use Studio](https://docs.mozaiks.ai/studio/) | The workspace and app-dashboard pages |
| [Genesis Builds and Refinement Runs](https://docs.mozaiks.ai/getting-started/genesis-builds-and-refinement-runs/) | Create the first version, then make safe changes without starting over |
| [Add a Workflow](https://docs.mozaiks.ai/guides/adding-workflows/01-overview/) | Extend an app with a custom AI workflow |
| [Add a Module](https://docs.mozaiks.ai/guides/adding-modules/01-overview/) | Add a self-contained backend capability |
| [Add a Page](https://docs.mozaiks.ai/guides/adding-pages/01-overview/) | Add new pages and routes to your app workspace |
| [Config Files](https://docs.mozaiks.ai/guides/configs/) | Find the right file to edit |
| [Integrations](https://docs.mozaiks.ai/guides/integrations/01-overview/) | Connect shared services once and let apps declare what they need |
| [App Shell & Branding](https://docs.mozaiks.ai/guides/custom-brand-integration/01-overview/) | Themes, navigation, logos, and shell behavior |
| [Self-Hosting](https://docs.mozaiks.ai/guides/self-hosting/) | Run Mozaiks on your own server |

Want to contribute? See the [Contributing guide](https://docs.mozaiks.ai/contributing/).

## 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.

```yaml
# 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:

| Port | Contract | Ships with |
|---|---|---|
| `EntitlementPort` | is this capability granted for this scope? | no-op + config-driven adapters |
| `ArtifactStore` | read/write named artifact blobs | local filesystem + S3 |
| `AppBackendPort` | runtime to backend request/emit/health | generic HTTP adapter |
| `SandboxPort` | isolated execution sessions | Docker adapter |

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

<div align="center">

### 💬 Embeddable Floating Widget

![Widget Demo](https://raw.githubusercontent.com/BlocUnited-LLC/mozaiks/main/docs/assets/widgetAction.gif)

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

---

### 🔀 Dual-Mode Interface

| Workflow Mode | Ask Mode |
|:---:|:---:|
| ![Workflow Mode](https://raw.githubusercontent.com/BlocUnited-LLC/mozaiks/main/docs/assets/ArtifactLayout.png) | ![Ask Mode](https://raw.githubusercontent.com/BlocUnited-LLC/mozaiks/main/docs/assets/AskMozaiks.png) |
| *Chat + Artifact split view* | *Full chat with history sidebar* |

</div>
---

## 📚 Documentation

- [Architecture Overview](https://github.com/BlocUnited-LLC/mozaiks/blob/main/ARCHITECTURE.md) — System design and component model
- [Getting Started](https://github.com/BlocUnited-LLC/mozaiks/blob/main/docs/getting-started.md) — Full setup guide
- [Releasing](https://github.com/BlocUnited-LLC/mozaiks/blob/main/docs/releasing.md) — Release hold and future publish workflow
- [Workflow Routing Transitions](https://github.com/BlocUnited-LLC/mozaiks/blob/main/docs/architecture/workflows/workflow-routing-transitions.md) — Flagship orchestration capability and runtime semantics
- [Workflow Authoring Contracts](https://github.com/BlocUnited-LLC/mozaiks/blob/main/docs/architecture/workflows/workflow-authoring-contracts.md) — Canonical strict YAML contract
- [Contributing](https://github.com/BlocUnited-LLC/mozaiks/blob/main/CONTRIBUTING.md) — 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](https://github.com/BlocUnited-LLC/mozaiks/blob/main/CONTRIBUTING.md#what-you-can-contribute-without-extra-setup)
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](CONTRIBUTING.md) for the full path.

Looking for a first issue? Start with
[good first issue](https://github.com/BlocUnited-LLC/mozaiks/labels/good%20first%20issue)
— 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](.github/AI_POLICY.md) 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](https://discord.gg/Qnsywad9kp).

## Contributors Wall

<div align="center">

<a href="https://github.com/BlocUnited-LLC/mozaiks/graphs/contributors">
  <img
    src="https://contrib.rocks/image?repo=BlocUnited-LLC/mozaiks"
    alt="Contributors wall for Mozaiks"
  />
</a>

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

</div>

This project follows the [Code of Conduct](CODE_OF_CONDUCT.md).

## License

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