Pathways.branch_on()method

Define conditional branch to another state based on specific conditions.

USAGE

Pathways.branch_on(condition, id)

Use with decision states to create multiple possible transitions based on user responses, detected conditions, or conversation context. Each branch should represent a distinct path through the workflow.

Parameters

condition : str

Specific, recognizable condition that triggers this branch. Be concrete and observable in conversation.

id : str

Target state ID for this branch condition. The target state must be defined later with .state().

Returns

Pathways

Self for method chaining, allowing combination with other pathway building methods to create comprehensive conversation flows.

Integration Notes

• Type Inference: infers current state type as "decision" if not explicitly set
• Mutual Exclusivity: conditions should be mutually exclusive when possible
• Forward Declaration: each branch must lead to a state defined later with .state()
• Concrete Conditions: be specific like "user mentions password issues" not "user has problems"
• Smart Routing: enables routing based on conditions with automatic decision state inference
• Reconvergence: allows multiple pathways that can reconverge later

The .branch_on() method enables smart routing based on conditions, automatically inferring the "decision" state type and allowing multiple pathways that can reconverge later.

Examples

---

Complete pathway showing .branch_on() creating conditional routing:

import talk_box as tb

# Creating a healthcare triage pathway
pathway = (
    tb.Pathways(
        title="Medical Triage",
        desc="route patients to appropriate care based on symptoms",
        activation="patient seeks medical assistance"
    )
    # === STATE: initial_assessment ===
    .state("initial assessment: assess patient symptoms and urgency")
    .required(["symptoms are described", "pain level", "duration"])
    .success_condition("Symptoms are clearly documented")
    .next_state("triage_decision")
    # === STATE: triage_decision ===
    .state("triage decision: determine appropriate care level")
    .required("urgency is evaluated")

    # .branch_on() routes based on severity -----
    .branch_on("severe or life-threatening symptoms", id="emergency_care")
    .branch_on("moderate symptoms requiring prompt attention", id="urgent_care")
    .branch_on("mild symptoms manageable with routine care", id="standard_care")

    # The first branch leads to emergency care -----
    # === STATE: emergency_care ===
    .state("emergency care: initiate emergency protocol")
    .required(["911 is called", "immediate first aid is provided"])
    .success_condition("emergency services are contacted")
    .next_state("follow_up")

    # The second branch leads to urgent care -----
    # === STATE: urgent_care ===
    .state("urgent care: schedule urgent care appointment")
    .required(["same day appointment", "preparation instructions"])
    .success_condition("urgent care is arranged")
    .next_state("follow_up")

    # The third branch leads to standard care -----
    # === STATE: standard_care ===
    .state("standard care: provide self-care guidance")
    .required(["home care instructions", "symptom monitoring"])
    .success_condition("patient understands self-care plan")
    .next_state("follow_up")
    # === STATE: follow_up ===
    .state("follow up: arrange follow-up care")
    .required(["follow up is scheduled"])
    .success_condition("continuity of care is ensured")
)

# See how branching creates appropriate care pathways
print(pathway)

**Medical Triage**
Purpose: route patients to appropriate care based on symptoms
Activate when:
- patient seeks medical assistance
Flow guidance:
- INITIAL_ASSESSMENT (collect): initial assessment: assess patient symptoms and urgency
  Required: (1) symptoms are described, (2) pain level, (3) duration
  Success: Symptoms are clearly documented
- TRIAGE_DECISION (collect): triage decision: determine appropriate care level
  Required: urgency is evaluated
  Branch 1: severe or life-threatening symptoms → EMERGENCY_CARE
  Branch 2: moderate symptoms requiring prompt attention → URGENT_CARE
  Branch 3: mild symptoms manageable with routine care → STANDARD_CARE
  - EMERGENCY_CARE (collect): emergency care: initiate emergency protocol
    Required: (1) 911 is called, (2) immediate first aid is provided
    Success: emergency services are contacted
  - URGENT_CARE (collect): urgent care: schedule urgent care appointment
    Required: (1) same day appointment, (2) preparation instructions
    Success: urgent care is arranged
  - STANDARD_CARE (collect): standard care: provide self-care guidance
    Required: (1) home care instructions, (2) symptom monitoring
    Success: patient understands self-care plan
- FOLLOW_UP (collect): follow up: arrange follow-up care
  Required: follow up is scheduled
  Success: continuity of care is ensured
Follow as flexible guidance, adapting to user conversation patterns while ensuring key objectives
are addressed.

/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/talk_box/pathways.py:561: UserWarning: State 'triage_decision' was inferred as 'collect' but method suggests 'decision'. Keeping first inference 'collect'.
  warnings.warn(