Component Dynamic Loading

Relevant source files

• agent/canvas.py
• agent/component/agent_with_tools.py
• agent/component/base.py
• agent/component/categorize.py
• agent/component/llm.py
• agent/component/message.py
• agent/tools/base.py
• api/apps/llm_app.py
• api/db/init_data.py
• api/db/services/llm_service.py
• common/mcp_tool_call_conn.py
• conf/llm_factories.json
• rag/llm/__init__.py
• rag/llm/chat_model.py
• rag/llm/cv_model.py
• rag/llm/embedding_model.py
• rag/llm/rerank_model.py
• rag/llm/sequence2txt_model.py
• rag/llm/tts_model.py
• rag/prompts/generator.py
• web/src/components/svg-icon.tsx
• web/src/constants/llm.ts
• web/src/utils/common-util.ts

Purpose and Scope

This document explains RAGFlow's dynamic class discovery and loading mechanism for agent components, workflow nodes, and LLM model providers. The system automatically discovers, registers, and provides runtime lookup for component classes located in the agent/component/, agent/tools/, and rag/flow/ packages. Additionally, it handles the dynamic registration of LLM model types (Chat, Embedding, Rerank, etc.) from rag/llm/ submodules.

This plugin-like architecture enables the Graph engine in agent/canvas.py and the task execution layer to instantiate components and parameters by name without hardcoding imports, facilitating easy extension of the system's capabilities.

For information about component base classes and lifecycle, see 8.2 Component System Architecture For details on individual model implementations, see 5.1 LLMBundle and Model Types

---

Architecture Overview

The component dynamic loading system consists of three primary mechanisms:

1. Module Discovery: Automatic scanning of Python files in target directories at import time.
2. Class Extraction: Inspection-based registration of classes into global registries and namespaces using the inspect module.
3. Lazy Lookup: Runtime resolution of classes by string identifiers across multiple packages using component_class().

Component Discovery Architecture

Title: Component Discovery and Registration Flow

The loading process occurs during package initialization, populating the registry with all available component classes. The component_class() function then provides O(1) lookup during workflow execution.

Sources: agent/component/__init__.py22-59

---

Component Discovery Process

Directory Scanning

The _import_submodules() function scans the agent/component/ directory for Python modules at package initialization time. It ignores special files and base classes to prevent circular dependencies.

Title: Module Discovery Algorithm

Key implementation details:

• Directory Access: Uses os.path.dirname(__file__) to locate the package path agent/component/__init__.py22
• Filtering: Skips files starting with __, files not ending in .py, and files starting with base agent/component/__init__.py26-28
• Dynamic Import: Uses importlib.import_module with relative package naming agent/component/__init__.py32

Sources: agent/component/__init__.py22-36

---

Class Extraction and Registration

Inspection-Based Discovery

The _extract_classes_from_module() function uses Python's inspect module to find valid component classes within the imported modules agent/component/__init__.py37-43

Registration Criteria:

Check	Purpose	Code Reference
inspect.isclass(obj)	Verify the object is a class entity	agent/component/__init__.py39
obj.__module__ == module.__name__	Ensure the class is defined in the current module	agent/component/__init__.py40
not name.startswith("_")	Exclude private helper classes	agent/component/__init__.py40

Dual Registration

Discovered classes are registered in two locations:

1. __all_classes dictionary: A mapping for internal registry tracking agent/component/__init__.py41
2. globals() namespace: Exporting the class directly to the agent.component package namespace agent/component/__init__.py42

Sources: agent/component/__init__.py37-43

---

LLM Model Provider Registration

A similar dynamic loading pattern is applied to the LLM integration layer in rag/llm/__init__.py. This system maps provider names to their respective implementation classes.

Module Mapping and Loading

The system iterates through a MODULE_MAPPING which associates model type names with their global registry dictionaries rag/llm/__init__.py155-164:

• chat_model -> ChatModel rag/llm/__init__.py156
• embedding_model -> EmbeddingModel rag/llm/__init__.py158
• rerank_model -> RerankModel rag/llm/__init__.py159
• cv_model -> CvModel rag/llm/__init__.py157

Provider Registration Logic

For each module, the system inspects all classes. Classes that define a _FACTORY_NAME attribute are automatically registered rag/llm/__init__.py174-182 For example, JinaRerank defines _FACTORY_NAME = "Jina" rag/llm/rerank_model.py96-97

Title: LLM Provider Registration Sequence

Sources: rag/llm/__init__.py155-182 rag/llm/rerank_model.py96-97 rag/llm/chat_model.py44-110

---

Component Lookup Function

component_class() Implementation

The component_class() function resolves a string name into a functional Python class agent/component/__init__.py51-59 This is used in Graph.load() to instantiate components like Begin, Retrieval, or Generate agent/canvas.py105-115

Search Path Priority

The function searches three module namespaces in specific order:

1. agent.component: Standard workflow nodes agent/component/__init__.py53
2. agent.tools: Specialized tools agent/component/__init__.py55
3. rag.flow: Specialized flow components agent/component/__init__.py57

Sources: agent/component/__init__.py51-59 agent/canvas.py102-115

---

Data Flow: From DSL to Runtime Object

DSL to Code Mapping

Title: Natural Language Space to Code Entity Space Mapping

LLMBundle Initialization

The LLMBundle class api/db/services/llm_service.py37-39 acts as a wrapper that selects the provider implementation. During API calls like set_api_key, the system checks if a factory exists in the dynamic registries: assert factory in ChatModel api/apps/llm_app.py111-112

Sources: api/db/services/llm_service.py37-150 api/apps/llm_app.py97-112 agent/canvas.py102-115