rcrewai 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7682076eeeb0d3c1bdc0de2185c83ad8c925ce19165786daa0910c1925fdf64
-  data.tar.gz: 1db4ba5508d8aef52b6645be9cae3dcb7328564f8335a24fe844655196d2f53f
+  metadata.gz: f742fcf06518c80cbf29191d0eff275830ee618c9b896c3d443258b06aa120ff
+  data.tar.gz: 5cc9c03182d0bd80d73d99edb08f2267252684f64a23da1626d2d61e0abe1683
 SHA512:
-  metadata.gz: dfaf95b581c86cd36573400729a02e72e307721f51267fefafdb3245aae28bffc89201855dcd294f38ecfc54a6a1dbf2062d92fbd55310e4f2f9d968b49a1a6e
-  data.tar.gz: 4c8ed1132d754e92ab154c192f28d8add3d80fdbedbaaa15fa6fd876002f18674d30a91f7ef9fb5dcba65a4240ca9f464d26fa15b64a8cdcdee4ad806cefe3bd
+  metadata.gz: 0c32e4110a5bbabac9b120262e2ebe0e86b0c58c3b4213a11214efcff647024d9714fcee12934f4b734c9f64184e1f802d82b97ec50e5dc7ceab424c4cec38f1
+  data.tar.gz: 8a678ae53008c7c6a73cf365b460b80989da05f22eb646cf3a9126028a0d6dd220e6af75ef4dee80c02d73e69b536fb3d2b7c23f827e929078b76ed450d8f1ce

data/.rubocop.yml

@@ -1 +1,21 @@
 inherit_from: .rubocop_todo.yml
+
+Naming/MethodParameterName:
+  # `k` (top-k retrieval) and short math vars for vector similarity are
+  # conventional and clearer than forced longer names. The rest are RuboCop's
+  # defaults, restated because AllowedNames replaces rather than extends.
+  AllowedNames:
+    - k
+    - a
+    - b
+    - io
+    - id
+    - to
+    - by
+    - 'on'
+    - in
+    - at
+    - ip
+    - db
+    - os
+    - pp

data/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-03
+
+This release closes the feature-parity gap with the modern CrewAI framework,
+adding its second pillar (**Flows**) alongside **Knowledge (RAG)**, structured
+output, guardrails, planning, and training/testing. See `ROADMAP.md`.
+
+### Added
+
+#### Flows (#11)
+- `RCrewAI::Flow` — an event-driven workflow engine (CrewAI's second pillar). Subclass it and declare methods with a class-level DSL: `start`, `listen`, `router`, and the `and_` / `or_` trigger combinators. `kickoff` runs the graph to a fixed point; routers emit labels that listeners trigger on.
+- Flow state (`Flow::State`) is a schemaless object with an automatic UUID, seedable via `kickoff(inputs:)`.
+- Flow persistence: pluggable state stores (`Flow::MemoryStateStore`, `Flow::FileStateStore`, or any `#save`/`#load` object); `flow.restore(id)` resumes a persisted run.
+- Flows can invoke a `Crew` as a step and pause for input via `#human_feedback`.
+
+#### Knowledge / RAG (#9)
+- `RCrewAI::Knowledge` module adds retrieval-augmented context. Sources (`StringSource`, `FileSource`, `PdfSource`, `CsvSource`, `UrlSource`) are chunked, embedded, and stored in an in-memory cosine-similarity vector store (no external DB required).
+- Attach via `Agent.new(knowledge:)` / `knowledge_sources:` (role-specific) or `Crew.new(knowledge:)` / `knowledge_sources:` (shared with all agents); relevant chunks are injected into each task's prompt at execution.
+- The embedder (`Knowledge::Embedder`, default OpenAI `text-embedding-3-small`) and vector store are pluggable.
+
+#### Task output processing (#6, #7, #8)
+- Structured output: `Task.new(output_schema:)` validates and coerces the agent's output against a JSON-schema subset, exposing the parsed object via `Task#structured_output` (and the raw string via `Task#raw_result`). JSON embedded in surrounding prose or a fenced code block is extracted automatically; output that doesn't conform re-runs the agent with the error fed back.
+- Guardrails: `Task.new(guardrail:)` takes a callable returning `[ok, value_or_error]` to validate and transform output before it flows downstream, retrying up to `guardrail_max_retries` (default 3) with the rejection reason fed back to the agent.
+- Output persistence & formatting: `Task.new(output_file:)` writes the result to disk (`create_directory:` controls parent-dir creation, default true), and `markdown: true` prepends a heading when the output isn't already a markdown document.
+- `RCrewAI::OutputSchema` — a small JSON-schema-subset validator/coercer used by structured task output.
+
+#### Per-agent LLM (#5)
+- `Agent.new(llm:)` accepts a provider symbol (`:anthropic`), an options hash (`{ provider:, model:, api_key:, temperature: }`), or a pre-built client instance. Agents in the same crew can use different providers/models (e.g. a cheap worker model and a stronger manager model). Omitting `llm:` keeps the previous global-configuration behavior.
+- `Configuration#with_overrides` returns a copy of the configuration with per-agent overrides applied, leaving global state untouched.
+
+#### Planning (#10)
+- `Crew.new(planning: true)` runs a single planner pass before execution that asks an LLM to draft a short plan for each task and folds it into the task's description. Optional `planning_llm:` selects the planner client (defaults to the global provider). Best-effort — a planner error or unparseable output leaves tasks unchanged and execution proceeds.
+- `Task#enrich_description` appends supplementary guidance (used by the planner) without discarding the original instructions.
+
+#### Training & testing (#12)
+- `Crew#train(n_iterations:, filename:)` runs the crew repeatedly, collects feedback after each iteration (via a `feedback:` callable, defaulting to a human prompt), and persists it as JSON.
+- `Crew#test(n_iterations:)` runs the crew repeatedly and reports per-run and average scores (via a `scorer:` callable, defaulting to the run's success rate).
+
 ## [0.3.0] - 2026-05-12
 
 ### Added
@@ -128,5 +165,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLI usage documentation
 - Real-world use cases and examples
 
-[Unreleased]: https://github.com/gkosmo/rcrewAI/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/gkosmo/rcrewAI/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/gkosmo/rcrewAI/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/gkosmo/rcrewAI/compare/v0.1.0...v0.3.0
 [0.1.0]: https://github.com/gkosmo/rcrewAI/releases/tag/v0.1.0

data/README.md

@@ -19,6 +19,8 @@ RCrewAI is a Ruby implementation of the CrewAI framework, allowing you to create
 - **🏗️ Hierarchical Teams**: Manager agents that coordinate and delegate tasks to specialist agents
 - **🔒 Production Ready**: Security controls, error handling, logging, monitoring, and sandboxing
 - **🎯 Flexible Orchestration**: Sequential, hierarchical, and concurrent execution modes
+- **🌊 Flows**: Event-driven workflows with `start`/`listen`/`router`, branching, and persistent state
+- **📚 Knowledge (RAG)**: Ground agents in your own documents with built-in retrieval
 - **💎 Ruby-First Design**: Built specifically for Ruby developers with idiomatic patterns
 
 ## 📦 Installation
@@ -169,6 +171,172 @@ RCrewAI.configure do |config|
 end
 ```
 
+### Per-agent LLM
+
+The `RCrewAI.configure` block sets the crew-wide default. Any agent can override
+it with the `llm:` option, so a single crew can mix providers and models — for
+example a cheap model for workers and a stronger one for the manager:
+
+```ruby
+# Provider only (uses that provider's configured model + key)
+researcher = RCrewAI::Agent.new(name: 'researcher', role: '...', goal: '...',
+                                llm: :anthropic)
+
+# Provider + model (and optionally api_key / temperature)
+manager = RCrewAI::Agent.new(name: 'manager', role: '...', goal: '...',
+                             llm: { provider: :anthropic, model: 'claude-3-opus-20240229' })
+
+worker = RCrewAI::Agent.new(name: 'worker', role: '...', goal: '...',
+                            llm: { provider: :openai, model: 'gpt-4o-mini' })
+
+# Or pass a pre-built client instance
+worker = RCrewAI::Agent.new(name: 'worker', role: '...', goal: '...',
+                            llm: my_client)
+```
+
+Omit `llm:` to use the global `RCrewAI.configure` settings. Overrides never
+mutate the global configuration.
+
+## 📤 Structured Output, Guardrails & File Output
+
+Tasks can validate, transform, and persist their output:
+
+```ruby
+task = RCrewAI::Task.new(
+  name: 'extract',
+  description: 'Extract the article title and word count as JSON',
+  agent: analyst,
+
+  # Structured output — validated & coerced against a JSON schema.
+  # Non-conforming output re-runs the agent with the error fed back.
+  output_schema: {
+    type: 'object',
+    properties: { title: { type: 'string' }, words: { type: 'integer' } },
+    required: ['title']
+  },
+
+  # Guardrail — ->(output) { [ok, value_or_error] }. On rejection the agent
+  # re-runs (up to guardrail_max_retries) with the reason appended.
+  guardrail: ->(out) { [out.length < 5000, 'must be under 5000 chars'] },
+  guardrail_max_retries: 3,
+
+  # Persist the result. Parent dirs are created unless create_directory: false.
+  output_file: 'out/report.md',
+  markdown: true
+)
+
+task.execute
+task.structured_output  # => { "title" => "...", "words" => 1234 }
+task.raw_result         # => the unprocessed string the agent produced
+```
+
+## 🗺️ Planning
+
+Enable `planning:` on a crew to run a planner pass before execution. The planner
+drafts a short plan for each task and folds it into the task description, giving
+the executing agent a head start:
+
+```ruby
+crew = RCrewAI::Crew.new('research_crew', planning: true)
+# Optionally use a dedicated (e.g. stronger) planner model:
+crew = RCrewAI::Crew.new('research_crew', planning: true,
+                         planning_llm: { provider: :anthropic, model: 'claude-3-opus-20240229' })
+```
+
+Planning is best-effort: if the planner errors or returns unparseable output,
+the crew runs with the original tasks unchanged.
+
+## 🏋️ Training & Testing
+
+Iterate on a crew by training it with feedback or scoring repeated runs:
+
+```ruby
+# Train: run N times, collect feedback after each run, persist to JSON.
+crew.train(n_iterations: 3, filename: 'training.json')
+
+# Provide feedback programmatically instead of prompting a human:
+crew.train(n_iterations: 3, filename: 'training.json',
+           feedback: ->(iteration, result) { "run #{iteration}: #{result[:success_rate]}%" })
+
+# Test: run N times and score each run (defaults to success_rate).
+crew.test(n_iterations: 5)
+# => { iterations: 5, scores: [...], average_score: 92.0 }
+```
+
+## 📚 Knowledge (RAG)
+
+Ground agents in your own documents. Sources are chunked, embedded, and stored
+in an in-memory vector store; the most relevant chunks are injected into each
+task's prompt automatically.
+
+```ruby
+kb = RCrewAI::Knowledge::Base.new(sources: [
+  RCrewAI::Knowledge::StringSource.new('Our refund window is 30 days.'),
+  RCrewAI::Knowledge::FileSource.new('docs/policy.txt'),
+  RCrewAI::Knowledge::PdfSource.new('handbook.pdf'),
+  RCrewAI::Knowledge::UrlSource.new('https://example.com/faq')
+])
+
+# Agent-level (role-specific) knowledge:
+support = RCrewAI::Agent.new(name: 'support', role: '...', goal: '...', knowledge: kb)
+
+# Or pass raw sources and let the agent build the base:
+support = RCrewAI::Agent.new(name: 'support', role: '...', goal: '...',
+                             knowledge_sources: [RCrewAI::Knowledge::StringSource.new('...')])
+
+# Crew-level knowledge is shared with every agent:
+crew = RCrewAI::Crew.new('support_crew', knowledge: kb)
+```
+
+Embeddings default to OpenAI's `text-embedding-3-small`; pass a custom
+`embedder:` (anything responding to `embed(texts)`) or vector store to swap the
+backend.
+
+## 🌊 Flows
+
+Beyond crews, RCrewAI has **Flows** — an event-driven workflow engine for
+orchestrating steps (and whole crews) with explicit branching and state:
+
+```ruby
+class ArticleFlow < RCrewAI::Flow
+  start :outline
+  def outline
+    state.sections = %w[intro body conclusion]
+    state.sections.length
+  end
+
+  listen :outline
+  def draft(section_count)
+    state.words = section_count * 100
+    state.words
+  end
+
+  router :draft
+  def review(words)
+    words >= 250 ? :publish : :expand
+  end
+
+  listen :publish
+  def publish = state.status = 'published'
+
+  listen :expand
+  def expand = state.status = 'needs more work'
+end
+
+flow = ArticleFlow.new
+flow.kickoff(inputs: { author: 'me' })
+flow.state.status      # => "published"
+flow.state.id          # => automatic UUID
+```
+
+- `start` / `listen` / `router` wire methods into a graph; a listener receives
+  its trigger's return value.
+- Combine triggers with `and_(:a, :b)` (all) and `or_(:a, :b)` (any).
+- **State** is a schemaless object with a UUID, seedable via `kickoff(inputs:)`.
+- **Persistence**: pass `state_store:` (`RCrewAI::Flow::FileStateStore.new(dir)`
+  or your own `#save`/`#load`) and call `flow.restore(id)` to resume.
+- Invoke a `Crew` inside any step, or pause with `human_feedback('Approve?')`.
+
 ## 💡 Examples
 
 ### Hierarchical Team with Human Oversight

data/ROADMAP.md

@@ -0,0 +1,84 @@
+# RCrewAI Roadmap
+
+This roadmap tracks feature parity between **RCrewAI** (Ruby) and the upstream
+[**crewai**](https://pypi.org/project/crewai/) Python framework.
+
+## Current status
+
+- **RCrewAI:** `0.3.0` (2026-05-12)
+- **Upstream crewai:** `1.15.x` (mid-2026)
+
+RCrewAI is a faithful port of CrewAI's **"Crews"** mental model (Agents / Tasks /
+Crew, sequential + hierarchical processes, tools, memory, human-in-the-loop). As
+of `0.3.0` the LLM plumbing is modern: native function calling across all five
+providers, a tool-schema DSL, typed streaming events, MCP client, and per-model
+pricing.
+
+Since CrewAI's `1.0`, the framework grew a second pillar (**Flows**) plus
+**Knowledge (RAG)**, **Guardrails**, **structured output**, **Planning**, and
+**Training/Testing**. As of the `[Unreleased]` changes, RCrewAI now implements
+all of these — see the matrix below. Only backlog polish items remain.
+
+**Status: all milestone issues (#5–#12) are complete.** The remaining backlog
+covers smaller polish items (reasoning, rate-limiting, batch kickoff, kickoff
+hooks, multimodal).
+
+## Parity matrix
+
+| Concept | crewai | RCrewAI 0.3.0 | Target |
+|---|---|---|---|
+| Agents / Tasks / Crew | ✅ | ✅ | — |
+| Sequential / hierarchical process | ✅ | ✅ | — |
+| Native function calling + tool DSL | ✅ | ✅ (0.3.0) | — |
+| Streaming events | ✅ | ✅ (0.3.0) | — |
+| MCP client | ✅ | ✅ (0.3.0) | — |
+| Per-model pricing / cost | ✅ | ✅ (0.3.0) | — |
+| Per-agent LLM override | ✅ | ✅ (#5) | ✅ done |
+| Structured output (schema) | ✅ | ✅ (#6) | ✅ done |
+| Task guardrails | ✅ | ✅ (#7) | ✅ done |
+| `output_file` / markdown | ✅ | ✅ (#8) | ✅ done |
+| Knowledge / RAG | ✅ | ✅ (#9) | ✅ done |
+| Planning | ✅ | ✅ (#10) | ✅ done |
+| Flows (`start`/`listen`/`router`) | ✅ | ✅ (#11) | ✅ done |
+| Flow state + persistence | ✅ | ✅ (#11) | ✅ done |
+| Training / Testing | ✅ | ✅ (#12) | ✅ done |
+| Reasoning, rate-limiting, batch kickoff | ✅ | ❌ | backlog |
+
+## Milestones (highest leverage first)
+
+### 0.3.1 — Per-agent LLM override
+Let `Agent.new(llm:)` accept a provider/model, instead of only the global
+`RCrewAI.configure`. Unblocks mixed-model crews (cheap model for workers, strong
+model for the manager).
+
+### 0.4.0 — Structured output & guardrails
+Builds directly on the 0.3.0 tool-schema/JSON-schema plumbing.
+- `Task.new(output_schema:)` → validated, coerced structured result.
+- `Task.new(guardrail:)` → proc/object that validates & transforms output, with
+  bounded retries (`guardrail_max_retries`).
+- `output_file:` + `markdown:` output formatting.
+
+### 0.5.0 — Knowledge (RAG) & Planning
+- Knowledge sources: string, `.txt`, PDF (have `pdf-reader`), CSV, JSON, URL
+  (have `nokogiri`). Embeddings client + a pluggable vector store (start with an
+  in-memory / SQLite cosine store; no hard Chroma dependency).
+- Attach at agent **and** crew level.
+- `Crew.new(planning: true)` → a planner pass that drafts a step plan before
+  execution.
+
+### 0.6.0 — Flows
+The flagship. A Ruby DSL mirroring CrewAI Flows:
+- `start`, `listen`, `router` decorators/class-methods.
+- `and_` / `or_` trigger combinators.
+- Structured flow **state** (a plain struct/`Data` or dry-struct) with a UUID.
+- `@persist`-equivalent state persistence across restarts.
+- `human_feedback` pause/resume point.
+
+### 0.7.0 — Training & Testing
+- `crew.train(n_iterations:, filename:)` capturing human feedback.
+- `crew.test(n_iterations:, model:)` scoring runs.
+
+### Backlog
+Per-agent reasoning (`reasoning:`, `max_reasoning_attempts:`), `max_rpm`
+rate-limiting, `respect_context_window`, `kickoff_for_each` batch execution,
+`before_kickoff` / `after_kickoff` hooks, multimodal agents.

data/lib/rcrewai/agent.rb

@@ -11,8 +11,10 @@ require_relative 'human_input'
 module RCrewAI
   class Agent
     include HumanInteractionExtensions
-    attr_reader :name, :role, :goal, :backstory, :tools, :memory, :llm_client
+    attr_reader :name, :role, :goal, :backstory, :tools, :memory, :llm_client, :knowledge
     attr_accessor :verbose, :allow_delegation, :max_iterations, :max_execution_time, :manager
+    # Set by the crew so agents see shared knowledge in addition to their own.
+    attr_writer :crew_knowledge
 
     def initialize(name:, role:, goal:, backstory: nil, tools: [], **options)
       @name = name
@@ -31,7 +33,8 @@ module RCrewAI
       @logger = Logger.new($stdout)
       @logger.level = verbose ? Logger::DEBUG : Logger::INFO
       @memory = Memory.new
-      @llm_client = LLMClient.for_provider
+      @llm_client = build_llm_client(options[:llm])
+      @knowledge = build_knowledge(options[:knowledge], options[:knowledge_sources])
       @subordinates = [] # For manager agents
     end
 
@@ -194,6 +197,21 @@ module RCrewAI
 
     private
 
+    # Resolves the +llm:+ option into an LLM client. See LLMClient.resolve.
+    def build_llm_client(llm)
+      LLMClient.resolve(llm)
+    end
+
+    # Accepts a pre-built Knowledge::Base via +knowledge:+ or an array of
+    # sources via +knowledge_sources:+ (wrapped in a Base). Returns nil if
+    # neither is given.
+    def build_knowledge(knowledge, sources)
+      return knowledge if knowledge
+      return nil if sources.nil? || sources.empty?
+
+      Knowledge::Base.new(sources: sources)
+    end
+
     def build_context(task)
       context = {
         agent_role: role,
@@ -226,12 +244,28 @@ module RCrewAI
       user << "\nExpected Output: #{task.expected_output}" if task.expected_output
       user << "\nAdditional Context:\n#{ctx[:context_data]}" if ctx[:context_data] && !ctx[:context_data].to_s.empty?
 
+      knowledge = retrieve_knowledge(task)
+      user << "\n\nRelevant Knowledge:\n#{knowledge}" unless knowledge.empty?
+
       [
         { role: 'system', content: system },
         { role: 'user', content: user }
       ]
     end
 
+    # Retrieves knowledge chunks relevant to the task from the agent's own
+    # knowledge base and/or the crew-level base injected via #knowledge=.
+    def retrieve_knowledge(task)
+      bases = [@knowledge, @crew_knowledge].compact
+      return '' if bases.empty?
+
+      chunks = bases.flat_map { |kb| kb.search(task.description, k: 3) }
+      chunks.uniq.join("\n---\n")
+    rescue StandardError => e
+      @logger.warn("Knowledge retrieval failed: #{e.message}")
+      ''
+    end
+
     def build_task_result(task, runner_result)
       {
         task: task.name,

data/lib/rcrewai/configuration.rb

@@ -59,6 +59,26 @@ module RCrewAI
       end
     end
 
+    # Returns a copy of this configuration with the given per-agent overrides
+    # applied. The original configuration is left untouched, so agents can each
+    # target a different provider/model without mutating global state.
+    #
+    #   config.with_overrides(provider: :anthropic, model: 'claude-3-opus-20240229')
+    def with_overrides(provider: nil, model: nil, api_key: nil, temperature: nil)
+      copy = dup
+      copy.llm_provider = provider.to_sym if provider
+      target = copy.llm_provider
+
+      copy.public_send("#{target}_model=", model) if model && copy.respond_to?("#{target}_model=")
+      copy.model = model if model
+
+      copy.public_send("#{target}_api_key=", api_key) if api_key && copy.respond_to?("#{target}_api_key=")
+      copy.api_key = api_key if api_key
+
+      copy.temperature = temperature unless temperature.nil?
+      copy
+    end
+
     def validate!
       raise ConfigurationError, 'LLM provider must be set' if @llm_provider.nil?
       raise ConfigurationError, "API key must be set for #{@llm_provider}" if api_key.nil? || api_key.empty?

data/lib/rcrewai/crew.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require 'logger'
 require_relative 'process'
 require_relative 'async_executor'
 require_relative 'events'
+require_relative 'planning'
 
 module RCrewAI
   class Crew
@@ -17,10 +19,20 @@ module RCrewAI
       @process_type = options.fetch(:process, :sequential)
       @verbose = options.fetch(:verbose, false)
       @max_iterations = options.fetch(:max_iterations, 10)
+      @planning = options.fetch(:planning, false)
+      @planning_llm = options[:planning_llm]
+      @planned = false
+      @knowledge = build_knowledge(options[:knowledge], options[:knowledge_sources])
       @process_instance = nil
       validate_process_type!
     end
 
+    attr_reader :knowledge, :stream_sink
+
+    def planning?
+      @planning
+    end
+
     def add_agent(agent)
       @agents << agent
     end
@@ -35,6 +47,9 @@ module RCrewAI
       Array(stream).each { |s| sinks << s } if stream
       @stream_sink = sinks.empty? ? nil : RCrewAI::Events.fan_out(sinks)
 
+      distribute_knowledge if @knowledge
+      run_planning_pass if planning?
+
       if async
         execute_async(**async_options)
       else
@@ -42,7 +57,34 @@ module RCrewAI
       end
     end
 
-    attr_reader :stream_sink
+    # Runs the crew repeatedly, collecting feedback after each iteration and
+    # persisting it to +filename+ as JSON. +feedback+ is a callable
+    # ->(iteration, result) { "..." }; it defaults to prompting a human.
+    # Mirrors CrewAI's crew.train.
+    def train(n_iterations:, filename:, feedback: nil)
+      feedback ||= method(:default_training_feedback)
+      entries = []
+
+      (1..n_iterations).each do |iteration|
+        result = execute
+        note = feedback.call(iteration, result)
+        entries << { iteration: iteration, feedback: note }
+      end
+
+      write_training_file(filename, entries)
+      { iterations: n_iterations, filename: filename, entries: entries }
+    end
+
+    # Runs the crew repeatedly and scores each run. +scorer+ is a callable
+    # ->(result) { Float }; it defaults to the run's success_rate.
+    # Mirrors CrewAI's crew.test.
+    def test(n_iterations:, scorer: nil, model: nil) # rubocop:disable Lint/UnusedMethodArgument
+      scorer ||= ->(result) { result[:success_rate].to_f }
+      scores = (1..n_iterations).map { scorer.call(execute) }
+      average = scores.empty? ? 0.0 : (scores.sum / scores.length).round(2)
+
+      { iterations: n_iterations, scores: scores, average_score: average }
+    end
 
     def execute_async(**options)
       puts "Executing crew: #{name} (async #{process_type} process)"
@@ -102,6 +144,42 @@ module RCrewAI
 
     private
 
+    def build_knowledge(knowledge, sources)
+      return knowledge if knowledge
+      return nil if sources.nil? || sources.empty?
+
+      Knowledge::Base.new(sources: sources)
+    end
+
+    def distribute_knowledge
+      @knowledge.build!
+      agents.each { |agent| agent.crew_knowledge = @knowledge if agent.respond_to?(:crew_knowledge=) }
+    end
+
+    def default_training_feedback(iteration, _result)
+      require_relative 'human_input'
+      response = HumanInput.new.request_input(
+        "Feedback for training iteration #{iteration} (press enter to skip):"
+      )
+      response.is_a?(Hash) ? response[:input].to_s : response.to_s
+    end
+
+    def write_training_file(filename, entries)
+      require 'json'
+      require 'fileutils'
+      FileUtils.mkdir_p(File.dirname(filename))
+      File.write(filename, JSON.pretty_generate(entries))
+    end
+
+    def run_planning_pass
+      return if @planned
+
+      logger = Logger.new($stdout)
+      logger.level = verbose ? Logger::DEBUG : Logger::INFO
+      Planning.new(self, llm: LLMClient.resolve(@planning_llm), logger: logger).plan!
+      @planned = true
+    end
+
     def validate_process_type!
       valid_processes = %i[sequential hierarchical consensual]
       return if valid_processes.include?(process_type)

data/lib/rcrewai/flow/state.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module RCrewAI
+  class Flow
+    # Mutable, schemaless flow state with a stable unique id. Access attributes
+    # as methods (state.foo, state.foo = 1) or via [] / to_h. Mirrors CrewAI's
+    # unstructured (dict-based) flow state, with an automatic UUID.
+    class State
+      def initialize(attributes = {})
+        @attributes = {}
+        attributes.each { |k, v| @attributes[k.to_sym] = v }
+        @attributes[:id] ||= SecureRandom.uuid
+      end
+
+      def id
+        @attributes[:id]
+      end
+
+      def [](key)
+        @attributes[key.to_sym]
+      end
+
+      def []=(key, value)
+        @attributes[key.to_sym] = value
+      end
+
+      def to_h
+        @attributes.dup
+      end
+
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      def method_missing(name, *args)
+        key = name.to_s
+        if key.end_with?('=')
+          @attributes[key[0..-2].to_sym] = args.first
+        else
+          @attributes[name]
+        end
+      end
+    end
+  end
+end

data/lib/rcrewai/flow/state_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module RCrewAI
+  class Flow
+    # Persists flow state keyed by state id, so a flow can be resumed across
+    # restarts. Two built-ins: in-memory (tests / single process) and file-based
+    # (JSON on disk). Any object with #save(id, hash) and #load(id) works.
+    class MemoryStateStore
+      def initialize
+        @data = {}
+      end
+
+      def save(id, hash)
+        @data[id] = hash.dup
+      end
+
+      def load(id)
+        @data[id]
+      end
+    end
+
+    # Stores each state as a JSON file named <id>.json under a directory.
+    class FileStateStore
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(@dir)
+      end
+
+      def save(id, hash)
+        File.write(path_for(id), JSON.pretty_generate(hash))
+      end
+
+      def load(id)
+        path = path_for(id)
+        return nil unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      end
+
+      private
+
+      def path_for(id)
+        File.join(@dir, "#{id}.json")
+      end
+    end
+  end
+end