🚀 Build LLM Agents in Ruby with FlowNodes — a LangChain Alternative

Finally, Rubyists get a clean way to build LLM workflows without swimming in TypeScript or bloated Python frameworks.

This was inspired by PocketFlow — a ~100-line Python framework that blew me away with its simplicity.
I loved the graph-based pattern so much, I built FlowNodes to bring that same power to Ruby. Now I use it in my own projects, and it just works.

⸻

💡 What is FlowNodes?

FlowNodes is a minimalist Ruby framework for building LLM-powered applications using a graph-based flow architecture — inspired by PocketFlow, rebuilt for the Rails ecosystem.

Think of it as:

• 🧠 Agents without chaos
• 🧩 Workflows without brittle prompt-chaining
• 🪄 RAG pipelines without rolling your own spaghetti logic

All while staying in Ruby. No extra services. No lang-* wrappers.
You can even integrate it with RubyLLM, which supercharges its capabilities.

⸻

🧱 Why I Built This

I wanted something that:

• Didn’t require Python glue code
• Didn’t assume I wanted 14 layers of abstraction
• Let me define clear flows: “User input → Tool → Decision → Output”
• Could run inside my existing Rails stack — not in some weird sidecar

FlowNodes does exactly that. It’s a Ruby-first approach to orchestrating LLM workflows.

Fun fact: I once rewrote the core in ~88 lines using metaprogramming… but debugging it was hell. Readability wins.

⸻

🧪 How It Works (TL;DR)

Define your flow with simple Ruby classes:

class GreetingNode < FlowNodes::Node
  def exec(params)
    puts "Hello, #{params[:name]}!"
    "greeted"
  end
end

class FarewellNode < FlowNodes::Node
  def exec(params)
    puts "Goodbye, #{params[:name]}!"
    nil # End the flow
  end
end

greeting = GreetingNode.new
farewell = FarewellNode.new

# Connect nodes: greeting -> farewell
greeting - :greeted >> farewell

flow = FlowNodes::Flow.new(start: greeting)
flow.set_params(name: "World")
flow.run(nil)

You’re literally just connecting logic like a graph. It’s simple, explicit, and debuggable.

⸻

🧰 Features You’ll Actually Use

• Graph-based node chaining (not magic, just clean)
• Async & parallel batch support
• Built-in retry and fallback logic
• Validated parameters
• Lifecycle hooks (prep, exec, post)
• Thread-safe and production-ready

The core gem is under 500 lines — you can grok the whole thing in an afternoon.
Performance metrics, observability, and memory stores are coming — but the philosophy stays lean and fast.

⸻

⚙️ Real Use Cases

• Toolchain-based LLM agents
• Context-aware email/report generators
• Batch RAG queries across PDFs or embeddings
• Multi-step AI flows inside your Rails apps

You don’t need LangChain. You don’t need Python. You just need Ruby.

⸻

🛠 Ready to Try?

gem install flow_nodes

Or add it to your Gemfile:

gem 'flow_nodes', '~> 0.1.0'

Tutorial (built with AI):
📚 https://code2tutorial.com/tutorial/927c15a8-5bba-45d8-a999-6ee873562c5a/index.md

⸻

🗺 What’s Next

Coming soon:

• Flow visualizations
• Built-in memory stores
• Native Rails generator support
• Community-driven use case templates

⸻

👋 Feedback Wanted

If you’re a Ruby dev curious about LLMs but tired of fighting Python wrappers, try FlowNodes.
Let me know how you’d use it — or what’s missing to make it battle-tested.