Design Philosophy

# Core installation - just 2 dependencies
pip install nadoo-flow-core

# Add what YOU need, when you need it
pip install openai  # For OpenAI integration
pip install redis   # For distributed caching
pip install celpy   # For CEL expressions

# Fluent interface for workflow construction
workflow = (
    WorkflowBuilder()
    .add_node(input_node)
    .add_node(process_node)
    .add_edge("input", "process")
    .build()
)

# Different strategies for parallel execution
parallel = ParallelNode(
    nodes=[...],
    strategy=ParallelStrategy.RACE  # First to complete wins
)

# Wrap nodes with additional behavior
cached = CachedNode(expensive_node)
resilient = RetryableNode(cached)
limited = RateLimitedNode(resilient)

# Multiple handlers observe workflow events
workflow.add_callback(LoggingHandler())
workflow.add_callback(MetricsHandler())
workflow.add_callback(AlertingHandler())

# Level 1: Simple function
node = FunctionNode(lambda x: x.upper())

# Level 2: Custom node
class MyNode(ChainableNode):
    async def execute(self, ctx, wf_ctx):
        return NodeResult(success=True, output=...)

# Level 3: Advanced features
class AdvancedNode(StreamingNode, ChatHistoryNode):
    async def execute_with_history_and_streaming(...):
        ...

# Clear error messages
if not isinstance(input_data, dict):
    raise ValueError(
        f"Expected dict for input_data, got {type(input_data).__name__}. "
        f"Ensure your node returns a dictionary in the 'output' field."
    )

# Validation at construction time, not runtime
node = MyNode(config=invalid)  # Fails immediately with clear error