npm package: @luckydraw/plastic
Description: Distributed flow execution platform with LLM-designed automations
Latest version: 0.3.0

# Plastic

**LLM-designed automation that runs without the LLM.**

Plastic is a distributed flow execution platform where an LLM designs deterministic automation pipelines, then gets out of the way. Flows execute cheaply and reliably at the edge — only escalating back to the LLM when they encounter situations requiring judgment.

```
  "The LLM's job is to make itself unnecessary for predictable situations."

  LLM  = Architect  (designs flows, handles escalations)
  Edge = Builder    (executes flows deterministically, works offline)
```

## Why Plastic?

Most LLM-powered automation calls the LLM on every event. That's expensive, slow, and fragile.

**Plastic inverts this:**

1. User describes what they want in natural language
2. LLM designs a flow through a structured conversation (asking clarifying questions as needed)
3. A design-time linter validates the flow before the user ever sees it
4. The flow executes at the edge without LLM involvement (98%+ of the time)
5. LLM only re-engages for edge cases, errors, or optimization

| Approach                   | Cost for 1000 daily events |
| -------------------------- | -------------------------- |
| LLM on every event         | ~$300/month                |
| Plastic (LLM as architect) | ~$6/month                  |

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      PLASTIC CLOUD (Netlify)                    │
│  ┌────────────────┐  ┌───────────────┐  ┌───────────────────┐  │
│  │ LLM Designer   │  │ Flow Registry │  │ Escalation Handler│  │
│  │ + Linter       │  │ + Sync        │  │                   │  │
│  └────────────────┘  └───────────────┘  └───────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
           │                    │                    │
           │  Design flows      │  Sync flows        │  Handle escalations
           ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                    EDGE RUNTIMES (Autonomous)                   │
├─────────────────┬─────────────────┬─────────────────────────────┤
│  WordPress      │  Browser/React  │  Node.js CLI                │
│  27 blocks      │  IndexedDB      │  SQLite                     │
│  7 triggers     │  Offline queue  │  Cron triggers              │
│  21 descriptors │  DOM triggers   │  Dashboard                  │
│  Linter         │                 │                             │
│                 │                 │                             │
│  Runs offline   │  Runs offline   │  Runs offline               │
└─────────────────┴─────────────────┴─────────────────────────────┘
```

**Key insight:** The brains live in the cloud, but execution happens at the edge. Flows continue running even when disconnected — escalations queue locally and sync when reconnected.

## How It Works

### 1. Design a Flow

Send a natural language request. The LLM designs the flow through a conversation — asking clarifying questions when the request is ambiguous, then returning a validated flow definition:

```typescript
const response = await fetch('https://plastic-app.netlify.app/flow-design', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    prompt: 'When a new member joins, send a personalized welcome if they have a referral source',
  }),
});

const { status, flow, questions } = await response.json();
// status: 'complete' (flow ready) or 'clarification_needed' (answer questions first)
```

### 2. Execute at the Edge (No API Calls)

```typescript
import { executeFlow } from 'plastic';

const result = await executeFlow(flow, {
  trigger: { type: 'event', data: { email: 'user@example.com', referral_source: 'twitter' } },
});
// Runs locally, deterministically, works offline
```

The LLM designs once. The edge executes forever.

## Edge-Agnostic Design

Every edge runtime — WordPress, Node.js, browser, or any future platform — plugs into Plastic through three contracts:

- **PlatformBlock** — Blocks self-describe their config fields, output shapes, examples, and hints. The LLM reads this as structured documentation. Third-party plugins register blocks via hooks.
- **PlatformTrigger** — Triggers declare their fields and aliases. The LLM sees trigger-specific `{{input.*}}` paths instead of guessing.
- **JSON Function Descriptors** — A generic gateway block interprets JSON descriptors at runtime, so new platform capabilities ship as data (not code). WordPress has 21 descriptors today; adding more requires zero PHP changes.

This means a Shopify edge, an IoT edge, or a mobile edge would implement the same contracts and get the same LLM grounding, design-time validation, and execution pipeline — no cloud-side changes needed.

## Key Features

- **Conversational flow design** — Multi-turn design with typed clarification questions (text, select, boolean, number, multiselect)
- **Design-time linter** — 14 validation rules catch errors before users see them; generate-lint-fix loop (max 3 rounds)
- **50+ composable blocks** — Control flow, transforms, integrations, data ops, intelligence (see [Block Library](./docs/blocks.md))
- **Expression engine** — `{{input.post_title}}`, `{{variables.blockId.field}}`, arithmetic, comparisons, ternary, 40+ built-in functions
- **Escalation pattern** — Flows escalate to the LLM only when stuck; the LLM can resolve, modify the flow, or alert a human
- **Self-optimization** — Metrics pipeline tracks success rate, escalation rate, latency; LLM proposes improvements when thresholds are breached
- **Flow versioning** — Semver, branching, diffing, undo/redo, partial regeneration

## WordPress Plugin

The WordPress plugin is the most mature edge runtime, with a full flow execution engine running entirely in PHP:

- **27 block classes** with self-describing metadata (config fields, output shapes, examples, hints)
- **7 triggers** with typed field descriptors and aliases
- **21 JSON function descriptors** (9 WordPress core, 7 BuddyPress, 5 WooCommerce) executed through a generic `wp_call` gateway
- **Flow linter** validating before save (8 rules, subset of the 14 cloud-side rules)
- **Expression evaluator** with arithmetic, comparisons, logic, ternary
- **Conversational UI** with structured clarification forms
- **Third-party extensibility** via `plastic_register_blocks`, `plastic_register_triggers`, `plastic_register_functions` hooks

See [WordPress Integration](./docs/integration-wordpress.md) for the full guide.

## Packages

| Package                 | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `plastic`               | Core library with blocks, runtime, and LLM designer |
| `@plastic/edge-runtime` | Portable runtime for edge environments (~50KB)      |
| `@plastic/browser-sdk`  | Browser/React SDK with offline support              |
| `@plastic/cli-runtime`  | CLI for local development and testing               |

## Documentation

- **[Library Integration](./docs/integration-library.md) — How to use Plastic as an npm dependency** (start here)
- [Concept Overview](./docs/concept-overview.md) — Philosophy and architecture
- [Block Library](./docs/blocks.md) — Complete block reference
- [Distributed Runtime](./docs/architecture-distributed-runtime.md) — Edge architecture
- [WordPress Integration](./docs/integration-wordpress.md) — WordPress plugin guide
- [Browser/React Integration](./docs/integration-browser-react.md) — Browser SDK guide
- [Current Implementation](./docs/current_implementation.md) — Detailed implementation status

## Development

```bash
npm install       # Install dependencies
npm test          # Run tests (1958 passing)
npm run build     # Build
npm run typecheck  # Type check (0 errors)
```

## License

MIT