Metadata-Version: 2.4
Name: marginkit
Version: 0.4.0
Summary: Pre-flight cost & risk compiler for n8n AI workflows.
Author: Omar Khandji
License: MIT
Project-URL: Homepage, https://marginkit.lemonsqueezy.com
Keywords: n8n,ai,workflow,cost,budget,agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# MarginKit

**Pre-flight cost & risk compiler for n8n AI workflows.**

One runaway loop can erase a month of margin. MarginKit reads your exported n8n
workflow *before* you ship it to a client and tells you:

- what each AI node will cost per run (low / typical / high — honest ranges, not fake precision)
- where the real loops are (actual cycle detection in the workflow graph)
- which retries will multiply a failing paid call
- where to set the caps — exported as machine-readable guardrail rules

Built for AI agencies and freelancers who deliver n8n workflows at a fixed price.

## Try it in the browser — zero install

The `web/` folder is a full static web version: drag-and-drop your workflow
export and read the report in the page. **100% local** — the analysis runs in
your browser, nothing is uploaded (verify it in your network tab). Host it on
any static host, or just open `web/index.html`.

The web engine is a line-by-line port of the Python engine;
`tests/test_web_parity.py` proves both produce identical numbers on the golden
corpus of real n8n templates.

## Install

```bash
pip install -e .
```

Requires Python 3.11+.

## Usage

```bash
# Compile a budget & risk report (markdown or html, by extension)
marginkit compile my-workflow.json --output report.html

# Also export machine-readable guardrail rules
marginkit compile my-workflow.json --output report.md --rules rules.json

# Adjust the volume assumption (default: 100 runs/day)
marginkit compile my-workflow.json --runs-per-day 500

# Just check that an export is readable
marginkit validate my-workflow.json
```

Export your workflow from n8n: open the workflow → menu (…) → **Download**.

## Free vs Pro

| Feature | Free | Pro |
|---|:---:|:---:|
| Cost report (Markdown/HTML) with honest ranges | ✅ | ✅ |
| Loop, retry-storm & premium-model risk detection | ✅ | ✅ |
| Paid-API HTTP call detection (direct OpenAI/Anthropic/... calls) | ✅ | ✅ |
| Monthly cost by traffic level (sensitivity table) | ✅ | ✅ |
| Machine-readable guardrail rules (`--rules`) | ✅ | ✅ |
| **White-label reports** — your agency name, client name, logo (`--agency`, `--client`, `--logo`) | | ✅ |
| **CI mode** — `--json` summary + `--fail-on high` exit code for pipelines | | ✅ |

Pro is a one-time purchase. Activate with:

```bash
marginkit activate XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX
```

CI pipelines can set the `MARGINKIT_LICENSE` environment variable instead.

```bash
# White-label report for a client, failing the pipeline on high risks
marginkit compile client-workflow.json --output report.html \
  --agency "Studio Nord" --client "Acme Inc" --logo logo.png \
  --rules guardrails.json --fail-on high
```

## What it detects

| Check | How |
|---|---|
| AI node costs | Real n8n node types (`@n8n/n8n-nodes-langchain.*`), including models resolved through `ai_languageModel` links to `lmChat*` sub-nodes |
| Loops | Cycle detection in the connection graph — not keyword guessing |
| AI inside a loop | Cost multiplies per iteration; flagged as high risk |
| Retry storms | Node-level `retryOnFail` / `maxTries` (the real n8n format) |
| Premium models | Price-table driven, not hardcoded names |
| Unknown models | Flagged with a warning, never silently priced |

## Honesty by design

- Estimates are **ranges** built from the prompt text present in your export.
  Runtime data injected by `{{ expressions }}` is unknown at compile time and
  is stated as an assumption, never hidden.
- The pricing table is dated (`as_of`) and unknown models are visibly flagged.
- Every report ends with "What this report does not know".

## What MarginKit is not

- not a guarantee of exact future cost
- not a replacement for runtime observability
- not an n8n-only product long term (LangGraph/CrewAI planned)

## Development

```bash
pip install -e .[dev]
pytest          # 78 tests incl. a golden corpus of real n8n.io templates
ruff check src tests scripts
```

After every pricing table update, regenerate the web pricing file:

```bash
python scripts/sync_pricing.py   # models_pricing.json -> web/pricing.js
```

`tests/test_web_parity.py` fails if the two pricing files drift, or if the
web engine and the Python engine disagree on any corpus workflow.
