DOCSEARCHbyAlgolia
Submit Docs

LiteFlow Documentation

repository·master·Indexed 25 days ago

https://github.com/dromara/liteflow

A powerful rules engine and orchestration framework for Java that decouples complex business logic into reusable components driven by DSL rules. It supports hot-reloading, multiple scripting languages (Groovy, Kotlin, Python, etc.), and advanced orchestration patterns including native AI Agent integration. Compatible with Spring Boot 2.X, 3.X, 4.X and JDK 8 through 25, featuring built-in observability via Micrometer, Prometheus, and Grafana.

Tokens
83.1K
Snippets
121
Records
332
Agent score
86%

What's inside LiteFlow

  1. Overview of Rule-DB mode with Redis plugin

    master

    The liteflow-rule-db-redis plugin implements the Rule-DB mode where Redis serves as the authoritative source for rules and scripts. It leverages the LiteFlow core runtime (indexing, caching, synchronization, and reconciliation) and provides low-latency rule updates via Redis Pub/Sub, change logs via ZSet (using score=seq for sequence tracking), and atomic publishing via Lua scripts.

    Key Components:

    • RedisRuleRepository: Implements the core RuleRepository SPI.
    • Redisson: Manages connections and automatically identifies single, sentinel, or cluster modes.
    • ZSet: Used for change logs to support fetchChangesSince operations and gap detection, aligning with SQL-based change_log semantics.
    • RTopic: Used for rule subscription via Pub/Sub.

  2. Overview of LiteFlow Rule-DB Mode

    master

    LiteFlow Rule-DB mode establishes a centralized authority for rules and scripts using backends like SQL, PostgreSQL, MongoDB, Redis, ZooKeeper, etcd, or Nacos.

    Unlike traditional rule plugins that load all rules into JVM heap at startup, Rule-DB mode uses a 'Storage is Authority, JVM is Cache' model:

    • Consistency: All nodes converge to the same version within a second-level window using a combination of 'Change Notification' (real-time or polling) and 'Periodic Reconciliation' (default 60s).
    • Memory Efficiency: Rule metadata (shadow Chain/Node) stays in memory, but heavy content like EL text, script source code, and compiled artifacts are stored in a Caffeine bounded cache. Content is lazily loaded and compiled only when first executed.

  3. Overview of LiteFlow Rules Engine

    master
    LiteFlow is a modern rules engine framework designed for complex, componentized business orchestration. It uses DSL (Domain Specific Language) rules to drive business logic, allowing for smooth hot deployment and the embedding of multiple scripting languages. It is suitable for decoupling complex systems and managing multi-threaded process choreography through simple expressions.

  4. Overview of LiteFlow ReAct Agent Module

    master

    LiteFlow is introducing a ReAct Agent component capability based on agentscope-java. This allows developers to define agent nodes that participate in EL (Expression Language) orchestration by extending an abstract class.

    Key Features:

    • Multi-Model Support: Supports OpenAI, Anthropic, Gemini, DashScope, and OpenAI-compatible providers (DeepSeek, Kimi, GLM, MiniMax).
    • Isolation: Provides session and workspace isolation.
    • Security: Includes configurable shell command control and path fencing via WorkspaceFileTools and ManagedShellCommandTool.

    Architecture Overview:

    • liteflow-core contains a pure POJO AgentConfig (zero extra dependencies).
    • ReActAgentComponent (extending NodeComponent) handles the execution logic.
    • AgentSessionManager manages sessions and workspaces.
    • Tools use native @Tool from agentscope.

  5. Overview of LiteFlow Rule Engine

    master

    LiteFlow is a modern rule engine framework that combines orchestration capabilities with rule engine features. It is designed for orchestrating complex, componentized business logic using a unique Domain Specific Language (DSL).

    Key capabilities include:

    • Component-based logic: All business logic is treated as a unified component.
    • Lightweight rules: Orchestration is driven by rule files (XML, JSON, or YAML) that are easy to learn and understand.
    • Hot Reloading: Supports smooth, real-time rule updates without application restarts, ensuring stability under high concurrency.
    • Extensive Scripting Support: Supports various scripting languages including Groovy, Java, Kotlin, JavaScript, QLExpress, Python, Lua, and Aviator.
    • Persistence: Native support for storing rules in databases, Nacos, Etcd, Zookeeper, Apollo, and Redis.
    • High Performance: Minimal overhead; performance is primarily determined by the efficiency of the individual components.

  6. Overview of LiteFlow ReAct Agent Modules

    master

    The liteflow-react-agent is an aggregate module where core capabilities reside in liteflow-react-agent-core. Different model providers are offered through independent sub-modules. Most business projects only need to import one platform module, which transitively includes the core module.

    ModulePurpose
    liteflow-react-agent-coreProvides ReActAgentComponent, ModelSpec infrastructure, session management (conversation/agentKey), memory persistence, streaming event bridging, workspace file tools, and managed Shell tools.
    liteflow-react-agent-openaiOpenAI official API + OpenAI compatible protocols. Includes built-in support for DeepSeek, Kimi, GLM, and Minimax.
    liteflow-react-agent-anthropicEntry point for Anthropic Claude models.
    liteflow-react-agent-geminiEntry point for Google Gemini models.
    liteflow-react-agent-dashscopeEntry point for Alibaba Cloud DashScope / Qwen models.

  7. Overview of LiteFlow Actuator Metrics and Observability

    master

    LiteFlow provides observability capabilities through a new metrics system designed to integrate with mainstream monitoring ecosystems. This system allows developers to:

    1. Inspect Structure: View all registered chains and nodes, including their definitions (EL source, component types, etc.) via a read-only endpoint.
    2. Monitor Runtime Metrics: Track execution counts, duration (latency), success/failure rates, and error rates for both Chains and Nodes.

    Key Design Principles:

    • Micrometer Integration: Metrics are registered as Micrometer Meter objects, allowing automatic exposure via Spring Boot Actuator to /actuator/prometheus or /actuator/metrics for use with Prometheus and Grafana.
    • Two-Level Granularity: Metrics are aggregated at the chainId and nodeId levels, enabling precise identification of slow chains or specific slow components.
    • Non-Intrusive: The metrics system is independent of the existing MonitorBus (log-based monitoring) and does not persist historical data itself, delegating storage to external systems like Prometheus.

  8. Understand the Rule-DB Unified Architecture

    master

    LiteFlow's Rule-DB architecture provides a unified way to manage rules across four backends: SQL, Redis, etcd, and ZK. Unlike traditional Rule Source plugins that load all rules into the JVM at startup, Rule-DB uses a 'lazy loading' model where only lightweight metadata indexes are kept in memory, and actual rule content (EL or scripts) is loaded on demand and cached with a bounded limit.

    Key Backend Behaviors:

    • SQL & Redis: Use a polling mechanism based on change logs.
    • etcd & ZK: Use native watch/subscription mechanisms for low-latency updates.
    • All Backends: Support periodic manifest reconciliation to recover from manual edits, lost notifications, or connection drops.

  9. Understand LiteFlow ReAct Agent Session Identifiers

    master

    LiteFlow ReAct Agent uses a two-layer identification system to manage sessions and memory:

    • conversationId: Represents the business or dialogue dimension. It remains consistent throughout a single chain and determines the workspace sub-directory. Multiple agents within the same conversationId share the same workspace directory for file collaboration.
    • agentKey: Represents the component dimension. By default, this is the nodeId. It is used to distinguish different ReActAgent instances and their specific memories within the same conversation.

    Key Behaviors:

    • A unique combination of (conversationId, agentKey) ensures the reuse of the same ReActAgent instance, memory, ReentrantLock, and persistence key.
    • Calls with the same (conversationId, agentKey) are executed serially to prevent concurrent memory modification.
    • Different agentKey values under the same conversationId can execute in parallel.
    • Valid characters for both IDs are [a-zA-Z0-9_-]+. Other characters are URL-encoded, and % is replaced with _.

  10. Key Features of LiteFlow

    master

    LiteFlow provides several advanced capabilities for business orchestration:

    • Unified Component Definition: All logic is treated as a component.
    • Rule Diversification: Supports XML, JSON, and YML rule file formats.
    • Arbitrary Arrangement: Supports mixing synchronous and asynchronous execution using orchestration operators.
    • Flexible Rule Loading: Natively supports structured databases, Nacos, Etcd, Zookeeper, Apollo, and Redis, with an extension interface for custom storage.
    • Hot Refresh: Allows updating rules instantly without restarting the application.
    • Wide Compatibility: Works with Spring Boot (2.X, 3.X, 4.X) and any Java framework. Supports JDK 8 through JDK 25 (including virtual threads on JDK 21+).
    • Scripting Support: Supports Groovy, Java, Kotlin, JavaScript, QLExpress, Python, Lua, and Aviator. Scripts can call Java methods and perform RPC calls.
    • Component Features: Supports component retry with custom configurations, context isolation for high concurrency, and declarative component support.
    • Monitoring: Includes built-in command-line monitoring for component execution time ranking.

  11. Understand the Rule-DB Mode Architecture

    master

    The Rule-DB mode treats persistent storage (SQL DB or Redis) as the authoritative source for rules and scripts, while LiteFlow JVM nodes act as bounded caches. This decouples JVM memory usage from the total number of rules and ensures eventual consistency across all nodes.

    Key Architectural Components:

    • RuleIndex (In-Memory): Stores lightweight metadata (ID $\rightarrow$ version/MD5) to track changes.
    • RuleCache (Bounded): Stores compiled Chain objects and script artifacts. It uses a capacity-based eviction policy (cache-capacity).
    • ChangeWatcher: Monitors changes via subscription (Redis) or polling (SQL) using a sequence number (seq).
    • Reconciler: Performs periodic full-inventory reconciliation to ensure consistency even if notifications are lost.
    • RulePublisher: An API used to atomically update content, versions, and sequence numbers.

  12. LiteFlow ReAct Agent Module Deliverables and Structure

    master

    The LiteFlow ReAct Agent feature is distributed across several modules. When integrating or extending the agent capabilities, you will interact with the following components:

    • liteflow-core: Contains the core configuration via LiteflowConfig, which now includes a private AgentConfig agent field. It also provides POJOs in the com.yomahub.liteflow.property.agent package, including AgentConfig, Workspace, Session, Shell, Defaults, and PlatformCredential.
    • liteflow-react-agent-core: Provides the foundational logic, including the ReActAgentComponent abstract class, AgentSessionManager, WorkspaceFileTools, and ManagedShellCommandTool.
    • Platform-specific modules: Specialized implementations for different LLM providers: liteflow-react-agent-openai, liteflow-react-agent-anthropic, liteflow-react-agent-gemini, and liteflow-react-agent-dashscope.
    • Integration testing: liteflow-testcase-el-springboot-agent is available for Spring Boot integration testing.