Pathways.branch_on()

Define conditional branch to another state based on specific conditions.

Usage

Source

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)