# sylphai-inc/adalflow architecture

> Architecture diagram of the GitHub repository sylphai-inc/adalflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sylphai-inc/adalflow
- Repository: https://github.com/sylphai-inc/adalflow

## Overview

AdalFlow is a PyTorch-like Python SDK for composing and auto-optimizing language-model workflows, including agents, RAG, and chatbots. A documented agent flow starts with a user prompt, passes through Runner to Agent, invokes tools as needed, and uses a configured model client to produce a result. Internally, Generator builds model requests from prompts and delegates model calls; components and parameters support optimization. The README also identifies tracing and human-in-the-loop support. Several paths are included from the tree or README capabilities without sampled implementation; those connections are left unverified.

Main entry points: [`adalflow/adalflow/core/generator.py`](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/generator.py) (Generator), [`adalflow/adalflow/components/agent/agent.py`](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/agent/agent.py) (Agent), [`adalflow/adalflow/components/agent/runner.py`](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/agent/runner.py) (Runner), [`adalflow/adalflow/core/component.py`](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/component.py) (Components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent Runtime"]
  node_runner["Runner<br/>[runner.py]"]
  node_agent_impl["Agent<br/>[agent.py]"]
  node_tools["Tool Manager<br/>[tool_manager.py]"]
end

subgraph group_core["Workflow Core"]
  node_component["Components<br/>[component.py]"]
  node_generator["Generator<br/>[generator.py]"]
  node_prompt["Prompt Builder<br/>[prompt_builder.py]"]
  node_parser["Output Parsers<br/>[string_parser.py]"]
  node_types["Workflow Types<br/>[types.py]"]
end

subgraph group_integrations["Models And Retrieval"]
  node_model_base["Model Interface<br/>[model_client.py]"]
  node_model_clients["Provider Clients<br/>[openai_client.py]"]
  node_retrieval["Retrievers"]
  node_data_process["Data Processing"]
  node_embedder["Embedder<br/>[embedder.py]"]
end

subgraph group_opt["Optimization And Evaluation"]
  node_optimizer["Optimizers<br/>[optimizer.py]"]
  node_parameter["Parameters<br/>[parameter.py]"]
  node_grad["Gradient Components<br/>[grad_component.py]"]
  node_trainer["Trainer<br/>[trainer.py]"]
  node_evaluation["Evaluation"]
end

subgraph group_ops["Tracing And Permissions"]
  node_tracing["Tracing"]
  node_permissions["Permissions"]
end

node_user(("User"))
node_answer["Workflow Result"]

node_user -->|"submits prompt"| node_runner
node_runner -->|"runs agent"| node_agent_impl
node_agent_impl -->|"invokes tools"| node_tools
node_agent_impl -->|"uses configured model"| node_model_clients
node_agent_impl -->|"returns result"| node_runner
node_runner -->|"provides answer"| node_answer
node_generator -->|"delegates model calls"| node_model_base
node_model_base -->|"implemented by"| node_model_clients
node_generator -->|"builds prompts"| node_prompt
node_generator -->|"extends workflow component"| node_component
node_component -->|"uses optimization state"| node_parameter
node_component -->|"uses gradient components"| node_grad
node_optimizer -->|"proposes parameter data"| node_parameter
node_trainer -.->|"evaluates predictions"| node_evaluation
node_retrieval -.->|"uses embeddings"| node_embedder
node_data_process -.->|"prepares retrieval data"| node_retrieval
node_generator -.->|"parses model output"| node_parser
node_generator -.->|"emits trace events"| node_tracing
node_agent_impl -.->|"checks permissions"| node_permissions

click node_runner "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/agent/runner.py"
click node_agent_impl "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/agent/agent.py"
click node_tools "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/tool_manager.py"
click node_component "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/component.py"
click node_generator "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/generator.py"
click node_prompt "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/prompt_builder.py"
click node_parser "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/string_parser.py"
click node_types "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/types.py"
click node_model_base "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/model_client.py"
click node_model_clients "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/model_client/openai_client.py"
click node_retrieval "https://github.com/sylphai-inc/adalflow/tree/main/adalflow/adalflow/components/retriever"
click node_data_process "https://github.com/sylphai-inc/adalflow/tree/main/adalflow/adalflow/components/data_process"
click node_embedder "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/embedder.py"
click node_optimizer "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/optimizer.py"
click node_parameter "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/parameter.py"
click node_grad "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/grad_component.py"
click node_trainer "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/trainer/trainer.py"
click node_evaluation "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/eval/answer_match_acc.py"
click node_tracing "https://github.com/sylphai-inc/adalflow/tree/main/adalflow/adalflow/tracing"
click node_permissions "https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/apps/permission_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_agent_impl,node_tools,node_user toneBlue
class node_component,node_generator,node_prompt,node_parser,node_types toneAmber
class node_model_base,node_model_clients,node_retrieval,node_data_process,node_embedder toneMint
class node_optimizer,node_parameter,node_grad,node_trainer,node_evaluation toneRose
class node_tracing,node_permissions,node_answer toneIndigo
```

## Components

### Agent Runtime

- [Runner](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/agent/runner.py): `adalflow/adalflow/components/agent/runner.py`
- [Agent](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/agent/agent.py): `adalflow/adalflow/components/agent/agent.py`
- [Tool Manager](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/tool_manager.py): `adalflow/adalflow/core/tool_manager.py`

### Workflow Core

- [Components](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/component.py): `adalflow/adalflow/core/component.py`
- [Generator](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/generator.py): `adalflow/adalflow/core/generator.py`
- [Prompt Builder](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/prompt_builder.py): `adalflow/adalflow/core/prompt_builder.py`
- [Output Parsers](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/string_parser.py): `adalflow/adalflow/core/string_parser.py`
- [Workflow Types](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/types.py): `adalflow/adalflow/core/types.py`

### Models And Retrieval

- [Model Interface](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/model_client.py): `adalflow/adalflow/core/model_client.py`
- [Provider Clients](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/components/model_client/openai_client.py): `adalflow/adalflow/components/model_client/openai_client.py`
- [Retrievers](https://github.com/sylphai-inc/adalflow/tree/main/adalflow/adalflow/components/retriever): `adalflow/adalflow/components/retriever`
- [Data Processing](https://github.com/sylphai-inc/adalflow/tree/main/adalflow/adalflow/components/data_process): `adalflow/adalflow/components/data_process`
- [Embedder](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/core/embedder.py): `adalflow/adalflow/core/embedder.py`

### Optimization And Evaluation

- [Optimizers](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/optimizer.py): `adalflow/adalflow/optim/optimizer.py`
- [Parameters](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/parameter.py): `adalflow/adalflow/optim/parameter.py`
- [Gradient Components](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/grad_component.py): `adalflow/adalflow/optim/grad_component.py`
- [Trainer](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/optim/trainer/trainer.py): `adalflow/adalflow/optim/trainer/trainer.py`
- [Evaluation](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/eval/answer_match_acc.py): `adalflow/adalflow/eval/answer_match_acc.py`

### Tracing And Permissions

- [Tracing](https://github.com/sylphai-inc/adalflow/tree/main/adalflow/adalflow/tracing): `adalflow/adalflow/tracing`
- [Permissions](https://github.com/sylphai-inc/adalflow/blob/main/adalflow/adalflow/apps/permission_manager.py): `adalflow/adalflow/apps/permission_manager.py`

### Other components

- **User**
- **Workflow Result**

## Connections

- User → Runner: submits prompt
- Runner → Agent: runs agent
- Agent → Tool Manager: invokes tools
- Agent → Provider Clients: uses configured model
- Agent → Runner: returns result
- Runner → Workflow Result: provides answer
- Generator → Model Interface: delegates model calls (evidence: `adalflow/adalflow/core/generator.py`)
- Model Interface → Provider Clients: implemented by (evidence: `adalflow/adalflow/components/model_client/openai_client.py`)
- Generator → Prompt Builder: builds prompts (evidence: `adalflow/adalflow/core/generator.py`)
- Generator → Components: extends workflow component (evidence: `adalflow/adalflow/core/generator.py`)
- Components → Parameters: uses optimization state (evidence: `adalflow/adalflow/core/component.py`)
- Components → Gradient Components: uses gradient components (evidence: `adalflow/adalflow/core/component.py`)
- Optimizers → Parameters: proposes parameter data (evidence: `adalflow/adalflow/optim/parameter.py`)
- Trainer → Evaluation: evaluates predictions
- Retrievers → Embedder: uses embeddings
- Data Processing → Retrievers: prepares retrieval data
- Generator → Output Parsers: parses model output (evidence: `adalflow/adalflow/core/generator.py`)
- Generator → Tracing: emits trace events (evidence: `adalflow/adalflow/core/generator.py`)
- Agent → Permissions: checks permissions