phronomy 0.8.0 → 0.9.0

data/lib/phronomy/vector_store.rb

@@ -1,11 +1,23 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Vector store implementations for embedding-based semantic search.
+  # Vector store infrastructure: backends, embeddings adapters, document loaders,
+  # and text splitters.
   #
-  # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::Agent::Context::Knowledge::VectorStore::Base
-  #   Phronomy::Agent::Context::Knowledge::VectorStore::InMemory
+  # Sub-namespaces are auto-loaded by Zeitwerk:
+  #   Phronomy::VectorStore::Base
+  #   Phronomy::VectorStore::InMemory
+  #   Phronomy::VectorStore::Pgvector
+  #   Phronomy::VectorStore::RedisSearch
+  #   Phronomy::VectorStore::Embeddings::Base
+  #   Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings
+  #   Phronomy::VectorStore::Loader::Base
+  #   Phronomy::VectorStore::Loader::PlainTextLoader
+  #   Phronomy::VectorStore::Loader::MarkdownLoader
+  #   Phronomy::VectorStore::Loader::CsvLoader
+  #   Phronomy::VectorStore::Splitter::Base
+  #   Phronomy::VectorStore::Splitter::FixedSizeSplitter
+  #   Phronomy::VectorStore::Splitter::RecursiveSplitter
   module VectorStore
   end
 end

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/phronomy.rb

@@ -8,7 +8,8 @@ loader = Zeitwerk::Loader.for_gem
 # Teach Zeitwerk that "llm" maps to "LLM" so that file names such as
 # ruby_llm_embeddings.rb resolve to RubyLLMEmbeddings (not RubyLlmEmbeddings).
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
-loader.inflector.inflect("rag_knowledge" => "RAGKnowledge")
+# RAG: Zeitwerk would infer "Rag" — override to "RAG".
+loader.inflector.inflect("rag" => "RAG")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".

data/scripts/api_snapshot.rb

@@ -24,26 +24,28 @@ require_relative "../lib/phronomy"
 PUBLIC_API_ENTRIES = [
   # Stable
   Phronomy::Agent::Base,
-  Phronomy::Tool::Base,
+  Phronomy::Agent::Context::Capability::Base,
   Phronomy::Workflow,
   Phronomy::WorkflowContext,
   Phronomy::Runnable,
-  Phronomy::PromptTemplate,
+  Phronomy::Agent::Context::Instruction::PromptTemplate,
   # Beta
   Phronomy::Agent::ReactAgent,
-  Phronomy::Agent::Orchestrator,
-  Phronomy::Agent::TeamCoordinator,
+  Phronomy::MultiAgent::Orchestrator,
+  Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Guardrail::InputGuardrail,
   Phronomy::Guardrail::OutputGuardrail,
   Phronomy::VectorStore::Base,
   Phronomy::VectorStore::InMemory,
-  Phronomy::Embeddings::Base,
-  Phronomy::KnowledgeSource::Base,
-  Phronomy::KnowledgeSource::StaticKnowledge,
-  Phronomy::KnowledgeSource::RAGKnowledge,
+  Phronomy::VectorStore::Embeddings::Base,
+  Phronomy::Agent::Context::Knowledge::Base,
+  Phronomy::Agent::Context::Knowledge::StaticKnowledge,
   Phronomy::Tracing::Base,
   Phronomy::Tracing::NullTracer,
-  Phronomy::Eval::Runner
+  Phronomy::Eval::Runner,
+  Phronomy::Tools::Mcp,
+  Phronomy::Tools::Agent,
+  Phronomy::Tools::VectorSearch
 ].freeze
 
 # Baseline methods common to all Ruby objects — excluded from the snapshot.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-30 00:00:00.000000000 Z
+date: 2026-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -64,8 +64,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-description: Phronomy provides Agent, Workflow, Tool, Guardrail, RAG, and Multi-agent
-  capabilities for building AI agents in Ruby. Powered by RubyLLM for LLM abstraction.
+description: Phronomy provides composable building blocks — Agents, Workflows, Tools,
+  Guardrails, and Tracing — for building AI agents in Ruby. Powered by RubyLLM for
+  LLM abstraction.
 email:
 - raizo.tcs@gmail.com
 executables: []
@@ -99,6 +100,7 @@ files:
 - docs/decisions/008-orchestrator-uses-os-threads.md
 - docs/decisions/009-state-store-abstraction.md
 - docs/decisions/010-cooperative-first-concurrency.md
+- docs/decisions/011-build-context-as-single-llm-input-authority.md
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
@@ -109,28 +111,12 @@ files:
 - lib/phronomy/agent/concerns/guardrailable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
-- lib/phronomy/agent/context/conversation/compaction_context.rb
-- lib/phronomy/agent/context/conversation/trigger_context.rb
-- lib/phronomy/agent/context/conversation/trim_context.rb
+- lib/phronomy/agent/context/capability/base.rb
+- lib/phronomy/agent/context/capability/scope_policy.rb
 - lib/phronomy/agent/context/instruction/prompt_template.rb
-- lib/phronomy/agent/context/knowledge/embeddings/base.rb
-- lib/phronomy/agent/context/knowledge/embeddings/ruby_llm_embeddings.rb
-- lib/phronomy/agent/context/knowledge/loader/base.rb
-- lib/phronomy/agent/context/knowledge/loader/csv_loader.rb
-- lib/phronomy/agent/context/knowledge/loader/markdown_loader.rb
-- lib/phronomy/agent/context/knowledge/loader/plain_text_loader.rb
-- lib/phronomy/agent/context/knowledge/source/base.rb
-- lib/phronomy/agent/context/knowledge/source/entity_knowledge.rb
-- lib/phronomy/agent/context/knowledge/source/rag_knowledge.rb
-- lib/phronomy/agent/context/knowledge/source/static_knowledge.rb
-- lib/phronomy/agent/context/knowledge/splitter/base.rb
-- lib/phronomy/agent/context/knowledge/splitter/fixed_size_splitter.rb
-- lib/phronomy/agent/context/knowledge/splitter/recursive_splitter.rb
-- lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb
-- lib/phronomy/agent/context/knowledge/vector_store/base.rb
-- lib/phronomy/agent/context/knowledge/vector_store/in_memory.rb
-- lib/phronomy/agent/context/knowledge/vector_store/pgvector.rb
-- lib/phronomy/agent/context/knowledge/vector_store/redis_search.rb
+- lib/phronomy/agent/context/knowledge/base.rb
+- lib/phronomy/agent/context/knowledge/entity_knowledge.rb
+- lib/phronomy/agent/context/knowledge/static_knowledge.rb
 - lib/phronomy/agent/fsm.rb
 - lib/phronomy/agent/invocation_pipeline.rb
 - lib/phronomy/agent/lifecycle/fsm_session.rb
@@ -151,7 +137,6 @@ files:
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
 - lib/phronomy/diagnostics.rb
-- lib/phronomy/embeddings.rb
 - lib/phronomy/eval.rb
 - lib/phronomy/eval/comparison.rb
 - lib/phronomy/eval/dataset.rb
@@ -181,7 +166,6 @@ files:
 - lib/phronomy/llm_context_window/context_version_cache.rb
 - lib/phronomy/llm_context_window/token_budget.rb
 - lib/phronomy/llm_context_window/token_estimator.rb
-- lib/phronomy/loader.rb
 - lib/phronomy/metrics.rb
 - lib/phronomy/multi_agent/handoff.rb
 - lib/phronomy/multi_agent/orchestrator.rb
@@ -203,7 +187,6 @@ files:
 - lib/phronomy/runtime/thread_scheduler.rb
 - lib/phronomy/runtime/timer_queue.rb
 - lib/phronomy/runtime/timer_service.rb
-- lib/phronomy/splitter.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
 - lib/phronomy/task.rb
@@ -218,16 +201,29 @@ files:
 - lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
-- lib/phronomy/tool/agent_tool.rb
-- lib/phronomy/tool/base.rb
-- lib/phronomy/tool/mcp_tool.rb
-- lib/phronomy/tool/scope_policy.rb
+- lib/phronomy/tools/agent.rb
+- lib/phronomy/tools/mcp.rb
+- lib/phronomy/tools/vector_search.rb
 - lib/phronomy/tracing.rb
 - lib/phronomy/tracing/base.rb
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
 - lib/phronomy/tracing/open_telemetry_tracer.rb
 - lib/phronomy/vector_store.rb
+- lib/phronomy/vector_store/async_backend.rb
+- lib/phronomy/vector_store/base.rb
+- lib/phronomy/vector_store/embeddings/base.rb
+- lib/phronomy/vector_store/embeddings/ruby_llm_embeddings.rb
+- lib/phronomy/vector_store/in_memory.rb
+- lib/phronomy/vector_store/loader/base.rb
+- lib/phronomy/vector_store/loader/csv_loader.rb
+- lib/phronomy/vector_store/loader/markdown_loader.rb
+- lib/phronomy/vector_store/loader/plain_text_loader.rb
+- lib/phronomy/vector_store/pgvector.rb
+- lib/phronomy/vector_store/redis_search.rb
+- lib/phronomy/vector_store/splitter/base.rb
+- lib/phronomy/vector_store/splitter/fixed_size_splitter.rb
+- lib/phronomy/vector_store/splitter/recursive_splitter.rb
 - lib/phronomy/version.rb
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow_context.rb

data/lib/phronomy/agent/context/conversation/compaction_context.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Conversation
-        # Context object passed to the +on_compact+ callback registered on an agent.
-        #
-        # The callback calls #compact one or more times to specify which ranges of
-        # messages to replace with a summary. Each call:
-        #   1. Yields the selected message elements to the block.
-        #   2. Receives the block's return value as the summary text.
-        #   3. Persists a compaction record to the memory store (if available).
-        #   4. Updates #result_messages so that the compacted range is replaced
-        #      by a single +:system+ summary message.
-        #
-        # The agent reads #result_messages after the callback returns and uses it
-        # as the new message list for this invocation.
-        #
-        # @example Summarise the oldest half of the conversation
-        #   on_compact do |ctx|
-        #     half = ctx.message_elements.length / 2
-        #     ctx.compact(0...half) do |elements|
-        #       texts = elements.map { |e| "#{e[:role]}: #{e[:message].content}" }.join("\n")
-        #       "Summary of earlier conversation:\n#{texts}"
-        #     end
-        #   end
-        class CompactionContext
-          # @return [Array<Hash>] message elements at compaction time
-          attr_reader :message_elements
-
-          # @return [Phronomy::LlmContextWindow::TokenBudget, nil]
-          attr_reader :budget
-
-          # @return [Integer] total estimated token count before compaction
-          attr_reader :total_tokens
-
-          # The current message list to be used after all compact calls have been made.
-          # Updated by each call to #compact.
-          #
-          # @return [Array]
-          attr_reader :result_messages
-
-          # @param message_elements [Array<Hash>]
-          #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-          # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
-          # @param thread_id [String, nil] used when saving compaction records
-          # @param memory [Object, nil] memory object; must respond to #save_compaction
-          #   for compaction records to be persisted
-          # @api private
-          # mutant:disable - e[:tokens] vs e.fetch(:tokens) and e[:message] vs e.fetch(:message) are genuine equivalent mutations: elements always carry both keys
-          def initialize(message_elements:, budget:, thread_id: nil, memory: nil)
-            @message_elements = message_elements.dup
-            @budget = budget
-            @total_tokens = message_elements.sum { |e| e[:tokens] }
-            @thread_id = thread_id
-            @memory = memory
-            @result_messages = @message_elements.map { |e| e[:message] }
-          end
-
-          # Replace a range of messages with a summary produced by the block.
-          #
-          # The block receives the selected Array<Hash> elements and must return a
-          # String that serves as the summary text. After the call, #result_messages
-          # reflects the replacement.
-          #
-          # If the memory object responds to #save_compaction, a compaction record
-          # { start_seq:, end_seq:, summary_text: } is persisted for auditability.
-          #
-          # @param range [Range, Integer] index range into message_elements (0-based)
-          # @yieldparam elements [Array<Hash>] the selected message elements
-          # @yieldreturn [String] summary text to replace the selected messages
-          # @return [Array] the updated result_messages array
-          # @api private
-          # mutant:disable - multiple genuine equivalent mutations: is_a? vs instance_of? (Array/Range have no subclasses), yield.to_s vs yield (block always returns String), [:seq]/[:message] vs .fetch(:seq)/.fetch(:message) (keys always present), range.to_i vs range/to_int/Integer() (Integer is already integer), || [] vs nothing (Array#[] never returns nil for slice), RubyLLM::Message vs Message (killfork inherits Message=Struct from integration specs, both expose identical role/content interface)
-          def compact(range)
-            # Normalise: Integer index → single-element Array; Range → Array slice.
-            raw = @message_elements[range]
-            elements = if raw.is_a?(Array)
-              raw
-            elsif raw.nil?
-              []
-            else
-              [raw]
-            end
-            return @result_messages if elements.empty?
-
-            summary_text = yield(elements).to_s
-
-            start_seq = elements.first[:seq]
-            end_seq = elements.last[:seq]
-
-            if @memory && @thread_id && @memory.respond_to?(:save_compaction)
-              @memory.save_compaction(
-                thread_id: @thread_id,
-                start_seq: start_seq,
-                end_seq: end_seq,
-                summary_text: summary_text
-              )
-            end
-
-            # Compute the last included index in the original @message_elements array.
-            last_idx = if range.is_a?(Range)
-              range.exclude_end? ? range.last - 1 : range.last
-            else
-              range.to_i
-            end
-
-            remaining = (@message_elements[(last_idx + 1)..] || []).map { |e| e[:message] }
-            summary_msg = RubyLLM::Message.new(role: :system, content: summary_text)
-            @result_messages = [summary_msg] + remaining
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/conversation/trigger_context.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Conversation
-        # Read-only context passed to the +on_compaction_trigger+ callback.
-        #
-        # The callback inspects the current message list and budget, then returns
-        # a truthy value to trigger compaction or a falsy value to skip it.
-        #
-        # No mutations are allowed through this object; use CompactionContext
-        # (passed to +on_compact+) for actual modifications.
-        #
-        # @example Trigger compaction when messages exceed 80% of the input budget
-        #   on_compaction_trigger do |ctx|
-        #     limit = ctx.budget&.available(used: 0) || Float::INFINITY
-        #     ctx.total_tokens > limit * 0.8
-        #   end
-        class TriggerContext
-          # @return [Array<Hash>] frozen snapshot of message elements
-          #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-          attr_reader :message_elements
-
-          # @return [Phronomy::LlmContextWindow::TokenBudget, nil] token budget for this invocation
-          attr_reader :budget
-
-          # @return [Integer] total estimated token count of all message elements
-          attr_reader :total_tokens
-
-          # @param message_elements [Array<Hash>]
-          # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
-          # @api private
-          def initialize(message_elements:, budget:)
-            @message_elements = message_elements.dup.freeze
-            @budget = budget
-            @total_tokens = message_elements.sum { |e| e[:tokens] }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/conversation/trim_context.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Conversation
-        # Context object passed to the +on_trim+ callback registered on an agent class.
-        #
-        # The callback receives a TrimContext and may call #remove to drop specific
-        # messages from the conversation before the LLM is called. Changes affect
-        # only the current invocation; the underlying memory store is not modified.
-        #
-        # Message elements are identified by a +:seq+ integer that is assigned
-        # sequentially (0-based) when messages are loaded from memory each turn.
-        #
-        # @example Remove the oldest two messages when the budget is tight
-        #   on_trim do |ctx|
-        #     if ctx.total_tokens > ctx.budget.available(used: 0) * 0.9
-        #       seqs_to_drop = ctx.message_elements.first(2).map { |e| e[:seq] }
-        #       ctx.remove(seqs_to_drop)
-        #     end
-        #   end
-        class TrimContext
-          # @return [Phronomy::LlmContextWindow::TokenBudget, nil] token budget for this invocation
-          attr_reader :budget
-
-          # @return [Integer] total estimated token count of all current message elements
-          attr_reader :total_tokens
-
-          # @param message_elements [Array<Hash>]
-          #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-          # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
-          # @api private
-          def initialize(message_elements:, budget:)
-            @message_elements = message_elements.dup
-            @budget = budget
-            recalculate!
-          end
-
-          # Returns a snapshot of the current message elements (defensive copy).
-          # Each element is a Hash with +:seq+, +:message+, +:tokens+, and +:role+.
-          #
-          # @return [Array<Hash>]
-          # @api private
-          def message_elements
-            @message_elements.dup
-          end
-
-          # Remove messages identified by seq numbers.
-          # Calling this multiple times accumulates removals.
-          #
-          # @param seqs [Integer, Array<Integer>] seq number(s) to remove
-          # @return [self]
-          # @api private
-          # mutant:disable - Array(seqs).to_set vs Array(seqs) and e[:seq] vs e.fetch(:seq) are genuine equivalent: Array#include? returns identical results for both
-          def remove(seqs)
-            seqs_set = Array(seqs).to_set
-            @message_elements.reject! { |e| seqs_set.include?(e[:seq]) }
-            recalculate!
-            self
-          end
-
-          # Convenience: returns the plain message objects (without element metadata).
-          #
-          # @return [Array]
-          # @api private
-          # mutant:disable - e[:message] vs e.fetch(:message) is a genuine equivalent mutation: elements always carry :message
-          def messages
-            @message_elements.map { |e| e[:message] }
-          end
-
-          private
-
-          # mutant:disable - e[:tokens] vs e.fetch(:tokens) is a genuine equivalent mutation: elements always carry :tokens
-          def recalculate!
-            @total_tokens = @message_elements.sum { |e| e[:tokens] }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/embeddings/base.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        module Embeddings
-          # Abstract interface for embedding adapters.
-          #
-          # Concrete implementations must override {#embed} and return a vector
-          # as an +Array<Float>+.
-          class Base
-            # Embed the given text and return a vector representation.
-            #
-            # @param text               [String]                         the text to embed
-            # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-            # @return [Array<Float>] the embedding vector
-            # @api public
-            def embed(text, cancellation_token = nil)
-              cancellation_token&.raise_if_cancelled!
-              raise NotImplementedError, "#{self.class}#embed is not implemented"
-            end
-
-            # Submits an {#embed} call to {BlockingAdapterPool} and returns a
-            # {BlockingAdapterPool::PendingOperation}.
-            #
-            # @param text               [String]
-            # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-            # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-            # @return [BlockingAdapterPool::PendingOperation]
-            # @api public
-            def embed_async(text, cancellation_token = nil, timeout: nil)
-              Phronomy::Runtime.instance.blocking_io.submit(
-                timeout: timeout,
-                cancellation_token: cancellation_token
-              ) do
-                embed(text, cancellation_token)
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/embeddings/ruby_llm_embeddings.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        module Embeddings
-          # Embeddings adapter backed by RubyLLM.
-          #
-          # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
-          # +Array<Float>+.
-          #
-          # @example Default model
-          #   embeddings = Phronomy::Agent::Context::Knowledge::Embeddings::RubyLLMEmbeddings.new
-          #   vector = embeddings.embed("Hello, world!")
-          #
-          # @example Explicit model
-          #   embeddings = Phronomy::Agent::Context::Knowledge::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
-          #   vector = embeddings.embed("Hello, world!")
-          class RubyLLMEmbeddings < Base
-            # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
-            # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
-            # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
-            #                                          (useful for locally hosted models not in the registry)
-            # @api public
-            def initialize(model: nil, provider: nil, assume_model_exists: false)
-              @model = model
-              @provider = provider
-              @assume_model_exists = assume_model_exists
-            end
-
-            # Embed text via RubyLLM.
-            #
-            # @param text               [String]
-            # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-            # @return [Array<Float>]
-            # @api public
-            def embed(text, cancellation_token = nil)
-              cancellation_token&.raise_if_cancelled!
-              opts = {}
-              opts[:model] = @model if @model
-              opts[:provider] = @provider if @provider
-              opts[:assume_model_exists] = true if @assume_model_exists
-              RubyLLM.embed(text, **opts).vectors
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/loader/base.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        module Loader
-          # Abstract base class for document loaders.
-          #
-          # A loader converts an external source (file path, URL, etc.) into an
-          # Array of document hashes understood by the rest of the pipeline:
-          #
-          #   [{ text: String, metadata: Hash }, ...]
-          #
-          # Subclasses must implement {#load}.
-          class Base
-            # Load documents from +source+ and return an array of document hashes.
-            #
-            # @param source [String] file path, URL, or other source identifier
-            # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
-            # @raise [NotImplementedError] when not overridden by a subclass
-            # @api public
-            def load(source)
-              raise NotImplementedError, "#{self.class}#load is not implemented"
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/loader/csv_loader.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-require "csv"
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        module Loader
-          # Loads a CSV file, converting each row into a separate document.
-          #
-          # By default the first row is treated as a header and column names are
-          # available in the document metadata.  The full row is serialised to
-          # a human-readable "key: value" string for embedding.
-          #
-          # @example
-          #   loader = Phronomy::Agent::Context::Knowledge::Loader::CsvLoader.new
-          #   docs   = loader.load("products.csv")
-          #   # => [
-          #   #   { text: "name: Widget\nprice: 9.99", metadata: { source: "...", row: 1, name: "Widget", price: "9.99" } },
-          #   #   ...
-          #   # ]
-          class CsvLoader < Base
-            # @param headers     [Boolean] treat the first row as headers (default: true)
-            # @param text_column [String, nil] if set, use only this column as the document text
-            # @api public
-            def initialize(headers: true, text_column: nil)
-              @headers = headers
-              @text_column = text_column
-            end
-
-            # @param source [String] path to a CSV file
-            # @return [Array<Hash>]
-            # @raise [Errno::ENOENT] if the file does not exist
-            # @api public
-            def load(source)
-              rows = CSV.read(source, headers: @headers, encoding: "UTF-8")
-
-              if @headers
-                rows.each_with_index.map do |row, idx|
-                  row_hash = row.to_h
-                  text = if @text_column
-                    row_hash[@text_column].to_s
-                  else
-                    row_hash.map { |k, v| "#{k}: #{v}" }.join("\n")
-                  end
-                  metadata = row_hash.transform_keys(&:to_sym).merge(source: source, row: idx + 1)
-                  {text: text, metadata: metadata}
-                end
-              else
-                rows.each_with_index.map do |row, idx|
-                  text = row.join(", ")
-                  {text: text, metadata: {source: source, row: idx + 1}}
-                end
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end