> ## Documentation Index
> Fetch the complete documentation index at: https://docs.re-factor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flows (Alpha)

> Orchestrate complex AI workflows

<Note>
  Flows are currently in private alpha and subject to change. If you would like to use them, please reach out to [re-factor Support](mailto:support@psci-labs.com).
</Note>

## Motivation

Flows in re-factor provide a powerful way to orchestrate complex AI workflows by combining [prompts](/core-concepts/prompts), [agents](/core-concepts/agents), and [tools](/core-concepts/tools) into coherent processes. They enable you to build sophisticated AI applications while maintaining clarity and control over the execution process.

## Basic Features

A flow in re-factor consists of several key components:

1. A sequence of steps that define the workflow
2. Input and output specifications for each step
3. Error handling and retry logic
4. State management across steps
5. Monitoring and observability features

## Enhanced Features

#### Step Definition

Steps in a flow can be any combination of:

<CodeGroup>
  ```typescript example.ts theme={null}
  import { Flow } from '@re-factor/sdk';

  const flow = new Flow({
      name: "Document Processing",
      steps: [{
          name: "extract_text",
          type: "tool",
          config: {
              tool: "pdf_extractor",
              input: "{{ document }}"
          }
      }, {
          name: "analyze_content",
          type: "prompt",
          config: {
              prompt: "Analyze the following text: {{ extract_text.output }}",
              model: "gpt-4"
          }
      }, {
          name: "generate_summary",
          type: "agent",
          config: {
              agent: "content_summarizer",
              input: "{{ analyze_content.output }}"
          }
      }]
  });

  const result = await flow.execute({
      document: pdfDocument
  });
  ```

  ```python example.py theme={null}
  from refactor.flows import Flow

  flow = Flow(
      name="Document Processing",
      steps=[{
          "name": "extract_text",
          "type": "tool",
          "config": {
              "tool": "pdf_extractor",
              "input": "{{ document }}"
          }
      }, {
          "name": "analyze_content",
          "type": "prompt",
          "config": {
              "prompt": "Analyze the following text: {{ extract_text.output }}",
              "model": "gpt-4"
          }
      }, {
          "name": "generate_summary",
          "type": "agent",
          "config": {
              "agent": "content_summarizer",
              "input": "{{ analyze_content.output }}"
          }
      }]
  )

  result = await flow.execute({
      "document": pdf_document
  })
  ```
</CodeGroup>

#### State Management

Flows maintain state across steps through:

* Input/output passing between steps
* Shared context objects
* Persistent storage options
* Variable scoping rules

#### Error Handling

Flows provide robust error handling mechanisms:

* Step-level retry policies
* Error recovery strategies
* Fallback paths
* Compensation handling for failed steps

#### Monitoring

Each flow comes with comprehensive monitoring capabilities:

* Real-time execution tracking
* Step-level metrics
* Resource usage monitoring
* Performance analytics

## Schema

Flows in re-factor are defined using Zod schemas that ensure type safety and validation:

### Step Schema

```typescript theme={null}
const StepSchema = {
    name: string,
    type: 'prompt' | 'tool' | 'agent' | 'flow',
    config: Record<string, any>,
    condition?: () => boolean,
    errorHandling?: {
        retry?: boolean,
        fallback?: any
    }
}
```

### Flow Schema

```typescript theme={null}
const FlowSchema = {
    // Metadata
    name: string,
    description?: string,
    tags?: string[],
    version?: string,
    created?: Date,
    updated?: Date,

    // Core Components
    steps: Step[],
    inputs?: Record<string, any>,
    outputs?: Record<string, any>,
    state?: {
        type: 'memory' | 'disk' | 'database',
        config?: Record<string, any>
    },
    monitoring?: {
        metrics?: string[],
        callbacks?: Record<string, Function>
    }
}
```

### Example Usage

<CodeGroup>
  ```typescript example.ts theme={null}
  import { Flow } from '@re-factor/sdk';

  const documentProcessingFlow = {
      name: 'document_processing',
      description: 'Processes and analyzes documents',
      version: '1.0.0',
      steps: [{
          name: 'extract_text',
          type: 'tool',
          config: {
              tool: 'pdf_extractor',
              input: '{{ document }}'
          },
          errorHandling: {
              retry: true,
              fallback: 'skip_document'
          }
      }, {
          name: 'analyze_content',
          type: 'prompt',
          config: {
              prompt: 'Analyze this text: {{ extract_text.output }}',
              model: 'gpt-4'
          }
      }, {
          name: 'generate_summary',
          type: 'agent',
          config: {
              agent: 'content_summarizer',
              input: '{{ analyze_content.output }}'
          }
      }],
      state: {
          type: 'memory',
          config: {
              persistence: false
          }
      },
      monitoring: {
          metrics: ['step_duration', 'error_rate'],
          callbacks: {
              onStepComplete: (step: string, result: any) => {
                  console.log(`Completed step: ${step}`);
              }
          }
      }
  };
  ```

  ```python example.py theme={null}
  from refactor import Flow

  document_processing_flow = {
      "name": "document_processing",
      "description": "Processes and analyzes documents",
      "version": "1.0.0",
      "steps": [{
          "name": "extract_text",
          "type": "tool",
          "config": {
              "tool": "pdf_extractor",
              "input": "{{ document }}"
          },
          "errorHandling": {
              "retry": True,
              "fallback": "skip_document"
          }
      }, {
          "name": "analyze_content",
          "type": "prompt",
          "config": {
              "prompt": "Analyze this text: {{ extract_text.output }}",
              "model": "gpt-4"
          }
      }, {
          "name": "generate_summary",
          "type": "agent",
          "config": {
              "agent": "content_summarizer",
              "input": "{{ analyze_content.output }}"
          }
      }],
      "state": {
          "type": "memory",
          "config": {
              "persistence": False
          }
      },
      "monitoring": {
          "metrics": ["step_duration", "error_rate"],
          "callbacks": {
              "onStepComplete": lambda step, result: print(f"Completed step: {step}")
          }
      }
  }
  ```
</CodeGroup>

## Best Practices

When designing flows in re-factor:

1. Keep steps focused and single-purpose
2. Handle errors at appropriate levels
3. Use meaningful step names
4. Document input/output requirements
5. Monitor resource usage
6. Test flows with various inputs

For detailed implementation guidance, refer to our [SDK documentation](/sdk).