Add example of control flow composition with router agent and sequential executor

[thepatrickchin]

Description

This PR adds an example of composing router agent with sequential executor. It showcases the following control flows:

• Router agent to sequential executor
• Sequential executor to router agent
• router agent to router agent

By Submitting this PR I confirm:

• I am familiar with the Contributing Guidelines.
• We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  • Any contribution which contains commits that are not Signed-Off will not be accepted.
• When the PR is ready for review, new or existing tests cover these changes.
• When the PR is ready for review, the documentation is up to date with these changes.

Summary by CodeRabbit

• Documentation

  • Added a new example showcasing mixed control-flow patterns with architecture diagram, full YAML configuration, installation/setup steps, run instructions for three workflow scenarios, and sample console outputs.

• Tests

  • Added integration tests exercising the example’s end-to-end workflows across various routing and sequencing patterns.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Walkthrough

Adds a new "Mixture of Control Flows" example: documentation, project metadata, a YAML workflow combining router_agent and sequential_executor patterns, mock function registrations, and integration tests exercising several routing and sequential scenarios.

Changes

Cohort / File(s)	Summary
Documentation examples/control_flow/mixture_of_control_flows/README.md	New README describing graph structure, complete YAML config, installation/run instructions, and sample outputs for three workflow scenarios.
Project metadata & packaging examples/control_flow/mixture_of_control_flows/pyproject.toml, examples/control_flow/mixture_of_control_flows/configs	New pyproject.toml defining build system, editable local sources and entry point; configs file pointing to the example configs directory.
Workflow configuration examples/control_flow/mixture_of_control_flows/src/mixture_of_control_flows/configs/config.yml	Adds comprehensive YAML describing an LLM config, multiple function components, two sequential_executor pipelines, two router_agent pipelines (including nested branches), and a top-level router workflow with detailed_logs.
Function registrations / implementation examples/control_flow/mixture_of_control_flows/src/mixture_of_control_flows/register.py	Registers four mock functions (input validator, uppercase converter, lowercase converter, result formatter) with config classes and async implementations for integration into the workflows.
Tests examples/control_flow/mixture_of_control_flows/tests/test_mixture_of_control_flows.py	Adds parameterized integration test exercising router→sequential, sequential→router, and nested router scenarios with expected outputs.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Client as Client
participant Router as RouterAgent
participant Seq as SequentialExecutor
participant LLM as LLM
participant Func as FunctionComponent

Client->>Router: Submit request
Router->>LLM: Evaluate routing decision
LLM-->>Router: Selected branch
alt Branch -> Sequential
    Router->>Seq: Forward to sequential pipeline
    Seq->>Func: Invoke step 1 (e.g., text_processor)
    Func-->>Seq: Result
    Seq->>Func: Invoke step 2 (e.g., report_generator)
    Func-->>Seq: Final result
    Seq-->>Router: Pipeline output
else Branch -> Nested Router
    Router->>Router: Forward to nested router
    Router->>LLM: Nested routing decision
    LLM-->>Router: Selected nested function
    Router->>Func: Invoke advisor function
    Func-->>Router: Advisor result
end
Router-->>Client: Final response

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding an example demonstrating control flow composition with router agents and sequential executors.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@examples/control_flow/mixture_of_control_flows/configs`:
- Line 1: The file named "configs" in the mixture_of_control_flows example
contains an absolute local path string ("/Users/...") and must be removed or
replaced: either delete this file from the repo, or recreate it as a proper
relative symlink that points to the example's configs directory (e.g., create a
symlink named configs that points to the src/mixture_of_control_flows/configs
directory); ensure no absolute local paths remain in the committed file.

🧹 Nitpick comments (6)

examples/control_flow/mixture_of_control_flows/pyproject.toml (1)

46-47: Add trailing newline at end of file.

Per coding guidelines, every file should end with a single newline.

Proposed fix

 [project.entry-points.'nat.components']
 nat_mixture_of_control_flows = "mixture_of_control_flows.register"
+

examples/control_flow/mixture_of_control_flows/src/mixture_of_control_flows/register.py (2)

31-57: Consider adding return type hints for async generator functions.

For better type safety and documentation, the async generator functions should include return type hints. The config and builder parameters are required by the @register_function decorator interface, so the Ruff warnings about unused arguments are false positives in this context.

Example type hint addition

+from collections.abc import AsyncGenerator
+
 `@register_function`(config_type=MockInputValidatorFunctionConfig, framework_wrappers=[LLMFrameworkEnum.LANGCHAIN])
-async def mock_input_validator_function(config: MockInputValidatorFunctionConfig, builder: Builder):
+async def mock_input_validator_function(
+    config: MockInputValidatorFunctionConfig, builder: Builder
+) -> AsyncGenerator[FunctionInfo, None]:

---

137-139: Add trailing newline at end of file.

Per coding guidelines, every file should end with a single newline.

Proposed fix

     yield FunctionInfo.from_fn(format_result, description="Format the final processing result")
+

examples/control_flow/mixture_of_control_flows/src/mixture_of_control_flows/configs/config.yml (2)

1-1: Copyright year inconsistency.

This file uses 2024-2026 while other files in this PR use 2025-2026. For consistency across the new example, consider updating to 2025-2026.

Proposed fix

-# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.

---

69-73: Add trailing newline at end of file.

Per coding guidelines, every file should end with a single newline.

Proposed fix

   branches: [text_analysis_pipeline, text_formatting_pipeline, general_advisor]
   llm_name: nim_llm
   detailed_logs: true
+

examples/control_flow/mixture_of_control_flows/tests/test_mixture_of_control_flows.py (1)

44-45: Add trailing newline at end of file.

Per coding guidelines, every file should end with a single newline.

Proposed fix

     await run_workflow(config_file=config_file, question=question, expected_answer=expected_answer)
+

[willkill07]

Minor feedback overall. Please address the symbolic link issue by having it be relative rather than absolute.

[willkill07]

Since we don't publish these packages, you can get away with:

Suggested change

	"nat_sequential_executor == {version}",
	"nat_router_agent == {version}",
	"nat_sequential_executor",
	"nat_router_agent",

[willkill07]

Nit: for each of these have an output immediately follow run.

[willkill07]

We are trying to reduce our dependence on this model. Have you tried this with nvidia/nemotron-3-nano-30b-a3b?

[willkill07]

Adjust this line/config if you adjust the file

[willkill07]

/ok to test 409ee7f

[willkill07]

One other request... if you update develop, please add nat_mixture_of_control_flows to the examples listing and reference it accordingly (and rerun uv lock in the root directory).

We are trying to do better at tracking examples and their dependencies.