Formula DSL

Learn how to write and customize formulas using the BotWash Domain-Specific Language (DSL). Formulas are JSON-based recipes that define a series of text transformations.

Formula Structure

A formula is a JSON object that defines operations:

{
  "operations": [
    {
      "type": "operation_name",
      "params": {
        "param1": "value1",
        "param2": 42
      }
    }
  ]
}

Formula Metadata

Formula metadata is managed separately through the API and includes:

Fields

• title - Short, descriptive name (3-50 characters)
• summary - One-line description (10-200 characters)
• categories - Array of category IDs for organization
• visibility - public, private, or organization

Optional Fields

• description - Detailed explanation (markdown supported)
• examples - Array of before/after examples
• author - Author name or organization
• version - Semantic version (auto-managed)

Operations Array

Operations execute in order, from first to last. Each operation transforms the output of the previous operation.

Operation Object

{
  "type": "operation_type",
  "params": {
    "param_name": "param_value"
  },
  "enabled": true,
  "id": "unique-id"
}

Fields

• type - Operation type (required, see Operations Reference)
• params - Parameters object (required, varies by operation)
• enabled - Whether operation is active (optional, default: true)
• id - Unique identifier (optional, auto-generated)

Example Formulas

Simple Polish

Basic cleanup for AI-generated blog posts:

{
  "operations": [
    {
      "type": "redundancy_pruner",
      "params": {
        "strictness": 7
      }
    },
    {
      "type": "readability_normalizer",
      "params": {
        "target_grade": 8
      }
    },
    {
      "type": "punctuation_sanity",
      "params": {
        "oxford_comma": true,
        "dash_style": "em"
      }
    }
  ]
}

Professional Email

Convert casual text to professional email style:

{
  "operations": [
    {
      "type": "formality_tuner",
      "params": {
        "level": "formal"
      }
    },
    {
      "type": "contraction_manager",
      "params": {
        "mode": "expand"
      }
    },
    {
      "type": "hedge_reducer",
      "params": {
        "level": 5,
        "keep_politeness": true
      }
    },
    {
      "type": "paragraph_rechunker",
      "params": {
        "target_lines_per_para": 3,
        "max_para_len": 5
      }
    }
  ]
}

Marketing Copy

Enhance text for marketing and sales:

{
  "operations": [
    {
      "type": "assertiveness_tuner",
      "params": {
        "direction": "more",
        "level": 7
      }
    },
    {
      "type": "sentiment_shifter",
      "params": {
        "target": "positive",
        "intensity": 8
      }
    },
    {
      "type": "call_to_action_crafter",
      "params": {
        "audience": "business professionals",
        "tone": "confident",
        "strength": 8
      }
    }
  ]
}

Academic Paper

Format for academic writing:

{
  "operations": [
    {
      "type": "formality_tuner",
      "params": {
        "level": "formal"
      }
    },
    {
      "type": "person_perspective_normalizer",
      "params": {
        "person": "3p"
      }
    },
    {
      "type": "hedge_reducer",
      "params": {
        "level": 3,
        "keep_politeness": true
      }
    },
    {
      "type": "citation_normalizer",
      "params": {
        "style": "APA",
        "in_text_only": false
      }
    },
    {
      "type": "terminology_consistency",
      "params": {
        "glossary": {
          "AI": "artificial intelligence",
          "ML": "machine learning"
        }
      }
    }
  ]
}

Best Practices

Operation Order

Order matters. Generally follow this sequence:

1. Structure - Fix paragraphs, sentences, lists
2. Content - Remove redundancy, adjust clarity
3. Tone - Adjust formality, sentiment, voice
4. Polish - Fix grammar, spelling, punctuation
5. Format - Final formatting and markup

Testing

• Test with multiple text samples of different lengths
• Start with fewer operations and add gradually
• Use the preview feature to see operation-by-operation changes
• Check edge cases (very short text, very long text, lists, etc.)

Performance

• Fewer operations = faster processing
• Some operations are computationally expensive (AI-based ones)
• Consider disabling optional operations for large texts
• Operations run sequentially, not in parallel

Versioning Guidelines

When publishing formula updates:

• Patch (1.0.1) - Bug fixes, parameter tweaks
• Minor (1.1.0) - Add operations, backward compatible
• Major (2.0.0) - Remove operations, breaking changes

Advanced Features

Conditional Operations

Operations can have conditions (coming soon):

{
  "type": "sentence_splitter",
  "params": {
    "max_len": 20
  },
  "condition": {
    "if": "input.word_count > 500"
  }
}

Operation Groups

Group related operations (coming soon):

{
  "groups": [
    {
      "name": "Clarity Pass",
      "operations": [...]
    },
    {
      "name": "Polish Pass",
      "operations": [...]
    }
  ]
}

Variables

Define reusable variables (coming soon):

{
  "variables": {
    "target_grade": 8,
    "formality": "formal"
  },
  "operations": [
    {
      "type": "readability_normalizer",
      "params": {
        "target_grade": "${target_grade}"
      }
    }
  ]
}

Publishing Formulas

Visibility Options

• Public - Anyone can discover and use
• Private - Only you can see and use
• Organization - Shared with team members

Quality Guidelines

For public formulas:

• Clear, descriptive title and summary
• Appropriate tags for discoverability
• At least one example showing before/after
• Well-documented parameter choices
• Tested with various text types

Community Standards

• No malicious operations (PII extraction, etc.)
• Accurate descriptions and tags
• Respect copyright and attribution
• Respond to feedback and issues

Validation

Formulas are validated on save. Common errors:

• Invalid operation type - Operation does not exist
• Missing required parameter - Required param not provided
• Invalid parameter type - Wrong type (string vs number)
• Invalid parameter value - Value out of allowed range
• Empty operations array - Formula must have at least one operation

Importing/Exporting

Export

Download formula as JSON file from the formula detail page.

Import

Upload a JSON file in the Formula Builder to import an existing formula.

Sharing

Share formulas via:

• Public URL (published formulas)
• JSON export file
• API (programmatic access)

API Usage

You can create and manage formulas programmatically. See the API Reference for details on the /api/v1/formulas endpoints.