phronomy 0.8.0 → 0.9.0

data/lib/phronomy/runtime.rb

@@ -135,7 +135,7 @@ module Phronomy
     # is first accessed; subsequent calls return the cached gate.  To change the
     # cap at runtime, call {#reset_gate} first.
     #
-    # @param name [:agent, :tool, :workflow, :llm, :rag, :vector] resource name
+    # @param name [:agent, :tool, :workflow, :llm, :vector] resource name
     # @return [ConcurrencyGate]
     # @api private
     def gate(name)
@@ -279,7 +279,6 @@ module Phronomy
     # | `active_agent_tasks`      | currently running agent spawns |
     # | `active_tool_tasks`       | currently running tool spawns |
     # | `active_workflow_tasks`   | currently running workflow spawns |
-    # | `active_rag_tasks`        | currently running RAG fetches |
     # | `active_llm_tasks`        | currently running LLM calls |
     # | `task_wait_time_p50_ms`   | p50 spawn-to-start latency (ms) |
     # | `task_wait_time_p95_ms`   | p95 spawn-to-start latency (ms) |

data/lib/phronomy/tool.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "tool/base"
-require_relative "tool/mcp_tool"
-require_relative "tool/agent_tool"
-
+# This file is intentionally empty.
+# Tool definitions have moved to Phronomy::Agent::Context::Capability.
+# See lib/phronomy/agent/context/capability/.
 module Phronomy
   module Tool
   end

data/lib/phronomy/{tool/agent_tool.rb → tools/agent.rb}

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Tool
+  module Tools
     # Wraps a Phronomy::Agent::Base subclass as a callable tool so that a parent
     # ReactAgent (or any agent that supports tools) can delegate sub-tasks to a
     # fully-capable agent.
     #
-    # Use AgentTool.from_agent to generate a concrete tool class.  The generated
+    # Use Agent.from_agent to generate a concrete tool class.  The generated
     # class is anonymous; assign it to a constant when you need a stable name.
     #
     # @example Wrap an existing agent
-    #   SummarizerTool = Phronomy::Tool::AgentTool.from_agent(
+    #   SummarizerTool = Phronomy::Tools::Agent.from_agent(
     #     SummarizerAgent,
     #     tool_name:   "summarize",
     #     description: "Summarizes a long text and returns a brief summary"
@@ -21,12 +21,12 @@ module Phronomy
     #     instructions "You are an orchestrator that delegates to specialist agents."
     #     tools SummarizerTool
     #   end
-    class AgentTool < Phronomy::Tool::Base
+    class Agent < Phronomy::Agent::Context::Capability::Base
       description "Wraps an agent as a tool"
       param :input, type: :string, desc: "The input to forward to the wrapped agent"
 
       class << self
-        # Generates a Phronomy::Tool::AgentTool subclass that delegates #execute to
+        # Generates a Phronomy::Tools::Agent subclass that delegates #execute to
         # an instance of +agent_class+.
         #
         # @param agent_class  [Class] a Phronomy::Agent::Base subclass
@@ -34,7 +34,7 @@ module Phronomy
         #   defaults to a snake_case derivation of the agent class name
         # @param description  [String, nil] description exposed to the LLM;
         #   defaults to "Delegates to <AgentClassName>"
-        # @return [Class] an anonymous Phronomy::Tool::AgentTool subclass
+        # @return [Class] an anonymous Phronomy::Tools::Agent subclass
         # @api public
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)

data/lib/phronomy/{tool/mcp_tool.rb → tools/mcp.rb}

@@ -8,8 +8,8 @@ require "shellwords"
 require "uri"
 
 module Phronomy
-  module Tool
-    # A Phronomy::Tool::Base subclass that wraps a tool exposed by an external
+  module Tools
+    # A Phronomy::Agent::Context::Capability::Base subclass that wraps a tool exposed by an external
     # MCP (Model Context Protocol) server.
     #
     # Supports two transport schemes:
@@ -19,15 +19,15 @@ module Phronomy
     #   HTTP/SSE MCP server using +net/http+.
     #
     # @example
-    #   web_search = Phronomy::Tool::McpTool.from_server(
+    #   web_search = Phronomy::Tools::Mcp.from_server(
     #     "stdio://./mcp-server",
     #     tool_name: "search_web"
     #   )
     #   agent = MyAgent.new
     #   agent_class.tools(web_search)
-    class McpTool < Base
+    class Mcp < Phronomy::Agent::Context::Capability::Base
       class << self
-        # Build a McpTool instance by querying a running MCP server for the
+        # Build a Mcp instance by querying a running MCP server for the
         # tool definition identified by +tool_name+.
         #
         # @param server_uri [String] URI of the MCP server.
@@ -35,11 +35,11 @@ module Phronomy
         #   - "stdio://<command>"  — spawn a child process
         #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
-        # @return [McpTool] a configured subclass instance ready for use with an Agent
+        # @return [Mcp] a configured subclass instance ready for use with an Agent
         # @api public
         def from_server(server_uri, tool_name:)
           # Use a short-lived transport only to query the tool definition,
-          # then close it.  Each McpTool instance creates its own transport
+          # then close it.  Each Mcp instance creates its own transport
           # so that concurrent callers never share IO streams.
           transport = build_transport(server_uri)
           begin
@@ -65,7 +65,7 @@ module Phronomy
         end
 
         def build_tool_class(tool_name, server_uri, tool_def)
-          klass = Class.new(McpTool)
+          klass = Class.new(Mcp)
           klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
 
@@ -289,7 +289,7 @@ module Phronomy
       # both the 2024-11-05 and 2025-03-26 MCP HTTP transport specifications.
       #
       # @example
-      #   tool = Phronomy::Tool::McpTool.from_server(
+      #   tool = Phronomy::Tools::Mcp.from_server(
       #     "http://localhost:8080/mcp",
       #     tool_name: "weather_lookup"
       #   )

data/lib/phronomy/tools/vector_search.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tools
+    # A Capability::Base subclass that wraps a {Phronomy::VectorStore::Base} and
+    # a {Phronomy::VectorStore::Embeddings::Base} adapter so that an agent can
+    # perform semantic search as a tool call.
+    #
+    # Do not instantiate this class directly.  Use the factory method
+    # {.from_store} to produce a configured subclass, then pass it to your agent.
+    #
+    # @example
+    #   store = Phronomy::VectorStore::InMemory.new
+    #   emb   = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new(model: "...")
+    #   tool  = Phronomy::Tools::VectorSearch.from_store(store, embeddings: emb,
+    #             k: 3, tool_name: "search_docs",
+    #             description: "Search the company knowledge base.")
+    #   agent = MyAgent.new
+    #   agent.tools tool
+    #
+    # @api public
+    class VectorSearch < Phronomy::Agent::Context::Capability::Base
+      description "Search for relevant documents using semantic similarity."
+      param :query, type: :string, desc: "The natural-language search query"
+
+      class << self
+        # Build a VectorSearch tool backed by the given store and embeddings adapter.
+        #
+        # @param store       [Phronomy::VectorStore::Base]
+        # @param embeddings  [Phronomy::VectorStore::Embeddings::Base]
+        # @param k           [Integer]       number of results to return (default 5)
+        # @param tool_name   [String]        name exposed to the LLM
+        # @param description [String, nil]   optional description override
+        # @return [Class] anonymous subclass of VectorSearch configured with the given store
+        # @api public
+        def from_store(store, embeddings:, k: 5, tool_name: "vector_search", description: nil)
+          klass = Class.new(self)
+          klass.tool_name(tool_name)
+          klass.description(description || "Search the vector store for documents similar to the query.")
+
+          klass.define_method(:initialize) do
+            @store = store
+            @embeddings = embeddings
+            @k = k
+          end
+
+          klass.define_method(:execute) do |query:|
+            embedding = @embeddings.embed(query)
+            results = @store.search(query_embedding: embedding, k: @k)
+            return "No results found." if results.empty?
+
+            results.map.with_index(1) do |r, i|
+              content = r.dig(:metadata, :content) ||
+                r.dig(:metadata, :text) ||
+                r[:metadata].to_s
+              "[#{i}] (score: #{r[:score].round(3)}) #{content}"
+            end.join("\n")
+          end
+
+          klass
+        end
+      end
+
+      # @api public
+      def execute(query:)
+        raise NotImplementedError, "Use VectorSearch.from_store to create a configured instance"
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/async_backend.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    # Mixin that defines the async interface for VectorStore backends.
+    #
+    # Mixing this module into a VectorStore class provides three choices:
+    #
+    # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
+    #    that route through {BlockingAdapterPool} (the previous behaviour).
+    #
+    # 2. **Override selectively** — override only the async methods where the
+    #    backend has a native async driver, while the remaining methods fall back
+    #    to the pool.
+    #
+    # 3. **Implement all natively** — override all async methods to avoid pool
+    #    allocation entirely.
+    #
+    # @example Native async search (no pool worker thread allocated)
+    #   class MyFastStore < Phronomy::VectorStore::Base
+    #     include Phronomy::VectorStore::AsyncBackend
+    #
+    #     def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
+    #       # Returns a PendingOperation backed by a native async driver.
+    #       native_async_search(query_embedding, k)
+    #     end
+    #   end
+    #
+    # @api public
+    module AsyncBackend
+      # Async variant of {VectorStore::Base#add}.
+      #
+      # Submits the add call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#search}.
+      #
+      # Submits the search call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#remove}.
+      #
+      # Submits the remove call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param id                 [String]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def remove_async(id:, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          remove(id: id)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#clear}.
+      #
+      # Submits the clear call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def clear_async(cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          clear
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/base.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    # Abstract interface for vector stores.
+    #
+    # Implementations manage a collection of (embedding, metadata) pairs and
+    # support similarity search.
+    #
+    # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
+    # are provided by the {AsyncBackend} mixin which defaults to routing calls
+    # through {BlockingAdapterPool}.  Backends with native async drivers may
+    # override individual async methods without touching the pool at all.
+    class Base
+      include AsyncBackend
+
+      # Add a document with its vector embedding.
+      #
+      # @param id                 [String]                         unique document identifier
+      # @param embedding          [Array<Float>]                   vector embedding
+      # @param metadata           [Hash]                           arbitrary metadata (e.g. the original message object)
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @api public
+      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
+        raise NotImplementedError, "#{self.class}#add is not implemented"
+      end
+
+      # Return the k most similar documents to the query embedding.
+      #
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]                        number of results
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @return [Array<Hash>] each element: { id:, score:, metadata: }
+      # @api public
+      def search(query_embedding:, k: 5, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
+        raise NotImplementedError, "#{self.class}#search is not implemented"
+      end
+
+      # Remove a single document by id.
+      #
+      # @param id [String] document identifier
+      # @api public
+      def remove(id:)
+        raise NotImplementedError, "#{self.class}#remove is not implemented"
+      end
+
+      # Remove all documents.
+      def clear
+        raise NotImplementedError, "#{self.class}#clear is not implemented"
+      end
+
+      # Return the number of documents stored.
+      #
+      # @return [Integer]
+      # @api public
+      def size
+        raise NotImplementedError, "#{self.class}#size is not implemented"
+      end
+
+      private
+
+      # Validates that embedding has the expected dimension.
+      # Raises ArgumentError if sizes differ.
+      # A nil expected_dimension is a no-op (dimension not yet established).
+      def validate_embedding_dimension!(embedding, expected_dimension)
+        return unless expected_dimension
+
+        actual = embedding.size
+        return if actual == expected_dimension
+
+        raise ArgumentError,
+          "Embedding dimension mismatch: expected #{expected_dimension}, got #{actual}"
+      end
+
+      # Validates that k is a positive integer.
+      # Accepts any value accepted by Integer() (e.g. "5"), but raises
+      # ArgumentError for non-integer strings, zero, and negative values.
+      def validate_k!(k)
+        int_k = Integer(k)
+        raise ArgumentError, "k must be a positive integer, got #{int_k}" unless int_k >= 1
+        int_k
+      rescue ArgumentError => e
+        raise ArgumentError, "k must be a positive integer: #{e.message}"
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    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

data/lib/phronomy/vector_store/embeddings/ruby_llm_embeddings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    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::VectorStore::Embeddings::RubyLLMEmbeddings.new
+      #   vector = embeddings.embed("Hello, world!")
+      #
+      # @example Explicit model
+      #   embeddings = Phronomy::VectorStore::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

data/lib/phronomy/vector_store/in_memory.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    # Pure-Ruby in-memory vector store using cosine similarity.
+    #
+    # Intended for tests, short-lived agents, and Retrieval::Semantic scenarios where
+    # the message count is small enough that a linear scan is fast enough.
+    #
+    # @example
+    #   store = Phronomy::VectorStore::InMemory.new
+    #   store.add(id: "1", embedding: [0.1, 0.9], metadata: { message: msg })
+    #   results = store.search(query_embedding: [0.1, 0.8], k: 3)
+    class InMemory < Base
+      # @param dimension [Integer, nil] expected embedding dimension.
+      #   When nil, the dimension is inferred from the first call to #add.
+      #   For multi-threaded use, pass dimension: explicitly; concurrent first
+      #   adds are not guaranteed to be race-free.
+      # @api public
+      def initialize(dimension: nil)
+        @documents = {}
+        @expected_dimension = dimension
+      end
+
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @api public
+      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
+        # Establish expected dimension on first add, then validate.
+        @expected_dimension ||= embedding.size
+        validate_embedding_dimension!(embedding, @expected_dimension)
+        @documents[id] = {embedding: embedding, metadata: metadata}
+        self
+      end
+
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @return [Array<Hash>] sorted by descending score
+      # @api public
+      # mutant:disable - genuine equivalent mutations: doc.fetch(:embedding) vs doc[:embedding] (key
+      #   always present); {id:, score:, metadata: doc.fetch(:metadata)} shorthand+fetch vs []
+      #   (key always present); -r.fetch(:score) vs -r[:score] (key always present); snapshot = @documents
+      #   vs .dup is equivalent in single-threaded tests (GVL makes Hash#dup atomic, no behaviour
+      #   difference under test isolation)
+      def search(query_embedding:, k: 5, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
+        k = validate_k!(k)
+        # search never establishes dimension; validate only when dimension is known.
+        validate_embedding_dimension!(query_embedding, @expected_dimension)
+        # Take an atomic snapshot before iterating.  Hash#dup is a C-level
+        # call that completes without releasing the GVL, so it is atomic with
+        # respect to any other Ruby thread.  Iterating the copy instead of
+        # @documents directly prevents "can't add a new key into hash during
+        # iteration" when a concurrent thread calls #add.
+        snapshot = @documents.dup
+        results = snapshot.map do |id, doc|
+          score = cosine_similarity(query_embedding, doc[:embedding])
+          {id: id, score: score, metadata: doc[:metadata]}
+        end
+        results.sort_by { |r| -r[:score] }.first(k)
+      end
+
+      def remove(id:)
+        @documents.delete(id)
+        self
+      end
+
+      def clear
+        @documents.clear
+        self
+      end
+
+      # @return [Integer] number of documents stored
+      # @api public
+      def size
+        @documents.size
+      end
+
+      private
+
+      # mutant:disable - empty-vector early-return condition variants (if false, if nil, if a.empty?,
+      #   if b.empty?, if a.empty? && b.empty?, if a.empty? || false, if false || b.empty?,
+      #   if nil || b.empty?, if nil && b.empty?) are genuine equivalents: dimension validation in
+      #   #add and #search enforces same-size embeddings, so a.empty? iff b.empty?; when both are
+      #   empty norm_a = sqrt(0) = 0 so the norm_a.zero? guard returns 0.0 anyway
+      def cosine_similarity(a, b)
+        return 0.0 if a.empty? || b.empty?
+
+        dot = a.zip(b).sum { |x, y| x * y }
+        norm_a = Math.sqrt(a.sum { |x| x**2 })
+        norm_b = Math.sqrt(b.sum { |x| x**2 })
+
+        return 0.0 if norm_a.zero? || norm_b.zero?
+
+        dot / (norm_a * norm_b)
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/loader/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    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