# Bland Pathway Design Guide

## Phone Tone Best Practices

Pathways power phone calls. Every prompt should be written for spoken conversation:

- **Keep responses short.** 1-3 sentences per turn. Nobody wants a monologue.
- **Use natural speech patterns.** Backchannels ("mhmm", "gotcha", "yep"), brief acknowledgments ("perfect", "great"), casual transitions.
- **Don't read lists.** Weave questions into conversation, one or two at a time.
- **Show emotion.** "Oh no, I'm sorry to hear that" or "That's awesome!" — not "I understand your concern."
- **Be warm but efficient.** Friendly doesn't mean slow. Respect the caller's time.
- **Avoid robotic phrasing.** No "I will now proceed to..." or "Please provide your..."
- **Mirror the caller.** If they're casual, be casual. If they're formal, match it.

## Node Design: Dense Context

Each node should be self-contained with rich context. The LLM only sees the current node's prompt, so pack in everything it needs:

```yaml
Check Availability:
  type: Default
  prompt: >-
    Ask what type of appointment they need and when they'd prefer to come in.
    We're open Monday-Friday 8am-6pm, Saturday 9am-1pm.

    Use the check_availability tool to look up slots. Share 2-3 options.
    If nothing works for their preferred time, suggest nearby alternatives.

    Keep it helpful: "Let me check what we've got for you."
  condition: >-
    Met when the caller has selected a specific appointment slot.
  extract_variables:
    - name: visit_type
      type: string
      description: Type of visit
    - name: preferred_date
      type: string
      description: Preferred date
```

## Tools on Nodes vs Webhook Nodes

**Prefer tools on nodes** over standalone webhook nodes:

| Use Tools On Nodes | Use Webhook Nodes |
|---|---|
| API lookups during conversation | Standalone operations that block flow |
| Inventory/availability checks | Payment processing |
| CRM data retrieval | Form submissions |
| Multiple tools on one node | Single critical API call |

### Tool Structure

```yaml
tools:
  - name: check_inventory        # LLM triggers via <function_name=check_inventory>
    description: Look up product stock
    type: webhook
    behavior: feed_context        # or "feed_context_and_route" for conditional routing
    speech: "Let me check that."  # Said before execution (optional)
    url: "https://api.example.com/stock"
    method: POST
    body:
      sku: "{{product_sku}}"      # {{var}} placeholders replaced at runtime
    response_data:
      - name: in_stock
        data: "$.available"       # JSONPath extraction
    timeout: 5000
    max_retries: 2
```

### Response-Based Routing

Route to different nodes based on API response:

```yaml
tools:
  - name: book_appointment
    type: webhook
    behavior: feed_context_and_route
    url: "https://api.example.com/book"
    method: POST
    body:
      patient: "{{patient_name}}"
      date: "{{date}}"
    response_data:
      - name: status
        data: "$.booking_status"
    response_pathways:
      - variable: status
        condition: "=="
        value: "confirmed"
        target_name: Booking Confirmed
      - variable: status
        condition: "=="
        value: "unavailable"
        target_name: Try Another Time
```

## Edge Design

Edges control conversation flow. Each edge needs:

- **label**: Short text shown on the edge (what triggers this transition)
- **description**: Detailed condition for the LLM to evaluate

```yaml
edges:
  - target: New Patient Info
    label: New patient
    description: Caller says they are new and haven't visited before.
  - target: Returning Patient
    label: Returning patient
    description: Caller says they've been here before or have an existing record.
```

## Node Conditions

The `condition` field tells the LLM when to transition away from this node:

```yaml
Collect Info:
  prompt: "Collect their name, phone, and email..."
  condition: >-
    Met when the caller has provided their full name, phone number,
    and email address.
```

## Variable Extraction

Extract structured data from conversation:

```yaml
extract_variables:
  - name: patient_name
    type: string
    description: The caller's full name
  - name: appointment_date
    type: string
    description: The selected appointment date and time
  - name: is_urgent
    type: boolean
    description: Whether the caller described an urgent medical need
```

## Model Options

Control LLM behavior per node:

```yaml
model_options:
  model_type: smart        # base, turbo, or smart
  temperature: 0.3         # Lower = more deterministic
  block_interruptions: true # Don't let caller interrupt during this node
```

## Complete Example

See `templates/complex-pathway.yaml` for a full appointment booking pathway with tools, conditions, and routing.