Crate cosmoflow

CosmoFlow

A lightweight, type-safe workflow engine for Rust, optimized for LLM applications.

CosmoFlow provides a minimal yet powerful framework for building complex workflows with clean abstractions and excellent performance.

Core Concepts

• Flow: A collection of nodes and the routes between them, representing a complete workflow.
• Node: A single unit of work in a workflow.
• Action: The result of a node’s execution, used to determine the next step in the flow.
• Shared Store: A key-value store used to share data between nodes.
• Storage Backend: A pluggable storage mechanism for the shared store.

Quick Start

Synchronous Usage (default)

use cosmoflow::prelude::*;

// Create a shared store with memory backend
let mut store = MemoryStorage::new();

// Define a simple node
struct MyNode;
impl<S: SharedStore> Node<S> for MyNode {
    type PrepResult = String;
    type ExecResult = ();
    type Error = NodeError;
    fn prep(&mut self, _store: &S, _context: &ExecutionContext) -> Result<String, Self::Error> {
        Ok("prepared".to_string())
    }
    fn exec(&mut self, _prep_result: String, _context: &ExecutionContext) -> Result<(), Self::Error> {
        Ok(())
    }
    fn post(&mut self, _store: &mut S, _prep_result: String, _exec_result: (), _context: &ExecutionContext) -> Result<Action, Self::Error> {
        Ok(Action::simple("complete"))
    }
}

// Create a flow
let mut flow = FlowBuilder::new()
    .node("start", MyNode)
    .terminal_route("start", "complete")
    .build();

// Execute the flow
let result = flow.execute(&mut store)?;

Asynchronous Usage (with async feature)

use cosmoflow::prelude::*;
use async_trait::async_trait;

// Create a shared store with memory backend
let mut store = MemoryStorage::new();

// Define a simple node
struct MyNode;
#[async_trait]
impl<S: SharedStore> Node<S> for MyNode {
    type PrepResult = String;
    type ExecResult = ();
    type Error = NodeError;
    async fn prep(&mut self, _store: &S, _context: &ExecutionContext) -> Result<String, Self::Error> {
        Ok("prepared".to_string())
    }
    async fn exec(&mut self, _prep_result: String, _context: &ExecutionContext) -> Result<(), Self::Error> {
        Ok(())
    }
    async fn post(&mut self, _store: &mut S, _prep_result: String, _exec_result: (), _context: &ExecutionContext) -> Result<Action, Self::Error> {
        Ok(Action::simple("complete"))
    }
}

// Create a flow
let mut flow = FlowBuilder::new()
    .node("start", MyNode)
    .terminal_route("start", "complete")
    .build();

// Execute the flow
let result = flow.execute(&mut store).await?;

Feature Flags

CosmoFlow uses a feature flag system to keep the core library lightweight and allow users to opt-in to additional functionality.

Storage Backends

• storage-memory: In-memory storage backend.
• storage-file: File-based storage backend.
• storage-redis: Redis storage backend for distributed workflows.

Convenience Features

• minimal: Core engine only (bring your own storage).
• basic: Basic usable configuration with memory storage.
• standard: Core + memory storage + async support.
• full: All storage backends + async support enabled.

Sync/Async Mode

• async: Enable async/await support (requires tokio runtime).
• Without async: Synchronous execution only (lighter weight).

Re-exports

pub use shared_store::SharedStore;

pub use action::Action;

pub use flow::Flow;

pub use flow::FlowBackend;

pub use flow::FlowBuilder;

pub use flow::FlowConfig;

pub use flow::FlowExecutionResult;

pub use flow::errors::FlowError;

pub use flow::route::Route;

pub use node::ExecutionContext;

pub use node::Node;

pub use node::NodeError;

Modules

action

Action definition and condition evaluation

flow

Flow definition and execution

node

Node execution system and traits

prelude

The prelude module for commonly used types and traits.

shared_store

Shared store for data communication between workflow nodes Type-safe data communication layer for CosmoFlow workflows

Macros

flow

Declarative workflow construction with explicit terminal routes and type inference.

Type Aliases

Result

A convenient result type alias for CosmoFlow operations