Dynamic Step

This guide will walk you through adding a toggle to your existing RAG pipeline to allow users to dynamically choose whether to use a component or not.

Toggle functionality gives users control over which components to execute in your pipeline, providing flexibility and optimization opportunities. For example, you can toggle knowledge base retrieval, specific processing steps, or any conditional logic based on runtime conditions.

This tutorial extends the Your First RAG Pipeline tutorial. Ensure you have followed the instructions to set up your repository.

Prerequisites

This example specifically requires:

1. Completion of the Your First RAG Pipeline tutorial - this builds directly on top of it

2. Completion of all setup steps listed on the Prerequisites page

3. A working OpenAI API key configured in your environment variables

You should be familiar with these concepts and components:

1. Components in Your First RAG Pipeline - Required foundation

2. toggle step

View full project code on GitHub

Installation

Linux, macOS, or Windows WSL

# you can use a Conda environment
pip install --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" gllm-rag gllm-core gllm-generation gllm-inference gllm-pipeline gllm-retrieval gllm-misc gllm-datastore

Windows Powershell

Windows Command Prompt

You can either:

1. You can refer to the guide whenever you need explanation or want to clarify how each part works.

2. Follow along with each step to recreate the files yourself while learning about the components and how to integrate them.

Both options will work—choose based on whether you prefer speed or learning by doing!

Project Setup

1

Extend Your RAG Pipeline Project

Start with your completed RAG pipeline project from the Your First RAG Pipeline tutorial. We don't need to add any new file for this tutorial. Therefore, the structure should stay as is:

<project-name>/
├── data/
│   ├── <index>/...                     
│   ├── chroma.sqlite3                  
│   ├── imaginary_animals.csv           
├── modules/
│   ├── retriever.py
│   └── response_synthesizer.py
├── .env
├── indexer.py                    
└── pipeline.py    # 👈 Will be updated with toggle

---

1) Build the Toggle Pipeline

Understanding Toggle Steps

A toggle step allows your pipeline to conditionally execute any components based on a boolean condition. This pattern can be applied to any pipeline step - retrieval, processing, validation, or custom logic. Here's how it works:

1. Toggle Condition: Evaluates a boolean condition from the pipeline state

2. Conditional Execution: If True, executes the specified steps; if False, skips them

3. Pipeline Continuation: The pipeline continues with subsequent steps regardless

In this example, we'll demonstrate toggling knowledge base retrieval, but the same pattern applies to any pipeline component.

Create the Enhanced Pipeline

1

Define the toggle state

Extend the RAG state to include the toggle condition:

class ToggleState(RAGState):
    use_knowledge_base: bool

This adds a use_knowledge_base field that controls whether retrieval is performed.

2

Create the toggle step

This is the core toggle logic that conditionally executes retrieval:

knowledge_base_toggle_step = toggle(
    condition=lambda x: x["use_knowledge_base"],
    if_branch=[retrieve_step],
)

How it works:

• condition: Lambda function that checks the use_knowledge_base boolean

• if_branch: Steps to execute if condition is True (document retrieval)

• else_branch: Not specified, so nothing happens if False

3

Compose the final pipeline

Chain the toggle step with the synthesis steps:

e2e_pipeline = knowledge_base_toggle_step | synthesize_step
e2e_pipeline.state_type = ToggleState

This creates a pipeline that:

1. Conditionally retrieves context from knowledge base based on the toggle

2. Synthesizes a response using either retrieved context or just the query

🧠 The response synthesizer can adapt its behavior based on whether context is available or not.

2) Run the Pipeline

When running the pipeline, you may encounter an error like this:

[2025-08-26T14:36:10+0700.550 chromadb.telemetry.product.posthog ERROR] Failed to send telemetry event CollectionQueryEvent: capture() takes 1 positional argument but 3 were given

Don't worry about this, since we do not use this Chroma feature. Your Pipeline should still work.

1

Configure the pipeline state for testing

Set up test cases with different toggle values to see conditional execution in action:

async def main():
    state = {
        "user_query": "Give me nocturnal creatures from the dataset", # Replace with your actual query
        "use_knowledge_base": False, # Set to True to retrieve from knowledge base
        "chunks": [] # Initialize to empty list if knowledge base is disabled
    }
    config = {
        "top_k": 5,
    }
    result = await e2e_pipeline.invoke(state, config)
    print(f"Pipeline result: {result['response']}")


if __name__ == "__main__":
    asyncio.run(main())

When you run the pipeline with knowledge base enabled, you should see retrieval happening in the debug logs. Otherwise, you should see no retrieval in the debug logs, and the response should be generated purely from the model's knowledge.

Troubleshooting

1. Pipeline always executes despite toggle being False:

   1. Check that you're using the correct state field name in your condition

   2. Verify the lambda condition syntax: lambda x: x["your_toggle_field"]

   3. Ensure you're passing the state correctly to invoke()

   4. Use debug mode to see which condition is being evaluated

2. Empty or unexpected responses when toggle is False:

   1. Check that downstream components can handle missing data from toggled steps

   2. Consider updating your prompts to handle scenarios when certain data is unavailable

3. Toggle condition not working:

   1. Verify your state class includes the boolean field: your_toggle_field: bool

   2. Check that the boolean value is properly set in your state

   3. Use debug mode to inspect the pipeline execution flow

   4. Test your lambda condition separately to ensure it evaluates correctly

4. General toggle pattern issues:

   1. Consider the impact of skipped steps on subsequent pipeline components

   2. Test both True and False conditions to verify expected behavior

---

Congratulations! You've successfully enhanced your RAG pipeline with toggle functionality. You can now conditionally execute any pipeline components based on runtime conditions, providing flexibility and optimization opportunities. This pattern can be applied to knowledge base retrieval, processing steps, validation, or any custom logic in your pipeline.