Migration Guide: v0.4.0 - Curated Public API

Overview

Flujo v0.4.0 introduces a curated, layered public API that improves discoverability, clarity, and long-term maintainability. The library now groups related components into logical sub-modules while keeping the most essential components accessible from the top level.

What Changed

Before (v0.3.x)

# Flat, overwhelming namespace with 40+ symbols
from flujo import (
    Flujo, Default, Step, step, Pipeline, Task, Candidate,
    StubAgent, SQLSyntaxValidator, SerializePydantic,
    UsageLimitExceededError, ConsoleTracer, format_prompt,
    # ... and 30+ more symbols
)

After (v0.4.0)

# Core components at top level for convenience
from flujo import Flujo, Step, step, Pipeline, Task, Candidate

# Related components grouped in sub-modules
from flujo import recipes, testing, plugins, processors, models
from flujo.testing import StubAgent
from flujo.plugins import SQLSyntaxValidator
from flujo.processors import SerializePydantic
from flujo.exceptions import UsageLimitExceededError
from flujo.validation import BaseValidator, validator

Migration Steps

1. Core Components (No Change)

The most essential components remain at the top level:

# ✅ Still works - no changes needed
from flujo import Flujo, Step, step, Pipeline, Task, Candidate

2. Recipes

# ❌ Old way
from flujo import Default, AgenticLoop

# ✅ New way
from flujo.recipes import Default, AgenticLoop

3. Testing Utilities

# ❌ Old way
from flujo import StubAgent, DummyPlugin

# ✅ New way
from flujo.testing import StubAgent, DummyPlugin

4. Built-in Plugins

# ❌ Old way
from flujo import SQLSyntaxValidator

# ✅ New way
from flujo.plugins import SQLSyntaxValidator

5. Built-in Processors

# ❌ Old way
from flujo import SerializePydantic, AddContextVariables

# ✅ New way
from flujo.processors import SerializePydantic, AddContextVariables

6. Domain Models

# ❌ Old way
from flujo import PipelineResult, StepResult, UsageLimits

# ✅ New way
from flujo.models import PipelineResult, StepResult, UsageLimits

7. Exceptions

# ❌ Old way
from flujo import UsageLimitExceededError, ConfigurationError

# ✅ New way
from flujo.exceptions import UsageLimitExceededError, ConfigurationError

8. Validation Utilities

# ❌ Old way
from flujo import BaseValidator, validator

# ✅ New way
from flujo.validation import BaseValidator, validator

9. Utility Functions

# ❌ Old way
from flujo import format_prompt

# ✅ New way
from flujo.utils import format_prompt

Available Sub-modules

Sub-module	Purpose	Key Exports
`flujo.recipes`	Pre-built workflow recipes	`Default`, `AgenticLoop`
`flujo.testing`	Testing utilities	`StubAgent`, `DummyPlugin`
`flujo.plugins`	Built-in plugins	`SQLSyntaxValidator`
`flujo.processors`	Built-in processors	`SerializePydantic`, `AddContextVariables`
`flujo.models`	Domain models	`PipelineResult`, `StepResult`, `UsageLimits`
`flujo.exceptions`	Exception classes	`UsageLimitExceededError`, `ConfigurationError`
`flujo.validation`	Validation utilities	`BaseValidator`, `validator`
`flujo.utils`	Utility functions	`format_prompt`
`flujo.domain`	Domain components	`AgentProcessors`, `ValidationPlugin`
`flujo.application`	Application components	`SelfImprovementAgent`
`flujo.infra`	Infrastructure components	`settings`, `init_telemetry`

Benefits

Better Discoverability: Related components are grouped together
Cleaner Namespace: Top-level imports are limited to essential components
Improved IDE Support: Better autocomplete and navigation
Future-Proof: Easier to evolve internal components without breaking changes
Professional API: Follows Python packaging best practices

Backward Compatibility

Core components remain at the top level for convenience
All functionality is still available, just organized differently
No breaking changes to the actual functionality

Need Help?

If you encounter any issues during migration, please: 1. Check the API Reference for the new import paths 2. Look at the updated examples for working code 3. Open an issue on GitHub if you find any problems