Natural Language Builder

Generate complete pipelines from plain English descriptions using AI-powered intent analysis and component matching.

Beta Feature - This feature is currently under heavy testing. For early access, contact [email protected].

FlowMason Studio includes an AI-powered Natural Language Builder that generates complete, working pipelines from plain English descriptions.

Overview

The Natural Language Builder enables:

• Pipeline Generation - Describe what you want, get a working pipeline
• Intent Analysis - Understand how your request is interpreted
• Component Matching - Automatically select the right components
• Iterative Refinement - Improve generated pipelines with feedback
• Template Library - Start from common patterns

Quick Start

Generate a Pipeline

POST /api/v1/nl-builder/generate
Content-Type: application/json

{
  "description": "Summarize a long article, then translate the summary to Spanish",
  "mode": "detailed"
}

Response:

{
  "success": true,
  "result": {
    "id": "gen_abc123",
    "status": "completed",
    "analysis": {
      "intent": "summarization",
      "actions": ["summarize", "translate"],
      "data_sources": ["user_input"],
      "outputs": ["text"]
    },
    "suggestions": [
      {
        "component_type": "generator",
        "purpose": "Generate summary from input",
        "confidence": 0.9
      },
      {
        "component_type": "generator",
        "purpose": "Translate content",
        "confidence": 0.85
      }
    ],
    "pipeline": {
      "name": "Summarization Pipeline",
      "stages": [
        {
          "id": "generator_1",
          "component_type": "generator",
          "config": {
            "prompt": "Summarize the following:\n\n{{input.text}}",
            "temperature": 0.7
          },
          "depends_on": []
        },
        {
          "id": "generator_2",
          "component_type": "generator",
          "config": {
            "prompt": "Translate to Spanish:\n\n{{stages.generator_1.output}}",
            "temperature": 0.7
          },
          "depends_on": ["generator_1"]
        }
      ]
    }
  }
}

Quick Generation

For simple pipelines, use the quick endpoint:

POST /api/v1/nl-builder/quick?description=Filter%20products%20by%20price%20and%20sort%20by%20rating

Returns just the pipeline without detailed analysis.

Generation Modes

Analyzing Requests

Preview how your description will be interpreted:

POST /api/v1/nl-builder/analyze?description=Fetch%20data%20from%20API%20and%20summarize

Response:

{
  "analysis": {
    "intent": "summarization",
    "actions": ["summarize", "call"],
    "data_sources": ["external_api"],
    "ambiguities": ["Output format not specified"]
  },
  "suggested_approach": "fetch from API -> summarize",
  "estimated_complexity": "moderate",
  "estimated_stages": 3
}

Finding Components

Search for components that match a task:

POST /api/v1/nl-builder/match-components
Content-Type: application/json

{
  "task": "filter a list of products by price",
  "limit": 3
}

Response:

{
  "matches": [
    {
      "component_type": "filter",
      "name": "Filter",
      "match_score": 0.95,
      "match_reason": "Direct match for filtering operations"
    },
    {
      "component_type": "json_transform",
      "name": "JSON Transform",
      "match_score": 0.6,
      "match_reason": "Can filter via JMESPath queries"
    }
  ]
}

Refining Pipelines

Improve a generated pipeline with feedback:

POST /api/v1/nl-builder/refine
Content-Type: application/json

{
  "generation_id": "gen_abc123",
  "feedback": "Add error handling and output as JSON"
}

Response:

{
  "original_id": "gen_abc123",
  "refined_id": "gen_def456",
  "changes_made": [
    "Wrapped stages in trycatch for error handling",
    "Added schema_validate for JSON output"
  ],
  "pipeline": { ... }
}

Templates

Start from predefined templates for common patterns:

Available Templates

Generate from Template

POST /api/v1/nl-builder/from-template/content-review
Content-Type: application/json

{
  "customization": "Focus on technical documentation"
}

Intent Recognition

The builder recognizes these intents:

Component Mapping

Actions are automatically mapped to components:

Advanced Options

Preferred/Avoided Components

Control which components are used:

{
  "description": "Process and validate user data",
  "preferred_components": ["schema_validate", "json_transform"],
  "avoid_components": ["http_request"]
}

Provide Context

Include additional context for better results:

{
  "description": "Generate a report from sales data",
  "context": {
    "available_fields": ["date", "amount", "product", "region"],
    "output_format": "markdown"
  },
  "examples": [
    {
      "input": {"sales": [{"amount": 100}]},
      "output": {"total": 100, "count": 1}
    }
  ]
}

Python Integration

from flowmason_studio.services.nl_builder_service import get_nl_builder_service
import asyncio

service = get_nl_builder_service()

async def generate():
    # Generate pipeline
    result = await service.generate_pipeline(
        description="Fetch news and summarize top 5",
        mode="detailed",
    )

    if result.pipeline:
        print(f"Generated: {result.pipeline.name}")
        for stage in result.pipeline.stages:
            print(f"  - {stage.id}: {stage.component_type}")

    # Find components
    matches = await service.find_components("filter by date", limit=3)
    for match in matches:
        print(f"{match.component_type}: {match.match_score:.2f}")

asyncio.run(generate())

Tips for Better Results

Good Descriptions

• “Fetch product data from API, filter by price under $100, and generate a summary report”
• “Validate JSON input against a schema, transform to new format, and send to webhook”
• “Take a list of articles, summarize each one, then combine into a newsletter”

Less Effective Descriptions

• “Process data” (too vague)
• “Make it work” (no specific intent)
• “Do the thing” (unclear)

Best Practices

1. Be Specific - Include details about inputs, outputs, and processing steps
2. Use Action Words - Start with verbs like “summarize”, “filter”, “transform”
3. Mention Data Sources - Specify if data comes from API, file, or user input
4. Describe Output Format - Mention if you need JSON, text, email, etc.
5. Iterate with Refinement - Use the refine endpoint to improve results