Pathwaysclass

Chainable builder for defining structured conversational pathways.

USAGE

Pathways(
    title,
    desc='',
    activation=None,
    completion_criteria=None,
    fallback_strategy=None,
)

The Pathways class provides intelligent conversation flow guidance while maintaining flexibility to adapt to natural conversation patterns. They serve as guardrails rather than rigid state machines, helping LLMs provide consistent and thorough assistance while remaining responsive to user needs and conversational context.

Parameters

title : str

A short, descriptive name for the pathway.

desc : str = ''

Clear, concise explanation of the pathway’s purpose and scope.

activation : Union[str, List[str], None] = None

Specific situations or user intents that trigger pathway activation. Can be a single string or a list of strings.

completion_criteria : Union[str, List[str], None] = None

High-level conditions that indicate the pathway’s objectives have been fully achieved. Can be a single string or a list of strings. Optional.

fallback_strategy : str = None

General approach for handling situations where the pathway doesn’t apply or users need different support. Optional.

Returns

Pathways

The configured Pathways object for further chaining with .state() and other methods.

Building Pathways

Building a pathway follows a specific sequence that ensures proper configuration and flow logic. Each step builds upon the previous one to create a coherent conversation structure.

1. Pathway Setup (call once, in order)

pathway = (
    tb.Pathways(
        title="Title",
        desc="Purpose and scope",               # What this pathway does
        activation=[...],                       # When to use this pathway
        completion_criteria=[...],              # What makes pathway successful
        fallback_strategy="..."                 # Handle unexpected situations
    )
    # First .state() call automatically becomes the starting state

2. State Definition

pathway = (
    tb.Pathways(
        title="Support Flow",
        desc="Customer support pathway",
        activation="User needs help"
    )
    # === STATE: intake ===
    .state("intake: gather customer information")
    .required(["issue description", "contact info"])
    .next_state("triage")
    # === STATE: triage ===
    .state("triage: route to appropriate support")
    .branch_on("Technical issue", id="tech_support")
    .branch_on("Billing question", id="billing")
    # === STATE: tech_support ===
    .state("tech support: resolve technical problems")
    .success_condition("Issue resolved")
)

This approach provides:

• visual state boundaries with # === STATE: description === comments
• natural state definition with shorthand syntax: .state("id: what happens here")
• smart type inference where .tools() → "tool", .branch_on() → "decision", .required() → "collect"
• automatic start state where the first .state() becomes the starting state

3. State Configuration Pattern (repeat for each state):

    # Define the state with description first
    .state("What happens in this state", id="state_name")
    .state("info: collect required information")            # inferred as "collect", id="info"
    .state("make decision: evaluate options and choose")    # "make decision" → id="make_decision"
    .state("use tools: apply specific capabilities")        # type inferred as "tool" from .tools()
    .state("final summary: provide conclusion", type="summary")  # explicit type with shorthand syntax
    .state("Wrap up")                                       # Linear states don't really need IDs

    # Configure the state
    .required([...])                               # What must be accomplished
    .optional([...])                               # What would be nice to have
    .tools([...])                                  # Available tools (infers type="tool")
    .success_condition("When state succeeds")      # How to know it's complete

    # Define state transitions (choose one)
    .next_state("next_state")                      # Linear progression
    .branch_on("condition", id="target_state")     # Conditional (infers type="decision")
    .next_state("common_state")                    # Reconverge after branching
    .fallback("error_condition", "backup_state")   # Error handling

State Types and Their Purpose

Each state type serves a specific role in the conversation flow:

• type="chat": open conversation, explanations, guidance (default)
• type="decision": branching logic, must use branch_on() not next_state()
• type="collect": structured information gathering
• type="tool": using specific tools or APIs, requires tools()
• type="summary": conclusions, confirmations, completion actions

Key Rules

• description is required and provided in .state() method
• if you use type="decision", you must use branch_on() and never next_state()
• type="tool" must include a tools() specification
• state names must be unique and use "lowercase_with_underscores"
• target states in transitions must be defined later with another .state()

Examples

---

The following examples demonstrate common pathway patterns that address different conversation needs. The first shows a simple linear flow where states progress sequentially—ideal for straightforward processes. The second illustrates branching logic that routes users down different paths before converging to a common endpoint—perfect for triage and support scenarios.

Simple Linear Flow

This password reset pathway demonstrates the basic pattern: setup the pathway, define states sequentially, and specify what information each state needs to collect. Notice how each state builds naturally toward the goal of helping the user regain access to their account.

import talk_box as tb

simple_pathway = (
    tb.Pathways(
        title="Password Reset",
        desc="Help users reset their forgotten passwords",
        activation=["User can't log in", "User forgot password"],
        completion_criteria="User successfully logs in with new password",
        fallback_strategy="If user lacks access to recovery methods, escalate to manual verification"
    )
    # === STATE: verification ===
    .state("verification: verify user identity")
    .required(["email address", "account verification"])
    .next_state("password_update")
    # === STATE: password_update ===
    .state("password update: guide user through creating new password")
    .required(["new password is created", "password requirements are met"])
    .success_condition("User successfully logs in with new password")
)

This linear flow moves step-by-step from identity verification to password creation. Each state has clear requirements and success conditions, making the pathway easy to follow and validate.

Branching Flow with Decision Points

This customer support pathway demonstrates decision state branching using the unified .state() method. Notice how different support paths merge back to a common completion state, ensuring consistent wrap-up regardless of the support type provided.

support_pathway = (
    tb.Pathways(
        title="Customer Support",
        desc="route and resolve customer inquiries",
        activation=["user needs help", "user reports problem"],
        completion_criteria=["customer issue fully resolved", "customer satisfied"],
        fallback_strategy="if issue is complex, escalate to human support"
    )
    # === STATE: triage ===
    .state("triage: determine the type of support needed")
    .branch_on("Technical problem reported", id="technical_support")
    .branch_on("Billing question asked", id="billing_support")
    .branch_on("General inquiry made", id="general_help")
    # === STATE: technical_support ===
    .state("technical support: diagnose and resolve technical issues")
    .tools(["system_diagnostics", "troubleshooting_guide"])
    .success_condition("Technical issue is resolved")
    .next_state("completion")
    # === STATE: billing_support ===
    .state("billing support: address billing and account questions")
    .required(["billing issue is understood", "solution is provided"])
    .next_state("completion")
    # === STATE: completion ===
    .state("completion: ensure customer satisfaction and wrap up", type="summary")
    .required(["issue resolved confirmation", "follow up if needed"])
    .success_condition("Customer satisfaction confirmed")
)

/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/talk_box/pathways.py:545: UserWarning: State 'completion' was explicitly set to 'summary' but method suggests 'collect'. Keeping explicit type 'summary'.
  warnings.warn(

This branching example shows how .state() creates clear decision points that route conversations appropriately, then merge back together for consistent completion.

Inspecting Pathways

Once you’ve built a pathway, you can inspect it using different string representations:

import talk_box as tb

# Create a simple pathway
pathway = (
    tb.Pathways(
        title="Quick Help",
        desc="Provide rapid assistance",
        activation="User needs help",
        completion_criteria="User's problem is resolved",
        fallback_strategy="If problem is complex, escalate to specialized support"
    )
    # === STATE: problem_intake ===
    .state("problem intake: understand the issue details")
    .required(["issue description"])
    .next_state("provide_solution")
    # === STATE: provide_solution ===
    .state("provide solution: offer targeted assistance")
    .success_condition("User's problem is resolved")
)

We can view the pathway in two ways, either as a brief summary by examining the object itself:

pathway

Quick Help

Provide rapid assistance

Problem Intake

Provide Solution

Chat

Collect

Tool

Decision

Summary

💡 Use .visualize() to save detailed pathway diagrams

Or with print() for a more detailed view:

print(pathway)

**Quick Help**
Purpose: Provide rapid assistance
Activate when:
- User needs help
Flow guidance:
- PROBLEM_INTAKE (collect): problem intake: understand the issue details
  Required: issue description
- PROVIDE_SOLUTION (summary): provide solution: offer targeted assistance
  Success: User's problem is resolved
Complete when: User's problem is resolved
Fallback: If problem is complex, escalate to specialized support
Follow as flexible guidance, adapting to user conversation patterns while ensuring key objectives
are addressed.

The summary view gives you a quick overview, while the detailed view shows the state types, description, and other configuration details. This is especially useful when debugging complex pathways or understanding existing pathway configurations.