npm package: @stable-canvas/sd-webui-a1111-prompt-parser
Description: sd-webui-a1111-prompt-parser is a Stable Diffusion webUI (A1111) prompt parser for JavaScript. It parses Stable Diffusion model prompts into structured data for easy analysis and manipulation by developers.
Author: zhzluke96
Latest version: 1.3.0

# sd-webui-a1111-prompt-parser

## Introduction

sd-webui-a1111-prompt-parser is a Stable Diffusion webUI (A1111) prompt parser for JavaScript. It parses Stable Diffusion model prompts into structured data for easy analysis and manipulation by developers.

## Features

- Parses A1111 format prompts, supporting the following syntax:
  - Plain text
  - Emphasis (parentheses)
  - Weight (brackets)
  - Lora models
  - Hypernetwork models
  - Negative prompts (square brackets)
  - Step Control (scheduling)
- Converts parsed results into JavaScript objects for easy manipulation and use
- Supports regenerating A1111 format prompts from JavaScript objects

## Installation

```
pnpm add @stable-canvas/sd-webui-a1111-prompt-parser
```

## Usage

```typescript
import { PromptParser } from "@stable-canvas/sd-webui-a1111-prompt-parser";

const parser = new PromptParser();

const prompt = `masterpiece, 1girl, blonde hair, <lora:Zelda_v1:0.5>, (chromatic aberration:0.7), sharp focus, hyper detailed, (fog:0.7), <hypernet:sxz-bloom:0.5>, [real photo], [highlight:dark:0.9], (((good anatomy)))`;

const output = parser.parse(prompt);

console.log(output);
```

Output:

```json
[
  { "type": "plain", "value": "masterpiece" },
  { "type": "plain", "value": "1girl" },
  { "type": "plain", "value": "blonde hair" },
  { "type": "extra_networks", "value": "lora", "args": ["Zelda_v1", "0.5"] },
  {
    "type": "weighted",
    "value": 0.7,
    "args": [{ "type": "plain", "value": "chromatic aberration" }]
  },
  { "type": "plain", "value": "sharp focus" },
  { "type": "plain", "value": "hyper detailed" },
  {
    "type": "weighted",
    "value": 0.7,
    "args": [{ "type": "plain", "value": "fog" }]
  },
  {
    "type": "extra_networks",
    "value": "hypernet",
    "args": ["sxz-bloom", "0.5"]
  },
  {
    "type": "negative",
    "value": 1,
    "args": [{ "type": "plain", "value": "real photo" }]
  },
  {
    "type": "scheduled_full",
    "value": 0.9,
    "args": [
      [{ "type": "plain", "value": "highlight" }],
      [{ "type": "plain", "value": "dark" }]
    ]
  },
  {
    "type": "positive",
    "value": 3,
    "args": [{ "type": "plain", "value": "good anatomy" }]
  }
]
```

### Usage Case: de-SD-styled (remove stable-diffusion styled prompt)

This function is used to clear all SD-WebUI style prompts, which is necessary when training new models based on DiT.

> Theoretically, it should iterate through the tokens (this is a high level AST structure), but generally, no one writes prompt control syntax beyond two levels.

```typescript
import {
  PromptParser,
  generation_str,
} from "@stable-canvas/sd-webui-a1111-prompt-parser";

const parser = new PromptParser();

function cleanPrompt(prompt: string): string {
  const tokens = parser
    .parse(prompt)
    .filter((x) => x.type !== "extra_networks")
    .flatMap((x) => {
      switch (x.type) {
        case "weighted":
        case "negative":
        case "positive":
        case "scheduled_full":
          return x.args;
        default:
          return x;
      }
    });

  return generation_str(tokens).trim();
}
```

## API

### `PromptParser` Class

#### Constructor

```typescript
new PromptParser(options?: SDPromptParser.ILarkOptions);
```

- `options`: Optional parameters for configuring the Lark parser. For detailed parameter descriptions, refer to the [Lark documentation](https://lark-parser.readthedocs.io/en/latest/classes/ Lark.html#lark.Lark).

#### `parse` Method

```typescript
parse(text: string, options?: ParseOptions): SDPromptParser.PromptNode[];
```

- `text`: The prompt string to be parsed.
- `options`: Optional parameters for configuring parsing behavior.
  - `force`: When set to `true`, parsing is forced even if there are syntax errors in the prompt. The parsing results may be incomplete. The default is `false`.
- Returns: An array of parsed prompt nodes, node type definitions refer to `SDPromptParser.PromptNode`.

### `compilation` Function

```typescript
compilation(node: SDPromptParser.IPromptASTNode): SDPromptParser.PromptNode[];
```

- `node`: The root node of the abstract syntax tree (AST) generated by the Lark parser.
- Returns: An array of parsed prompt nodes, node type definitions refer to `SDPromptParser.PromptNode`.

### `generation_token` Function

```typescript
generation_token(nodes: SDPromptParser.PromptNode[], options?: GenerationOptions): string[];
```

- `nodes`: An array of nodes for which to generate prompt strings.
- `options`: Optional parameters for configuring generation behavior.
  - `remove_1_weighted`: When set to `true`, nodes with a weight of 1 are removed. The default is `false`.
- Returns: An array of generated prompt strings.

### `generation_str` Function

```typescript
generation_str(nodes: SDPromptParser.PromptNode[], options?: GenerationOptions): string;
```

- `nodes`: An array of nodes for which to generate the prompt string.
- `options`: Optional parameters for configuring generation behavior.
  - `remove_1_weighted`: When set to `true`, nodes with a weight of 1 are removed. The default is `false`.
- Returns: The generated prompt string.

## Build

### 1. Build the Parser

#### 1.1 Install Lark.js

```
pip install lark-js
```

#### 1.2 Build

```
pnpm build-lark
```

### 2. Build the Package

```
pnpm build
```

## Test

```
pnpm test
```

## License

MIT