rcrewai 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f742fcf06518c80cbf29191d0eff275830ee618c9b896c3d443258b06aa120ff
-  data.tar.gz: 5cc9c03182d0bd80d73d99edb08f2267252684f64a23da1626d2d61e0abe1683
+  metadata.gz: 68a381d21e047e37972fda09fd7e9faa93da77e6fe01a040a4c77b9ee0066aca
+  data.tar.gz: 3818acc6b9b6eb71d27d4099cb1c1fc574adbdd0a3a8128389803c051c364774
 SHA512:
-  metadata.gz: 0c32e4110a5bbabac9b120262e2ebe0e86b0c58c3b4213a11214efcff647024d9714fcee12934f4b734c9f64184e1f802d82b97ec50e5dc7ceab424c4cec38f1
-  data.tar.gz: 8a678ae53008c7c6a73cf365b460b80989da05f22eb646cf3a9126028a0d6dd220e6af75ef4dee80c02d73e69b536fb3d2b7c23f827e929078b76ed450d8f1ce
+  metadata.gz: 65d796bde314db55466f7f4f043db9eeb772dee3e72914d2bc27947eb6dfe84ce246b89a6181d473c3f7d175d353fbc9531914c8baa5b7b010e02229324bac27
+  data.tar.gz: b2fffaab35dc672b12d2a5aea5fd0b02e6519b2f4a5ca98daaf66bef740551e2e674f4cc39967f3d987ed9dfe1c13e7dec4c8a30e5b86e2140242e347dd96a11

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-03
+
+Polish release completing the roadmap backlog: crew lifecycle hooks, batch
+execution, rate limiting, per-agent reasoning, context-window management, and
+multimodal image input. All additive — existing code runs unchanged.
+
+### Added
+- Crew lifecycle hooks: `Crew#before_kickoff` and `Crew#after_kickoff` register callbacks that run before/after execution. A `before_kickoff` hook receives the inputs hash (passed via `crew.execute(inputs:)`) and may transform it; an `after_kickoff` hook receives the result and may transform it. Multiple hooks run in registration order. The (possibly transformed) inputs are exposed on `Crew#last_inputs`. (#15)
+- `Crew#kickoff_for_each(inputs:)` runs the crew once per input set and returns one result per input, in order. Runs are isolated — each execution starts from only its own inputs. (#16)
+- Rate limiting: `Agent.new(max_rpm:)` throttles the agent's LLM calls to the given requests-per-minute using a thread-safe rolling-window `RCrewAI::RateLimiter`. The agent's client is transparently wrapped (`RateLimiter::ThrottledClient`) so every `chat` acquires a slot first; `max_rpm` nil/0 means unlimited. (#17)
+- Reasoning: `Agent.new(reasoning: true)` runs a reasoning/planning pass before answering — the LLM drafts a short plan for the task, which is injected into the answer prompt and surfaced on the result hash as `:reasoning` (without polluting `task.result`). Bounded by `max_reasoning_attempts` (default 3), retrying if the model returns empty output; if every attempt is empty, execution proceeds without a plan. Off by default. (#18)
+- Context-window management: `Agent.new(respect_context_window: true)` trims the message history to fit the model's context window before each LLM call, dropping the oldest non-system messages while always keeping system messages and the latest message. The new `RCrewAI::ContextWindow` module provides the token estimate (chars/4 heuristic), a per-model window-size table, and the `fit` trimmer. Off by default. (#19)
+- Multimodal input: `Task.new(attachments:)` accepts image attachments (`{ type: :image, url: '...' }` or `{ type: :image, path: '...' }`). When a task has attachments, the agent builds an OpenAI-style multimodal user message (text + `image_url` parts); local files are base64-encoded into data URLs with a mime type inferred from the extension. Supported on OpenAI/Azure; other providers raise a clear `Multimodal::UnsupportedProviderError`. The new `RCrewAI::Multimodal` module builds the content parts. (#20)
+
 ## [0.4.0] - 2026-07-03
 
 This release closes the feature-parity gap with the modern CrewAI framework,
@@ -165,7 +179,8 @@ output, guardrails, planning, and training/testing. See `ROADMAP.md`.
 - CLI usage documentation
 - Real-world use cases and examples
 
-[Unreleased]: https://github.com/gkosmo/rcrewAI/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/gkosmo/rcrewAI/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/gkosmo/rcrewAI/compare/v0.4.0...v0.5.0
 [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

@@ -263,6 +263,88 @@ crew.test(n_iterations: 5)
 # => { iterations: 5, scores: [...], average_score: 92.0 }
 ```
 
+## 🪝 Kickoff Hooks & Batch Runs
+
+Run setup/teardown around a crew, and batch it over many inputs:
+
+```ruby
+crew.before_kickoff { |inputs| inputs.merge(started_at: Time.now) } # may transform inputs
+crew.after_kickoff  { |result| notify(result); result }            # may transform result
+
+crew.execute(inputs: { topic: 'ruby' })
+crew.last_inputs   # => the (possibly transformed) inputs the run used
+
+# Batch: run the crew once per input set, results returned in order.
+results = crew.kickoff_for_each(inputs: [
+  { topic: 'ruby' },
+  { topic: 'python' }
+])
+```
+
+## ⏱️ Rate Limiting
+
+Cap an agent's LLM calls to stay under provider limits. Calls beyond the cap
+block until the rolling 60-second window frees up:
+
+```ruby
+agent = RCrewAI::Agent.new(name: 'a', role: '...', goal: '...', max_rpm: 20)
+```
+
+The limiter (`RCrewAI::RateLimiter`) is thread-safe, so it holds under async
+execution. `max_rpm: nil` (the default) or `0` means unlimited.
+
+## 🧠 Reasoning
+
+Have an agent think through a plan before answering. The reasoning trace is
+surfaced on the result and does not pollute `task.result`:
+
+```ruby
+agent = RCrewAI::Agent.new(name: 'a', role: '...', goal: '...',
+                           reasoning: true, max_reasoning_attempts: 3)
+
+result = agent.execute_task(task)
+result[:reasoning]   # => the plan the agent drafted before answering
+result[:content]     # => the final answer
+```
+
+Off by default. If the reasoning pass keeps returning empty output past
+`max_reasoning_attempts`, the agent proceeds without a plan.
+
+## 🪟 Context Window Management
+
+Keep long tool-use loops or large injected context from overflowing the model's
+context window. When enabled, the oldest non-system messages are dropped to fit
+before each LLM call (system messages and the latest message are always kept):
+
+```ruby
+agent = RCrewAI::Agent.new(name: 'a', role: '...', goal: '...',
+                           respect_context_window: true)
+```
+
+Window sizes come from `RCrewAI::ContextWindow` (with a conservative default for
+unknown models); headroom for the response is reserved from `max_tokens`. Off by
+default.
+
+## 🖼️ Multimodal Input
+
+Pass images to a vision-capable model via task attachments. Local files are
+base64-encoded automatically; URLs pass through:
+
+```ruby
+RCrewAI.configure { |c| c.llm_provider = :openai; c.openai_model = 'gpt-4o' }
+
+task = RCrewAI::Task.new(
+  name: 'describe', description: 'What is in this chart?', agent: agent,
+  attachments: [
+    { type: :image, path: 'chart.png' },
+    { type: :image, url: 'https://example.com/photo.jpg' }
+  ]
+)
+```
+
+Supported on OpenAI and Azure; other providers raise a clear error when
+attachments are present.
+
 ## 📚 Knowledge (RAG)
 
 Ground agents in your own documents. Sources are chunked, embedded, and stored

data/ROADMAP.md

@@ -16,12 +16,11 @@ 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.
+**Training/Testing**. RCrewAI now implements all of these — see the matrix below.
 
-**Status: all milestone issues (#5–#12) are complete.** The remaining backlog
-covers smaller polish items (reasoning, rate-limiting, batch kickoff, kickoff
-hooks, multimodal).
+**Status: complete.** All milestone issues (#5–#12) shipped in v0.4.0, and all
+backlog items (#15–#20) are done and merged to `main` (awaiting the next
+release). There is no outstanding roadmap work.
 
 ## Parity matrix
 
@@ -42,7 +41,7 @@ hooks, multimodal).
 | Flows (`start`/`listen`/`router`) | ✅ | ✅ (#11) | ✅ done |
 | Flow state + persistence | ✅ | ✅ (#11) | ✅ done |
 | Training / Testing | ✅ | ✅ (#12) | ✅ done |
-| Reasoning, rate-limiting, batch kickoff | ✅ | ❌ | backlog |
+| Reasoning, rate-limiting, batch kickoff, hooks, context window, multimodal | ✅ | ✅ (#15–#20) | ✅ done |
 
 ## Milestones (highest leverage first)
 
@@ -78,7 +77,14 @@ The flagship. A Ruby DSL mirroring CrewAI Flows:
 - `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.
+### Backlog — ✅ all complete
+
+Formerly polish items with no set version; all shipped in the `[Unreleased]`
+changes (see CHANGELOG):
+
+- [#15](https://github.com/gkosmo/rcrewAI/issues/15) — `before_kickoff` / `after_kickoff` lifecycle hooks ✅
+- [#16](https://github.com/gkosmo/rcrewAI/issues/16) — `kickoff_for_each` batch execution ✅
+- [#17](https://github.com/gkosmo/rcrewAI/issues/17) — `max_rpm` rate limiting ✅
+- [#18](https://github.com/gkosmo/rcrewAI/issues/18) — per-agent reasoning (`reasoning:`, `max_reasoning_attempts:`) ✅
+- [#19](https://github.com/gkosmo/rcrewAI/issues/19) — `respect_context_window` history trimming ✅
+- [#20](https://github.com/gkosmo/rcrewAI/issues/20) — multimodal agents (image/file inputs) ✅

data/docs/upgrading-to-0.4.md

@@ -0,0 +1,191 @@
+# Upgrading to RCrewAI 0.4
+
+RCrewAI 0.4 closes the feature-parity gap with the modern CrewAI framework. It
+adds CrewAI's second pillar — **Flows** — alongside **Knowledge (RAG)**,
+structured task output, guardrails, planning, and training/testing.
+
+**0.4 is fully backward compatible.** There are no breaking changes: existing
+0.3 code runs unchanged. Everything below is opt-in.
+
+Each new capability has a runnable example under `examples/` — see the links
+throughout.
+
+---
+
+## 1. What you must do
+
+Nothing. Upgrade the gem and your existing code keeps working:
+
+```ruby
+gem 'rcrewai', '~> 0.4'
+```
+
+---
+
+## 2. What you can do (new capabilities)
+
+### 2a. Per-agent LLM
+
+Give each agent its own provider/model instead of only the global default.
+Pass a provider symbol, an options hash, or a pre-built client:
+
+```ruby
+worker  = RCrewAI::Agent.new(name: 'worker', role: '...', goal: '...',
+                             llm: { provider: :openai, model: 'gpt-4o-mini' })
+manager = RCrewAI::Agent.new(name: 'manager', role: '...', goal: '...',
+                             llm: { provider: :anthropic, model: 'claude-3-opus-20240229' })
+```
+
+Omitting `llm:` keeps the global `RCrewAI.configure` behavior. Overrides never
+mutate the global configuration.
+
+### 2b. Structured output, guardrails, and file output
+
+Post-process a task's result after the agent produces it:
+
+```ruby
+task = RCrewAI::Task.new(
+  name: 'extract', description: '...', agent: agent,
+
+  # Validate & coerce against a JSON schema. Non-conforming output re-runs the
+  # agent with the error fed back. Parsed object on task.structured_output.
+  output_schema: { type: 'object', properties: { title: { type: 'string' } },
+                   required: ['title'] },
+
+  # Validate & transform. ->(output) { [ok, value_or_error] }. Retries up to
+  # guardrail_max_retries (default 3) with the reason fed back to the agent.
+  guardrail: ->(out) { [out.length < 5000, 'too long'] },
+
+  # Persist the result (parent dirs created unless create_directory: false).
+  output_file: 'out/report.md', markdown: true
+)
+
+task.execute
+task.structured_output  # => { "title" => "..." }
+task.raw_result         # => the unprocessed string the agent produced
+```
+
+See `examples/structured_output_example.rb`.
+
+### 2c. Knowledge (RAG)
+
+Ground agents in your own documents. Sources are chunked, embedded, and stored
+in an in-memory cosine vector store; relevant chunks are injected into each
+task's prompt automatically.
+
+```ruby
+kb = RCrewAI::Knowledge::Base.new(sources: [
+  RCrewAI::Knowledge::StringSource.new('Refunds within 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):
+agent = RCrewAI::Agent.new(name: 'support', role: '...', goal: '...', knowledge: kb)
+
+# Or pass raw sources and let the agent build the base:
+agent = 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', knowledge: kb)
+```
+
+Embeddings default to OpenAI's `text-embedding-3-small`; pass a custom
+`embedder:` (anything responding to `embed(texts)`) to swap the backend.
+See `examples/knowledge_rag_example.rb`.
+
+### 2d. Planning
+
+Have a planner pass draft a per-task plan before execution:
+
+```ruby
+crew = RCrewAI::Crew.new('research_crew', planning: true)
+# Optionally use a dedicated (stronger) planner model:
+crew = RCrewAI::Crew.new('research_crew', planning: true,
+                         planning_llm: { provider: :anthropic, model: 'claude-3-opus-20240229' })
+```
+
+The plan is folded into each task's description. Planning is best-effort: a
+planner error or unparseable output leaves tasks unchanged.
+
+### 2e. Training & testing
+
+Iterate on a crew with feedback, or score repeated runs:
+
+```ruby
+# 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]}%" })
+
+# Run N times and score each run (defaults to success_rate).
+crew.test(n_iterations: 5)
+# => { iterations: 5, scores: [...], average_score: 92.0 }
+```
+
+See `examples/planning_and_training_example.rb`.
+
+### 2f. Flows
+
+Flows are an event-driven workflow engine — the biggest addition in 0.4.
+Subclass `RCrewAI::Flow` and wire methods with a class-level DSL:
+
+```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"
+```
+
+- `start` / `listen` / `router` wire methods into a graph; a listener receives
+  its trigger's return value, and a router's return becomes a label listeners
+  fire on.
+- 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?')`.
+
+See `examples/flow_example.rb`.
+
+---
+
+## When to use Flows vs. Crews
+
+- **Crew** — a team of agents collaborating on a set of tasks (sequential,
+  hierarchical, or async). Reach for a crew when the work is "have these agents
+  produce these outputs."
+- **Flow** — explicit, branching orchestration with state. Reach for a flow
+  when you need conditional paths, joins, persistence/resumption, or you want to
+  coordinate multiple crews and plain Ruby steps.
+
+They compose: a Flow step can kick off a Crew.

data/examples/flow_example.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Flows — event-driven workflows (RCrewAI's second pillar).
+#
+# Subclass RCrewAI::Flow and wire methods together with the class-level DSL:
+# `start` kicks things off, `listen` reacts to another method's output, and
+# `router` branches by emitting a label that listeners can trigger on. State
+# is a schemaless object with an automatic UUID, and can be persisted so a run
+# can be resumed later.
+#
+# This example needs no API key — it demonstrates the engine itself.
+#
+# Run:
+#   ruby examples/flow_example.rb
+
+require_relative '../lib/rcrewai'
+
+# A tiny content pipeline: outline -> draft -> review (router) -> publish/expand.
+class ArticleFlow < RCrewAI::Flow
+  start :outline
+  def outline
+    state.sections = %w[intro body conclusion]
+    state.sections.length # this return value is passed to listeners of :outline
+  end
+
+  listen :outline
+  def draft(section_count)
+    state.words = section_count * 100
+    state.words
+  end
+
+  # A router's return value (:publish / :expand) becomes a label that the
+  # matching `listen` methods fire on.
+  router :draft
+  def review(words)
+    words >= 250 ? :publish : :expand
+  end
+
+  listen :publish
+  def publish
+    state.status = 'published'
+  end
+
+  listen :expand
+  def expand
+    state.status = 'needs more work'
+  end
+end
+
+puts '== Basic run =='
+flow = ArticleFlow.new
+flow.kickoff(inputs: { author: 'Ada' })
+puts "id:       #{flow.state.id}"
+puts "author:   #{flow.state.author}      (seeded via kickoff inputs)"
+puts "sections: #{flow.state.sections.inspect}"
+puts "words:    #{flow.state.words}"
+puts "status:   #{flow.state.status.inspect}   (routed to :publish since words >= 250)"
+
+puts "\n== and_/or_ combinators =="
+class GateFlow < RCrewAI::Flow
+  start :fetch_a
+  def fetch_a = 'A'
+
+  start :fetch_b
+  def fetch_b = 'B'
+
+  # Fires only after BOTH starts complete.
+  listen and_(:fetch_a, :fetch_b)
+  def merge
+    state.merged = 'both done'
+  end
+end
+
+gate = GateFlow.new
+gate.kickoff
+puts "merged: #{gate.state.merged.inspect}   (and_ waited for both starts)"
+
+puts "\n== Persistence round-trip =="
+require 'tmpdir'
+store = RCrewAI::Flow::FileStateStore.new(File.join(Dir.tmpdir, 'rcrewai-flow-demo'))
+
+original = ArticleFlow.new(state_store: store)
+original.kickoff
+id = original.state.id
+
+resumed = ArticleFlow.new(state_store: store)
+resumed.restore(id)
+puts "restored status for #{id[0, 8]}...: #{resumed.state.status.inspect}"

data/examples/knowledge_rag_example.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Knowledge (RAG) — ground agents in your own documents.
+#
+# Sources (strings, files, PDFs, CSVs, URLs) are chunked, embedded, and stored
+# in an in-memory cosine-similarity vector store. At execution time the most
+# relevant chunks are injected into the agent's task prompt.
+#
+# This example uses a fake, deterministic embedder so it runs WITHOUT an API
+# key. In real use you'd omit `embedder:` and let it default to OpenAI's
+# text-embedding-3-small (set OPENAI_API_KEY).
+#
+# Run:
+#   ruby examples/knowledge_rag_example.rb
+
+require_relative '../lib/rcrewai'
+
+# A toy embedder: maps text to a small vector by keyword presence. Any object
+# responding to `embed(texts) -> [[float, ...], ...]` works here.
+class KeywordEmbedder
+  KEYWORDS = %w[refund shipping warranty].freeze
+
+  def embed(texts)
+    texts.map do |t|
+      lower = t.downcase
+      KEYWORDS.map { |kw| lower.include?(kw) ? 1.0 : 0.0 }
+    end
+  end
+end
+
+# 1. Build a knowledge base from a few policy snippets.
+knowledge = RCrewAI::Knowledge::Base.new(
+  sources: [
+    RCrewAI::Knowledge::StringSource.new('Refunds are available within 30 days of purchase.'),
+    RCrewAI::Knowledge::StringSource.new('Standard shipping takes 5-7 business days.'),
+    RCrewAI::Knowledge::StringSource.new('The warranty covers manufacturing defects for one year.')
+  ],
+  embedder: KeywordEmbedder.new
+)
+
+# 2. Retrieve directly (what the agent does under the hood).
+puts '== Direct retrieval =='
+%w[refund shipping warranty].each do |query|
+  top = knowledge.search(query, k: 1).first
+  puts "#{query.ljust(9)} -> #{top}"
+end
+
+# 3. Attach the knowledge to an agent and see it injected into the prompt.
+puts "\n== Injected into the agent prompt =="
+RCrewAI.configure(validate: false) do |c|
+  c.llm_provider = :openai
+  c.api_key = 'demo-key' # not used — we only build the prompt below
+end
+
+agent = RCrewAI::Agent.new(
+  name: 'support',
+  role: 'Customer support specialist',
+  goal: 'Answer customer questions using company policy',
+  knowledge: knowledge
+)
+task = RCrewAI::Task.new(
+  name: 'answer',
+  description: 'What is the refund policy?',
+  agent: agent
+)
+
+messages = agent.send(:build_initial_messages, task)
+puts messages.find { |m| m[:role] == 'user' }[:content]
+
+# Crew-level knowledge is shared with every agent, e.g.:
+#   crew = RCrewAI::Crew.new('support', knowledge: knowledge)

data/examples/planning_and_training_example.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Crew planning, plus the train/test workflows.
+#
+#   - planning: true            -> a planner pass drafts a per-task plan and
+#                                  folds it into each task's description before
+#                                  execution.
+#   - crew.train(...)           -> runs the crew repeatedly, collecting feedback
+#                                  after each run and persisting it as JSON.
+#   - crew.test(...)            -> runs the crew repeatedly and scores each run.
+#
+# This example stubs the planner LLM and the process so it runs WITHOUT an API
+# key, focusing on the wiring.
+#
+# Run:
+#   ruby examples/planning_and_training_example.rb
+
+require_relative '../lib/rcrewai'
+require 'tmpdir'
+
+RCrewAI.configure(validate: false) do |c|
+  c.llm_provider = :openai
+  c.api_key = 'demo-key'
+end
+
+# A fake planner client: returns a JSON map of task name -> plan.
+class FakePlanner
+  def chat(**)
+    { content: '{"research": "list 3 sources", "summarize": "write 5 bullets"}' }
+  end
+end
+
+agent = RCrewAI::Agent.new(name: 'analyst', role: 'Analyst', goal: 'Analyze')
+research = RCrewAI::Task.new(name: 'research', description: 'Research the topic', agent: agent)
+summarize = RCrewAI::Task.new(name: 'summarize', description: 'Summarize findings', agent: agent)
+
+crew = RCrewAI::Crew.new('analysis', planning: true, planning_llm: FakePlanner.new)
+crew.add_agent(agent)
+crew.add_task(research)
+crew.add_task(summarize)
+
+# Stub the actual task execution so the demo needs no live LLM.
+module RCrewAI
+  module Process
+    class Sequential
+      def execute
+        [{ status: :completed }]
+      end
+    end
+  end
+end
+
+puts '== Planning pass =='
+crew.execute
+puts "research.description:\n  #{research.description.gsub("\n", "\n  ")}"
+puts "summarize.description:\n  #{summarize.description.gsub("\n", "\n  ")}"
+
+puts "\n== Training (feedback persisted to JSON) =="
+file = File.join(Dir.tmpdir, 'rcrewai-training-demo.json')
+summary = crew.train(
+  n_iterations: 3,
+  filename: file,
+  feedback: ->(iteration, _result) { "run #{iteration}: looked good" }
+)
+puts "iterations: #{summary[:iterations]}, file: #{summary[:filename]}"
+puts File.read(file)
+File.delete(file)
+
+puts "\n== Testing (per-run scores) =="
+result = crew.test(n_iterations: 3, scorer: ->(_run) { 90.0 + rand(10) })
+puts "scores: #{result[:scores].inspect}, average: #{result[:average_score]}"

data/examples/structured_output_example.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Structured output, guardrails, and file output on a Task.
+#
+# After the agent produces its answer, a Task can:
+#   - validate & coerce it against a JSON schema  (output_schema:)
+#   - validate & transform it with a guardrail     (guardrail:)
+#   - write it to disk, optionally as markdown      (output_file:, markdown:)
+#
+# Schema/guardrail failures re-run the agent with the error fed back.
+#
+# This example stubs the agent so it runs WITHOUT an API key. In real use the
+# agent calls your configured LLM.
+#
+# Run:
+#   ruby examples/structured_output_example.rb
+
+require_relative '../lib/rcrewai'
+require 'tmpdir'
+
+# A stand-in agent: returns canned responses so we can demonstrate the
+# post-processing pipeline deterministically. A real Agent behaves the same
+# way from the Task's point of view (it returns { content: "..." }).
+class ScriptedAgent
+  def initialize(responses)
+    @responses = responses
+  end
+
+  def tools = []
+
+  def execute_task(_task)
+    { content: @responses.shift }
+  end
+end
+
+puts '== Structured output (with a repair retry) =='
+# First response is invalid JSON; the task feeds the error back and retries,
+# and the second response conforms to the schema.
+agent = ScriptedAgent.new(['sorry, not sure', '{"title": "Q3 Report", "words": 1200}'])
+
+task = RCrewAI::Task.new(
+  name: 'extract',
+  description: 'Extract the article title and word count as JSON',
+  agent: agent,
+  output_schema: {
+    type: 'object',
+    properties: { title: { type: 'string' }, words: { type: 'integer' } },
+    required: ['title']
+  }
+)
+task.execute
+puts "structured_output: #{task.structured_output.inspect}"
+puts "raw_result:        #{task.raw_result.inspect}"
+
+puts "\n== Guardrail (transform + reject/retry) =="
+# The guardrail requires the answer to mention a price; the first attempt does
+# not, so the task re-runs, and the second attempt passes (and is stripped).
+agent = ScriptedAgent.new(['no price yet', '  Final price: $49  '])
+
+guardrail = lambda do |output|
+  if output.include?('$')
+    [true, output.strip] # accept + transform
+  else
+    [false, 'must include a price'] # reject with a reason (fed back to the agent)
+  end
+end
+
+task = RCrewAI::Task.new(
+  name: 'quote',
+  description: 'Give the final price',
+  agent: agent,
+  guardrail: guardrail,
+  guardrail_max_retries: 2
+)
+puts "result: #{task.execute.inspect}"
+
+puts "\n== File output (markdown) =="
+agent = ScriptedAgent.new(['All systems nominal.'])
+path = File.join(Dir.tmpdir, 'rcrewai-report-demo.md')
+
+task = RCrewAI::Task.new(
+  name: 'report',
+  description: 'Write a status report',
+  agent: agent,
+  output_file: path,
+  markdown: true
+)
+task.execute
+puts "wrote #{path}:"
+puts File.read(path)
+File.delete(path)

data/lib/rcrewai/agent.rb

@@ -3,6 +3,9 @@
 require 'logger'
 require_relative 'llm_client'
 require_relative 'memory'
+require_relative 'rate_limiter'
+require_relative 'agent_augmentations'
+require_relative 'multimodal'
 require_relative 'tools/base'
 require_relative 'tool_runner'
 require_relative 'legacy_react_runner'
@@ -11,7 +14,8 @@ require_relative 'human_input'
 module RCrewAI
   class Agent
     include HumanInteractionExtensions
-    attr_reader :name, :role, :goal, :backstory, :tools, :memory, :llm_client, :knowledge
+    include AgentAugmentations
+    attr_reader :name, :role, :goal, :backstory, :tools, :memory, :llm_client, :knowledge, :rate_limiter
     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
@@ -32,8 +36,12 @@ module RCrewAI
       @require_approval_for_final_answer = options.fetch(:require_approval_for_final_answer, false)
       @logger = Logger.new($stdout)
       @logger.level = verbose ? Logger::DEBUG : Logger::INFO
+      @reasoning = options.fetch(:reasoning, false)
+      @max_reasoning_attempts = options.fetch(:max_reasoning_attempts, 3)
+      @respect_context_window = options.fetch(:respect_context_window, false)
       @memory = Memory.new
-      @llm_client = build_llm_client(options[:llm])
+      @rate_limiter = options[:max_rpm] ? RateLimiter.new(max_rpm: options[:max_rpm]) : nil
+      @llm_client = wrap_with_rate_limiter(build_llm_client(options[:llm]))
       @knowledge = build_knowledge(options[:knowledge], options[:knowledge_sources])
       @subordinates = [] # For manager agents
     end
@@ -46,6 +54,9 @@ module RCrewAI
         initial_messages = build_initial_messages(task)
         sink = stream || ->(_) {}
 
+        reasoning = reasoning? ? run_reasoning_pass(task) : nil
+        initial_messages = inject_reasoning(initial_messages, reasoning) if reasoning
+
         runner_class = pick_runner_class
         @logger.info "[rcrewai] agent=#{name} runner=#{runner_class.name.split('::').last}"
 
@@ -63,7 +74,7 @@ module RCrewAI
         memory.add_execution(task, result_string, execution_time)
         task.result = result_string
 
-        build_task_result(task, runner_result)
+        build_task_result(task, runner_result, reasoning: reasoning)
       rescue StandardError => e
         @logger.error "Task execution failed: #{e.message}"
         task.result = "Task failed: #{e.message}"
@@ -202,6 +213,13 @@ module RCrewAI
       LLMClient.resolve(llm)
     end
 
+    # Wraps the client so every #chat is throttled, when a rate limiter is set.
+    def wrap_with_rate_limiter(client)
+      return client unless @rate_limiter
+
+      RateLimiter::ThrottledClient.new(client, @rate_limiter)
+    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.
@@ -249,10 +267,20 @@ module RCrewAI
 
       [
         { role: 'system', content: system },
-        { role: 'user', content: user }
+        { role: 'user', content: build_user_content(user, task) }
       ]
     end
 
+    # Returns a plain string, or an OpenAI-style multimodal parts array when the
+    # task carries attachments (guarded to providers that support it).
+    def build_user_content(text, task)
+      attachments = task.respond_to?(:attachments) ? task.attachments : nil
+      return text if attachments.nil? || attachments.empty?
+
+      Multimodal.ensure_supported_provider!(RCrewAI.configuration.llm_provider)
+      Multimodal.content_parts(text, attachments)
+    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)
@@ -266,7 +294,7 @@ module RCrewAI
       ''
     end
 
-    def build_task_result(task, runner_result)
+    def build_task_result(task, runner_result, reasoning: nil)
       {
         task: task.name,
         agent: name,
@@ -274,10 +302,14 @@ module RCrewAI
         tool_calls_history: runner_result[:tool_calls_history] || [],
         usage: runner_result[:usage] || {},
         iterations: runner_result[:iterations],
-        finish_reason: runner_result[:finish_reason]
+        finish_reason: runner_result[:finish_reason],
+        reasoning: reasoning
       }
     end
 
+    # Asks the LLM to think through an approach before answering. Retries up to
+    # @max_reasoning_attempts if the model returns empty output; returns nil if
+    # every attempt is empty (execution then proceeds without a plan).
     def pick_runner_class
       schemas_ok = @tools.empty? || @tools.all? { |t| t.respond_to?(:json_schema) && t.json_schema }
       native = @llm_client.respond_to?(:supports_native_tools?) &&

data/lib/rcrewai/agent_augmentations.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative 'context_window'
+
+module RCrewAI
+  # Optional per-task augmentations mixed into Agent: a reasoning/planning pass
+  # before answering, and context-window trimming of the message history.
+  # Kept in a module so Agent's core stays focused.
+  module AgentAugmentations
+    def reasoning?
+      @reasoning
+    end
+
+    def respect_context_window?
+      @respect_context_window
+    end
+
+    # Trims a message list to fit the model's context window when the agent has
+    # respect_context_window enabled; otherwise returns it unchanged. Called by
+    # the runners before each LLM call.
+    def fit_context(messages)
+      return messages unless @respect_context_window
+
+      limit = ContextWindow.window_for(llm_model_name)
+      reserve = [RCrewAI.configuration.max_tokens.to_i, 0].max
+      ContextWindow.fit(messages, limit: limit, reserve: reserve)
+    end
+
+    private
+
+    # Asks the LLM to think through an approach before answering. Retries up to
+    # @max_reasoning_attempts if the model returns empty output; returns nil if
+    # every attempt is empty (execution then proceeds without a plan).
+    def run_reasoning_pass(task)
+      prompt = <<~PROMPT
+        You are #{role}. Before answering, think step by step about how to best
+        accomplish this task. Produce a short, concrete plan (do not answer yet).
+
+        Task: #{task.description}
+        Expected Output: #{task.expected_output || 'not specified'}
+      PROMPT
+
+      @max_reasoning_attempts.times do
+        response = @llm_client.chat(messages: [{ role: 'user', content: prompt }])
+        text = (response.is_a?(Hash) ? response[:content] : response).to_s.strip
+        return text unless text.empty?
+      end
+      nil
+    rescue StandardError => e
+      @logger.warn("Reasoning pass failed: #{e.message}")
+      nil
+    end
+
+    # Adds the reasoning trace to the user message so the answer pass can use it.
+    def inject_reasoning(messages, reasoning)
+      messages.map do |msg|
+        next msg unless msg[:role] == 'user'
+
+        { role: 'user', content: "#{msg[:content]}\n\nYour plan:\n#{reasoning}" }
+      end
+    end
+
+    # Best-effort model name from the (possibly wrapped) client, for context
+    # window sizing. Falls back to the global configured model.
+    def llm_model_name
+      if @llm_client.respond_to?(:config) && @llm_client.config.respond_to?(:model)
+        @llm_client.config.model
+      else
+        RCrewAI.configuration.model
+      end
+    rescue StandardError
+      RCrewAI.configuration.model
+    end
+  end
+end

data/lib/rcrewai/context_window.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  # Keeps a conversation within a model's context window by dropping the oldest
+  # non-system messages when it would overflow. Token counts use a cheap
+  # chars/4 heuristic (no tokenizer dependency); the goal is to avoid hard
+  # context-length errors, not exact accounting.
+  module ContextWindow
+    CHARS_PER_TOKEN = 4
+    DEFAULT_WINDOW = 8_192
+
+    # Approximate context window sizes (in tokens) by model.
+    WINDOWS = {
+      'gpt-4o' => 128_000,
+      'gpt-4o-mini' => 128_000,
+      'gpt-4-turbo' => 128_000,
+      'gpt-4' => 8_192,
+      'gpt-3.5-turbo' => 16_385,
+      'claude-opus-4-7' => 200_000,
+      'claude-sonnet-4-6' => 200_000,
+      'claude-haiku-4-5' => 200_000,
+      'claude-3-5-sonnet-20241022' => 200_000,
+      'claude-3-haiku-20240307' => 200_000,
+      'gemini-1.5-pro' => 1_000_000,
+      'gemini-1.5-flash' => 1_000_000
+    }.freeze
+
+    module_function
+
+    def estimate_tokens(input)
+      text = input.is_a?(Array) ? input.map { |m| m[:content].to_s }.join : input.to_s
+      (text.length / CHARS_PER_TOKEN.to_f).ceil
+    end
+
+    def window_for(model)
+      WINDOWS[model] || DEFAULT_WINDOW
+    end
+
+    # Returns a copy of +messages+ trimmed to fit within (limit - reserve)
+    # tokens. System messages are always kept, as is the final message. The
+    # oldest non-system, non-final messages are dropped first.
+    def fit(messages, limit:, reserve: 0)
+      budget = limit - reserve
+      return messages if estimate_tokens(messages) <= budget
+
+      system = messages.select { |m| m[:role] == 'system' }
+      last = messages.last
+      # Candidates for dropping: everything that isn't a system message or the
+      # final message, oldest first.
+      middle = messages.reject { |m| m[:role] == 'system' || m.equal?(last) }
+
+      kept_middle = middle.dup
+      until fits?(system, kept_middle, last, budget) || kept_middle.empty?
+        kept_middle.shift # drop the oldest
+      end
+
+      rebuild(messages, system, kept_middle, last)
+    end
+
+    # -- helpers --------------------------------------------------------------
+
+    def fits?(system, middle, last, budget)
+      parts = system + middle
+      parts << last unless system.include?(last) || middle.include?(last)
+      estimate_tokens(parts) <= budget
+    end
+
+    def rebuild(original, system, middle, last)
+      keep = (system + middle)
+      keep << last unless keep.include?(last)
+      # Preserve original ordering.
+      original.select { |m| keep.include?(m) }
+    end
+  end
+end

data/lib/rcrewai/crew.rb

@@ -23,16 +23,33 @@ module RCrewAI
       @planning_llm = options[:planning_llm]
       @planned = false
       @knowledge = build_knowledge(options[:knowledge], options[:knowledge_sources])
+      @before_kickoff_hooks = []
+      @after_kickoff_hooks = []
+      @last_inputs = {}
       @process_instance = nil
       validate_process_type!
     end
 
-    attr_reader :knowledge, :stream_sink
+    attr_reader :knowledge, :stream_sink, :last_inputs
 
     def planning?
       @planning
     end
 
+    # Register a callback run before execution. Receives the inputs hash and may
+    # return a transformed hash. Multiple hooks run in registration order.
+    def before_kickoff(&block)
+      @before_kickoff_hooks << block
+      self
+    end
+
+    # Register a callback run after execution. Receives the result and may
+    # return a transformed result. Multiple hooks run in registration order.
+    def after_kickoff(&block)
+      @after_kickoff_hooks << block
+      self
+    end
+
     def add_agent(agent)
       @agents << agent
     end
@@ -41,20 +58,25 @@ module RCrewAI
       @tasks << task
     end
 
-    def execute(async: false, stream: nil, **async_options, &block)
+    def execute(async: false, stream: nil, inputs: {}, **async_options, &block)
       sinks = []
       sinks << block if block_given?
       Array(stream).each { |s| sinks << s } if stream
       @stream_sink = sinks.empty? ? nil : RCrewAI::Events.fan_out(sinks)
 
+      run_before_hooks(inputs)
+
       distribute_knowledge if @knowledge
       run_planning_pass if planning?
 
-      if async
-        execute_async(**async_options)
-      else
-        execute_sync
-      end
+      result = async ? execute_async(**async_options) : execute_sync
+      run_after_hooks(result)
+    end
+
+    # Runs the crew once per input set, returning one result per input in order.
+    # Runs are isolated: each execution starts from only its own inputs.
+    def kickoff_for_each(inputs:)
+      Array(inputs).map { |input| execute(inputs: input) }
     end
 
     # Runs the crew repeatedly, collecting feedback after each iteration and
@@ -144,6 +166,22 @@ module RCrewAI
 
     private
 
+    def run_before_hooks(inputs)
+      # Assign before running hooks so a hook that reads #last_inputs sees this
+      # run's own inputs; update it as each hook transforms them.
+      @last_inputs = inputs || {}
+      @before_kickoff_hooks.each do |hook|
+        @last_inputs = hook.call(@last_inputs) || @last_inputs
+      end
+      @last_inputs
+    end
+
+    def run_after_hooks(result)
+      @after_kickoff_hooks.reduce(result) do |acc, hook|
+        hook.call(acc) || acc
+      end
+    end
+
     def build_knowledge(knowledge, sources)
       return knowledge if knowledge
       return nil if sources.nil? || sources.empty?

data/lib/rcrewai/legacy_react_runner.rb

@@ -30,7 +30,7 @@ module RCrewAI
         iter += 1
         emit(Events::IterationStart, iteration: iter, iteration_index: iter)
 
-        response = @llm.chat(messages: msgs)
+        response = @llm.chat(messages: fit_context(msgs))
         accumulate_usage(total_usage, response[:usage])
         reasoning = response[:content] || ''
         last_reasoning = reasoning
@@ -60,6 +60,12 @@ module RCrewAI
 
     private
 
+    # Trims the message list to the model's context window when the agent
+    # supports it; a no-op otherwise.
+    def fit_context(messages)
+      @agent.respond_to?(:fit_context) ? @agent.fit_context(messages) : messages
+    end
+
     def parse_and_execute_actions(reasoning, iter)
       results = []
       iteration_history = []

data/lib/rcrewai/multimodal.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module RCrewAI
+  # Builds multimodal message content (text + images) in the OpenAI
+  # chat-completions format:
+  #   [{ type: 'text', text: '...' },
+  #    { type: 'image_url', image_url: { url: '...' } }]
+  #
+  # Local image paths are base64-encoded into data URLs; URLs pass through.
+  # Only OpenAI-style multimodal is supported today; other providers raise.
+  module Multimodal
+    SUPPORTED_PROVIDERS = %i[openai azure].freeze
+
+    MIME_TYPES = {
+      '.png' => 'image/png',
+      '.jpg' => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.gif' => 'image/gif',
+      '.webp' => 'image/webp'
+    }.freeze
+
+    module_function
+
+    # Returns an OpenAI-style content-parts array for the given text and
+    # attachments. With no attachments this is a single text part.
+    def content_parts(text, attachments)
+      parts = [{ type: 'text', text: text.to_s }]
+      Array(attachments).each { |att| parts << image_part(att) }
+      parts
+    end
+
+    def supported_provider?(provider)
+      SUPPORTED_PROVIDERS.include?(provider.to_sym)
+    end
+
+    def ensure_supported_provider!(provider)
+      return if supported_provider?(provider)
+
+      raise UnsupportedProviderError,
+            "multimodal attachments are not supported for provider #{provider}"
+    end
+
+    def image_part(attachment)
+      type = attachment[:type] || attachment['type']
+      raise UnsupportedAttachmentError, "unsupported attachment type: #{type.inspect}" unless type.to_sym == :image
+
+      url = attachment[:url] || attachment['url']
+      path = attachment[:path] || attachment['path']
+      resolved = url || data_url_for(path)
+
+      { type: 'image_url', image_url: { url: resolved } }
+    end
+
+    def data_url_for(path)
+      raise UnsupportedAttachmentError, 'image attachment needs a :url or :path' unless path
+
+      mime = MIME_TYPES[File.extname(path).downcase] || 'application/octet-stream'
+      encoded = Base64.strict_encode64(File.binread(path))
+      "data:#{mime};base64,#{encoded}"
+    end
+
+    class UnsupportedAttachmentError < RCrewAI::Error; end
+    class UnsupportedProviderError < RCrewAI::Error; end
+  end
+end

data/lib/rcrewai/rate_limiter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  # Thread-safe requests-per-minute throttle. Records call timestamps in a
+  # rolling 60-second window; `acquire` blocks (sleeps) until a slot is free.
+  #
+  # The clock and sleeper are injectable so tests can drive time deterministically
+  # without touching the wall clock. `max_rpm` of nil or 0 means unlimited.
+  class RateLimiter
+    WINDOW = 60.0
+
+    def initialize(max_rpm:, clock: nil, sleeper: nil)
+      @max_rpm = max_rpm
+      @clock = clock || -> { current_time }
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @calls = []
+      @mutex = Mutex.new
+    end
+
+    # Blocks until making a call would keep us within max_rpm, then records it.
+    def acquire
+      return record_unlimited if unlimited?
+
+      loop do
+        wait = @mutex.synchronize do
+          prune(@clock.call)
+          if @calls.length < @max_rpm
+            @calls << @clock.call
+            return
+          end
+          # Time until the oldest in-window call ages out.
+          (@calls.first + WINDOW) - @clock.call
+        end
+
+        @sleeper.call(wait) if wait.positive?
+      end
+    end
+
+    # Number of calls currently inside the window (useful for tests/metrics).
+    def recent_count
+      @mutex.synchronize do
+        prune(@clock.call)
+        @calls.length
+      end
+    end
+
+    private
+
+    def unlimited?
+      @max_rpm.nil? || @max_rpm.zero?
+    end
+
+    def record_unlimited
+      @mutex.synchronize { @calls << @clock.call }
+      nil
+    end
+
+    def prune(now)
+      cutoff = now - WINDOW
+      @calls.reject! { |t| t <= cutoff }
+    end
+
+    def current_time
+      # Fully-qualified: bare `Process` would resolve to RCrewAI::Process here.
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    # Wraps an LLM client so every #chat acquires a rate-limiter slot first.
+    # All other messages delegate to the wrapped client unchanged.
+    class ThrottledClient
+      def initialize(client, limiter)
+        @client = client
+        @limiter = limiter
+      end
+
+      def chat(**kwargs, &block)
+        @limiter.acquire
+        @client.chat(**kwargs, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private)
+      end
+
+      def method_missing(name, *args, **kwargs, &block)
+        if @client.respond_to?(name)
+          @client.public_send(name, *args, **kwargs, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rcrewai/task.rb

@@ -9,7 +9,7 @@ module RCrewAI
     include AsyncExtensions
     include HumanInteractionExtensions
     attr_reader :name, :description, :agent, :context, :expected_output, :tools, :async,
-                :raw_result, :structured_output
+                :raw_result, :structured_output, :attachments
     attr_accessor :result, :status, :start_time, :end_time, :execution_time
 
     def initialize(name:, description:, agent: nil, **options)
@@ -21,6 +21,7 @@ module RCrewAI
       @tools = options[:tools] || []      # Additional tools for this specific task
       @async = options[:async] || false   # Whether task can run asynchronously
       @callback = options[:callback]      # Callback function after completion
+      @attachments = options[:attachments] || [] # Multimodal inputs (images)
 
       # Output processing (0.4.0)
       @output_schema = options[:output_schema]            # JSON-schema for structured output

data/lib/rcrewai/tool_runner.rb

@@ -27,7 +27,7 @@ module RCrewAI
         emit(Events::IterationStart, iteration: iter, iteration_index: iter)
 
         response = @llm.chat(
-          messages: msgs,
+          messages: fit_context(msgs),
           tools: @tools.map(&:json_schema),
           stream: ->(e) { @sink.call(retag(e, iter)) }
         )
@@ -80,6 +80,12 @@ module RCrewAI
 
     private
 
+    # Trims the message list to the model's context window when the agent
+    # supports it; a no-op otherwise.
+    def fit_context(messages)
+      @agent.respond_to?(:fit_context) ? @agent.fit_context(messages) : messages
+    end
+
     def tool_result_message(call_id, content)
       { role: 'tool', tool_call_id: call_id, content: content }
     end

data/lib/rcrewai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RCrewAI
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/rcrewai.rb

@@ -23,6 +23,9 @@ require_relative 'rcrewai/sse_parser'
 require_relative 'rcrewai/pricing'
 require_relative 'rcrewai/llm_client'
 require_relative 'rcrewai/memory'
+require_relative 'rcrewai/rate_limiter'
+require_relative 'rcrewai/context_window'
+require_relative 'rcrewai/multimodal'
 require_relative 'rcrewai/knowledge'
 require_relative 'rcrewai/human_input'
 require_relative 'rcrewai/tool_schema'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rcrewai
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - gkosmo
@@ -349,17 +349,24 @@ files:
 - docs/tutorials/index.md
 - docs/tutorials/multiple-crews.md
 - docs/upgrading-to-0.3.md
+- docs/upgrading-to-0.4.md
 - examples/async_execution_example.rb
+- examples/flow_example.rb
 - examples/hierarchical_crew_example.rb
 - examples/human_in_the_loop_example.rb
+- examples/knowledge_rag_example.rb
 - examples/mcp_example.rb
 - examples/native_tools_example.rb
+- examples/planning_and_training_example.rb
 - examples/streaming_example.rb
+- examples/structured_output_example.rb
 - lib/rcrewai.rb
 - lib/rcrewai/agent.rb
+- lib/rcrewai/agent_augmentations.rb
 - lib/rcrewai/async_executor.rb
 - lib/rcrewai/cli.rb
 - lib/rcrewai/configuration.rb
+- lib/rcrewai/context_window.rb
 - lib/rcrewai/crew.rb
 - lib/rcrewai/events.rb
 - lib/rcrewai/flow.rb
@@ -386,11 +393,13 @@ files:
 - lib/rcrewai/mcp/transport/http.rb
 - lib/rcrewai/mcp/transport/stdio.rb
 - lib/rcrewai/memory.rb
+- lib/rcrewai/multimodal.rb
 - lib/rcrewai/output_schema.rb
 - lib/rcrewai/planning.rb
 - lib/rcrewai/pricing.rb
 - lib/rcrewai/process.rb
 - lib/rcrewai/provider_schema.rb
+- lib/rcrewai/rate_limiter.rb
 - lib/rcrewai/sse_parser.rb
 - lib/rcrewai/task.rb
 - lib/rcrewai/tool_runner.rb