# How Emolysis works

> The fixed path from a request to a deployed pipeline: connect, describe, pick a shape, fill a template, test on DuckDB, deploy, publish.

Every request in Emolysis follows the same fixed path. The agent does not write a pipeline from scratch. It picks a shape, fills a template for your platform, proves the result on your machine, and only then deploys. This page walks through that path and says where each step runs.

## The path at a glance

1. **Connect** a platform once per workspace.
2. **Describe** what you need in plain language.
3. **Pick a shape** from the ten pipeline shapes.
4. **Fill the template** for that shape and platform.
5. **Lint, dry run and test** on your machine.
6. **Loop on red** until the tests are green.
7. **Deploy** as your platform's native unit.
8. **Publish** a dashboard, if that is what you built.

## 1. Connect

You connect a platform once per workspace, authorizing through the platform's own sign-in. The credentials are kept in your machine's credential store. Emolysis then loads the [platform profile](https://emolysis.com/docs/platform-profiles), a structured description of that platform, and reads your catalog into a local mirror so the agent can see your schemas. From then on, only templates for that platform are offered.

You can also work without a platform. Against local CSV and Parquet files, Emolysis runs on DuckDB alone; like every use of Emolysis, that needs an Emolysis account, and the Free plan is one. See [Connecting Databricks](https://emolysis.com/docs/connect-databricks) for the first platform.

## 2. Describe

You ask for what you need in plain language: a business question ("monthly revenue by region") or a pipeline ("keep history for the customer table"). The agent sends your request, with the schema details it needs, to the AI model provider you choose. See [Model keys and credits](https://emolysis.com/docs/model-keys-and-credits) for how that provider is set up, and [Data handling](https://emolysis.com/docs/data-handling) for what a prompt can contain.

## 3. Pick a shape

The agent maps the request to one or more of the ten [pipeline shapes](https://emolysis.com/docs/shapes). A customer history request is [SCD Type 2](https://emolysis.com/shapes/scd2). A revenue question ends in [Aggregation / gold](https://emolysis.com/shapes/aggregation-gold), often after [Dedupe / conform](https://emolysis.com/shapes/dedupe-conform). Each shape has a slot schema, so the agent asks you only for what it cannot find in the catalog, such as which columns to track.

It tells you which shape it picked and why, and you can change the choice.

## 4. Fill the template

The agent fills the template for that shape and platform. Templates are written in a canonical form, and values are rendered for your platform's dialect. Every generated file is tagged with its platform and profile version, so a file written for one platform cannot be deployed to another by accident. See [Templates and slots](https://emolysis.com/docs/templates).

## 5. Lint, dry run and test

Three checks run before anything reaches your platform:

- **Platform lint rules** run on every pipeline the agent writes and catch known traps before anything runs.
- **A dry run** writes the deployment files for you to review before anything is deployed.
- **Golden tests** run before deploy: fixed input, expected output, exact comparison. See [Golden tests on DuckDB](https://emolysis.com/docs/golden-tests).

You can also pull a small sample of your real tables into DuckDB to see the result on your own data. That sample read is a query on your platform; the result lands on your machine.

## 6. Loop on red

A failing test sends the agent back to the template fill, not forward to your platform. It fixes the fill and runs the tests again, and you see each attempt and its result. The agent deploys only after a green run.

## 7. Deploy

When the tests are green, you deploy. Emolysis translates the pipeline into your platform's dialect and packages it as the platform's native unit, such as a Databricks Asset Bundle. It runs on your platform's compute, under your account. If your team uses pull requests, `emo check` runs the same checks in your CI (the GitHub App is planned), and green checks become the gate. See [Deploying](https://emolysis.com/docs/deploying) and [GitHub checks](https://emolysis.com/docs/github-checks).

## 8. Publish

For a dashboard, the last step is publishing. You choose who can see it, and the dashboard leaves your machine at that moment, as a fixed snapshot behind a link. See [Sharing dashboards](https://emolysis.com/docs/sharing).

## Everything is a command

Each step above is a command with an id, such as `template.render` or `dashboard.publish`. The desktop app, the `emo` command line and the MCP server all call the same commands, so a step you take in one place works the same way in the others. Every command returns either a result or a typed error with one of nine error codes. See [Troubleshooting](https://emolysis.com/docs/troubleshooting) and [Error codes](https://emolysis.com/docs/error-codes).

## What runs where

| Step                        | Where it runs                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| Lint, dry run, golden tests | Your machine, on DuckDB                                                                               |
| Writing code                | The AI model provider you choose; with a paid plan's model usage, through Emolysis's metering service |
| Sampling                    | A query on your platform; results on your machine                                                     |
| Deployed pipelines          | Your platform, under your account                                                                     |
| Published dashboards        | Emolysis, for the audience you choose                                                                 |

Emolysis's own services hold accounts, plans, usage records and the dashboards you publish. They are designed never to connect to your data platform.

## What the design rules out

- **Free-coding a pipeline.** If no shape fits, the agent says so.
- **Deploying on red.** A failing test goes back to the template; it never goes forward.
- **Deploying to the wrong platform.** The platform tag on every generated file blocks it without an explicit translation step.
- **Surprise compute use.** Testing on a local sample spends no warehouse compute. The platform runs only when you deploy or ask for a sample.

---

Page: https://emolysis.com/docs/how-it-works. Emolysis is a product of Bandpey GmbH, Munich, Germany. It is in private development, and nothing is released yet.